incubator-mod_ftp-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scte...@apache.org
Subject svn commit: r475411 - /incubator/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml
Date Wed, 15 Nov 2006 20:40:52 GMT
Author: sctemme
Date: Wed Nov 15 12:40:52 2006
New Revision: 475411

URL: http://svn.apache.org/viewvc?view=rev&rev=475411
Log:
Complete migration of directive documentation. There are several FIXMEs 
throughout the document, mostly stuff that has to be reconciled with what
the actual code does. Three directives have not been documented by Covalent. 
While it's easy enough to add language for those, I want to have the straight
migration in first. 

Finally, I don't know whether we need to have all those notes about 
inheritance. If I recall correctly, those were put in at specific request
when we developed the module and its documentation, but we can probably
lose the notes wherever the principle of least surprise is not violated.

Modified:
    incubator/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml

Modified: incubator/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml
URL: http://svn.apache.org/viewvc/incubator/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml?view=diff&rev=475411&r1=475410&r2=475411
==============================================================================
--- incubator/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml (original)
+++ incubator/mod_ftp/trunk/docs/manual/mod/mod_ftp.xml Wed Nov 15 12:40:52 2006
@@ -52,23 +52,6 @@
   <seealso><a href="../ftp/">FTP Documentation</a></seealso>
   <seealso><module>mod_ssl</module></seealso>
   
-  <!-- Any number of sections may be included below -->
-  <section id="moredocs"><title>Additional Documentation</title>
-    
-    <p>More detailed information about the module in general (as
-      opposed to the individual directives) can follow in sections
-      containing titles.</p>
-
-    <p>The <code>id</code> attribute will be translated into a hypertext
-      anchor target.</p>
-
-    <p>References to directives should use the directive tag:
-      <directive module="mod_template">TemplateDirective</directive>.
-      References to modules should use the module tag
-      <module>mod_template.xml</module>.</p>
-    
-  </section>
-  
   <directivesynopsis>
     <name>FTP</name>
     <description>Run an FTP Server on this host</description>
@@ -226,21 +209,20 @@
 	    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
-	    <directive>FTPHomeDir</directive> directive.  If the
-	    <directive>FTPHomeDir</directive> directive is not
-	    specified, this option has no effect.</p> 
+	<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> 
-	    <p>This option will only work if the
-	    <directive>FTPHomeDir</directive> directories are
-	      accessible to the process owner of the Apache HTTP
-	    Server, typically on UNIX systems the user
-	    <code>nobody</code>.</p>
+	      recommended.  This is because a directory is created for
+	      each unique user (usually identified by their email
+	      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,
+	      typically on UNIX systems the user
+	      <code>nobody</code>.</p>
 	  </note>
 	</dd>
 	<dt><code>RemoveUserGroup</code></dt>
@@ -330,9 +312,9 @@
       <context>virtual host</context></contextlist>
     <usage>
       <p>This directive is identical to
-	<directive>FTPPASVaddr</directive> except that the Apache FTP
-	Server attempts to bind to the specified 
-	<em>IP address</em>.</p>
+	<directive module="mod_ftp">FTPPASVaddr</directive> except
+	that the Apache FTP Server attempts to bind to the specified
+	<em>IP address</em>.</p> 
       <note>This directive is <strong>not</strong> inherited from the
 	global configuration file.</note> 
     </usage>
@@ -371,24 +353,24 @@
       <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> 
-      <ul>
-	<li><code>%T</code><p>Local time (in the form <code>Mon Apr
29
-	      20:36:48 2002</code>)</p></li>
-	<li><code>%C</code><p>Current working directory</p></li>
-	<li><code>%h</code><p>Remote host</p></li>
-	<li><code>%L</code><p>Local host</p></li>
-	<li><code>%E</code><p>Server administrator (as given by
-	    <directive>ServerAdmin</directive>)</p></li>
-	<li><code>%a</code><p>Remote IP-address</p></li>
-	<li><code>%A</code><p>Local IP-address</p></li>
-	<li><code>%u</code><p>Remote user</p></li>
-	<li><code>%f</code><p>Number of files transferred</p></li>
-	<li><code>%t</code><p>Total number of bytes downloaded</p></li>
-	<li><code>%x</code><p>Number of data transfers</p></li>
-	<li><code>%b</code><p>Total traffic for the session (both
-	    control and data)</p></li>
-      </ul>
+      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>
@@ -406,7 +388,7 @@
 	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>FTPBannerMessage</directive>.</p>
+	<directive module="mod_ftp">FTPBannerMessage</directive>).</p>
       <note>This directive is inherited to all virtual hosts from the
 	global configuration file.</note>
     </usage> 
@@ -422,10 +404,10 @@
     <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>DocumentRoot</directive> for the server.  For
+	<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>DocumentRoot</directive><code>/home/</code><code>username</code>
+	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
@@ -433,7 +415,7 @@
 	(&quot;<code>/</code>&quot;) directory.  If you want the home
 	directory created automatically, see the
 	<directive>CreateHomeDirs</directive> option to the
-	<directive>FTPOptions</directive> directive.</p> 
+	<directive module="mod_ftp">FTPOptions</directive> directive.</p> 
     </usage>
     <note>This directive is <strong>not</strong> inherited from the
       global configuration file.</note>
@@ -443,51 +425,141 @@
     <name>FTPDocRootEnv</name>
     <description>Set the DocumentRoot based on the given environment
       variable, such as a per-user LDAP property</description>
-    <syntax></syntax>
-    <default></default>
+    <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>
+      <!-- The references to CovalentLDAP obviously need to go away -->
+      <p>This may be used with the <directive>CovalentLDAPPassProperty
+	</directive> directive, or other directives that provide an
+	environment variable assignment, to change FTP's Document Root
+	on a per-user basis.</p> 
+      <example>
+	<p><code>CovalentLDAPPassProperty homeDir </code></p> 
+	<p><code>FTPDocRootEnv homeDir</code></p>
+	<p>Extract a user's LDAP <code>homeDir</code> property, and
+	  then use it for the user's FTP Document Root.</p>
+      </example>
+    </usage>
   </directivesynopsis>
 
   <directivesynopsis>
     <name>FTPJailUser</name>
     <description>Users are not allowed to leave their home
       directories</description>
-    <syntax></syntax>
-    <default></default>
+    <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></syntax>
-    <default></default>
+    <syntax>FTPActiveRange <em>min [max]</em></syntax>
+    <default>If this directive is not specified, the server will use
+      random high-numbered ports</default> 
     <contextlist><context>server config</context>
       <context>virtual host</context></contextlist>
+    <usage>
+      <p>This directive defines the port or ports that the Covalent
+	Enterprise FTP Server 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>
+    </usage>
   </directivesynopsis>
 
   <directivesynopsis>
     <name>FTPReadmeMessage</name>
     <description>Set per-directory Readme file</description>
-    <syntax></syntax>
-    <default></default>
-    <contextlist><context>server config</context>
-      <context>virtual host</context><context>.htaccess</context></contextlist>
+    <syntax>FTPReadmeMessage 
+      <em>message</em>|<em>file:/path/to/file</em>
+    </syntax>
+    <default>Unset</default>
+    <contextlist>
+      <context>server config</context>
+      <context>virtual host</context>
+      <context>directory</context>
+      <context>.htaccess</context>
+    </contextlist>
+    <usage><p>This directive sets a <em>message</em> that is displayed
+	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> 
+      <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> 
+      <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></syntax>
-    <default></default>
-    <!-- This directive is allowed in RSRC_CONF, which is not in line
+    <syntax>FTPLimitLoginUser <em>number</em></syntax>
+    <default>FTPLimitLoginUser 0 (unlimited)</default>
+    <!-- FIXME This directive is allowed in RSRC_CONF, which is not in line
     with Covalent documentation -->
     <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>
@@ -507,23 +579,40 @@
     <name>FTPLimitLoginServer</name>
     <description>Set the maximum number of concurrent logins per
       server</description> 
-    <syntax></syntax>
-    <default></default>
-    <!-- This directive is allowed in RSRC_CONF, which is not in line
+    <syntax>FTPLimitLoginServer <em>number</em></syntax>
+    <default>FTPLimitLoginServer 0 (unlimited)</default>
+    <!-- FIXME This directive is allowed in RSRC_CONF, which is not in line
     with Covalent documentation -->
     <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>FTPLimitDBFile</name>
     <description>Set the location for the Login Limit DB file</description>
-    <syntax></syntax>
-    <default></default>
+    <syntax>FTPLimitDBFile <em>file-path</em></syntax>
+    <default>Unset</default>
     <!-- This directive is allowed in RSRC_CONF, which is not in line
     with Covalent documentation -->
     <contextlist><context>server config</context>
     </contextlist>
+    <usage>
+      <!-- FIXME FTPLimitLoginIP is not mentioned in Covalent
+      documentation -->
+      <p>To allow for <directive module="mod_ftp">FTPLimitLoginUser</directive>
and
+	<directive module="mod_ftp">FTPLimitLoginServer</directive> capability, the
FTP
+	server 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
+	must point to a valid file-location.</p>
+      <example><code>FTPLimitDBFile logs/ftplogins</code></example>
+      </usage>
   </directivesynopsis>
 
   <directivesynopsis>
@@ -531,10 +620,8 @@
     <description>Block size in bytes to use during data transfers</description>
     <syntax></syntax>
     <default></default>
-    <!-- This directive is allowed in RSRC_CONF, which is not in line
-    with Covalent documentation -->
     <contextlist><context>server config</context>
-      </contextlist>
+      <context>virtual host</context></contextlist>
     <usage>
       <note>Not documented by Covalent</note>
     </usage>



Mime
View raw message