trAvis - MANAGER

Edit File: mod_lang.html

<html>
<head>
<title>ProFTPD module mod_lang</title>
</head>

<hr>
<center>
<h2>ProFTPD module <code>mod_lang</code></h2>
</center>
<hr>

Internalization and Localization 
The <code>mod_lang</code> module is ProFTPD's module for handling the
<code>LANG</code> and <code>OPTS UTF8</code> commands, in support of
<a href="http://www.faqs.org/rfcs/rfc2640.html">RFC 2640</a>. The
<code>mod_lang</code> 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
<code>mod_lang.c</code> file for ProFTPD 1.3.x, and is compiled in
whenever the <code>--enable-nls</code> configure option is used. Installation
instructions are discussed <a href="#Installation">here</a>. Examples
of using <code>mod_lang</code> for various encodings and character sets can
be seen <a href="#Usage">here</a>.

The most current version of <code>mod_lang</code> can be found in the
ProFTPD source distribution:
<pre>
 <a href="http://www.proftpd.org/">http://www.proftpd.org/</a>
</pre>

<h2>Directives</h2>
<ul>
 <li><a href="#LangDefault">LangDefault</a>
 <li><a href="#LangEngine">LangEngine</a>
 <li><a href="#LangPath">LangPath</a>
 <li><a href="#UseEncoding">UseEncoding</a>
</ul>

<hr>
<h2><a name="LangDefault">LangDefault</a></h2>
Syntax: LangDefault language 
Default: LangDefault en_US 
Context: &quot;server config&quot;, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_lang 
Compatibility: 1.3.1rc1

The <code>LangDefault</code> directive is used to specify the default
language of specific server configuration. Note that the specified language
must be listed in the output from:
<pre>
 $ locale -a
</pre>

Example:
<pre>
 &lt;IfModule mod_lang.c&gt;
 # Set the default to be Italian
 LangDefault it_IT
 &lt;/IfModule&gt;
</pre>

<hr>
<h2><a name="LangEngine">LangEngine</a></h2>
Syntax: LangEngine on|off 
Default: LangEngine on 
Context: &quot;server config&quot;, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_lang 
Compatibility: 1.3.1rc1

The <code>LangEngine</code> directive enables or disables the module's
handling of the <code>LANG</code> command. If it is set to off this
module does no localization of responses.

Note that setting <code>LangEngine</code> to off also keeps
<code>proftpd</code> from advertisting "UTF8" in its <code>FEAT</code> response.
As required by RFC 2640, <code>proftpd</code> can only show "UTF8"
in response to a <code>FEAT</code> command if the <code>LANG</code> command
is also supported. Hence why it is the <code>LangEngine</code> directive,
and not <code>UseUTF8</code>, which controls the appearance of "UTF8".

<hr>
<h2><a name="LangPath">LangPath</a></h2>
Syntax: LangPath path 
Default: None 
Context: &quot;server config&quot; 
Module: mod_lang 
Compatibility: 1.3.1rc1

The <code>LangPath</code> directive is used to configure an alternative
directory from which <code>mod_lang</code> will load locale files. By
default, <code>mod_lang</code> uses $prefix/<code>locale/</code>,
where $prefix is where you installed <code>proftpd</code>,
e.g. <code>/usr/local/</code>.

The path parameter must be an absolute path.

Example:
<pre>
 LangPath /etc/proftpd/locale
</pre>

Example:
<pre>
 LangPath /path/to/ftpd/locale
</pre>

<hr>
<h2><a name="UseEncoding">UseEncoding</a></h2>
Syntax: UseEncoding on|off|local-charset client-charset [&quot;strict&quot;] 
Default: None 
Context: &quot;server config&quot;, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_lang 
Compatibility: 1.3.2rc1

The <code>UseEncoding</code> directive is used to explicitly configure which
character sets should be used for encoding. By default, the
<code>mod_lang</code> 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
<code>OPTS UTF8</code> command (as per RFC 2640). However, if the
<code>UseEncoding</code> directive is explicitly used to indicate the character
sets to use (or not use) and the &quot;strict&quot; keyword
is used, then any OPTS UTF8 commands used by clients will be refused.

For example, to disable all use of encoding, use the following in your
<code>proftpd.conf</code>:
<pre>
 UseEncoding off
</pre>
Similarly, to enable use of UTF8 encoding and to not allow clients
to change the use of UTF8, you would use:
<pre>
 UseEncoding on
</pre>

In addition to the on|off parameters, the <code>UseEncoding</code>
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:
<pre>
 UseEncoding koi8-r cp1251
</pre>
With the above, a client could still request a switch from <code>koi8-r</code>
encoding to UTF-8 via the <code>OPTS UTF8</code> command. If, however, you
wished to prevent clients from changing the encoding to UTF-8, the above
configuration would instead look like:
<pre>
 UseEncoding koi8-r cp1251 strict
</pre>

For a full list of the character sets which are supported, use:
<pre>
 $ iconv --list
</pre>

<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_lang</code> module is distributed with ProFTPD. To enable use
of NLS (Natural Language Support) in your <code>proftpd</code> daemon, use the
<code>--enable-nls</code> configure option:
<pre>
 ./configure --enable-nls
 make
 make install
</pre>
This option causes <code>mod_lang</code> to be compiled into
<code>proftpd</code>.

<hr>
<h2><a name="Usage">Usage</a></h2>

One common request of <code>proftpd</code> 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.
<a href="http://www.faqs.org/rfcs/rfc959.html">RFC 959</a> (which defines FTP)
mandates that the Telnet control codes be supported in FTP implementations.

The <code>mod_lang</code> module, however, can be used to deal with this
situation. If the <a href="#UseEncoding">UseEncoding</code></a>
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 <code>proftpd</code> will disable support of the Telnet control
codes.

To make a long explanation short, if you want to use Cyrillic characters
in paths with <code>proftpd</code>, compile your <code>proftpd</code>
using the <code>--enable-nls</code> configure option (to enable the use
of <code>mod_lang</code>), then use something like the following in your
<code>proftpd.conf</code>:
<pre>
 &lt;IfModule mod_lang.c&gt;
 UseEncoding utf8 cp1251
 &lt;/IfModule&gt;
</pre>
The current list of character sets for which Telnet code support is disabled
is listed below; the names are not case-sensitive:
<ul>
 <li>cp866
 <li>cp1251
 <li>iso-8859-1
 <li>koi8-r
 <li>windows-1251
</ul>

<a name="FAQ"></a>
Frequently Asked Questions

<a name="Translations">
Question: What translations for proftpd currently exist? 
Answer: ProFTPD has currently been translated into:
<ul>
 <li>bg_BG
 <li>en_US
 <li>es_ES
 <li>fr_FR
 <li>it_IT
 <li>ja_JP
 <li>ko_KR
 <li>ru_RU
 <li>zh_CN
 <li>zh_TW
</ul>
If you are interested in providing more translations, please read this
<a href="../howto/Translations.html">howto</a>.

<a name="SpecialCharacters">
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 <code>proftpd</code> has been compiled with NLS
support. Type <code>proftpd -V</code>, and make sure you see:
<pre>
 + NLS support
</pre>
appear in the output.

Next, make sure that the <code>LANG</code> 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:
<pre>
 # export LANG=de_DE.utf8
 # export LANG=fr_FR.ISO8859-1
</pre>

Last, check that any routers/firewalls/NAT between the clients and the server
are not interfering. ProFTPD lists "UTF8" in its <code>FEAT</code> response
data; many FTP clients use the <code>OPTS UTF8 ON</code> command to inform the
server that UTF8 filenames will be sent. Some routers, firewalls, and NATs
have been known to filter both the <code>FEAT</code> response and/or block
commands like <code>OPTS UTF8</code>, thus interfering with the protocol and
causing encoding problems.

<a name="UnsupportedLanguage">
Question: I have configured my <code>mod_lang</code>
module to use a language, but when I start <code>proftpd</code>, I see an
error like this:
<pre>
 mod_lang/0.9: LangDefault 'language', configured for server 'serverName', is not a supported language, removing
</pre>
Answer: This usually happens for one of two reasons:
<ul>
 <li>The configured language is not listed in <code>`setlocale -a'</code>
 <li>The configured language is not one of the <a href="#Translations">supported translations</a>
</ul>
Both of these conditions must be true, otherwise you will see the
"not a supported language" error.

<hr> 
Author: $Author: castaglia $ 
Last Updated: $Date: 2012-10-10 01:26:33 $ 
 <hr>

<hr>

</body>
</html>