<!-- $Id: ListOptions.html,v 1.3 2005/08/02 23:38:34 castaglia Exp $ -->
<!-- $Source: /cvsroot/proftp/proftpd/doc/howto/ListOptions.html,v $ -->
<html>
<head>
<title>ProFTPD mini-HOWTO - Directory Lists and ListOptions</title>
</head>
<body bgcolor=white>
<hr>
<center><h2><b>Directory Lists and <code>ListOptions</code></b></h2></center>
<hr>
<p>
The <code><a href="http://www.proftpd.org/docs/directives/linked/config_ref_ListOptions.html">ListOptions</a></code> directive of ProFTPD can be used
to control how directory listings are generated. Directory listings are
sent in response to the <code>LIST</code> and <code>NLST</code> FTP commands.
<p>
The <code>ListOptions</code> directive supports the following options:
<ul>
<li><dt>-1</dt>
<dd>List one file per line</dd>
<li><dt>-A</dt>
<dd>List all files except "." and ".."</dd>
<li><dt>-a</dt>
<dd>List all files including those whose names start with "."</dd>
<li><dt>-C</dt>
<dd>List entries by columns</dd>
<li><dt>-d</dt>
<dd>List directory entries instead of directory contents</dd>
<li><dt>-F</dt>
<dd>Append file type indicator (one of "*", "/", "=", "@" or "|") to names</dd>
<li><dt>-h</dt>
<dd>Print file sizes in human-readable format (<i>e.g.</i> 1K, 234M, 2G)</dd>
<li><dt>-L</dt>
<dd>List files pointed to by symlinks</dd>
<li><dt>-l</dt>
<dd>Use a long listing format</dd>
<li><dt>-n</dt>
<dd>List numeric UIDs/GIDs instead of user/group names</dd>
<li><dt>-R</dt>
<dd>List subdirectories recursively</dd>
<li><dt>-r</dt>
<dd>Sort filenames in reverse order</dd>
<li><dt>-S</dt>
<dd>Sort by file size</dd>
<li><dt>-t</dt>
<dd>Sort by modification time</dd>
</ul>
<p>
Although not strictly supported by the FTP RFCs, many FTP clients send these
options with the <code>LIST</code> and <code>NLST</code> commands, and many
FTP servers honor them. The <code>ListOptions</code> directive configures
default options to be used, in addition to any sent by the client. For
example, to show all files except the "hidden" files for clients,
you could use:
<pre>
ListOptions -a
</pre>
<p>
Another use of <code>ListOptions</code> is to <i>prevent</i> certain options
from being used. The <code>-R</code> option, for recursively listing
all subdirectories, can use a lot of system resources, especially on very
large and/or very deep directory structures, as <code>proftpd</code> scans
all of the files. For this reason, some sites may wish to prevent the
<code>-R</code> option from being used. <code>ListOptions</code> supports
this with use of the "+" character. Options are enabled using the
"-" character, thus they are disabled using "+"--think
of the "+" as cancelling out the "-". For example:
<pre>
ListOptions +R strict
</pre>
would disable all use of the <code>-R</code> option.
<p>
Where did the <code>strict</code> come from in the example above?
<code>ListOptions</code> configures a set of default options, but if a client
sends its own directory options, <code>proftpd</code> will use the client's
options instead. To ignore the client options and use <i>only</i> the
<code>ListOptions</code> configured, one uses the "strict" keyword.
That is why the <code>+R</code> example above required
"strict"--it causes <code>proftpd</code> to ignore any
<code>-R</code> option the client might send.
<p>
What if you wanted to enable some options and disable others in the same
<code>ListOptions</code> directive? You would surround your options in quotation marks, like so:
<pre>
ListOptions "-a +R" strict
</pre>
<p>
The following keywords are supported, in addition to "strict":
<ul>
<li><dt>maxfiles</dt>
<dd>Sets a maximum limit on the number of files listed in one directory listing</dd>
<li><dt>maxdirs</dt>
<dd>Sets a maximum limit on the number of directories listed in one directory listing</dd>
<li><dt>maxdepth</dt>
<dd>Sets a maximum recursion depth, if the <code>-R</code> option is allowed</dd>
</ul>
These keywords were added for finer-grained control over directory listings.
They make it possible to allow recursive listings and yet still apply limits,
to keep the recursion from taking too long:
<pre>
ListOptions -a maxfiles 2000 maxdepth 3
</pre>
This configures the <code>-a</code> option by default, and limits the maximum
files in the generated listing to 2000. If the client uses the <code>-R</code>
option, <code>proftpd</code> will not recurse into directories more than 3
levels deep when generating the listing.
<p>
Note that <code><a href="Limit.html"><Limit></a></code> sections can be
used to block the <code>LIST</code> and <code>NLST</code> commands altogether.
<p>
<hr>
<i>$Date: 2005/08/02 23:38:34 $</i><br>
</body>
</html>
