GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
KICONVTOOL(8) FreeBSD System Manager's Manual KICONVTOOL(8)

kiconvtool
load kernel iconv charset tables

kiconvtool [-hvmd] [-l local ...] [-f foreign ...] [-p pair ...]

On FreeBSD, it's possible to allow unprivileged users to mount file systems without using su or sudo. This can be enabled with vfs.usermount sysctl. However, if file name conversion is used when mounting a file system, in most cases mount will fail with e.g. `mount_msdosfs: msdosfs_iconv: Operation not permitted' error. This is caused by the fact that mount needs to load character set tables into kernel for file name conversion to work, but this operation can't be allowed to unprivileged users because it's possible to waste lots of kernel memory filling it with many charset tables, which may lead to DoS.

kiconvtool utility allows you to preload specific charset tables into kernel, so you can allow unprivileged users to mount file systems with file name conversion, but still control amount of memory taken by conversion tables.

The options are as follows:

Display short help.
Turn on verbose output.
Display amount of memory used by tables already loaded into kernel. This is similar to `vmstat -m | grep iconv_data'.
Display list of currently loaded charset conversion tables.
charset
Specify local charset(s). Usually locale(s) of user(s) who will mount file systems.
charset
Specify foreign charset(s). These are charset(s) used inside file systems to store file names. Note that you don't need to specify UTF-16BE as it's always assumed.
pair
Specify charset pair(s). Each pair consists of local charset and foreign charset, separated by colon.

To load needed charset conversion tables, you should specify one or more local-foreign charset pairs. You can do it in two ways:

  • Explicitly specify needed pairs with -p flag. For example:
    kiconvtool -p KOI8-R:CP866 KOI8-R:CP1251
        
  • Specify all required local charsets with -l flag and all required foreign charsets with -f flag. For example:
    kiconvtool -l KOI8-R -f CP866 CP1251
        

You can combine those two ways (first, pairs are formed from all possible combinations of provided local/foreign charsets, then explicitly defined pairs are added).

To know which character sets you need for your media, first mount it under root user, then use the following command:

kiconvtool -d

to get list of charset tables loaded after your mounts. Note, that for each charset pair (LOCAL, FOREIGN), there will be two conversions (LOCAL -> FOREIGN and FOREIGN -> LOCAL).

Don't forget, that you need iconv library and iconv support for specific file system(s) to either be compiled into kernel or loaded as modules. Thus, for msdosfs you either need

msdosfs_iconv_load="YES"

in your /boot/loader.conf or

options   LIBICONV
options   MSDOSFS_ICONV

in your kernel config. Alternatively, rc.d script provided with kiconvtool can load required modules for you (see below).

1) My locale is ru_RU.KOI8-R, and I want to mount FAT32 with Russian file names from my USB flash drive with the following command:
mount_msdosfs -L ru_RU.KOI8-R -D CP866 /dev/da0s1 ~/mnt/flash

In my case, msdosfs uses both CP866 for 8.3 legacy file names and UTF-16BE for Win95 long names. So to be able to execute the mount command above as unprivileged user, I need to run this as root first (note that UTF-16BE doesn't need to be specified):

kiconvtool -l KOI8-R -f CP866

2) The same thing, but for mounting CD-ROM. I want to run this as a user:

mount_cd9660 -C KOI8-R /dev/acd0 ~/mnt/cdrom

ISO9660 only uses UTF-16BE internally, so I only need to specify local charset:

kiconvtool -l KOI8-R

You only need to call kiconvtool once to load charset tables - after that, mounting will work until reboot. For convenience, you can use rcNG script provided with kiconvtool to load charset conversion tables on system startup. Just add the following lines to /etc/rc.conf:

# enable kiconv script
kiconv_preload="YES"

# specify local/foreign encodings (all 4 ways demonstrated here load the same set):
kiconv_local_charsets="KOI8-R UTF-8"
kiconv_foreign_charsets="CP866"
# or
kiconv_charset_pairs="UTF-8:CP866 KOI8-R:CP866"
# or (you may specify kiconvtool flags directly)
kiconv_flags="-l KOI8-R UTF-8 -f CP866"
# or
kiconv_flags="-p UTF-8:CP866 KOI8-R:CP866"

# script also offers a convenient way to load required kernel iconv modules
kiconv_fstypes="msdosfs cd9660"

mount_cd9660(8), mount_msdosfs(8), mount_smbfs(8), mount_udf(8), kiconv(3)

Dmitry Marakasov ⟨amdmi3@FreeBSD.org⟩

The main bug is not in kiconvtool itself, but in kernel iconv implementation: charset names are case sensitive. So if you're using KOI8-R for mounting, you should use KOI8-R (not koi8-r or Koi8-R) in kiconvtool as well. The best idea is to use uppercase charset names everywhere.
May 8, 2018 FreeBSD

Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.