ProFTPD module mod_core

## ProFTPD module `mod_core`

The `mod_core` module handles most of the core FTP commands.

## Directives

- GroupOwner
- Include
- MaxCommandRate
- PassivePorts
- PathAllowFilter
- PathDenyFilter
- ProcessTitles
- Protocols
- TCPBacklog
- TimeoutLinger
- Trace
- TraceLog
- TraceOptions
- TransferLog

## GroupOwner

Syntax: GroupOwner group-name|"~"
Default: None
Context: `<Anonymous>`, `<Directory>`, .ftpaccess
Module: mod_core
Compatibility: 0.99.0 and later

The `GroupOwner` directive configures which group (via the group-name parameter) will own all newly created directories and files, within the configuration context that `GroupOwner` is set. The group ID of group-name cannot be 0.

Note that `GroupOwner` cannot be used to override the operating system/filesystem user/group paradigm. If the current user is not a member of the specified group, new files and directories cannot be `chown()`ed to the `GroupOwner` group. If this happens, the `STOR` and `MKD`/`XMKD` FTP commands will succeed normally, however the new directory entries will be owned by the current user's default group (and a warning message logged). However, if you also use the `UserOwner` directive in the same configuration context, this restriction is lifted.

Some operating systems (e.g. FreeBSD) will use the GID of the parent directory where the new file/directory is created, rather than GID of the logged-in user which creates the new file/directory. To force the GID of the newly created file to be that of the logged-in user, use:

      # The tilde (~) syntax uses the GID of the logged-in user
      GroupOwner ~

See also: `UserOwner`

## Include

Syntax: Include path|pattern
Default: None
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`, `<Directory>`
Module: mod_core
Compatibility: 1.2.10rc1 and later

The `Include` directive allows inclusion of other configuration files from within the server configuration files.

Shell-style (`fnmatch(3)`) wildcard characters can be used to include several files at once, in alphabetical order. In addition, if `Include` points to a directory, rather than a file, then `proftpd` will read all files in that directory. Note that including entire directories is not recommended, as it is easy to accidentally leave temporary files in a directory that can cause `proftpd` to fail.

The path must be an absolute path. Examples:

      Include /etc/proftpd/conf/tls.conf
      Include /etc/proftpd/conf/vhosts/*.conf

## MaxCommandRate

Syntax: MaxCommandRate count [secs]
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_core
Compatibility: 1.3.4rc2 and later

The `MaxCommandRate` directive is used to configure a maximum number of commands per time interval, after which `proftpd` will start injecting a delay before handling the command. The more over the configured command/sec rate the client is, the longer the delay. This feature is used to "throttle" automated and/or malicious clients.

For example:

      MaxCommandRate 200

sets a maximum command rate of 200 commands per sec. Or:

      MaxCommandRate 500 2

sets a maximum command rate of 500 commands every 2 secs.

## PassivePorts

Syntax: PassivePorts min max
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_core
Compatibility: 1.2.0rc2 and later

The `PassivePorts` directive restricts the range of ports from which the server will select, when the client sends the `PASV` or `EPSV` commands (i.e. requesting a passive data transfer). The server will randomly choose a number from within the specified range until an open port is found. Should no open ports be found within the configured range, the server will default to a random kernel-assigned port, and a message logged.

The port range configured must be in the non-privileged range (e.g. greater than or equal to 1024); it is STRONGLY RECOMMENDED that the chosen range be large enough to handle many simultaneous passive connections (for example, 49152-65534, the IANA-registered ephemeral port range). The smaller your configured port range is, the greater the chance that all of those ports will be in use (depending on the traffic to your FTP server), and thus the greater the chance that a port outside that range will be configured.

Example:

      # Use the IANA registered ephemeral port range
      PassivePorts 49152 65534

Note: Many admins wonder why the recommended port range is so large. The answer is that there is really no value in having a small range. ProFTPD does NOT automatically listen on these ports. For those people who are worried about port scanning, having a larger `PassivePorts` range will not mean that port scans will show those ports as being open AND that something is listening there. Conversely, the question to ask yourself as an administrator is: why do you think you need such a small `PassivePorts` range?

## PathAllowFilter

Syntax: PathAllowFilter pattern [flags]
Default: None
Context: server config, `<VirtualHost>`, `<Global>, `<Anonymous>`, `<Directory>`, .ftpaccess
Module: mod_core
Compatibility: 1.1.7 and later

The `PathAllowFilter` directive allows the configuration of a regular expression pattern that must be matched for all newly uploaded (stored) files. The regular expression is applied against the entire pathname specified by the client, so care must be taken when creating a proper regex. Paths that fail the regex match result in a "Forbidden filename" error being returned to the client. If the regular expression pattern parameter contains whitespace, it must be enclosed in quotes.

For example:

      # Only allow a-z 0-9 . - _ in file names
      PathAllowFilter ^[a-z0-9._-]+$

      # As above but with upper case characters as well
      PathAllowFilter ^[A-Za-z0-9._-]+$

The optional flags paramete, if present, modifies how the given pattern will be evaludated. The supported flags are:

- nocase|NC (no case)
  This makes the pattern case-insensitive, i.e. there is no difference between 'A-Z' and 'a-z' when pattern is matched against the path

The Filters howto covers filtering in greater detail.

See also: `PathDenyFilter`

## PathDenyFilter

Syntax: PathDenyFilter pattern [flags]
Default: None
Context: server config, `<VirtualHost>`, `<Global>, `<Anonymous>`, `<Directory>`, .ftpaccess
Module: mod_core
Compatibility: 1.1.7 and later

Similar to the `PathAllowFilter` directive, `PathDenyFilter` specifies a regular expression pattern which must not match any uploaded pathnames. If the regex does match, a "Forbidden filename" error is returned to the client. This can be especially useful for forbidding .ftpaccess or .htaccess files.

For example:

      # We don't want .ftpaccess or .htaccess files to be uploaded
      PathDenyFilter "(\\.ftpaccess|\\.htaccess)$"

The optional flags paramete, if present, modifies how the given pattern will be evaludated. The supported flags are:

- nocase|NC (no case)
  This makes the pattern case-insensitive, i.e. there is no difference between 'A-Z' and 'a-z' when pattern is matched against the path

The Filters howto covers filtering in greater detail.

See also: `PathAllowFilter`

## ProcessTitles

Syntax: ProcessTitles terse|verbose
Default: ProcessTitles verbose
Context: server config Module: mod_core
Compatibility: 1.3.4rc2 and later

The `ProcessTitles` directive is used to tweak how `proftpd` modifies the process title for session processes.

By default, `proftpd` updates the process title to show the current FTP command and its arguments for every session, e.g.:

      # ps aux | grep proftpd
      proftpd  30667  0.0  0.1   7304  1584 ?        Ss   02:12   0:00 proftpd: (accepting connections)
      user1    31892  0.2  0.3   8004  3505 ?        SL   20:13   0:12 proftpd: user1 - remote.client1.com: RETR file1.doc
      user2    31934  0.0  0.3   8004  3500 ?        SL   21:27   0:00 proftpd: user2 - 4.3.2.1: STOR file2.zip
      user3    31891  0.2  0.3   8004  3504 ?        SL   20:11   0:09 proftpd: user3 - remote.client2.com: RETR whatever.iso

This is the same as having:

      ProcessTitles verbose

in your proftpd.conf.

To obscure the process titles, you can use:

      ProcessTitles terse

which results in process titles which look like:

      # ps aux | grep proftpd
      proftpd  30667  0.0  0.1   7304  1584 ?        Ss   02:12   0:00 proftpd: (accepting connections)
      user1    31892  0.2  0.3   8004  3505 ?        SL   20:13   0:12 proftpd: processing connection
      user2    31934  0.0  0.3   8004  3500 ?        SL   21:27   0:00 proftpd: processing connection
      user3    31891  0.2  0.3   8004  3504 ?        SL   20:11   0:09 proftpd: processing connection

## Protocols

Syntax: Protocols protocol1 ...
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_core
Compatibility: 1.3.4rc1 and later

The `Protocols` directive is used to enable/disable specific protocols support by the `proftpd` and its collection of modules. This directive can be used, in conjunction with the `mod_ifsession` module, to enable certain features for specific users/groups/classes.

The allowed protocols must be configured as a space-delimited list. For example:

      # Only enable FTPS and SFTP support, but not FTP or SCP
      Protocols ftps sftp

The currently known/supported protocols include:

- `ftp`
- `ftps` (from `mod_tls`)
- `scp` (from `mod_sftp`)
- `sftp` (from `mod_sftp`)

## TCPBacklog

Syntax: TCPBacklog backlog-size
Default: 5
Context: server config
Module: mod_core
Compatibility: 0.99.0 and later

The `TCPBacklog` directive controls the TCP connection queue size for listening sockets; this directive only applies to `proftpd` when it is configured with "`ServerType standalone`". It has no effect if "`ServerType inetd`" is configured.

When a TCP connection is established by the TCP/IP stack within the kernel, there is a short period of time between the actual establishment of the TCP connection and when that connection is accepted for use by the listening daemon via the `accept(2)` system call. The duration of this period of time can vary quite a bit, and can depend upon several factors (e.g. hardware, system load, etc). Any TCP connection which hasn't been accepted by the listening daemon is placed in a "backlog" or queue of pending connections. The `TCPBacklog` directive controls how the size of this queue of pending connections.

If this queue of pending connections becomes full, new TCP connections cannot be estaslished. Under heavy load, this can result in occasional (or even frequent) errors seen by clients, such as "Connection refused", even though the daemon is clearly running.

The larger the backlog-size, the more TCP connections can be established to the daemon. This also means more kernel memory and other kernel resources.

The issue is complicated further by the fact that different operating systems handle the backlog-size value differently. The pending connection queue is a critical kernel-level structure, and is sensitive to TCP syn floods. Each operating system, then, has different ways of handling incoming and pending connections, to attempt to guard against such attacks. For Linux systems, read the `tcp(7)` man page and specifically about `tcp_abort_on_overflow`,

`tcp_max_syn_backlog`, and `tcp_syncookies`. On FreeBSD, read the `syncookies(4)` man page. And read here for additional tuning considerations on Solaris.

## TimeoutLinger

Syntax: TimeoutLinger secs
Default: 30
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_core
Compatibility: 1.2.10rc2 and later

The `TimeoutLinger` directive configures the maximum number of seconds that `proftpd` will wait (or "linger") when closing a data connection (i.e. for uploads, downloads, and directory listings). Once the data connection is closed, `proftpd` will send a response message ("226 Transfer complete") on the control connection indicating the closure. This delay is necessary for properly handling some FTP clients.

If the client aborts a transfer and there is a long delay, this lingering close is the most likely culprit. So if you encounter this delay, set `TimeoutLinger` to a low number to remove the delay.

For the curious, here are the full details: some FTP clients will close their end of a data connection as soon as they are done sending their data; other FTP clients will wait until the server closes its end of the data connection, and some will close their side of the data connection only after they receive the "226 Transfer complete" message on the control connection. In order to ensure that all of the data has been transferred on a data connection, `proftpd` will "linger" for a certain amount of time (governed by the `TimeoutLinger` directive) before sending that "226 Transfer complete" response, thus giving all client behaviors a chance to do the right thing. However, this means that some clients will see a this `TimeoutLinger` delay unnecessarily. The `proftpd` daemon can't detect which type of behavior the client will use, so it is up to the site admin to configure `proftpd` to work best with their FTP clients.

## Trace

Syntax: Trace channel1:level1 ...
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_core
Compatibility: 1.3.1rc1 and later

The `Trace` directive is used to configure which trace channels are logged to the `TraceLog` file, and which log levels for messages in that trace channel.

For example, to get the default trace channels logged:

      Trace DEFAULT:10

To disable logging of a particular trace channel entirely, use a log level of zero, e.g.:

      # Log all of the default trace channels except for 'lock' and
      # 'scoreboard'
      Trace DEFAULT:10 lock:0 scoreboard:0

To see only a certain range of log levels in a given trace channel, you can specify the log level range like this:

      # Log only messages at levels 7-10 for the default channels
      TraceLog DEFAULT:7-10

See the Tracing howto for more information.

## TraceLog

Syntax: TraceLog path
Default: None
Context: server config
Module: mod_core
Compatibility: 1.3.1rc1 and later

The `TraceLog` directive is used to specify a log file for trace logging messages. The path parameter given must be the full path to the file to use for logging.

Note that this path must not be to a world-writable directory and, unless `AllowLogSymlinks` is explicitly set to on (generally a bad idea), the path must not be a symbolic link.

See the Tracing howto for more information.

## TraceOptions

Syntax: TraceOptions opt1 ... optN
Default: None
Context: "server config", <VirtualHost>, <Global>
Module: mod_core
Compatibility: 1.3.4rc2 and later

The `TraceOptions` directive can be used to change the format of the `TraceLog` messages, e.g. adding/remove certain fields of data.

The options supported by the `TraceOptions` directive are:

- ConnIPs
- TimestampMillis

These options are all disabled by default.

To enable an option, preface the option name with a '+' (plus) character; to disable the option, use a '-' (minus) character prefix. For example:

      # Log timestamps inncluding millisecs, but do not include the connection
      # IP address/port information
      TraceOptions +TimestampMillis -ConnIPs

## TransferLog

Syntax: TransferLog path|"none"
Default: None
Context: "server config", <VirtualHost>, <Global>, <Anonymous>
Module: mod_core
Compatibility: 1.1.4 and later

The `TransferLog` directive configures the full path to the "wu-ftpd style" file transfer log; see the `xferlog(5)` man page for a description of this log file format. Separate log files can be created for each `<Anonymous>` and/or `<VirtualHost>`. Additionally, the special keyword "none" (available in proftpd-1.1.7 and later) can be used, which disables wu-ftpd style transfer logging for the context in which the directive is used.

See also: `ExtendedLog`, `LogFormat`

## Installation

The `mod_core`module is always installed.

Author: $Author: castaglia $
Last Updated: $Date: 2011/07/01 18:34:07 $

© Copyright 2000-2011 The ProFTPD Project
All Rights Reserved