ProFTPD module mod_lang

## ProFTPD module `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.

The most current version of `mod_lang` can be found in the ProFTPD source distribution.

## Directives

- LangDefault
- LangEngine
- LangOptions
- LangPath
- UseEncoding

### LangDefault

Syntax: LangDefault language
Default: LangDefault en_US
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_lang
Compatibility: 1.3.1rc1

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:

      $ locale -a

Example:

      <IfModule mod_lang.c>
        # Set the default to be Italian
        LangDefault it_IT
      </IfModule>

### LangEngine

Syntax: LangEngine on|off
Default: LangEngine on
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_lang
Compatibility: 1.3.1rc1

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.

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

### LangOptions

Syntax: LangOptions opt1 ...
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_lang
Compatibility: 1.3.6rc1 and later

The `LangOptions` directive is used to configure various optional behavior of `mod_lang`.

Example:

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

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

### LangPath

Syntax: LangPath path
Default: None
Context: server config
Module: mod_lang
Compatibility: 1.3.1rc1

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/`.

The path parameter must be an absolute path.

Example:

      LangPath /etc/proftpd/locale

Example:

      LangPath /path/to/ftpd/locale

### UseEncoding

Syntax: UseEncoding on|off|local-charset client-charset
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_lang
Compatibility: 1.3.2rc1

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

      UseEncoding off

Similarly, to enable use of UTF8 encoding and to not allow clients to change the use of UTF8, you would use:

      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

With the above, a client could still request a switch from `koi8-r` encoding to UTF-8 via the `OPTS UTF8` command. If, however, you wished to prevent clients from changing the encoding to UTF-8, the above configuration would instead look like:

      LangOptions PreferServerEncoding
      UseEncoding koi8-r cp1251

For a full list of the character sets which are supported, use:

      $ iconv --list

## Installation

The `mod_lang` module is distributed with ProFTPD. To enable use of NLS (Natural Language Support) in your `proftpd` daemon, use the `--enable-nls` configure option:

      $ ./configure --enable-nls
      $ make
      $ make install

This option causes `mod_lang` to be compiled into `proftpd`.

## Usage

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>

The current list of character sets for which Telnet code support is disabled is listed below; the names are not case-sensitive:

- cp866
- cp1251
- iso-8859-1
- koi8-r
- windows-1251

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