You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by wr...@apache.org on 2007/12/05 02:14:33 UTC
svn commit: r601181 - /httpd/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml
Author: wrowe
Date: Tue Dec 4 17:14:32 2007
New Revision: 601181
URL: http://svn.apache.org/viewvc?rev=601181&view=rev
Log:
Overhaul mod_ftp docs; alphasort the directives, drop the "this
is inherited" garbage, clarify PASV and Range related directives,
and add FTPEPSVIgnoreFamily. More work needed, but this is a much
better starting poing.
Modified:
httpd/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml
Modified: httpd/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml
URL: http://svn.apache.org/viewvc/httpd/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml?rev=601181&r1=601180&r2=601181&view=diff
==============================================================================
--- httpd/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml (original)
+++ httpd/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml Tue Dec 4 17:14:32 2007
@@ -1,7 +1,6 @@
-<?xml version="1.0"?>
+<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -18,14 +17,12 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-
<!--
Original Copyright (c) Covalent Technologies 2001-2005
FTP Protocol module for Apache 2.0
-->
-
-<modulesynopsis metafile="mod_ftp.xml.meta" >
+<modulesynopsis metafile="mod_ftp.xml.meta">
<name>mod_ftp</name>
<description>Provides support for the File Transfer Protocol</description>
@@ -33,7 +30,7 @@
<sourcefile>mod_ftp.c</sourcefile>
<identifier>ftp_module</identifier>
<compatibility>Apache 2.3 and higher</compatibility>
-
+
<summary>
<p>This module provides support for the File Transfer Protocol
within the Apache HTTP Server. It was originally developed by
@@ -44,14 +41,14 @@
control modules, mod_ssl and any dynamic content generator to
provide veratile, scalable and secure FTP services.</p>
- <p>Further details, discussion and examples are provided in the <a
- href="../ftp/">FTP documentation</a>.</p>
+ <p>Further details, discussion and examples are provided in the
+ <a href="../ftp/">FTP documentation</a>.</p>
</summary>
<!-- References to other documents or directives -->
<seealso><a href="../ftp/">FTP Documentation</a></seealso>
<seealso><module>mod_ssl</module></seealso>
-
+
<directivesynopsis>
<name>FTP</name>
<description>Run an FTP Server on this host</description>
@@ -60,30 +57,98 @@
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <p>You must define a <directive>Listen</directive> directive to
- listen for FTP requests. This directive is <strong>not</strong>
- inherited from the global configuration file.</p>
+ <p>You must define a <directive>Listen</directive> directive to
+ listen for FTP requests.</p>
+ <note>This directive is <strong>not</strong> inherited from the
+ global configuration file.</note>
</usage>
</directivesynopsis>
-
+
<directivesynopsis>
- <name>FTPUmask</name>
- <description>Set the umask for created files</description>
- <syntax>FTPUmask <em>umask</em></syntax>
- <default>FTPUmask 022</default>
+ <name>FTPActiveRange</name>
+ <description>Ports the server will use for connecting to the
+ client</description>
+ <syntax>FTPActiveRange <em>min [max]</em></syntax>
+ <default>If this directive is not specified, the server will use
+ an arbitrary ephemeral high-numbered port</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <p>This directive sets the permission mask for file creation
- access. The default is 022 which gives the owner complete
- access and disables write access for the group and other
- users.</p>
- <note>This directive is inherited to all virtual
- hosts from the global configuration file.</note>
- <note>This directive is not supported on Windows.</note>
+ <p>This directive defines the port or ports that mod_ftp will
+ use when making an active connection to the client. It accepts
+ one or two arguments. If only one argument is given, the server
+ will always use that port. If two arguments are given, the
+ server will treat them as a range of ports to be used.</p>
+ <note>Use a sufficient range to satisfy all client requests! Between
+ the time that the client makes a data channel request following the
+ <code>PORT</code> or <code>EPRT</code> request, and the point at
+ which the server has connected to the client, the origin port
+ may be unavailable to any other client.</note>
+ <note>By default, the operating system will not allow the FTP server
+ to use privileged ports for active connections. If you specify a
+ port range below 1024 with FTPActiveRange, the server will fail
+ to satisfy the <code>PORT</code> or <code>EPRT</code> request!</note>
+ <example>
+ <p><code>FTPActiveRange 5050</code></p>
+ <p>Force the server to use port 5050</p>
+ <p><code>FTPActiveRange 5050 5080</code></p>
+ <p>Allow the server to use any port between 5050 and 5080,
+ inclusive.</p>
+ </example>
+ </usage>
+ </directivesynopsis>
+
+ <directivesynopsis>
+ <name>FTPBannerMessage</name>
+ <description>Set initial login message</description>
+ <syntax>FTPBannerMessage
+ <em>message</em>|<em>file:/path/to/file</em></syntax>
+ <default><em>none</em></default>
+ <contextlist><context>server config</context>
+ <context>virtual host</context></contextlist>
+ <usage>
+ <p>This directive sets a <em>message</em> that is displayed to
+ the client on initial connection. This can either be a string,
+ or a path to a file. The message can contain a variety of
+ meta-characters:</p>
+ <table>
+ <tr><th><code>%T</code></th><td>Local time (in the form
+ <code>Mon Apr 29 20:36:48 2002</code>)</td></tr>
+ <tr><th><code>%C</code></th><td>Current working directory</td></tr>
+ <tr><th><code>%h</code></th><td>Remote host</td></tr>
+ <tr><th><code>%L</code></th><td>Local host</td></tr>
+ <tr><th><code>%E</code></th><td>Server administrator (as given by
+ <directive module="core">ServerAdmin</directive>)</td></tr>
+ <tr><th><code>%a</code></th><td>Remote IP-address</td></tr>
+ <tr><th><code>%A</code></th><td>Local IP-address</td></tr>
+ <tr><th><code>%u</code></th><td>Remote user</td></tr>
+ <tr><th><code>%f</code></th><td>Number of files transferred</td></tr>
+ <tr><th><code>%t</code></th><td>Total bytes downloaded</td></tr>
+ <tr><th><code>%x</code></th><td>Number of data transfers</td></tr>
+ <tr><th><code>%b</code></th><td>Total traffic for the session (both
+ control and data)</td></tr>
+ </table>
</usage>
</directivesynopsis>
-
+
+ <directivesynopsis>
+ <name>FTPDataBlockSize</name>
+ <description>Block size in bytes between control channel tests</description>
+ <syntax>FTPDataBlockSize <em>bytes</em></syntax>
+ <default>48000 bytes</default>
+ <contextlist><context>server config</context>
+ <context>virtual host</context></contextlist>
+ <usage>
+ <p>When mod_ftp is transmitting data via the operating system,
+ it's not possible to monitor the control channel for <code>ABOR</code>
+ signals. FTPDataBlockSize partitions the transfer; between each block
+ mod_ftp will see if there is a pending control channel request, or if
+ the socket is ready to send more data, and proceed to the next block.
+ Based on anticipated bandwidth, set this value to a reasonable window
+ of time in which the server should answer the control channel.</p>
+ </usage>
+ </directivesynopsis>
+
<directivesynopsis>
<name>FTPDirUmask</name>
<description>Set the umask for created directory</description>
@@ -92,74 +157,99 @@
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <note>Not documented</note>
+ <p>This directive sets the permission mask for directory creation
+ access. The default is 022 which gives the owner complete
+ access and disables write access for the group and other
+ users.</p>
+ <note>This directive is not supported on Windows.</note>
</usage>
</directivesynopsis>
-
+
<directivesynopsis>
- <name>FTPTimeoutLogin</name>
- <description>Idle time allowed when logging in</description>
- <syntax>FTPTimeoutLogin <em>time</em></syntax>
- <default>FTPTimeoutLogin 60</default>
+ <name>FTPDocRootEnv</name>
+ <description>Set the DocumentRoot based on the given environment
+ variable, such as a per-user LDAP property</description>
+ <syntax>FTPDocRootEnv <em>envvar</em></syntax>
+ <default><em>unset</em></default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <p>This directive sets the amount of <em>time</em> in seconds
- that a user has to send a username to the server. If the
- username is not received in this amount of time, the user is
- disconnected.</p>
- <note>This directive is inherited to all virtual hosts from the
- global configuration file.</note>
+ <p>This directive will cause FTP to use the value of the
+ <code>envvar</code> environment variable in place of the
+ default <code>DocumentRoot</code>, if the environment variable
+ is defined. The <code>envvar</code> variable must contain a
+ full, rooted file path, e.g. <code>/some/path</code> on Unix
+ or <code>d:/some/path</code> on Windows.</p>
+ <p>This may be used with any authentication module which sets
+ the value of an environment variable based on the logged in
+ user or another condition (similar to <module>mod_env</module>
+ or <module>mod_setenvif</module> to change FTP's Document Root
+ on a per-user basis.</p>
+ <note>This directive is <strong>not</strong> inherited from the
+ global configuration file.</note>
</usage>
</directivesynopsis>
<directivesynopsis>
- <name>FTPTimeoutIdle</name>
- <description>Idle time allowed during a FTP session</description>
- <syntax>FTPTimeoutIdle <em>time</em></syntax>
- <default>FTPTimeoutIdle 600</default>
+ <name>FTPEPSVIgnoreFamily</name>
+ <description>Force EPSV to ignore the requested IP family
+ (IPv4 vs. IPv6)</description>
+ <syntax>FTPEPSVIgnoreFamily <em>On</em></syntax>
+ <default>Off</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <p>This directive sets the amount of <em>time</em> in seconds
- allowed between commands sent by the client. If no commands
- are received in this amount of time, the user is
- disconnected.</p>
- <note>This directive is inherited to all virtual hosts from the
- global configuration file.</note>
+ <p>This directive allows the client's <code>EPSV</code> request to bind
+ to the local address, ignoring IPv4 vs. IPv6 requested by the client,
+ in order to work around network address translation which presented
+ an apparently different family.
+ You may find this useful when the FTP Server is behind a firewall.</p>
+ <note>This directive is <strong>not</strong> inherited from the global
+ configuration file.</note>
</usage>
</directivesynopsis>
<directivesynopsis>
- <name>FTPTimeoutData</name>
- <description>Idle time allowed during a data transfer</description>
- <syntax>FTPTimeoutData <em>time</em></syntax>
- <default>FTPTimeoutData 300</default>
+ <name>FTPExitMessage</name>
+ <description>Set logout message</description>
+ <syntax>FTPExitMessage
+ <em>message</em>|<em>file:/path/to/file</em></syntax>
+ <default><em>none</em></default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
- <usage>
- <p>This directive sets the <em>time</em> in seconds the server
- will wait during a data transfer. If no data is sent to the
- client in this amount of time, the data connection is
- closed.</p>
- <note>This directive is inherited to all virtual hosts from the
- global configuration file.</note>
- </usage>
+ <usage><p>This directive sets a <em>message</em> that is displayed to
+ the client on disconnect. This can either be a string, or a
+ path to a file. The message can contain a variety of
+ meta-characters (see
+ <directive module="mod_ftp">FTPBannerMessage</directive>).</p>
+ </usage>
</directivesynopsis>
<directivesynopsis>
- <name>FTPMaxLoginAttempts</name>
- <description>Maximum number of login attempts</description>
- <syntax>FTPMaxLoginAttempts <em>attempts</em></syntax>
- <default>FTPMaxLoginAttempts 3</default>
+ <name>FTPHomeDir</name> <description>Set the path to directory
+ containing user's home directories</description>
+ <syntax>FTPHomeDir /directory</syntax>
+ <default><em>unset</em></default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
- <usage>
- <p>This directive controls the number of failed
- <em>attempts</em> to log in that are allowed before breaking
- the connection and logging the failed attempts.</p>
- <note>This directive is inherited to all virtual hosts from the
- global configuration file.</note>
+ <usage><p>This directive defines where the user home <em>directory</em>
+ is located. This directory must be given as an absolute path,
+ but is actually relative to the configured
+ <directive module="core">DocumentRoot</directive> for the server. For
+ example, <code>FTPHomeDir /home</code> will cause the Apache FTP
+ Server to look for the user home in the directory <directive
+ module="code">DocumentRoot</directive><code
+ >/home/</code><code>username</code>
+ (where <em>username</em> is the login name of the user).</p>
+ <p>If <directive>FTPHomeDir</directive> has been specified and
+ the home directory for the user does not exist, the server logs
+ an error and user is logged into the root
+ ("<code>/</code>") directory. If you want the home
+ directory created automatically, see the
+ <directive>CreateHomeDirs</directive> option to the
+ <directive module="mod_ftp">FTPOptions</directive> directive.</p>
+ <note>This directive is <strong>not</strong> inherited from the
+ global configuration file.</note>
</usage>
</directivesynopsis>
@@ -183,6 +273,109 @@
</directivesynopsis>
<directivesynopsis>
+ <name>FTPJailUser</name>
+ <description>Users are not allowed to leave their home
+ directories</description>
+ <syntax>FTPJailUser on|off</syntax>
+ <default>FTPJailUser off</default>
+ <contextlist><context>server config</context>
+ <context>virtual host</context></contextlist>
+ <usage>
+ <p>This directive confines the user to the directory tree in
+ which they were placed upon login. The user can access any
+ subdirectory of their default directory, but cannot access the
+ parent directory or any other related directories.</p>
+ <p>If the <directive module="mod_ftp">FTPHomeDir</directive>
+ directive is not used, then <directive>FTPJailUser</directive>
+ has no effect. This combination of directives can be very
+ powerful for restricting where in your filesystem users may
+ traverse.</p>
+ <note>This directive is <strong>not</strong> inherited from the
+ global configuration file.</note>
+ </usage>
+ </directivesynopsis>
+
+ <directivesynopsis>
+ <name>FTPLimitDBFile</name>
+ <description>Set the location for the Login Limit DB file</description>
+ <syntax>FTPLimitDBFile <em>file-path</em></syntax>
+ <default><em>unset</em></default>
+ <!-- FIXME This directive is allowed in RSRC_CONF??? -->
+ <contextlist><context>server config</context>
+ </contextlist>
+ <usage>
+ <p>To provide <directive module="mod_ftp">FTPLimitLoginUser</directive>
+ and <directive module="mod_ftp">FTPLimitLoginServer</directive>
+ features, mod_ftp uses a small DBM file to store login data. This
+ directive determines the filename-path of that database file.
+ If either <code>FTPLimit</code> directive is used, this directive
+ must specify a filename for this DBM, writeable by the server.</p>
+ <example><code>FTPLimitDBFile logs/ftplogins</code></example>
+ </usage>
+ </directivesynopsis>
+
+ <directivesynopsis>
+ <name>FTPLimitLoginIP</name>
+ <description>Set the maximum number of concurrent logins per IP
+ address</description>
+ <syntax></syntax>
+ <default></default>
+ <contextlist><context>server config</context>
+ <context>virtual host</context></contextlist>
+ <usage>
+ <note>Not documented</note>
+ </usage>
+ </directivesynopsis>
+
+ <directivesynopsis>
+ <name>FTPLimitLoginServer</name>
+ <description>Set the maximum number of concurrent logins per
+ server</description>
+ <syntax>FTPLimitLoginServer <em>number</em></syntax>
+ <default>FTPLimitLoginServer 0 (unlimited)</default>
+ <!-- FIXME This directive is allowed in RSRC_CONF??? -->
+ <contextlist><context>server config</context>
+ </contextlist>
+ <usage>
+ <p>This directive allows the administrator to limit the total
+ number of concurrent/simultaneous FTP logins. For example, if
+ set to 10, no more than 10 FTP logins would be allowed. The
+ default value is 0 (unlimited).</p>
+ </usage>
+ </directivesynopsis>
+
+ <directivesynopsis>
+ <name>FTPLimitLoginUser</name>
+ <description>Set the maximum number of concurrent logins per
+ user</description>
+ <syntax>FTPLimitLoginUser <em>number</em></syntax>
+ <default>FTPLimitLoginUser 0 (unlimited)</default>
+ <!-- FIXME This directive is allowed in RSRC_CONF??? -->
+ <contextlist><context>server config</context>
+ </contextlist>
+ <usage><p>This directive allows the administrator to limit the
+ number of concurrent/simultaneous logins of a single FTP user.
+ For example, if set to 3, then no single FTP account would be
+ allowed to have more than 3 concurrent logins (including the
+ guest/anonymous account). The default value is 0 (unlimited).</p>
+ </usage>
+ </directivesynopsis>
+
+ <directivesynopsis>
+ <name>FTPMaxLoginAttempts</name>
+ <description>Maximum number of login attempts</description>
+ <syntax>FTPMaxLoginAttempts <em>attempts</em></syntax>
+ <default>FTPMaxLoginAttempts 3</default>
+ <contextlist><context>server config</context>
+ <context>virtual host</context></contextlist>
+ <usage>
+ <p>This directive controls the number of failed
+ <em>attempts</em> to log in that are allowed before breaking
+ the connection and logging the failed attempts.</p>
+ </usage>
+ </directivesynopsis>
+
+ <directivesynopsis>
<name>FTPOptions</name>
<description>Set options for this server</description>
<syntax>FTPOptions <em>option1 [option2] ...</em></syntax>
@@ -209,15 +402,15 @@
accept queue until another client disconnects.</p>
</dd>
<dt><code>CreateHomeDirs</code></dt>
- <dd><p>This option causes the server to automatically create a
- home directory in the location specified by the
+ <dd><p>This option causes the server to automatically create a
+ home directory in the location specified by the
<directive module="mod_ftp">FTPHomeDir</directive> directive.
If the <directive module="mod_ftp">FTPHomeDir</directive>
directive is not specified, this option has no effect.</p>
<note><p>Setting this option on an anonymous site is not
recommended. This is because a directory is created for
each unique user (usually identified by their email
- address) that logs onto the server. </p>
+ address) that logs onto the server. </p>
<p>This option will only work if the <directive
module="mod_ftp">FTPHomeDir</directive> directories are
accessible to the process owner of the Apache HTTP Server,
@@ -242,7 +435,7 @@
<note><p>
Setting this option will cause commands that request
multiple files to fail and should be used with
- caution.</p>
+ caution.</p>
</note>
</dd>
<dt><code>NLSTisLIST</code></dt>
@@ -255,7 +448,7 @@
<note>
<p>Setting this option will cause commands that request
multiple files to fail and should be used with
- caution.</p>
+ caution.</p>
</note>
</dd>
<dt><code>LISTisNLST</code></dt>
@@ -265,7 +458,7 @@
<directive>NLSTisLIST</directive>, the output is a list of
files without details. If the -l option is passed to
<code>LIST</code> requests, details will be provided,
- whether this option is set or not.</p>
+ whether this option is set or not.</p>
</dd>
<dt><code>ShowUnAuthorizedFiles</code></dt>
<dd><p>This option causes
@@ -273,7 +466,7 @@
authorization to retrieve and directories that the user
does not have authorization to enter (<code>cd</code> will
fail) when it receives a <code>LIST</code> or similar
- <code>NLST</code> command. These commands will then behave
+ <code>NLST</code> command. These commands will then behave
as most standard FTP servers, where users see the list of
all files and directories, even those they are not allowed
to access.</p>
@@ -284,20 +477,23 @@
<directivesynopsis>
<name>FTPPASVaddr</name>
- <description>Set the allowed PASV server IP address for the data
- channel</description>
+ <description>Set the apparent server IP address for PASV data
+ channels</description>
<syntax>FTPPASVAddr <em>IP address</em></syntax>
- <!-- FIXME Find out what the code does -->
- <default>Unset</default>
+ <default>The server's actual IP address of the control channel
+ connection.</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <p>This directive allows you to specify a different <em>IP
- address</em> to be sent on replies to <code>PASV</code> requests.
- You will find this useful when the FTP Server is behind a
- firewall.</p>
+ <p>This directive allows you to specify a different <em>IP address</em>
+ to be presented to the client in response to <code>PASV</code>
+ requests. It has no effect on the IP address the server will
+ listen on, use <directive module="mod_ftp">FTPPASVbindaddr</directive>
+ instead to affect the IP address of the actual data connection.</p>
+ <p>You may find this useful when the FTP Server is behind a firewall.
+ It has <em>no</em> effect on <code>EPSV</code> requests.</p>
<note>This directive is <strong>not</strong> inherited from the global
- configuration file.</note>
+ configuration file.</note>
</usage>
</directivesynopsis>
@@ -306,215 +502,54 @@
<description>Set and bind the allowed PASV server IP address for
the data channel</description>
<syntax>FTPPASVbindaddr <em>IP address</em></syntax>
- <!-- FIXME Ditto FTPPASVaddr -->
- <default>Unset</default>
+ <default>The specified FTPPASVaddr, or in it's absense, the server's
+ actual IP address of the control channel connection.</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <p>This directive is identical to
- <directive module="mod_ftp">FTPPASVaddr</directive> except
- that the Apache FTP Server attempts to bind to the specified
- <em>IP address</em>.</p>
+ <p>This directive is similar to the
+ <directive module="mod_ftp">FTPPASVaddr</directive> directive,
+ except that the Apache FTP Server attempts to bind to the specified
+ <em>IP address</em>, and note that any
+ <directive module="mod_ftp">FTPPASVaddr</directive> directive
+ continues to override the address presented to the client.</p>
+ <p>You may find this useful when the FTP Server is behind a firewall.
+ It has <em>no</em> effect on <code>EPSV</code> requests.</p>
<note>This directive is <strong>not</strong> inherited from the
- global configuration file.</note>
+ global configuration file.</note>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>FTPPASVrange</name>
- <description>Set the allowed PASV port range</description>
+ <description>Set the allowed passive port range</description>
<syntax>FTPPASVrange <em>number number</em></syntax>
- <!-- FIXME Find out what the code does: this is probably the
- default behaviour when binding to an unspecified port, and will
- vary by platform and OS. -->
- <default>Unset</default>
- <contextlist><context>server config</context>
- <context>virtual host</context></contextlist>
- <usage>
- <p>This directive defines the port range (<em>number</em> to
- <em>number</em> inclusive) to be used for passive connections.
- This directive is designed for use in environments where you
- only want to open a specific range of ports on your
- firewall.</p>
- <note>This directive is inherited to all virtual hosts from the
- global configuration file.</note>
- </usage>
- </directivesynopsis>
-
- <directivesynopsis>
- <name>FTPBannerMessage</name>
- <description>Set initial login message</description>
- <syntax>FTPBannerMessage
- <em>message</em>|<em>file:/path/to/file</em></syntax>
- <default>Unset</default>
- <contextlist><context>server config</context>
- <context>virtual host</context></contextlist>
- <usage>
- <p>This directive sets a <em>message</em> that is displayed to
- the client on initial connection. This can either be a string,
- or a path to a file. The message can contain a variety of
- meta-characters:</p>
- <table>
- <tr><th><code>%T</code></th><td>Local time (in the form <code>Mon Apr 29
- 20:36:48 2002</code>)</td></tr>
- <tr><th><code>%C</code></th><td>Current working directory</td></tr>
- <tr><th><code>%h</code></th><td>Remote host</td></tr>
- <tr><th><code>%L</code></th><td>Local host</td></tr>
- <tr><th><code>%E</code></th><td>Server administrator (as given by
- <directive module="core">ServerAdmin</directive>)</td></tr>
- <tr><th><code>%a</code></th><td>Remote IP-address</td></tr>
- <tr><th><code>%A</code></th><td>Local IP-address</td></tr>
- <tr><th><code>%u</code></th><td>Remote user</td></tr>
- <tr><th><code>%f</code></th><td>Number of files transferred</td></tr>
- <tr><th><code>%t</code></th><td>Total number of bytes downloaded</td></tr>
- <tr><th><code>%x</code></th><td>Number of data transfers</td></tr>
- <tr><th><code>%b</code></th><td>Total traffic for the session (both
- control and data)</td></tr>
- </table>
- <note>This directive is inherited to all virtual hosts from the
- global configuration file.</note>
- </usage>
- </directivesynopsis>
-
- <directivesynopsis>
- <name>FTPExitMessage</name>
- <description>Set logout message</description>
- <syntax>FTPExitMessage
- <em>message</em>|<em>file:/path/to/file</em></syntax>
- <default></default>
- <contextlist><context>server config</context>
- <context>virtual host</context></contextlist>
- <usage><p>This directive sets a <em>message</em> that is displayed to
- the client on disconnect. This can either be a string, or a
- path to a file. The message can contain a variety of
- meta-characters (see
- <directive module="mod_ftp">FTPBannerMessage</directive>).</p>
- <note>This directive is inherited to all virtual hosts from the
- global configuration file.</note>
- </usage>
- </directivesynopsis>
-
- <directivesynopsis>
- <name>FTPHomeDir</name> <description>Set the path to directory
- containing user's home directories</description>
- <syntax>FTPHomeDir /directory</syntax>
- <default>Unset</default>
- <contextlist><context>server config</context>
- <context>virtual host</context></contextlist>
- <usage><p>This directive defines where the user home <em>directory</em>
- is located. This directory must be given as an absolute path,
- but is actually relative to the configured
- <directive module="core">DocumentRoot</directive> for the server. For
- example, <code>FTPHomeDir /home</code> will cause the Apache FTP
- Server to look for the user home in the directory <directive
- module="code">DocumentRoot</directive><code>/home/</code><code>username</code>
- (where <em>username</em> is the login name of the user).</p>
- <p>If <directive>FTPHomeDir</directive> has been specified and
- the home directory for the user does not exist, the server logs
- an error and user is logged into the root
- ("<code>/</code>") directory. If you want the home
- directory created automatically, see the
- <directive>CreateHomeDirs</directive> option to the
- <directive module="mod_ftp">FTPOptions</directive> directive.</p>
- </usage>
- <note>This directive is <strong>not</strong> inherited from the
- global configuration file.</note>
- </directivesynopsis>
-
- <directivesynopsis>
- <name>FTPDocRootEnv</name>
- <description>Set the DocumentRoot based on the given environment
- variable, such as a per-user LDAP property</description>
- <syntax>FTPDocRootEnv <em>envvar</em></syntax>
- <default>Unset</default>
- <contextlist><context>server config</context>
- <context>virtual host</context></contextlist>
- <usage>
- <p>This directive will cause FTP to use the value of the
- <code>envvar</code> environment variable in place of the
- default <code>DocumentRoot</code>, if the environment variable
- is defined. The <code>envvar</code> variable must contain a
- full, rooted file path, e.g. <code>/some/path</code> on Unix
- or <code>d:/some/path</code> on Windows.</p>
- <p>This may be used with any authentication module which sets
- the value of an environment variable based on the logged in
- user or another condition (similar to <module>mod_env</module>
- or <module>mod_setenvif</module> to change FTP's Document Root
- on a per-user basis.</p>
- </usage>
- </directivesynopsis>
-
- <directivesynopsis>
- <name>FTPJailUser</name>
- <description>Users are not allowed to leave their home
- directories</description>
- <syntax>FTPJailUser on|off</syntax>
- <default>FTPJailUser off</default>
- <contextlist><context>server config</context>
- <context>virtual host</context></contextlist>
- <usage>
- <p>This directive confines the user to the directory tree in
- which they were placed upon login. The user can access any
- subdirectory of their default directory, but cannot access the
- parent directory or any other related directories.</p>
- <p>If the <directive module="mod_ftp">FTPHomeDir</directive>
- directive is not used, then <directive>FTPJailUser</directive>
- has no effect. This combination of directives can be very
- powerful for restricting where in your filesystem users may
- traverse.</p>
- <note>This directive is <strong>not</strong> inherited from the
- global configuration file.</note>
- </usage>
- </directivesynopsis>
-
- <directivesynopsis>
- <name>FTPActiveRange</name>
- <description>Ports the server will use for connecting to the
- client</description>
- <syntax>FTPActiveRange <em>min [max]</em></syntax>
<default>If this directive is not specified, the server will use
- random high-numbered ports</default>
+ an arbitrary ephemeral high-numbered port</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <p>This directive defines the port or ports that mod_ftp will
- use when making an active connection to the client. It accepts
- one or two arguments. If only one argument is given, the server
- will always use that port. If two arguments are given, the
- server will treat them as a range of ports to be used.</p>
-
- <note><p>By default, Apache will not allow the FTP server to use
- privileged ports for active connections. If you specify a
- port range under 1024 in FTPActiveRange, the server will
- default to a random high-level port instead.
- <!-- FIXME I don't think that code is currently even in there
- To solve this problem, you must add the following directive
- to your config file:</p>
- <p><code>AllowSwitchToRoot On</code></p>
- <p>Adding this directive will allow any module to switch the
- Apache child process back to root, which can be a security
- issue. Only use this directive if you are certain that your
- modules will not misuse this ability.--></p>
- </note>
- <example>
- <p><code>FTPActiveRange 5050</code></p>
- <p>Force the server to use port 5050</p>
- <p><code>FTPActiveRange 5050 5080</code></p>
- <p>Allow the server to use any port between 5050 and 5080,
- inclusive.</p>
- </example>
- <note>This directive is inherited to all virtual hosts from
- the global configuration file.</note>
+ <p>This directive defines the port range (<em>number</em> to
+ <em>number</em> inclusive) to be used for all passive connections,
+ including <code>PASV</code> and <code>EPSV</code> requests.
+ This directive is designed for use in environments where you
+ only want to open a specific range of ports on your
+ firewall.</p>
+ <note>Use a sufficient range to satisfy all client requests!
+ Between the time that the server answers a <code>PASV</code>
+ or <code>EPSV</code> request, and the point at which the client
+ connects to the indiciated port, that specific port is
+ unavailable to any other client.</note>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>FTPReadmeMessage</name>
<description>Set per-directory Readme file</description>
- <syntax>FTPReadmeMessage
+ <syntax>FTPReadmeMessage
<em>message</em>|<em>file:/path/to/file</em>
</syntax>
- <default>Unset</default>
+ <default><em>none</em></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
@@ -525,95 +560,77 @@
to the client upon entering a new directory. This can either
be a string, or a path to a file. The message can contain a
variety of meta-characters (see <directive
- module="mod_ftp">FTPBannerMessage</directive>).</p>
+ module="mod_ftp">FTPBannerMessage</directive>).</p>
<p>When this directive is placed in the <directive module="core"
type="section">VirtualHost</directive> container, the README
message will apply to all directories. When it is used in a
<directive module="core" type="section">Directory</directive>
container or placed in an <code>.htaccess</code> file, only
- that directory will inherit the README message.</p>
+ that directory will inherit the README message.</p>
<p>Configuring a README message for a directory will also override any
global README messages.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
- <name>FTPLimitLoginUser</name>
- <description>Set the maximum number of concurrent logins per
- user</description>
- <syntax>FTPLimitLoginUser <em>number</em></syntax>
- <default>FTPLimitLoginUser 0 (unlimited)</default>
- <!-- FIXME This directive is allowed in RSRC_CONF??? -->
- <contextlist><context>server config</context>
- </contextlist>
- <usage><p>This directive allows the administrator to limit the
- number of concurrent/simultaneous logins of a single FTP user.
- For example, if set to 3, then no single FTP account would be
- allowed to have more than 3 concurrent logins (including the
- guest/anonymous account). The default value is 0 (unlimited).</p>
- </usage>
- </directivesynopsis>
-
- <directivesynopsis>
- <name>FTPLimitLoginIP</name>
- <description>Set the maximum number of concurrent logins per IP
- address</description>
- <syntax></syntax>
- <default></default>
+ <name>FTPTimeoutData</name>
+ <description>Idle time allowed during a data transfer</description>
+ <syntax>FTPTimeoutData <em>time</em></syntax>
+ <default>FTPTimeoutData 300</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <note>Not documented</note>
- </usage>
+ <p>This directive sets the <em>time</em> in seconds the server
+ will wait during a data transfer. If no data is sent to the
+ client in this amount of time, the data connection is
+ closed.</p>
+ </usage>
</directivesynopsis>
<directivesynopsis>
- <name>FTPLimitLoginServer</name>
- <description>Set the maximum number of concurrent logins per
- server</description>
- <syntax>FTPLimitLoginServer <em>number</em></syntax>
- <default>FTPLimitLoginServer 0 (unlimited)</default>
- <!-- FIXME This directive is allowed in RSRC_CONF??? -->
+ <name>FTPTimeoutIdle</name>
+ <description>Idle time allowed during a FTP session</description>
+ <syntax>FTPTimeoutIdle <em>time</em></syntax>
+ <default>FTPTimeoutIdle 600</default>
<contextlist><context>server config</context>
- </contextlist>
+ <context>virtual host</context></contextlist>
<usage>
- <p>This directive allows the administrator to limit the total
- number of concurrent/simultaneous FTP logins. For example, if
- set to 10, no more than 10 FTP logins would be allowed. The
- default value is 0 (unlimited).</p>
+ <p>This directive sets the amount of <em>time</em> in seconds
+ allowed between commands sent by the client. If no commands
+ are received in this amount of time, the user is
+ disconnected.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
- <name>FTPLimitDBFile</name>
- <description>Set the location for the Login Limit DB file</description>
- <syntax>FTPLimitDBFile <em>file-path</em></syntax>
- <default>Unset</default>
- <!-- FIXME This directive is allowed in RSRC_CONF??? -->
+ <name>FTPTimeoutLogin</name>
+ <description>Idle time allowed when logging in</description>
+ <syntax>FTPTimeoutLogin <em>time</em></syntax>
+ <default>FTPTimeoutLogin 60</default>
<contextlist><context>server config</context>
- </contextlist>
+ <context>virtual host</context></contextlist>
<usage>
- <p>To provide <directive module="mod_ftp">FTPLimitLoginUser</directive>
- and <directive module="mod_ftp">FTPLimitLoginServer</directive>
- features, mod_ftp uses a small DBM file to store login data. This
- directive determines the filename-path of that database file.
- If either <code>FTPLimit</code> directive is used, this directive
- must specify a filename for this DBM, writeable by the server.</p>
- <example><code>FTPLimitDBFile logs/ftplogins</code></example>
- </usage>
+ <p>This directive sets the amount of <em>time</em> in seconds
+ that a user has to send a username to the server. If the
+ username is not received in this amount of time, the user is
+ disconnected.</p>
+ </usage>
</directivesynopsis>
<directivesynopsis>
- <name>FTPDataBlockSize</name>
- <description>Block size in bytes to use during data transfers</description>
- <syntax></syntax>
- <default></default>
+ <name>FTPUmask</name>
+ <description>Set the umask for created files</description>
+ <syntax>FTPUmask <em>umask</em></syntax>
+ <default>FTPUmask 022</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
- <note>Not documented</note>
+ <p>This directive sets the permission mask for file creation
+ access. The default is 022 which gives the owner complete
+ access and disables write access for the group and other
+ users.</p>
+ <note>This directive is not supported on Windows.</note>
</usage>
</directivesynopsis>
-
+
</modulesynopsis>
-