trAvis - MANAGER

Edit File: mod_xfer.html

<html>
<head>
<title>ProFTPD module mod_xfer</title>
</head>

<hr>
<center>
<h2>ProFTPD module <code>mod_xfer</code></h2>
</center>
<hr>

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>

<hr>
<h2><a name="AllowOverwrite">AllowOverwrite</a></h2>
Syntax: AllowOverwrite on|off 
Default: <code>AllowOverwrite off</code> 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code>, <code>.ftpaccess</code> 
Module: mod_xfer 
Compatibility: 0.99.0 and later

The <code>AllowOverwrite</code> directive permits newly transfered files to
overwrite existing files. By default, FTP clients cannot overwrite
existing files.

<hr>
<h2><a name="AllowRetrieveRestart">AllowRetrieveRestart</a></h2>
Syntax: AllowRetrieveRestart on|off 
Default: <code>AllowRetrieveRestart on</code> 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code>, <code>.ftpaccess</code> 
Module: mod_xfer 
Compatibility: 0.99.0 and later

The <code>AllowRetrieveRestart</code> directive permits (or denies) clients
from performing "restart" download (retrieve) file transfers via the FTP
<code>REST</code> command. By default, restarted downloads are allowed, so
that clients may resume interrupted file transfers at a later time without
losing previously collected data.

See also: <a href="#AllowStoreRestart"><code>AllowStoreRestart</code></a>

<hr>
<h2><a name="AllowStoreRestart">AllowStoreRestart</a></h2>
Syntax: AllowStoreRestart on|off 
Default: <code>AllowStoreRestart on</code> 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code>, <code>.ftpaccess</code> 
Module: mod_xfer 
Compatibility: 0.99.0 and later

The <code>AllowStoreRestart</code> directive permits (or denies) clients from
"restarting" interrupted upload (store) transfers. By default restarting (via
the FTP <code>REST</code> command) is not permitted when uploading
files to the server. Care should be taken to disallow anonymous FTP
"incoming" transfers to be restarted, as this will allow clients to corrupt or
increase the size of previously stored files (even if not their own).

The FTP <code>REST</code> command is automatically blocked when
<code>HiddenStores</code> is enabled, with the server returning a 501 error
code to the client.

See also: <a href="#AllowRetrieveRestart"><code>AllowRetrieveRestart</code></a>,
<a href="#DeleteAbortedStores"><code>DeleteAbortedStore</code></a>,
<a href="#HiddenStores"><code>HiddenStores</code></a>

<hr>
<h2><a name="DeleteAbortedStores">DeleteAbortedStores</a></h2>
Syntax: DeleteAbortedStores on|off 
Default: <code>DeleteAbortedStores off</code> 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code>, <code>.ftpaccess</code> 
Module: mod_xfer 
Compatibility: 1.2.0rc2 and later

The <code>DeleteAbortedStores</code> directive controls whether ProFTPD
deletes partially uploaded files if the transfer is stopped via the
FTP <code>ABOR</code> command (as opposed to a connection failure).
By default, <code>DeleteAbortedStores</code> is off; however when
<code>HiddenStores</code> is enabled, then <code>DeleteAbortedStores</code>
is automatically enabled as well.

See also: <a href="#HiddenStores"><code>HiddenStores</code></a>

<hr>
<h2><a name="HiddenStores">HiddenStores</a></h2>
Syntax: HiddenStores on|off|prefix [suffix] 
Default: <code>HiddenStores off</code> 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code> 
Module: mod_xfer 
Compatibility: 1.2.7rc1 and later

The <code>HiddenStores</code> directive enables two-step file uploads: files
are uploaded as ".in.filename." and once the upload is complete,
renamed to just filename. This provides a degree of atomicity and
helps prevent 1) incomplete uploads and 2) files being used
while they are still being uploaded. When <code>HiddenStores</code> is
enabled, then <a href="#DeleteAbortedStores"><code>DeleteAbortedStores</code></a> is automatically enabled as well.

Note that if the temporary file name is already in use (e.g., a server
crash during upload), it will prevent the file from being uploaded.

The FTP <code>REST</code> command is automatically blocked when
<code>HiddenStores</code> is enabled, with the server returning a 501 error
code to the client.

In <code>proftpd-1.3.3rc2</code> and later, the ".in." prefix can be
customised via the <code>HiddenStores</code> directive, e.g.:
<pre>
 # Use a different prefix for HiddenStores
 HiddenStores filepart-
</pre>

In <code>proftpd-1.3.5rc2</code> and later, the "." suffix can be
customised using the <code>HiddenStores</code> directive as well, e.g.:
<pre>
 # Use a different prefix and suffix for HiddenStores
 HiddenStores incoming- .lock
</pre>
You can also use this capability to configure no prefix, and just
a suffix:
<pre>
 # Use an empty string as the prefix, and a suffix of ".filepart".
 HiddenStores "" ".filepart"
</pre>
Note that in order to specify the suffix, you must specify a
prefix as well.

Discussion 
When would you want or need to specify different prefix and suffix values
for <code>HiddenStores</code>? You might need this when, for example, your
<code>proftpd</code> writes files to an NFS-mounted filesystem. Another
machine mounts that same filesystem remotely using a CIFS client (e.g.
a NetApp machine). The trailing "." suffix causes the CIFS client to list
the temporary filenames different (e.g. in a Windows 8.3 file format
style): "in.test." becomes "INTES~1". This view confuses users/admins.

By changing the default <code>HiddenStores</code> suffix, then, that modified
CIFS client filename view can be avoided.

See also: <a href="#AllowStoreRestart"><code>AllowStoreRestart</code></a>,
<a href="#DeleteAbortedStores"><code>DeleteAbortedStores</code></a>

<hr>
<h2><a name="MaxRetrieveFileSize">MaxRetrieveFileSize</a></h2>
Syntax: MaxRetrieveFileSize [number|"*" units ["user"|"group"|"class" expression]] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code>, <code>.ftpaccess</code> 
Module: mod_xfer 
Compatibility: 1.2.7rc1 and later

The <code>MaxRetrieveFileSize</code> directive sets a maximum limit on the
size of a single file downloaded from <code>proftpd</code>. If the
requested file size is larger than than the configured maximum limit,
the data transfer will be rejected.

A single "*" argument configures unlimited file sizes, and is used primarily to
override any inherited restrictions from higher-level configuration sections.
The given number 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 number of bytes is
multiplied by the appropriate factor.

The optional parameters are used to restrict the file size limits only to
specific users. If the "user" restriction is given, then expression is
a user-expression specifying to which users the rule applies. Similarly
for the "group" restriction. For the "class" restriction, the
expression 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.e. no
"user", "group", or "class" identifier) is applied.

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>

See also: <a href="#MaxStoreFileSize"><code>MaxStoreFileSize</code></a>

<hr>
<h2><a name="MaxStoreFileSize">MaxStoreFileSize</a></h2>
Syntax: MaxStoreFileSize [number|"*" units ["user"|"group"|"class" expression]] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code>, <code>.ftpaccess</code> 
Module: mod_xfer 
Compatibility: 1.2.7rc1 and later

The <code>MaxStoreFileSize</code> directive sets a maximum limit on the
size of a single file uploaded to <code>proftpd</code>. When the
configured maximum limit is reached, the data transfer will be aborted.

A single "*" argument configures unlimited file sizes, and is used primarily to
override any inherited restrictions from higher-level configuration sections.
The given number 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 number of bytes is
multiplied by the appropriate factor.

The optional parameters are used to restrict the file size limits only to
specific users. If the "user" restriction is given, then expression
is a user-expression specifying to which users the rule applies.
Similarly for the "group" restriction. For the "class" restriction, the
expression 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.e.
no "user", "group", or "class" identifier) is applied.

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>

NOTE: In FTP uploads, the size of the file being uploaded is not
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>
cannot be used to prevent an FTP client from even sending the bytes
over the network.

See also: <a href="#MaxRetrieveFileSize"><code>MaxRetrieveFileSize</code></a>

<hr>
<h2><a name="TimeoutNoTransfer">TimeoutNoTransfer</a></h2>
Syntax: TimeoutNoTransfer seconds 
Default: 300 seconds 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_xfer 
Compatibility: 0.99.0 and later

The <code>TimeoutNoTransfer</code> directive configures the maximum number of
seconds a client is allowed to spend connected, after authentication,
without issuing a data transfer command which results in a data connection
(i.e. sending/receiving a file, or requesting a directory listing).
The maximum allowed seconds value is 65535 (108 minutes).

See also: <a href="mod_core.html#TimeoutIdle"><code>TimeoutIdle</code></a>,
<a href="mod_auth.html#TimeoutLogin"><code>TimeoutLogin</code></a>,
<a href="#TimeoutStalled"><code>TimeoutStalled</code></a>.

<hr>
<h2><a name="TimeoutStalled">TimeoutStalled</a></h2>
Syntax: TimeoutStalled seconds 
Default: 3600 seconds 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_xfer 
Compatibility: 1.1.6 and later

The <code>TimeoutStalled</code> directive sets the maximum number of
seconds a data connection between <code>proftpd</code> and a client
can exist but have no actual data transferred (i.e. "stalled"). If the
seconds parameter is set to zero, data transfers are allowed to stall
indefinitely; note that this is not a recommended configuration.
The maximum allowed seconds value is 65535 (108 minutes).

<hr>
<h2><a name="TransferPriority">TransferPriority</a></h2>
Syntax: TransferPriority cmd-list "low"|"medium"|"high"|number 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code> 
Module: mod_xfer 
Compatibility: 1.3.2rc1 and later

The <code>TransferPriority</code> directive is used to tweak the process
priority (a la <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.

The priority 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.

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>

<hr>
<h2><a name="TransferRate">TransferRate</a></h2>
Syntax: TransferRate cmd-list kbytes-per-sec[:free-bytes] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code>, .ftpaccess 
Module: mod_xfer 
Compatibility: 1.2.8rc1 and later

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>).
Note that these limits only apply to an individual session, and
do not apply to the overall transfer rate of the entire daemon.

The cmd-list 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>.

The kbytes-per-sec parameter is the actual transfer rate to be applied.

The free-bytes 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.

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.

&lt;IfClass uploaders&gt;
 TransferRate APPE,STOR 8.0:1024
 &lt;/IfClass&gt;
</pre>

<hr>
<h2><a name="UseSendfile">UseSendfile</a></h2>
Syntax: UseSendfile on|off|len units|percentage 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code>, <code>&lt;Anonymous&gt;</code>, <code>&lt;Directory&gt;</code>, .ftpaccess 
Module: mod_xfer 
Compatibility: 1.3.0rc1 and later

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.

<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_xfer</code>module is always installed.

<hr>

Author: $Author: castaglia $ 
Last Updated: $Date: 2013-03-13 18:08:28 $

<hr>