<!-- $Id: mod_xfer.html,v 1.4 2011/04/26 16:10:11 castaglia Exp $ -->
<!-- $Source: /cvsroot/proftp/proftpd/doc/modules/mod_xfer.html,v $ -->
<html>
<head>
<title>ProFTPD module mod_xfer</title>
</head>
<body bgcolor=white>
<hr>
<center>
<h2><b>ProFTPD module <code>mod_xfer</code></b></h2>
</center>
<hr><br>
<p>
The <code>mod_xfer</code> module handles most of the FTP commands related to
file transfers.
<h2>Directives</h2>
<ul>
<li><a href="#AllowOverwrite">AllowOverwrite</a>
<li><a href="#AllowRetrieveRestart">AllowRetrieveRestart</a>
<li><a href="#AllowStoreRestart">AllowStoreRestart</a>
<li><a href="#DeleteAbortedStores">DeleteAbortedStores</a>
<li><a href="#DisplayFileTransfer">DisplayFileTransfer</a>
<li><a href="#HiddenStores">HiddenStores</a>
<li><a href="#MaxRetrieveFileSize">MaxRetrieveFileSize</a>
<li><a href="#MaxStoreFileSize">MaxStoreFileSize</a>
<li><a href="#MaxTransfersPerHost">MaxTransfersPerHost</a>
<li><a href="#MaxTransfersPerUser">MaxTransfersPerUser</a>
<li><a href="#StoreUniquePrefix">StoreUniquePrefix</a>
<li><a href="#TimeoutNoTransfer">TimeoutNoTransfer</a>
<li><a href="#TimeoutStalled">TimeoutStalled</a>
<li><a href="#TransferPriority">TransferPriority</a>
<li><a href="#TransferRate">TransferRate</a>
<li><a href="#UseSendfile">UseSendfile</a>
</ul>
<p>
<hr>
<h2><a name="MaxRetrieveFileSize">MaxRetrieveFileSize</a></h2>
<strong>Syntax:</strong> MaxRetrieveFileSize <em>[number|"*" units ["user"|"group"|"class" expression]]</em>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code>, <code><Directory></code>, <code>.ftpaccess</code><br>
<strong>Module:</strong> mod_xfer<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>MaxRetrieveFileSize</code> directive sets a maximum limit on the
size of a <b>single file</b> downloaded from <code>proftpd</code>. If the
requested file size is larger than than the configured maximum limit,
the data transfer will be rejected.
<p>
A single "*" argument configures unlimited file sizes, and is used primarily to
override any inherited restrictions from higher-level configuration sections.
The given <em>number</em> is the number of bytes for the limit, and is followed
by a units specifier of (case-insensitive) "Gb" (Gigabytes), "Mb" (Megabytes),
"Kb" (Kilobytes), or "B" (bytes). The given <em>number</em> of bytes is
multiplied by the appropriate factor.
<p>
The optional parameters are used to restrict the file size limits only to
specific users. If the "user" restriction is given, then <em>expression</em> is
a <i>user-expression</i> specifying to which users the rule applies. Similarly
for the "group" restriction. For the "class" restriction, the
<em>expression</em> is simply the name of connection class for whom the rule
will apply. If no matching user, group, or class expression (in that order) is
found for the current user, then a limit with no expression (<i>i.e.</i> no
"user", "group", or "class" identifier) is applied.
<p>
Examples:
</pre>
# Restrict downloads to only 1 gigabyte
MaxRetrieveFileSize 1 Gb
# Restrict downloads for user fred, but allow unlimited download size for
# everyone else
MaxRetrieveFileSize 50 Kb user fred
MaxRetrieveFileSize *
</pre>
<p>
See also: <a href="#MaxStoreFileSize"><code>MaxStoreFileSize</code></a>
<p>
<hr>
<h2><a name="MaxStoreFileSize">MaxStoreFileSize</a></h2>
<strong>Syntax:</strong> MaxStoreFileSize <em>[number|"*" units ["user"|"group"|"class" expression]]</em>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code>, <code><Directory></code>, <code>.ftpaccess</code><br>
<strong>Module:</strong> mod_xfer<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>MaxStoreFileSize</code> directive sets a maximum limit on the
size of a <b>single file</b> uploaded to <code>proftpd</code>. When the
configured maximum limit is reached, the data transfer will be aborted.
<p>
A single "*" argument configures unlimited file sizes, and is used primarily to
override any inherited restrictions from higher-level configuration sections.
The given <em>number</em> is the number of bytes for the limit, and is followed
by a units specifier of (case-insensitive) "Gb" (Gigabytes), "Mb" (Megabytes),
"Kb" (Kilobytes), or "B" (bytes). The given <em>number</em> of bytes is
multiplied by the appropriate factor.
<p>
The optional parameters are used to restrict the file size limits only to
specific users. If the "user" restriction is given, then <em>expression</em>
is a <i>user-expression</i> specifying to which users the rule applies.
Similarly for the "group" restriction. For the "class" restriction, the
<em>expression</em> is simply the name of connection class for whom the rule
will apply. If no matching user, group, or class expression (in that order) is
found for the current user, then a limit with no expression (<i>i.e.</i>
no "user", "group", or "class" identifier) is applied.
<p>
Examples:
<pre>
# Restrict upload to only 3 megabytes
MaxStoreFileSize 3 Mb
# Restrict anonymous uploads to 50k, but allow unlimited upload size for
# everyone else
MaxStoreFileSize 50 Kb user anonymous
MaxStoreFileSize *
</pre>
<p>
<b>NOTE</b>: In FTP uploads, the size of the file being uploaded is <b>not</b>
sent to the FTP server first; this means that the FTP server does not know in
advance how much data the FTP client is going to send. The FTP server can only
count the number of bytes being uploaded, and stop the transfer when a
configured limit is reached. This means that <code>MaxStoreFileSize</code>
<b>cannot</b> be used to prevent an FTP client from even sending the bytes
over the network.
<p>
See also: <a href="#MaxRetrieveFileSize"><code>MaxRetrieveFileSize</code></a>
<p>
<hr>
<h2><a name="TransferPriority">TransferPriority</a></h2>
<strong>Syntax:</strong> TransferPriority <em>cmd-list "low"|"medium"|"high"|number</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code><br>
<strong>Module:</strong> mod_xfer<br>
<strong>Compatibility:</strong> 1.3.2rc1 and later
<p>
The <code>TransferPriority</code> directive is used to tweak the process
priority (<i>a la</i> <code>nice(1)</code>) of the session during data
transfers. For example, large (or anonymous) data transfers can be configured
to have lower priorities, so as to get lower priority than other applications
from the kernel.
<p>
The <em>priority</em> parameter can one of the convenient "high", "medium", or
"low" keywords, or it can be an explicit number. As per the
<code>nice(1)</code> man page, the higher the number, the lower the priority;
the highest priority is -20, and the lower priority is 19.
<p>
Examples:
<pre>
# All data transfers get a low priority
TransferPriority APPE,RETR,STOR low
</pre>
Or maybe only downloads should have lower priorities, but uploads should be
fine:
<pre>
TransferPriority RETR low
</pre>
<p>
<hr>
<h2><a name="TransferRate">TransferRate</a></h2>
<strong>Syntax:</strong> TransferRate <em>cmd-list kbytes-per-sec[:free-bytes]</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code>, <code><Directory></code>, .ftpaccess<br>
<strong>Module:</strong> mod_xfer<br>
<strong>Compatibility:</strong> 1.2.8rc1 and later
<p>
The <code>TransferRate</code> directive is used to set transfer rate limits
on the transfer of data. This directive allows for transfer rates to be set
in a wide variety of contexts, on a per-command basis, and for certain subsets
of users (via
<a href="../contrib/mod_ifsession.html"><code>mod_ifsession</code></a>).
<b>Note</b> that these limits only apply to <i>an individual session</i>, and
do <b>not</b> apply to the overall transfer rate of the entire daemon.
<p>
The <em>cmd-list</em> parameter may be an comma-separated list of any of the
following commands: <code>APPE</code>, <code>RETR</code>, <code>STOR</code>,
and <code>STOU</code>.
<p>
The <em>kbytes-per-sec</em> parameter is the actual transfer rate to be applied.
<p>
The <em>free-bytes</em> parameter, if configured, allows that number of bytes
to be transferred before the rate limit is applied. This allows for clients
transferring small files to be unthrottled, but for larger files, such as MP3s
and ISO images, to be throttled.
<p>
Here are some examples:
<pre>
# Limit downloads for everyone
TransferRate RETR 1.5
# Limit uploads (and appends!) to the prolific users in the
# lotsofuploadfiles.net domain. This presumes that a Class has been defined
# for that domain, and that that Class has been named "uploaders". Let them
# upload small files without throttling, though.
<IfClass uploaders>
TransferRate APPE,STOR 8.0:1024
</IfClass>
</pre>
<p>
<hr>
<h2><a name="UseSendfile">UseSendfile</a></h2>
<strong>Syntax:</strong> UseSendfile <em>on|off|len units|percentage</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code>, <code><Directory></code>, .ftpaccess<br>
<strong>Module:</strong> mod_xfer<br>
<strong>Compatibility:</strong> 1.3.0rc1 and later
<p>
The <code>UseSendfile</code> directive controls use of <code>sendfile(2)</code>
functionality, which is an optimization for sending files to clients. Use of
<code>sendfile(2)</code> functionality avoids separate read and send kernel
operations, and buffer allocations. Read this
<a href="../howto/Sendfile.html">howto</a> for more details.
<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_xfer</code>module is <b>always</b> installed.
<p>
<hr><br>
Author: <i>$Author: castaglia $</i><br>
Last Updated: <i>$Date: 2011/04/26 16:10:11 $</i><br>
<br><hr>
<font size=2><b><i>
© Copyright 2000-2011 The ProFTPD Project<br>
All Rights Reserved<br>
</i></b></font>
<hr><br>
</body>
</html>
