mod_lang
Internalization and Localization The mod_lang module is ProFTPD's module for handling the LANG and OPTS UTF8 commands, in support of RFC 2640. The mod_lang module also supports character sets other than UTF-8, for those sites which do not require RFC 2640 support, but do use character sets other than ASCII. This module is contained in the mod_lang.c file for ProFTPD 1.3.x, and is compiled in whenever the --enable-nls configure option is used. Installation instructions are discussed here. Examples of using mod_lang for various encodings and character sets can be seen here.
LANG
OPTS UTF8
mod_lang.c
--enable-nls
The most current version of mod_lang can be found in the ProFTPD source distribution.
<VirtualHost>
<Global>
The LangDefault directive is used to specify the default language of specific server configuration. Note that the specified language must be listed in the output from:
LangDefault
$ locale -a
Example:
<IfModule mod_lang.c> # Set the default to be Italian LangDefault it_IT </IfModule>
The LangEngine directive enables or disables the module's handling of the LANG command. If it is set to off this module does no localization of responses.
LangEngine
Note that setting LangEngine to off also keeps proftpd from advertisting "UTF8" in its FEAT response. As required by RFC 2640, proftpd can only show "UTF8" in response to a FEAT command if the LANG command is also supported. Hence why it is the LangEngine directive, and not UseUTF8, which controls the appearance of "UTF8".
proftpd
FEAT
UseUTF8
The LangOptions directive is used to configure various optional behavior of mod_lang.
LangOptions
LangOptions PreferServerEncoding
The currently implemented options are:
PreferServerEncoding
This option will cause mod_lang to refuse any OPTS UTF8 commands used by clients; these commands are used to change the server's handling of UTF8 encoded filenames.
Note that this option replaces the previous "strict" keyword supported by the UseEncoding directive, in older versions of mod_lang.
UseEncoding
RequireValidEncoding
This option will cause proftpd to reject commands on filenames if those filenames, as sent by the client, are not properly encoded in the expected character set.
The LangPath directive is used to configure an alternative directory from which mod_lang will load locale files. By default, mod_lang uses $prefix/locale/, where $prefix is where you installed proftpd, e.g. /usr/local/.
LangPath
locale/
/usr/local/
The path parameter must be an absolute path.
LangPath /etc/proftpd/locale
LangPath /path/to/ftpd/locale
The UseEncoding directive is used to explicitly configure which character sets should be used for encoding. By default, the mod_lang module will automatically discover the local character set, and will use UTF-8 for the client character set. The module will also allow the use of UTF-8 encoding to be changed by clients using the OPTS UTF8 command (as per RFC 2640).
For example, to disable all use of encoding, use the following in your proftpd.conf:
proftpd.conf
UseEncoding off
UseEncoding on
In addition to the on|off parameters, the UseEncoding directive allows administrators to specify exactly which character sets to use locally (i.e. for paths on local disks) and for dealing with clients. One such usage this way might look like:
UseEncoding koi8-r cp1251
koi8-r
LangOptions PreferServerEncoding UseEncoding koi8-r cp1251
For a full list of the character sets which are supported, use:
$ iconv --list
$ ./configure --enable-nls $ make $ make install
One common request of proftpd is to properly handle Cyrillic characters in file and directory names. The usual character sets which contain Cyrillic characters use the same codes as used for Telnet control codes, unfortunately. RFC 959 (which defines FTP) mandates that the Telnet control codes be supported in FTP implementations.
The mod_lang module, however, can be used to deal with this situation. If the UseEncoding directive is used to translate between local and client character sets, and the client character set is one of the known Cyrillic character sets, then proftpd will disable support of the Telnet control codes.
To make a long explanation short, if you want to use Cyrillic characters in paths with proftpd, compile your proftpd using the --enable-nls configure option (to enable the use of mod_lang), then use something like the following in your proftpd.conf:
<IfModule mod_lang.c> UseEncoding utf8 cp1251 </IfModule>
Frequently Asked Questions
Question: What translations for proftpd currently exist? Answer: ProFTPD has currently been translated into: bg_BG en_US es_ES fr_FR it_IT ja_JP ko_KR ru_RU zh_CN zh_TW If you are interested in providing more translations, please read this howto.
Question: When I upload a file with special characters (e.g. umlauts, accents, cedillas, etc) in the file name, the special characters are turned into '?' on the server. What's wrong? Answer: There are a couple of things to check when this happens. First, make sure that your proftpd has been compiled with NLS support. Type proftpd -V, and make sure you see: + NLS support appear in the output. Next, make sure that the LANG environment variable is set before starting the server. Special characters require that UTF-8 or ISO-8859-1 be used, thus you might use things like: # export LANG=de_DE.utf8 # export LANG=fr_FR.ISO8859-1 Last, check that any routers/firewalls/NAT between the clients and the server are not interfering. ProFTPD lists "UTF8" in its FEAT response data; many FTP clients use the OPTS UTF8 ON command to inform the server that UTF8 filenames will be sent. Some routers, firewalls, and NATs have been known to filter both the FEAT response and/or block commands like OPTS UTF8, thus interfering with the protocol and causing encoding problems. Question: I have configured my mod_lang module to use a language, but when I start proftpd, I see an error like this: mod_lang/0.9: LangDefault 'language', configured for server 'serverName', is not a supported language, removing Answer: This usually happens for one of two reasons: The configured language is not listed in `setlocale -a' The configured language is not one of the supported translations Both of these conditions must be true, otherwise you will see the "not a supported language" error. © Copyright 2006-2017 TJ Saunders All Rights Reserved
First, make sure that your proftpd has been compiled with NLS support. Type proftpd -V, and make sure you see:
proftpd -V
+ NLS support
Next, make sure that the LANG environment variable is set before starting the server. Special characters require that UTF-8 or ISO-8859-1 be used, thus you might use things like:
# export LANG=de_DE.utf8 # export LANG=fr_FR.ISO8859-1
Last, check that any routers/firewalls/NAT between the clients and the server are not interfering. ProFTPD lists "UTF8" in its FEAT response data; many FTP clients use the OPTS UTF8 ON command to inform the server that UTF8 filenames will be sent. Some routers, firewalls, and NATs have been known to filter both the FEAT response and/or block commands like OPTS UTF8, thus interfering with the protocol and causing encoding problems.
OPTS UTF8 ON
Question: I have configured my mod_lang module to use a language, but when I start proftpd, I see an error like this: mod_lang/0.9: LangDefault 'language', configured for server 'serverName', is not a supported language, removing Answer: This usually happens for one of two reasons: The configured language is not listed in `setlocale -a' The configured language is not one of the supported translations Both of these conditions must be true, otherwise you will see the "not a supported language" error. © Copyright 2006-2017 TJ Saunders All Rights Reserved
mod_lang/0.9: LangDefault 'language', configured for server 'serverName', is not a supported language, removing
`setlocale -a'