ProFTPD module mod_xfer



The mod_xfer module handles most of the FTP commands related to file transfers.

Directives


AllowOverwrite

Syntax: AllowOverwrite on|off
Default: AllowOverwrite off
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 0.99.0 and later

The AllowOverwrite directive permits newly transferred files to overwrite existing files. By default, FTP clients cannot overwrite existing files.


AllowRetrieveRestart

Syntax: AllowRetrieveRestart on|off
Default: AllowRetrieveRestart on
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 0.99.0 and later

The AllowRetrieveRestart directive permits (or denies) clients from performing "restart" download (retrieve) file transfers via the FTP REST 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: AllowStoreRestart


AllowStoreRestart

Syntax: AllowStoreRestart on|off
Default: AllowStoreRestart off
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 0.99.0 and later

The AllowStoreRestart directive permits (or denies) clients from "restarting" interrupted upload (store) transfers. By default restarting (via the FTP REST 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 REST command is automatically blocked when HiddenStores is enabled, with the server returning a 501 error code to the client.

See also: AllowRetrieveRestart, DeleteAbortedStore, HiddenStores


DefaultTransferMode

Syntax: DefaultTransferMode ascii|binary
Default: DefaultTransferMode ascii
Context: server config, <VirtualHost>, <Global>
Module: mod_xfer
Compatibility: 1.2.0pre9 and later

The DefaultTransferMode directive sets the default transfer mode used for data transfers. Per RFC 959 requirements, the default transfer mode is "ascii", which means that carriage return (CR) and line feed (LF) translation will be performed: CRLF sequences in uploaded data will be translated to LF, and LF translated to CRLF in downloaded data.


DeleteAbortedStores

Syntax: DeleteAbortedStores on|off
Default: DeleteAbortedStores off
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 1.2.0rc2 and later

The DeleteAbortedStores directive controls whether ProFTPD deletes partially uploaded files if the transfer is stopped via the FTP ABOR command (as opposed to a connection failure). By default, DeleteAbortedStores is off.

However, when HiddenStores is enabled, then DeleteAbortedStores is automatically enabled as well.

See also: HiddenStores


HiddenStores

Syntax: HiddenStores on|off|prefix [suffix]
Default: HiddenStores off
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>
Module: mod_xfer
Compatibility: 1.2.7rc1 and later

The HiddenStores 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 HiddenStores is enabled, then DeleteAbortedStores 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 REST command is automatically blocked when HiddenStores is enabled, with the server returning a 501 error code to the client.

In proftpd-1.3.3rc2 and later, the ".in." prefix can be customised via the HiddenStores directive, e.g.:

  # Use a different prefix for HiddenStores
  HiddenStores filepart-

In proftpd-1.3.5rc2 and later, the "." suffix can be customised using the HiddenStores directive as well, e.g.:

  # Use a different prefix and suffix for HiddenStores
  HiddenStores incoming- .lock
You can also use this capability to configure no prefix, and just a suffix:
  # Use an empty string as the prefix, and a suffix of ".filepart".
  HiddenStores "" ".filepart"
Note that in order to specify the suffix, you must specify a prefix as well.

In proftpd-1.3.6rc1 and later, the prefix and suffix values can use the %P variable, which will be substituted with the session PID. This can help to reduce issues encountered when an FTP upload fails in such a way that proftpd cannot properly clean up the HiddenStores temporary file. For example:

  # Use the session PID as part of the name
  HiddenStores .in. .%P

Discussion
When would you want or need to specify different prefix and suffix values for HiddenStores? You might need this when, for example, your proftpd 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 HiddenStores suffix, then, that modified CIFS client filename view can be avoided.

See also: AllowStoreRestart, DeleteAbortedStores


MaxRetrieveFileSize

Syntax: MaxRetrieveFileSize [number|"*" units ["user"|"group"|"class" expression]]
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 1.2.7rc1 and later

The MaxRetrieveFileSize directive sets a maximum limit on the size of a single file downloaded from proftpd. 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:

  # 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 *

See also: MaxStoreFileSize


MaxStoreFileSize

Syntax: MaxStoreFileSize [number|"*" units ["user"|"group"|"class" expression]]
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 1.2.7rc1 and later

The MaxStoreFileSize directive sets a maximum limit on the size of a single file uploaded to proftpd. 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:

  # 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 *

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 MaxStoreFileSize cannot be used to prevent an FTP client from even sending the bytes over the network.

See also: MaxRetrieveFileSize


MaxTransfersPerHost

Syntax: MaxTransfersPerHost cmd-list count [message]
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 1.3.2rc1 and later

The MaxTransfersPerHost directive limits the number of data transfers happening at the same time from the same host. The cmd-list parameter is a comma-separated list of the data transfer FTP commands (APPE, RETR, STOR, and/or STOU) to which the limit applies. The optional message parameter may be used, which will be displayed to a client attempting to exceed the maximum value. If message is not supplied, the following message is used by default:

  "Sorry, the maximum number of data transfers (%m) from your host are currently being used."

For example:

  MaxTransfersPerHost RETR 2
will result in the following FTP response to a client exceeding the download limit:
  "451 Sorry, the maximum number of data transfers (2) from your host are currently being used."
And for uploads, you might using something like:
  MaxTransferPerHost APPE,STOR,STOU 1

See also: MaxTransfersPerUser


MaxTransfersPerUser

Syntax: MaxTransfersPerUser cmd-list count [message]
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 1.3.2rc1 and later

The MaxTransfersPerUser directive limits the number of data transfers happening at the same time for the same user name. The cmd-list parameter is a comma-separated list of the data transfer FTP commands (APPE, RETR, STOR, and/or STOU) to which the limit applies. The optional message parameter may be used, which will be displayed to a client attempting to exceed the maximum value. If message is not supplied, the following message is used by default:

  "Sorry, the maximum number of data transfers (%m) from this user are currently being used."

For example:

  MaxTransfersPerUser RETR 2
will result in the following FTP response to a client exceeding the download limit:
  "451 Sorry, the maximum number of data transfers (2) from this user are currently being used."
And for uploads, you might using something like:
  MaxTransferPerUser APPE,STOR,STOU 1

See also: MaxTransfersPerHost


StoreUniquePrefix

Syntax: StoreUniquePrefix prefix
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 1.2.6rc1 and later

The StoreUniquePrefix directive is used to configure a prefix for the generated unique random filenames used for the STOU FTP command. The last six characters of the filename will be random. Note: Slash (/) characters are not allowed in the prefix value.


TimeoutNoTransfer

Syntax: TimeoutNoTransfer seconds
Default: 300 seconds
Context: server config, <VirtualHost>, <Global>
Module: mod_xfer
Compatibility: 0.99.0 and later

The TimeoutNoTransfer 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 (18 hours).

See also: TimeoutIdle, TimeoutLogin, TimeoutStalled.


TimeoutStalled

Syntax: TimeoutStalled seconds
Default: 3600 seconds
Context: server config, <VirtualHost>, <Global>
Module: mod_xfer
Compatibility: 1.1.6 and later

The TimeoutStalled directive sets the maximum number of seconds a data connection between proftpd 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 (18 hours).


TransferOptions

Syntax: TransferOptions opt1 ...
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_xfer
Compatibility: 1.3.6rc1 and later

The TransferOptions directive to configure various optional data transfer behaviors.

The currently implemented options are:


TransferRate

Syntax: TransferRate cmd-list kbytes-per-sec[:free-bytes]
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 1.2.8rc1 and later

The TransferRate 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 mod_ifsession). 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: APPE, RETR, STOR, and STOU.

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:

  # 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>


UseSendfile

Syntax: UseSendfile on|off|len units|percentage
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_xfer
Compatibility: 1.3.0rc1 and later

The UseSendfile directive controls use of sendfile(2) functionality, which is an optimization for sending files to clients. Use of sendfile(2) functionality avoids separate read and send kernel operations, and buffer allocations. Read this howto for more details.


Installation

The mod_xfer module is always installed.

Logging
The mod_xfer module supports trace logging, via the module-specific log channels:

Thus for trace logging, to aid in debugging, you would use the following in your proftpd.conf:
  TraceLog /path/to/ftpd/trace.log
  Trace xfer:20
This trace logging can generate large files; it is intended for debugging use only, and should be removed from any production configuration.


© Copyright 2000-2023 The ProFTPD Project
All Rights Reserved