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

NAME
     kiconvtool – load kernel iconv charset tables

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

DESCRIPTION
     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:

     -h 	Display short help.

     -v 	Turn on verbose output.

     -m 	Display amount of memory used by tables already loaded into
		kernel. This is similar to `vmstat -m | grep iconv_data'.

     -d 	Display list of currently loaded charset conversion tables.

     -l charset
		Specify local charset(s). Usually locale(s) of user(s) who
		will mount file systems.

     -f 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.

     -p 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).

EXAMPLES
     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"

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

AUTHORS
     Dmitry Marakasov ⟨amdmi3@FreeBSD.org⟩

BUGS
     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.

FreeBSD 			  May 8, 2018			       FreeBSD