## ProFTPD module `mod_core`

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

## Directives

- AllowFilter
- AuthOrder
- DebugLevel
- DefaultAddress
- DenyFilter
- DisplayChdir
- DisplayConnect
- DisplayQuit
- GroupOwner
- HideGroup
- HideNoAccess
- HideUser
- Include
- MasqueradeAddress
- MaxCommandRate
- MaxInstances
- PassivePorts
- PathAllowFilter
- PathDenyFilter
- Port
- ProcessTitles
- Protocols
- ScoreboardFile
- ScoreboardMutex
- ServerIdent
- ServerType
- SocketOptions
- SyslogFacility
- SyslogLevel
- TCPBacklog
- TimeoutIdle
- TimeoutLinger
- Trace
- TraceLog
- TraceOptions
- TransferLog
- Umask
- <VirtualHost>

## AllowFilter

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

The `AllowFilter` allows the configuration of a regular expression pattern that must be matched for all command arguments sent to ProFTPD. It is extremely useful in controlling what characters may be sent in a command to ProFTPD, preventing some possible types of attacks against ProFTPD.

The regular expression pattern is applied against the arguments to the command sent by the client, so care must be taken when creating a proper regex. Commands that fail the regex match result in a "Forbidden command" error being returned to the client. If the pattern contains whitespace, it must be enclosed in quotes.

The optional flags parameter, if present, modifies how the givenpattern 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 example below allows commands which contain alphanumeric characters and whitespace:

      AllowFilter "^[a-zA-Z0-9 ,]*$"

The Filters howto covers filtering in greater detail.

See also: `DenyFilter`, `PathAllowFilter`, `PathDenyFilter`

## AuthOrder

Syntax: AuthOrder module-name1 ...
Default: mod_auth_file.c mod_auth_unix.c
Context: "server config", `<VirtualHost>`, `<Global>`
Module: mod_core
Compatibility: 1.2.8rc1 and later

The `AuthOrder` directive configures the names of auth modules, and the order in which they will be checked when authenticating a client.

At least one module name must be given; there is no maximum number of modules that can be listed. The listed module names must the full name of the source file, e.g. "mod_auth_unix.c". To see a full list of module names, use:

      $ proftpd -l

Do not use "mod_auth.c", as that module is the authentication front end module, and is necessary. Also, do not use "mod_auth_pam.c" as the only module, as that module does not provide, by itself, all of the information needed by proftpd for authenticating a client.

You can make an auth module be "authoritative" by appending an asterisk (*) after the module name. Usually this is done for the "mod_auth_pam.c" module, to ensure that the login fails if the PAM check fails.

Examples

      # Use only AuthUserFiles when authenticating, and not the system's /etc/passwd
      AuthOrder mod_auth_file.c

      # If the user's information is not in LDAP, they're not a user to use
      # this server.
      AuthOrder mod_ldap.c

      # Use SQL tables first, then LDAP, for authentication
      AuthOrder mod_sql.c mod_ldap.c

      # Use the normal system /etc/passwd and PAM, but make sure that PAM is
      # authoritative about accepting or rejecting the login
      AuthOrder mod_auth_pam.c* mod_auth_unix.c

## DebugLevel

Syntax: DebugLevel level
Default: DebugLevel 0
Context: "server config", `<VirtualHost>`, `<Global>`
Module: mod_core
Compatibility: 1.2.8rc1 and later

The `DebugLevel` directive configures the debugging level the server will use when logging. The level parameter must be between 0 and 10. This directive will take precedence over any `-d`/`--debug` command-line debugging option used.

The Logging howto covers logging in greater detail.

## DefaultAddress

Syntax: DefaultAddress ip-address|dns-name [ip-address|dns-name ...]
Default: None
Context: "server config"
Module: mod_core
Compatibility: 1.2.7rc1 and later

The `DefaultAddress` directive sets the the address to which the main server instance (i.e. the server configured by the "server config" context) will bind. The default behaviour is to select whatever IP address is reported by the operating system as the primary IP address.

Starting with `proftpd-1.3.0rc1`, it is possible to use more than one FQDN or IP address.

Examples

      ServerName "Default FTP Server"
      Port 21

      # We want the main server instance to listen on a specific IP
      DefaultAddress 192.168.10.30

      # Since 1.3.0rc1 it's also possible to use the following:
      DefaultAddress 192.168.10.30 my.domain.tld

In `proftpd-1.3.5rc1`, the `DefaultAddress` directive also handles names which indicates the device-name (or interface-name); the IP address associated with this device/interface will be used. For example, you can use:

      DefaultAddress eth0

Using the device/interface name is useful in cases where the same `proftpd.conf` file is going to be deployed to multiple different machines, which will have the same device/interface names but different IP addresses.

See also: `<VirtualHost>`

## DenyFilter

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

The `DenyFilter` directive, like the `AllowFilter` directive, specifies a regular expression pattern which must not match any of the command arguments. If the pattern does match, a "Forbidden command" error is returned to the client. This can be especially useful for forbidding certain command argument combinations from ever reaching ProFTPD.

Note that the `PASV` SFTP command cannot be blocked using this directive.

The optional flags parameter, if present, modifies how the givenpattern 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

For example, to reject commands which contain the percent (`%`) character, you could use:

      DenyFilter "%"

The Filters howto covers filtering in greater detail.

See also: `AllowFilter`, `PathAllowFilter`, `PathDenyFilter`

## DisplayChdir

Syntax: DisplayChdir filename ["on"|"off"]
Default: None
Context: "server config", `<VirtualHost>`, `<Global>`, `<Anonymous>`, `<Directory>`
Module: mod_core
Compatibility: 1.3.1rc1 and later

The `DisplayChdir` directive configures the name of a text file that will be displayed to the user, every time they change into a directory. If the text file should only be displayed once to the client, the first time they change into the directory (or if `proftpd` detects that the `DisplayChdir` file has been changed since it was last displayed to the client), then set the optional second parameter to on or true.

If the filename is relative, it is looked for in the directory that the user has changed into. Note that for anonymous ftp logins, filename must reside within the `chroot()`ed directory. If filename cannot be found or accessed, no error occurs and nothing is logged or displayed to the client.

See the Display files howto for more information on the variables that can be used in a `DisplayChdir` file.

See also: `DisplayConnect`, `DisplayQuit`

## DisplayConnect

Syntax: DisplayConnect filename
Default: None
Context: "server config", `<VirtualHost>`, `<Global>`
Module: mod_core
Compatibility: 1.2.0pre2 and later

The `DisplayConnect` directive configures the filename of a text file that will be displayed to the user when they initially connect, before they login. The filename can be either relative or absolute. In the case of a relative filename, the file is searched for starting in the home directory of the `User` as which the server is running. As this can lead confusion, absolute pathnames are highly recommended. If filename cannot be found or accessed, no error occurs and nothing is logged or displayed to the client.

See the Display files howto for more information on the variables that can be used in a `DisplayConnect` file.

See also: `DisplayChdir`, `DisplayQuit`

## DisplayQuit

Syntax: DisplayQuit filename
Default: None
Context: "server config", `<VirtualHost>`, `<Global>`, `<Anonymous>`
Module: mod_core
Compatibility: 1.2.0pre8 and later

The `DisplayQuit` directive configures the filename of a text file that will be displayed to the user when they explicitly end the FTP session using the `QUIT` command. The filename can be either relative or absolute. In the case of a relative filename, the file is searched for starting in the home directory of the logged-in user. Note: if the session is restricted via `chroot`, either by the `DefaultRoot` directive or because its an `<Anonymous>` login, then filename must reside within the `chroot()` directory. As this can lead confusion, absolute pathnames are highly recommended. If filename cannot be found or accessed, no error occurs and nothing is logged or displayed to the client.

See the Display files howto for more information on the variables that can be used in a `DisplayQuit` file.

See also: `DisplayChdir`, `DisplayConnect`

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

## HideGroup

Syntax: HideGroup group-name
Default: None
Context: `<Anonymous>`, `<Directory>`
Module: mod_core
Compatibility: 0.99.0 and later

The `HideGroup` directive configures a `<Directory>` or `<Anonymous>` section to hide all directory entries owned by the specified group-name. The group-name can also be `~` (tilde), which is evaluated as the group-name of the primary group of the logged-in user. This can be combined with a prefix `!` (exclamation point) character, e.g. "!~", to mean "any group that is not the primary group of the logged-in-user".

Normally, hidden directories and files cannot be seen via `LIST` or `NLST` commands but can be operated on via other FTP commands (`CWD`, `DELE`, `RETR`, etc). This behavior can be modified via the `IgnoreHidden` directive.

Examples:

      <Directory path>
        # Hide all files belonging to group 'wheel'
        HideGroup wheel

        # Hide all files belonging to the primary group of the logged-in user
        HideGroup ~

        # Hide all files that are NOT owned by the primary group of the logged-in
        # user
        HideGroup !~
      </Directory>

See also: `HideUser`, `HideNoAccess`, `IgnoreHidden`

## HideNoAccess

Syntax: HideNoAccess on|off
Default: None
Context: `<Anonymous>`, `<Directory>`
Module: mod_core
Compatibility: 0.99.0 and later

The `HideNoAccess` directive configures a `<Directory>` or `<Anonymous>` section to hide all directory entries in a directory listing (e.g. via the `LIST` or `NLST` FTP commands) to which the current logged-in, authenticated user has no access. Normal Unix-style permissions always apply, so that although a user may not be able to see a directory entry that has "HideNoAccess on" applied, they will receive a normal "Permission denied" error message when attempting to blindly manipulate the file system object. The directory or file can be made completely invisible to all FTP commands by applying `IgnoreHidden` in conjunction with `HideNoAccess`.

See also: `HideGroup`, `HideUser`, `IgnoreHidden`

## HideUser

Syntax: HideUser user-name
Default: None
Context: `<Anonymous>`, `<Directory>`
Module: mod_core
Compatibility: 0.99.0 and later

The `HideUser` directive configures a `<Directory>` or `<Anonymous>` section to hide all directory entries owned by the specified user-name. The user-name can also be `~` (tilde), which is evaluated as the user-name of the logged-in user. This can be combined with a prefix `!` (exclamation point) character, e.g. "!~", to mean "any user that is not the logged-in-user".

Normally, hidden directories and files cannot be seen via `LIST` or `NLST` commands but can be operated on via other FTP commands (`CWD`, `DELE`, `RETR`, etc). This behavior can be modified via the `IgnoreHidden` directive.

Examples:

      <Directory path>
        # Hide all files belonging to user 'root'
        HideUser root

        # Hide all files belonging to the logged-in user
        HideUser ~

        # Hide all files that are NOT owned by the logged-in user
        HideUser !~
      </Directory>

See also: `HideGroup`, `HideNoAccess`, `IgnoreHidden`

## 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. (If no matches for the pattern are found, the `Include` directive is silently ignored.) 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

## MasqueradeAddress

Syntax: MasqueradeAddress ip-address|dns-name|device-name
Default: None
Context: server config, `<VirtualHost>`
Module: mod_core
Compatibility: 1.2.2 and later

The `MasqueradeAddress` directive causes the server to display the network information for the specified IP address or DNS hostname to the client in the responses to `PASV` and `EPSV` FTP commands, on the assumption that that IP address or DNS host is acting as a NAT gateway or port forwarder for the server. For example:

      MasqueradeAddress nat-gw.mydomain.com

The `MasqueradeAddress` directive also handles a parameter which indicates the device-name (or interface-name); the IP address associated with this device/interface will be used. For example, you can use:

      MasqueradeAddress eth0

Using the device/interface name is useful in cases where the same `proftpd.conf` file is going to be deployed to multiple different machines, which will have the same device/interface names but different IP addresses.

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

## MaxInstances

Syntax: MaxInstances count
Default: None
Context: server config
Module: mod_core
Compatibility: 1.1.6p11 and later

The `MaxInstances` directive configures the maximum number of child (session) processes that may be spawned by the `proftpd` daemon process when running with "ServerType standalone" configured. The directive has no effect when `proftpd` is configured with "ServerType inetd".

Each `proftpd` child process represents a single client connection, and thus this directive also controls the maximum number of simultaneous connections allowed. Additional connections beyond the configured limit are logged, and silently disconnected. The `MaxInstances` directive can be used to prevent undesirable denial-of-service attacks (e.g. by repeatedly connecting to the FTP control port, a malicious client could try to cause `proftpd` to repeatedly fork new processes, creating a "fork-bomb"). By default, no limit is placed on the number of child processes that may run at one time; it is highly recommended that a maximum number, suitable to your sites traffic, be configured.

## 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 parameter, 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 parameter, 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`

## Port

Syntax: Port number
Default: Port 21
Context: server config, `<VirtualHost>`
Module: mod_core
Compatibility: 0.99.0 and later

The `Port` directive configures the TCP port to which `proftpd` will listen while running in standalone mode. This directive has no effect when used on a server running in inetd mode; see `ServerType`. The directive can be used in conjunction with `<VirtualHost>` in order to run a virtual server on the same IP address as the master server, but listening on a different port.

For any server, either `<VirtualHost>` or "server config", using a number value of zero (0) will effectively disable/turn off that server:

      <VirtualHost ...>
        # This virtual server is disabled because of this Port setting
        Port 0

        ...
      </VirtualHost>

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

## ScoreboardFile

Syntax: ScoreboardFile path|"none"
Default: ScoreboardFile /usr/local/var/proftpd.scoreboard Context: server config
Module: mod_core
Compatibility: 1.2.7rc1 and later

The `ScoreboardFile` directive sets the path to the file where the daemon will store its run-time "scoreboard" session information. This file is necessary for support features such as `MaxClients` to work properly, as well as other utilities (such as ftpwho, ftptop, and ftpcount). Note that the directory containing the scoreboard cannot be world-writable.

For performance reasons, it is strongly recommended that the `ScoreboardFile` path not be located on a networked filesystem, but rather be located on a local physical disk.

In order to disable scoreboarding (which can increase performance, at the cost of functionality), any of the following can be used:

      ScoreboardFile /dev/null
      ScoreboardFile none
      ScoreboardFile off

Please read the Scoreboard howto before disabling scoreboarding.

## ScoreboardMutex

Syntax: ScoreboardMutex path
Default: ScoreboardMutex /usr/local/var/proftpd.scoreboard.lck Context: server config
Module: mod_core
Compatibility: 1.3.4rc1 and later

The `ScoreboardMutex` directive sets the path to a "mutex" file which is used for scoreboard locking/synchronization; this mutex is used to increase the daemon's performance under load.

For performance reasons, it is strongly recommended that the `ScoreboardMutex` path not be located on a networked filesystem, but rather be located on a local physical disk. It is best if the `ScoreboardMutex` be located in the same directory as the `ScoreboardFile`.

## ServerIdent

Syntax: ServerIdent off|on "identification string"
Default: ServerIdent on "ProFTPD [version] Server (server name) [hostname]"
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_core
Compatibility: 1.2.0pre2 and later

The `ServerIdent` directive sets the default message displayed when a new client connects. Setting this to off displays:

      [hostname] FTP server ready.

If set to on, the directive can take an optional string argument, which will be displayed instead of the default text. Sites desiring to give out minimal information will probably want a setting like:

      ServerIdent on "FTP Server ready."

which won't even reveal the hostname.

An example of a custom identification string might be:

      ServerIdent on "Welcome to ftp.linux.co.uk"

## ServerType

Syntax: ServerType "standalone"|"inetd"
Default: ServerType standalone
Context: server config
Module: mod_core
Compatibility: 0.99.0 and later

The `ServerType` directive configures the `proftpd` server operating mode. The parameter can either be inetd or standalone.

A parameter value of inetd configures `proftpd` to expect to be run from the `inetd`/`xinetd` "super server." New connections are passed from `inetd`/`xinetd` to `proftpd` and are processed immediately.

A parameter value of standalone configures `proftpd` to start up on its own, and to begin listening to the configured addresses/ports for incoming connections. New connections result in forked child processes dedicated to processing all requests from the newly connected client.

## SocketOptions

Syntax: SocketOptions [maxseg byte-count] [rcvbuf byte-count] [sndbuf byte-count] [keepalive "on"|"off"|spec]
Default: None
Context: server config, `<VirtualHost>`
Module: mod_core
Compatibility: 1.2.9rc1 and later

The `SocketOptions` directive is used to tune various socket-level options. The rcvbuf and sndbuf parameters are used for setting the TCP send/receive window sizes. The maxseg parameter is used for setting a MSS (Maximum Segment Size) via `setsockopt(2)`'s `TCP_MAXSEG` option. If the MSS is larger than the network interface's MTU, it is ignored and has no effect.

Examples:

      # Use buffer sizes of 32KB for both reading and writing
      SocketOptions rcvbuf 32768 sndbuf 32768

In `proftpd-1.3.5rc1`, the `SocketOptions` directive gained support for the keepalive parameter. By default, `proftpd` enables TCP keepalives on all of its connections, both control and data. To disable use of TCP keepalives, use:

      SocketOptions keepalive off

while to have TCP keepalives explicitly enabled in the config, you would use:

      SocketOptions keepalive on

The keepalive parameter also handles an argument in the form of a "keepalive-spec", which is a colon-separated string of three numeric values: idle-secs, probe-count, and interval-secs. On most TCP stacks, the default TCP keepalive behavior uses 2 hours as the time (per recommendation in RFC 1122), with 9 probes at 75 seconds between each probe. Using the keepalive parameter, this would be configured as:

      SocketOption keepalive 7200:9:75

The first number (idle-secs) indicates the number of seconds the TCP connection must be idle before the first TCP keepalive probe is sent. Once the idle-secs time has passed, the TCP stack will send a number of "probes", trying to elicit a response (`ACK`, `RST`, etc) from the remote peer; the number of probes sent is configured by the second number (probe-count). The probes will be sent out at intervals governed by the third number (interval-secs), which configures the number of seconds between each keepalive probe.

Note that not all platforms support configuring the idle, count, and interval values of the TCP keepalive behavior in their TCP stack. On such platforms, if the keepalive spec format is used, e.g.:

      SocketOptions keepalive 7500:9:75

and `proftpd` knows that it cannot alter the TCP keepalive values, then `proftpd` will assume that the keepalive configuration is equivalent to:

      SocketOptions keepalive on

## SyslogFacility

Syntax: SyslogFacility facility
Default: SyslogFacility daemon
Context: server config
Module: mod_core
Compatibility: 1.1.6 and later

By default, ProFTPD logs its activity via the Unix syslog mechanism, which allows for several different general classifications of logging messages, known as "facilities." Normally, all authentication related messages are logged with the `AUTHPRIV` (or `AUTH`) facility (since these messages are intended to be secure, and never seen by unwanted eyes), while normal operational messages are logged with the `DAEMON` facility. The `SyslogFacility` directive allows all logging messages to be directed to a different facility than the default.

When this directive is used, all logging is done with the specified facility, both authentication (secure) and otherwise. The facility argument must be one of the following:

- `AUTH` (or `AUTHPRIV`)
- `CRON`
- `DAEMON`
- `FTP`
- `KERN`
- `LPR`
- `MAIL`
- `NEWS`
- `USER`
- `UUCP`
- `LOCAL0`
- `LOCAL1`
- `LOCAL2`
- `LOCAL3`
- `LOCAL4`
- `LOCAL5`
- `LOCAL6`
- `LOCAL7`

For more information on syslog facilities, see the `syslog.conf` man page.

The Logging howto covers logging in greater detail.

See also: `SyslogLevel`, `SystemLog`

## SyslogLevel

Syntax: SyslogLevel level
Default: SyslogLevel debug
Context: server config
Module: mod_core
Compatibility: 1.2.0rc2 and later

The `SyslogLevel` directive adjusts the verbosity of the messages recorded via the default Unix syslog logging. The following levels are available, in order of decreasing significance:

Level | Description
`emerg` | Emergencies (e.g. the system is unusable)
`alert` | Action must be taken immediately
`crit` | Critical conditions
`error` | Error conditions
`warn` | Warning conditions
`notice` | Normal but significant conditions
`info` | Informational
`debug` | Debug-level messages

When a particular level is specified, messages from all other levels of higher significance will be reported as well. For example, when:

      SyslogLevel info

is configured, then messages with log levels of `notice` and `warn` will also be logged. Using a level of at least `crit` is recommended.

The Logging howto covers logging in greater detail.

See also: `SyslogFacility`, `SystemLog`

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

## TimeoutIdle

Syntax: TimeoutIdle seconds
Default: 600 seconds
Context: server config, `<VirtualHost>`, `<Global>`, `<Anonymous>`
Module: mod_core
Compatibility: 0.99.0 and later

The `TimeoutIdle` directive configures the maximum number of seconds that `proftpd` will allow clients to stay connected without receiving any data on either the control or data connection. If data are received on either connection, the idle timer is reset. Setting `TimeoutIdle` to zero disables the idle timer completely, meaning that clients can stay connected forever, without sending data. Note: this is generally a very bad idea, as a "hung" TCP connection which is never properly disconnected (e.g. the remote network may have become disconnected from the Internet, etc) will cause a session process to never exit, until manually killed. This session process will thus linger, using up one of the `MaxInstances` as well as any of the other configured limits. The maximum allowed seconds value is 65535 (108 minutes).

See also: `TimeoutLogin`, `TimeoutNoTransfer`, `TimeoutStalled`.

## TimeoutLinger

Syntax: TimeoutLinger seconds
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. The maximum allowed seconds is 65535 (108 minutes).

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`

## Umask

Syntax: Umask file-umask [dir-umask]
Default: None
Context: "server config", <VirtualHost>, <Global>, <Anonymous>, .ftpaccess
Module: mod_core
Compatibility: 0.99.0 and later

The `Umask` directive sets the mask applied to newly created file and directory permissions. Any parameters supplied must be an octal number, in the format `0xxx`.

An optional second dir-umask parameter can specify a different `Umask` to be used when creating directories, rather than files. If this second parameter is not used, directories are created using the file-umask value from the first parameter. For more information on umasks, consult your operating system documentation/man pages.

Note: ProFTPD will not create files that have the executable bit enabled; this is a security-driven design decision. The permissions of an uploaded file can be changed by issuing a `SITE CHMOD` command, e.g.:

      SITE CHMOD 0755 /path/to/uploaded/file

The `Umask` howto also talks about umasks in greater detail.

## <VirtualHost>

Syntax: <VirtualHost ip-address|dns-name [ip-address|dns-name ...]>
Default: None
Context: "server config"
Module: mod_core
Compatibility: 0.99.0 and later

The `<VirtualHost>` configuration section is used to create an independent set of configuration directives that apply to a particular hostname or IP address. It is often used in conjunction with system level IP aliasing or dummy network interfaces in order to establish one or more virtual servers which all run on the same physical machine. The section is terminated with a `</VirtualHost>` directive.

By using the `Port` directive inside a `<VirtualHost>` section, it is possible to create a virtual server which uses the same IP address as the master server, but which listens on a different TCP port (Note, however, that this approach is incompatible with a `ServerType` of "inetd").

When `proftpd` starts up, virtual server connections are handled in one of two ways, depending on the `ServerType` setting:

- inetd

  The daemon examines the destination address and port of the incoming connection being handed off from `inetd/xinetd`. If the connection matches one of the configured `<VirtualHost>` sections, the connection is handled by that matching configuration. If no `<VirtualHost>` section matches, and the main server does not match, the client is informed that no server is available to handle their requests, and the client is disconnected.

- standalone

  After parsing the configuration file, the daemon begins listening for connections on all configured ports, spawning child processes as necessary to handle connections for either the main server or any `<VirtualHost>` sections.

  Because of the method that the daemon uses to listen for connections when in standalone mode, it is possible to support an exceedingly large number of virtual servers, potentially exceeding the number of per-process file descriptors. This is due to the fact that a single file descriptor is used to listen to each configured port, regardless of the number of addresses being monitored. Note that it may be necessary to increase the `TCPBackLog` value on heavily loaded servers in order to avoid kernel-rejected client connections; clients will receive a "Connection refused" error when this condition happens.

Starting with `proftpd-1.3.0rc1`, it is possible to use more than one DNS name or IP address. And starting with `proftpd-1.3.5rc1`, a device/interface name can also be used.

Examples:

      <VirtualHost host1.domain.com host2.domain.com>
        ...
      </VirtualHost>

      # Establish a virtual server for the eth1 interface
      <VirtualHost eth1>
        ...
      </VirtualHost>

The virtual server howto also talks about virtual servers in greater detail.

See also: `DefaultAddress`

## Installation

The `mod_core` module is always installed.

Author: $Author: castaglia $
Last Updated: $Date: 2013/01/10 00:21:34 $

© Copyright 2000-2013 The ProFTPD Project
All Rights Reserved