source: src/router/proftpd/doc/modules/mod_lang.html @ 17876

Last change on this file since 17876 was 17876, checked in by BrainSlayer, 20 months ago

update proftp
File size: 8.8 KB
Line 
1<!-- $Id: mod_lang.html,v 1.8 2010/08/10 17:39:08 castaglia Exp $ -->
2<!-- $Source: /cvsroot/proftp/proftpd/doc/modules/mod_lang.html,v $ -->
3
4<html>
5<head>
6<title>ProFTPD module mod_lang</title>
7</head>
8
9<body bgcolor=white>
10
11<hr>
12<center>
13<h2><b>ProFTPD module <code>mod_lang</code></b></h2>
14</center>
15<hr><br>
16
17<p>
18<b>Internalization and Localization</b><br>
19The <code>mod_lang</code> module is ProFTPD's module for handling the LANG
20and OPTS UTF8 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
21sets other than UTF8, for those sites which do not require RFC2640 support, but
22<i>do</i> use character sets other than ASCII.  This module is contained in the
23<code>mod_lang.c</code> file for ProFTPD 1.3.<i>x</i>, and is compiled in
24whenever the <code>--enable-nls</code> configure option is used.  Installation
25instructions are discussed <a href="#Installation">here</a>.  Examples
26of using <code>mod_lang</code> for various encodings and character sets can
27be seen <a href="#Usage">here</a>.
28
29<p>
30The most current version of <code>mod_lang</code> can be found in the
31ProFTPD source distribution:
32<pre>
33  <a href="http://www.proftpd.org/">http://www.proftpd.org/</a>
34</pre>
35
36<h2>Directives</h2>
37<ul>
38  <li><a href="#LangDefault">LangDefault</a>
39  <li><a href="#LangEngine">LangEngine</a>
40  <li><a href="#LangPath">LangPath</a>
41  <li><a href="#UseEncoding">UseEncoding</a>
42</ul>
43
44<p>
45<hr>
46<h2><a name="LangDefault">LangDefault</a></h2>
47<strong>Syntax:</strong> LangDefault <em>language</em><br>
48<strong>Default:</strong> LangDefault en_US<br>
49<strong>Context:</strong> &quot;server config&quot;, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code><br>
50<strong>Module:</strong> mod_lang<br>
51<strong>Compatibility:</strong> 1.3.1rc1
52
53<p>
54The <code>LangDefault</code> directive is used to specify the default
55language of specific server configuration.  Note that the specified language
56must be listed in the output from:
57<pre>
58  $ locale -a
59</pre>
60
61<p>
62Example:
63<pre>
64  &lt;IfModule mod_lang.c&gt;
65    # Set the default to be Italian
66    LangDefault it_IT
67  &lt;/IfModule&gt;
68</pre>
69
70<p>
71<hr>
72<h2><a name="LangEngine">LangEngine</a></h2>
73<strong>Syntax:</strong> LangEngine <em>on|off</em><br>
74<strong>Default:</strong> LangEngine on<br>
75<strong>Context:</strong> &quot;server config&quot;, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code><br>
76<strong>Module:</strong> mod_lang<br>
77<strong>Compatibility:</strong> 1.3.1rc1
78
79<p>
80The <code>LangEngine</code> directive enables or disables the module's
81handling of the LANG command.  If it is set to <em>off</em> this module does no
82localization of responses.
83
84<p>
85<b>Note</b> that setting <code>LangEngine</code> to <em>off</em> also keeps
86<code>proftpd</code> from advertisting "UTF8" in its <code>FEAT</code> response.
87As required by RFC 2640, <code>proftpd</code> can <i>only</i> show "UTF8"
88in response to a <code>FEAT</code> command if the <code>LANG</code> command
89is also supported.  Hence why it is the <code>LangEngine</code> directive,
90and not <code>UseUTF8</code>, which controls the appearance of "UTF8".
91
92<p>
93<hr>
94<h2><a name="LangPath">LangPath</a></h2>
95<strong>Syntax:</strong> LangPath <em>path</em><br>
96<strong>Default:</strong> None<br>
97<strong>Context:</strong> &quot;server config&quot;<br>
98<strong>Module:</strong> mod_lang<br>
99<strong>Compatibility:</strong> 1.3.1rc1
100
101<p>
102The <code>LangPath</code> directive is used to configure an alternative
103directory from which <code>mod_lang</code> will load locale files.  By
104default, <code>mod_lang</code> uses <em>$prefix</em>/<code>locale/</code>,
105where <em>$prefix</em> is where you installed <code>proftpd</code>,
106<i>e.g.</i> <code>/usr/local/</code>.
107
108<p>
109The <em>path</em> parameter must be an absolute path.
110
111<p>
112Example:
113<pre>
114  LangPath /etc/proftpd/locale
115</pre>
116
117<p>
118Example:
119<pre>
120  LangPath /path/to/ftpd/locale
121</pre>
122
123<p>
124<hr>
125<h2><a name="UseEncoding">UseEncoding</a></h2>
126<strong>Syntax:</strong> UseEncoding <em>on|off|local-charset client-charset</em><br>
127<strong>Default:</strong> None<br>
128<strong>Context:</strong> &quot;server config&quot;, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code><br>
129<strong>Module:</strong> mod_lang<br>
130<strong>Compatibility:</strong> 1.3.2rc1
131
132<p>
133The <code>UseEncoding</code> directive is used to explicitly configure which
134character sets should be used for encoding.  By default, the
135<code>mod_lang</code> will automatically discover the local character set,
136and will use UTF8 for the client character set.  The module will also allow
137the use of UTF8 encoding to be changed by clients using the OPTS UTF8 command
138(as per RFC2640).  However, if the <code>UseEncoding</code> directive is
139explicitly used to indicate the character sets to use (or not use), then any
140OPTS UTF8 commands used by clients will be refused.
141
142<p>
143For example, to disable all use of encoding, use the following in your
144<code>proftpd.conf</code>:
145<pre>
146  UseEncoding off
147</pre>
148Similarly, to enable use of UTF8 encoding and to <i>not</i> allow clients
149to change the use of UTF8, you would use:
150<pre>
151  UseEncoding on
152</pre>
153
154<p>
155In addition to the <em>on|off</em> parameters, the <code>UseEncoding</code>
156directive allows administrators to specify exactly which character sets
157to use locally (<i>i.e.</i> for paths on local disks) and for dealing with
158clients.  One such usage this way might look like:
159<pre>
160  UseEncoding koi8-r cp1251
161</pre>
162For a full list of the character sets which are supported, use:
163<pre>
164  $ iconv --list
165</pre>
166
167<p>
168<hr>
169<h2><a name="Installation">Installation</a></h2>
170The <code>mod_lang</code> module is distributed with ProFTPD.  To enable use
171of NLS (Natural Language Support) in your <code>proftpd</code> daemon, use the
172<code>--enable-nls</code> configure option:
173<pre>
174  ./configure --enable-nls
175  make
176  make install
177</pre>
178This option causes <code>mod_lang</code> to be compiled into
179<code>proftpd</code>.
180
181<p>
182<hr>
183<h2><a name="Usage">Usage</a></h2>
184
185<p>
186One common request of <code>proftpd</code> is to properly handle Cyrillic
187characters in file and directory names.  The usual character sets which
188contain Cyrillic characters use the same codes as used for Telnet
189control codes, unfortunately.  RFC959 (which defines FTP) mandates that the
190Telnet control codes be supported in FTP implementations.
191
192<p>
193The <code>mod_lang</code> module, however, can be used to deal with this
194situation.  <b><i>If</i></b> the <a href="#UseEncoding">UseEncoding</code></a>
195directive is used to translate between local and client character sets,
196<i>and</i> the client character set is one of the known Cyrillic character
197sets, then <code>proftpd</code> will disable support of the Telnet control
198codes.
199
200<p>
201To make a long explanation short, if you want to use Cyrillic characters
202in paths with <code>proftpd</code>, compile your <code>proftpd</code>
203using the <code>--enable-nls</code> configure option (to enable the use
204of <code>mod_lang</code>), then use something like the following in your
205<code>proftpd.conf</code>:
206<pre>
207  &lt;IfModule mod_lang.c&gt;
208    UseEncoding utf8 cp1251
209  &lt;/IfModule&gt;
210</pre>
211The current list of character sets for which Telnet code support is disabled
212is listed below; the names are <b>not</b> case-sensitive:
213<ul>
214  <li>cp866
215  <li>cp1251
216  <li>iso-8859-1
217  <li>koi8-r
218  <li>windows-1251
219</ul>
220
221<p><a name="FAQ"></a>
222<b>Frequently Asked Questions</b><br>
223
224<p><a name="SpecialCharacters">
225<font color=red>Question</font>: When I upload a file with special characters
226(<i>e.g.</i> umlauts, accents, cedillas, <i>etc</i>), the special characters
227are turned into '?' on the server.  What's wrong?<br>
228<font color=blue>Answer</font>: There are a couple of things to check when
229this happens.
230
231<p>
232First, make sure that your <code>proftpd</code> has been compiled with NLS
233support.  Type <code>proftpd -V</code>, and make sure you see:
234<pre>
235  + NLS support
236</pre>
237appear in the output.
238
239<p>
240Next, make sure that the <code>LANG</code> environment variable is set before
241starting the server.  Special characters require that UTF8 or ISO-8859-1 be
242used, thus you might use things like:
243<pre>
244  # export LANG=de_DE.utf8
245  # export LANG=fr_FR.ISO8859-1
246</pre>
247
248<p>
249Last, check that any routers/firewalls/NAT between the clients and the server
250are not interfering.  ProFTPD lists "UTF8" in its <code>FEAT</code> response
251data; many FTP clients use the <code>OPTS UTF8 ON</code> command to inform the
252server that UTF8 filenames will be sent.  Some routers, firewalls, and NATs
253have been known to filter both the <code>FEAT</code> response and/or block
254commands like <code>OPTS UTF8</code>, thus interfering with the protocol and
255causing encoding problems.
256
257<p>
258<hr><br>
259Author: <i>$Author: castaglia $</i><br>
260Last Updated: <i>$Date: 2010/08/10 17:39:08 $</i><br>
261<br><hr>
262
263<font size=2><b><i>
264&copy; Copyright 2006-2010 TJ Saunders<br>
265 All Rights Reserved<br>
266</i></b></font>
267
268<hr><br>
269
270</body>
271</html>
272
Note: See TracBrowser for help on using the repository browser.