ProFTPD module mod_core



The mod_core module handles most of the core FTP commands.

Directives


Allow

Syntax: Allow [from] "all"|"none"|host|network|...]
Default: Allow from all
Context: <Limit>
Module: mod_core
Compatibility: 0.99.0p16 and later

The Allow directive is used inside a <Limit> section to explicitly specify which hosts and/or networks have access to the commands or operations being limited. Allow is typically used in conjunction with the Order and Deny directives in order to create sophisticated access control rules.

Allow takes an optional first parameter: the keyword "from". Using "from" is purely cosmetic. The remaining parameters are expected to be a list of hosts and/or networks which will be explicitly granted access. The keyword "all" can be used to indicate that all hosts will explicitly be granted access; this "all" keyword is analogous to the AllowAll directive, except with a lower priority. In addition, the keyword "none" can be used to indicate that no hosts or networks will be explicitly granted access. Note, though, that using "none" does not prevent the hosts/networks from being implicitly granted access. If the "all" or "none" keywords are used, no other hosts or networks can be supplied.

Host and network addresses can be specified by name or by numeric address. For security reasons, it is recommended that all address information be supplied using IP addresses. Relying solely on DNS names causes access controls to depend heavily upon DNS servers which themselves may be vulnerable to attack or spoofing. IP addresses which specify an entire network should end in a trailing period (i.e. "10.0.0." for the entire 10.0.0 subnet). DNS names which specify an entire network should begin with a leading period (i.e. ".proftpd.org" for the entire proftpd.org domain).

Examples:

  <Limit LOGIN>
    Order allow,deny
    Allow from 128.44.26. 128.44.27. myhost.mydomain.edu .trusted-domain.org
    Deny from all
  </Limit>

See also: Deny, <Limit>, Order


AllowAllow

Syntax: AllowAll
Default: None
Context: <Anonymous>, <Limit>, <Directory>, .ftpaccess
Module: mod_core
Compatibility: 0.99.0 and later

The AllowAll directive explicitly allows access to its parent <Anonymous>, <Limit>, or <Directory> configuration section.

The default ProFTPD behavior is to implicitly allow access, which has a low priority. The AllowAll directive creates an explicit allow rule, overriding any higher level Deny directives.

See also: DenyAll


AllowClass

Syntax: AllowClass ["AND"|"OR"|"regex"] expression
Default: None
Context: <Limit>
Module: mod_core
Compatibility: 1.2.10rc1 and later

The AllowClass directive specifies an expression of classes that are permitted access within the parent <Limit> configuration section. The expression parameter has a similar syntax as that used in AllowGroup, in that the parameter should contain a comma delimited list of class names (or "not" class names, by prefixing a class name with the ! character) that are to be allowed access in that configuration section.

By default, the expression is parsed as a Boolean "OR" list, meaning that any elements of the expression must evaluate to logically true in order for the explicit allow rule to apply, e.g. "this name or that name or this other name...". In order to treat the expression as a Boolean "AND" list, meaning that all of the elements must evaluate to logically true (e.g. "this name and not that name..."), use the optional AND keyword. Similarly, to treat the expression as a regular expression, use the regex keyword.

Examples:

  # An OR-evaluated AllowClass directive
  AllowClass OR known,good,trusted

  # An AND-evaluated AllowClass directive
  AllowClass AND good,!scanner

  # A regular expression AllowClass directive
  AllowClass regex ^known

See also: AllowUser, AllowGroup, DenyClass, DenyGroup, DenyUser


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 directive 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 given pattern will be evaludated. The supported flags are:

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


AllowForeignAddress

Syntax: AllowForeignAddress on|off
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_core
Compatibility: 1.1.7 and later

Normally, proftpd disallows clients from using the FTP PORT or EPRT command with anything other than their own IP address (i.e. the source IP address of the FTP control connection), as well as preventing the use of PORT or EPRT to specify a low-numbered (i.e. less than 1024) port number. In either case, the client is sent an "Invalid port" response error and a message is logged indicating either "address mismatch" or "bounce attack".

By enabling the AllowForeignAddress directive, proftpd will allow clients to transmit foreign data connection addresses that do not match the client's IP address. This allows such tricks as permitting a client to transfer a file between two FTP servers without involving itself in the actual data connection. However, allowing this functionality is generally considered a bad idea, security-wise. The AllowForeignAddress directive only affects FTP data connection addresses; not TCP ports. There is no way (and no valid reason) to allow a client to use a low-numbered port in its PORT or EPRT command.


AllowGroup

Syntax: AllowGroup ["AND"|"OR"|"regex"] expression
Default: None
Context: <Limit>
Module: mod_core
Compatibility: 1.1.1 and later

The AllowGroup directive configures an expression that is specifically permitted within the context of the containing <Limit> section. The expression parameter should contain a comma separated list of group names, or "not" groups (by prefixing a group name with the ! character), that are to be allowed access to the section.

By default, the expression is evaluated as a Boolean AND list, meaning that all elements of the expression must evaluate to logically true (i.e. "this group and this group and that group...") in order to the explicit allow rule to apply. To evaluate the expression as a Boolean OR list, meaning that any of the elements must evaluate to logically true (i.e. "this group or this group or that group..."), use the optional OR keyword. Similarly, to evalulate the expression as a regular expression, use the regex keyword.

Examples:

  <Limit LOGIN>
    # Allow logins from users in the the www OR doc groups
    AllowGroup OR www,doc

    # Allow logins from users in the ftp group and not in the admin group
    AllowGroup AND ftp,!admin

    # Deny logins from any group starting with "sys"
    DenyGroup regex ^sys
  </Limit>

See also: AllowUser, DenyGroup, DenyUser


AllowOverride

Syntax: AllowOverride on|off
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_core
Compatibility: 1.2.7rc1 and later

Normally, the proftpd server will look for, and parse, any files named .ftpaccess in the encountered directories. These files provide functionality similar to Apache's .htaccess files -- mini-configuration files. This AllowOverride directive controls when/if these .ftpaccess files will be parsed.


AllowUser

Syntax: AllowUser ["AND"|"OR"|"regex"] expression
Default: None
Context: <Limit>
Module: mod_core
Compatibility: 1.1.7 and later

The AllowUser directive configures an expression that is specifically permitted within the context of the containing <Limit> section. The expression parameter should contain a comma separated list of user names, or "not" users (by prefixing a user name with the ! character), that are to be allowed access to the section.

Now, unlike AllowGroup, the AllowUser expression is evaluated as a Boolean OR list by default, meaning that any elements of the expression must evaluate to logically true (i.e. "this user or this user or that user...") in order to the explicit allow rule to apply. To evaluate the expression as a Boolean AND list, meaning that all of the elements must evaluate to logically true (i.e. "this user and this user and that user..."), use the optional AND keyword. (Note that a single user cannot be "this user and that user" at the same time, thus the value of AND lists for users is debatable.) Similarly, to evalulate the expression as a regular expression, use the regex keyword.

Examples:

  <Limit RETR>
    # Allow these users to download
    AllowUser OR alice,bob,chuck

    # Or these users, based on our regex
    AllowUser regex ^ftp_
  </Limit>

See also: AllowGroup, DenyGroup, DenyUser


<Anonymous>

Syntax: <Anonymous anon-directory>
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_core
Compatibility: 0.99.0 and later

The <Anonymous> configuration section is used to create an anonymous FTP login, and is closed by a matching </Anonymous> directive. The anon-directory parameter specifies the directory to which the daemon, immediately after successful authentication, will restrict the session via chroot(2).

Once the chroot(2) successfully completes, higher level directories are no longer accessible to that session process (and thus to the logged in user). By default, ProFTPD assumes an anonymous login if the remote client attempts to authenticate as the currently running User for that server. Unless the current user is "root", in which case anonymous logins are not allowed regardless of the presence of an <Anonymous> section. To force anonymous logins to be bound to a user other than the current user, see the User and Group directives. In addition, if a User or Group directive is present in an <Anonymous> section, ProFTPD permanently switches to that UID/GID before the chroot(2).

Normally, anonymous logins are not required to authenticate with a password, but are expected to enter a valid email address in place of a normal password; this email address is logged. If this behavior is undesirable for a given <Anonymous> configuration section, it can be overridden via the AnonRequirePassword directive.

The following is an example of a typical anonymous FTP configuration:

  <Anonymous /home/ftp>
    # After anonymous login, daemon runs as user/group ftp.
    User ftp
    Group ftp

    # The client login 'anonymous' is aliased to the "real" user 'ftp'.
    UserAlias anonymous ftp

    # Deny write operations to all directories, except for 'incoming' where
    # STOR is allowed (but READ operations are prohibited).
    <Directory *>
      <Limit WRITE>
        DenyAll
      </Limit>
    </Directory>

    <Directory incoming>
      <Limit READ>
        DenyAll
      </Limit>

      <Limit STOR>
        AllowAll
      </Limit>
    </Directory>
  </Anonymous>


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


<Class>

Syntax: <Class name>
Default: None
Context: server config
Module: mod_core
Compatibility: 1.2.10rc1 and later

The <Class> and </Class> encompass a section which defines and names a connection class.

Example:

  <Class LAN>
    From 192.168.0.0/16
  </Class>
These connection classes are covered in much greater detail in the Classes howto.


CommandBufferSize

Syntax: CommandBufferSize size
Default: CommandBufferSize 512
Context: server config, <VirtualHost>, <Global>
Module: mod_core
Compatibility: 1.2.0pre7 and later

The CommandBufferSize directive controls the maximum command size (in bytes) permitted to be sent to the server. This allows you to effectively control the longest command the server may accept, and can help protect the server from various Denial of Service or resource-consumption attacks.


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>


DefaultServer

Syntax: DefaultServer on|off
Default: None
Context: server config, <VirtualHost>
Module: mod_core
Compatibility: 0.99.0 and later

The DefaultServer directive controls which server configuration is used as the fallback when a matching vhost cannot be found for an incoming connection.

Normally, if the incoming connection is destined for an IP address which is neither the host's primary IP address nor one of the addresses specified in a <VirtualHost> configuration section, the "unknown" connection receives the following response:

  500 Sorry, no server available to handle request on a.b.c.d
and is disconnected. When DefaultServer is enabled for either the primary server configuration or a virtual server, these "unknown" connections are handled by that configuration.

Only a single server configuration can be set as the DefaultServer.


Define

Syntax: Define label
Default: None
Context: any
Module: mod_core
Compatibility: 1.2.6rc1 and later

The Define directive defines a label, and is used in conjunction with <IfDefine> to provide conditional configuration sections. This directive is the configuration file equivalent of the -D command-line option.

Example:

  # Define ANONYMOUS (or comment this out), for anonymous login support
  Define ANONYMOUS

  # If the label ANONYMOUS is defined, use this <Anonymous> section
  <IfDefine ANONYMOUS>
    <Anonymous ~ftp>
      ...
    </Anonymous>
  </IfDefine>


Deny

Syntax: Deny [from] "all"|"none"|host|network...
Default: None
Context: <Limit>
Module: mod_core
Compatibility: 0.99.0p16 and later

The Deny directive is used to create a list of hosts and/or networks which will explicitly be denied access to a given <Limit> section. The keywords "all" and "none" can be used to indicate that all hosts are denied access, or that no hosts are explicitly denied, respectively. For more information on the syntax and usage of the Deny directive, see the Allow description.

Examples:

  <Limit LOGIN>
    Order deny,allow
    Deny from 128.44.26.,128.44.27.,.evil-domain.com
    Allow from all
  </Limit>

See also: Allow, <Limit>, Order


DenyAll

Syntax: DenyAll
Default: None
Context: <Anonymous>, <Limit>, <Directory>, .ftpaccess
Module: mod_core
Compatibility: 0.99.0 and later

The DenyAll directive explicitly denies access to its parent <Anonymous>, <Limit>, or <Directory> configuration section.

The default ProFTPD behavior is to implicitly allow access, which has a low priority. The DenyAll directive creates an explicit deny rule, overriding any higher level Allow directives.

See also: AllowAll


DenyClass

Syntax: DenyClass ["AND"|"OR"|"regex"] expression
Default: None
Context: <Limit>
Module: mod_core
Compatibility: 1.2.10rc1 and later

The DenyClass directive specifies an expression of classes that are denied access within the parent <Limit> configuration section. The expression parameter has a similar syntax as that used in AllowGroup, in that the parameter should contain a comma delimited list of class names (or "not" class names, by prefixing a class name with the ! character) that are to be denied access in that configuration section.

By default, the expression is parsed as a Boolean "OR" list, meaning that any elements of the expression must evaluate to logically true in order for the explicit deny rule to apply, e.g. "this name or that name or this other name...". In order to treat the expression as a Boolean "AND" list, meaning that all of the elements must evaluate to logically true (e.g. "this name and not that name..."), use the optional AND keyword. Similarly, to treat the expression as a regular expression, use the regex keyword.

Examples:

  # An OR-evaluated DenyClass directive
  DenyClass OR bad,scanner,spammer

  # An AND-evaluated DenyClass directive
  DenyClass AND bad,!known

  # A regular expression DenyClass directive
  DenyClass regex ^spam

See also: AllowUser, AllowClass, AllowGroup, DenyGroup, DenyUser


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 parameter 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 given pattern will be evaludated. The supported flags are:

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


DenyGroup

Syntax: DenyGroup ["AND"|"OR"|"regex"] expression
Default: None
Context: <Limit>
Module: mod_core
Compatibility: 1.1.1 and later

The DenyGroup directive configures an expression that is specifically permitted within the context of the containing <Limit> section. The expression parameter should contain a comma separated list of group names, or "not" groups (by prefixing a group name with the ! character), that are to be denied access to the section.

By default, the expression is evaluated as a Boolean AND list, meaning that all elements of the expression must evaluate to logically true (i.e. "this group and this group and that group...") in order to the explicit deny rule to apply. To evaluate the expression as a Boolean OR list, meaning that any of the elements must evaluate to logically true (i.e. "this group or this group or that group..."), use the optional OR keyword. Similarly, to evalulate the expression as a regular expression, use the regex keyword.

Examples:

  <Limit LOGIN>
    # Deny logins from users in the the www OR doc groups
    DenyGroup OR www,doc

    # Deny logins from users in the ftp group and not in the admin group
    DenyGroup AND ftp,!admin

    # Allow logins from any group starting with "sys"
    AllowGroup regex ^sys
  </Limit>

See also: AllowGroup, AllowUser, DenyUser


DenyUser

Syntax: DenyUser ["AND"|"OR"|"regex"] expression
Default: None
Context: <Limit>
Module: mod_core
Compatibility: 1.1.7 and later

The DenyUser directive configures an expression that is specifically denied within the context of the containing <Limit> section. The expression parameter should contain a comma separated list of user names, or "not" users (by prefixing a user name with the ! character), that are to be denied access to the section.

Now, unlike AllowGroup, the DenyUser expression is evaluated as a Boolean OR list by default, meaning that any elements of the expression must evaluate to logically true (i.e. "this user or this user or that user...") in order to the explicit deny rule to apply. To evaluate the expression as a Boolean AND list, meaning that all of the elements must evaluate to logically true (i.e. "this user and this user and that user..."), use the optional AND keyword. (Note that a single user cannot be "this user and that user" at the same time, thus the value of AND lists for users is debatable.) Similarly, to evalulate the expression as a regular expression, use the regex keyword.

Examples:

  <Limit RETR>
    # Deny to these users downloading
    DenyUser OR alice,bob,chuck

    # Or these users, based on our regex
    DenyUser regex ^ftp_
  </Limit>

See also: AllowGroup, AllowUser, DenyGroup


<Directory>

Syntax: <Directory path>
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_core
Compatibility: 0.99.0 and later

The <Directory> section creates a set of configuration directives which applies only to the specified directory and its sub-directories. The section is ended with a matching </Directory>. Per-directory configuration is implemented with a "closest" match algorithm, meaning that the <Directory> section with the closest matching path to the actual path of the file/directory in question is used. Per-directory configuration is inherited by all sub-directories until a closer matching <Directory> is found.

A trailing slash and wildcard ("/*") can be appended to the path, specifying that the configuration section applies only to the contents (and sub-contents), not to the actual directory itself. Such wildcard matches always take precedence over non-wildcard <Directory> configuration sections. <Directory> sections cannot be nested; they are automatically nested at runtime based on their paths. Paths must always be absolute (except inside <Anonymous> sections), and should not reference symbolic links. Path inside of an <Anonymous> section may be relative, indicating that they are based on the <Anonymous> root directory.

As of proftpd-1.1.3 and later, <Directory> paths that begin with the special character ~, and which do not specify a username immediately after the ~ character, are put into a special deferred mode. When deferred mode, the <Directory> section is not merged into the overall server configuration at startup time, but instead the merge is deferred until the client has authentication, at which time the ~ character is replaced with that authenticated user's home directory. This allows for a <Directory> section which applies to all users' home directories. This feature is not supported within an <Anonymous> section, however.

Some examples:

  <Directory /users/robroy/private>
    HideNoAccess on
  </Directory>

  <Directory ~/anonftp>
    <Limit WRITE>
      DenyAll
    </Limit>
  </Directory>

More information on using <Directory> sections, including examples, can be found in the <Directory> howto.


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


FSCachePolicy

Syntax: FSCachePolicy on|off|size count [maxAge secs]
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_core
Compatibility: 1.3.6rc1 and later

The FSCachePolicy directive configures the internal filesystem-related cache, used for performance optimizations on e.g. network filesystems. This directive can be used to disable this internal cache, or to tune the caching policy.

To disable the cache altogether, use:

  FSCachePolicy off

To configure the maximum number of entries in the cache before eviction happens:

  FSCachePolicy size 64

To configure the maximum age (in seconds) of a cached entry before it is evicted:

  FSCachePolicy maxAge 60

The size and maxAge parameters can be combined/set in the same directive, e.g.:

  # Set the maximum cache size at 128, and the max age at 120 seconds
  FSCachePolicy size 128 maxAge 120

FSOptions

Syntax: FSOptions opt1 ...
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_core
Compatibility: 1.3.6rc3 and later

The FSOptions directive configures various optional behavior of ProFTPD's filesystem API. The currently supported options are:



Global

Syntax: <Global>
Default: None
Context: server config, <VirtualHost>
Module: mod_core
Compatibility: 1.16 and later

The <Global> section is used to create a set of configuration directives; this set is then applied universally to both the main server configuration and all <VirtualHost> sections. Most, but not all, other directives can be used inside of a <Global> section.

In addition, multiple <Global> sections can be used in the configuration file. At startup, all <Global> sections are combined, and then merged into each server's configuration. <Global> sections are closed by a matching </Global> directive.


Group

Syntax: Group name
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_core
Compatibility: 0.99.0 and later

The Group directive configures which GID ProFTPD will use when running. See the User directive for details.


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


HideFiles

Syntax: HideFiles [!]regex|"none"]
Default: None
Context: <Directory>, .ftpaccess
Module: mod_core
Compatibility: 1.2.7rc1 and later

The HideFiles directive configures a <Directory> section to hide all directory entries, e.g. its files and sub-directories, that match the given regex. These files can still be operated on by other FTP commands (DELE, RETR, etc), as constrained by any applicable <Limit> sections; this can be modified using the IgnoreHidden directive.

Since <Directory> configurations are inherited by sub-directories, the none keyword can be used to disable any inherited file hiding within a sub-directory. This usually occurs through the use of a .ftpaccess file.

Examples:

  <Directory />
    # Hide configuration and passwd files from view
    HideFiles "(\\.conf|passwd)$"

    # ...or the same regex, without the quotes
    HideFiles (\.conf|passwd)$

    # Using the ! prefix to "invert" the regular expression matching,
    # allow only .txt and .html files to be seen
    HideFiles !(\.txt|\.html)$
  </Directory>

See also: HideGroup, HideNoAccess, HideUser


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


IgnoreHidden

Syntax: IgnoreHidden on|off
Default: IgnoreHidden off
Context: <Limit>
Module: mod_core
Compatibility: 0.99.0 and later

The IgnoreHidden directive tells ProFTPD to ignore files/directories that are hidden by other directives, such as HideFiles, HideUser, and HideGroup.

Normally, files marked as "hidden" by HideFiles, HideUser or HideGroup can be operated on by all FTP commands (assuming Unix file permissions allow access); these files simplly do not appear in directory listings. Additionally, even when normal file system permissions deny access, ProFTPD returns a "Permission denied" error to the client, indicating that the requested file/directory does exist, even if the client cannot use it. The IgnoreHidden directive configures a <Limit> section so as to completely ignore any hidden directory entries for the set of FTP commands encompassed by the <Limit>. This has the effect of returning an error similar to "No such file or directory" when the client attempts to use the command upon a hidden directory or file.

Example:

  <Directory />
    # Hide files/directories owned by root
    HideUser root

    <Limit DIRS>
      # Return "No such file or directory" for hidden files/directories
      IgnoreHidden on
    </Limit>
  </Directory>

See also: HideFiles, HideGroup, HideUser


<IfDefine>

Syntax: <IfDefine [!]label>
Default: None
Context: any
Module: mod_core
Compatibility: 1.2.6rc1 and later

The <IfDefine> and </IfDefine> define a conditional configuration section. The directives appearing within that section are processed only if the label expression, used by <IfDefine>, is true/exists. Otherwise, everything within the configuration section is skipped.

For example, assume you had something like the following in your proftpd.conf:

  <IfDefine USE_TLS>
    TLSEngine on
    TLSRequired on
    ...
  </IfDefine>
Then you can enable that TLS functionality using the -D command-line option when starting ProFTPD, e.g.:
  $ /usr/local/sbin/proftpd -DUSE_TLS ...

For configuration for which there are multiple conditions, you would use multiple nested <IfDefine> sections, e.g.:

  <IfDefine USE_TLS>
    TLSEngine on

    <IfDefine !REQUIRE_TLS>
      # Require TLS for authentication, but allow clients to downgrade back
      # to plain TCP after that.
      TLSRequired auth
    </IfDefine>

    <IfDefine REQUIRE_TLS>
      # Require TLS for control and data connections
      TLSRequired on
    </IfDefine>
  </IfDefine>

See also: Define


<IfModule>

Syntax: <IfModule [!]module-name>
Default: None
Context: any
Module: mod_core
Compatibility: 1.2.6rc1 and later

The <IfModule> and </IfModule> define a conditional configuration section. The directives appearing within that section are processed only if the module-name , used by <IfModule>, is present/loaded. Otherwise, everything within the configuration section is skipped.

Example:

  <IfModule mod_load.c>
    MaxLoad 10 "Acces denied, server too busy"
  </IfModule>

For configuration for which there are multiple modules required, you would use multiple nested <IfModule> sections, e.g.:

  <IfModule mod_sql.c>
    SQLEngine on

    <IfModule mod_sql_mysql.c>
      # Use an SQLConnectInfo using MySQL parameters
    </IfModule>

    <IfModule !mod_sql_mysql.c>
      <IfModule mod_sql_sqlite.c>
        # No mod_sql_mysql, but we do have mod_sql_sqlite available;
        # use an SQLConnectInfo to a local SQLite database file.
      </IfModule>
    </IfModule>

    <IfModule mod_sql_passwd.c>
      # Try more different password hashes with mod_sql_passwd
      SQLAuthTypes ...
    </IfModule>

    <IfModule !mod_sql_passwd.c>
      # Use only the basic SQLAuthTypes provided by mod_sql
      SQLAuthTypes Crypt OpenSSL
    </IfModule>
  </IfModule>

See also: Define


Include

Syntax: Include path|pattern
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Limit>, <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

Note that an Include directive appearing inside of a <Limit> section which itself is in a .ftpaccess file will be ignored. Include directives are not allowed in .ftpaccess files, even indirectly.


IncludeOptions

Syntax: IncludeOptions opt1 ...
Default: None
Context: server config
Module: mod_core
Compatibility: 1.3.6rc3 and later

The IncludeOptions directive is used to configure various optional behavior of Include directive. For example:

  IncludeOptions IgnoreTempFiles

The currently implemented options are:


<Limit>

Syntax: <Limit cmd-list>
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>, <Directory>, .ftpaccess
Module: mod_core
Compatibility: 0.99.0 and later

The <Limit> section is used to place access restrictions on one or more FTP commands, within a given configuration section. Limits flow downward, so that a <Limit> section in the "server config" context applies to all <Directory> and <Anonymous> sections that also reside in that configuration. Any number of command parameters can be specified in the cmd-list, against which the contents of the <Limit> section will be applied.

<Limit> command restrictions should not be confused with file/directory access permission. While limits can be used to restrict a command in a certain directory, they cannot be used to override the file permissions; limits cannot grant access if the underlying filesystem restricts access.

More information on using <Limit> sections, including examples, can be found in the <Limit> howto.


MasqueradeAddress

Syntax: MasqueradeAddress ip-address|dns-name|device-name
Default: None
Context: server config, <VirtualHost>, <Global>
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 seconds.


MaxConnectionRate

Syntax: MaxConnectionRate count [interval]
Default: None
Context: server config
Module: mod_core
Compatibility: 1.2.7rc1 and later

The MaxConnectionRate directive is used to configure a maximum count of connections per time interval (in seconds). If this connection rate is reached, proftpd will simply close additional connections, until the connection rate drops below the threshold. The default interval is 1 second.

For example:

  MaxConnectionRate 200
sets a maximum connection rate of 200 connections per sec. Or:
  MaxConnectionRate 500 2
sets a maximum connection rate of 500 connections every 2 seconds.


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 clients will not receive an FTP response in this case, but instead will encounter connection-level errors such as "Connection reset by peer". In order to provide a more user-facing error message, use the MaxClients directive, set to a value lower than MaxInstances, e.g.:

  # Set MaxClients lower than MaxInstances, so that clients receive a nicer error message when they are rejected.
  MaxClients 100
  MaxInstances 101

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.


MultilineRFC2228

Syntax: MultilineRFC2228 on|off
Default: MultilineRFC2228 off
Context: server config, <VirtualHost>, <Global>
Module: mod_core
Compatibility: 1.2.0pre3 and later

By default, ProFTPD sends multi-line responses as per RFC 959, i.e.:

  200-First line
   More lines...
  200 Last line

RFC 2228 specifies that "6xy" responses will be sent as follows:

  600-First line
  600-More lines...
  600 Last line
Note that RFC 2228 only specifies this format for response codes starting with '6'.

Enabling the MultilineRFC2228 directive causes all multiline responses to be sent in this format, which may be more compatible with certain web browsers and clients. Using this format multiline responses is more likely to be compatible with all clients, although it is not strictly RFC compliant, and is thus not enabled by default.


Order

Syntax: Order "allow,deny"|"deny,allow"
Default: Order allow,deny
Context: <Limit>
Module: mod_core
Compatibility: 0.99.0p16 and later

The Order directive configures the order in which Allow and Deny directives are checked inside of a <Limit> configuration section.

Allow directives are permissive, and Deny directives restrictive, thus the order in which they are examined can significantly alter the way access control functions. If the default setting of allow,deny is used, then "allowed" access permissions are checked first. If an Allow directive explicitly allows access to the <Limit> section, access is granted, and any Deny directives are never checked. However, if Allow directives do not explicitly permit access, Deny directives are checked. And if any Deny directive applies, access is explicitly denied. Otherwise, access is granted.

When deny,allow is used, Deny directive access restrictions are checked first. If any restriction applies, access is denied immediately. If nothing is denied, then Allow permissions are checked. If an Allow directive explicitly permits access, access is permitted; otherwise access is implicitly denied.

For clarification, the following illustrates the steps used when checking Allow/Deny access:

See also: Allow, Deny, <Limit>


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:

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:

The Filters howto covers filtering in greater detail.

See also: PathAllowFilter


PidFile

Syntax: PidFile path
Default: PidFile $prefix/var/proftpd.pid
Context: server config
Module: mod_core
Compatibility: 1.2.0rc2 and later

The PidFile directive configures the path to which the daemon process records its process ID (PID). The path must be an absolute path, e.g. /var/run/proftpd/proftpd.pid. The PidFile is only used in standalone mode.

It is often useful to be able to send the daemon a signal, so that it closes and then reopens its log files (e.g. ExtendedLog, TransferLog), and re-reads its configuration files. This is done by sending the SIGHUP signal to the PID contained in the PidFile -- the PID of the daemon process.


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:


RegexOptions

Syntax: RegexOptions [MatchLimit limit] [MatchRecursionLimit limit]
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_core
Compatibility: 1.3.5rc1 and later

The RegexOptions directive configures limits that can be set on the handling of regular expressions. ProFTPD can use regular expressions for many things; some malicious clients may attempt resource consumption attacks by forcing these regular expressions into very memory/CPU-intensive matching. The RegexOptions directive can be used in such cases to enforce lower limits on the regular expression handling.

The pcreapi documentation talks more about what the match limit and match recursion limit values do.

Note, however, that these limits are only used when PCRE support is enabled (via the --enable-pcre built-time option). If PCRE support is not enabled, this directive has no effect.


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.


ScoreboardScrub

Syntax: ScoreboardScrub on|off|secs
Default: ScoreboardScrub on
Context: server config
Module: mod_core
Compatibility: 1.3.3rc1 and later

The ScoreboardScrub directive configures the "scrubbing" of the ScoreboardFile. Scrubbing can be turned off entirely (not recommended), left on, or configured to run at a custom interval (in seconds).

Example:

  # Disable scoreboard scrubbing
  ScoreboardScrub off

  # Scrub the scoreboard every 2 minutes
  ScoreboardScrub 120


ServerAdmin

Syntax: ServerAdmin email-address
Default: ServerAdmin root@host
Context: server config, <VirtualHost>
Module: mod_core
Compatibility: 0.99.0 and later

The ServerAdmin directive sets the email address of the administrator of the host.

Example:

  ServerAdmin ftp@example.com


ServerAlias

Syntax: ServerAlias hostname ...
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_core
Compatibility: 1.3.6rc1 and later

The ServerAlias directive is used to configure a hostname for the virtual server, such than an FTP client can connect to that virtual server using the HOST command. In effect, you use ServerAlias to define the names that you want to support, for true name-based virtual hosting.

For example, you could define a virtual host using an IP address, and explicitly add the HOST names which should be "hosted" (handled) by that virtual host configuration, like so:

  <VirtualHost 1.2.3.4>
    Port 21
    ServerAlias *.domain.com
    ServerAlias example.com
    ...
  </VirtualHost>
So an FTP client which connected to 1.2.3.4:21, and issued:
  HOST ftp.domain.com
or:
  HOST example.com
would be handled as one would expect.

Defining a virtual host using DNS names would automatically handle the DNS name as a ServerAlias:

  <VirtualHost example.com>
    Port 21
    ...
  </VirtualHost>
would work just like:
  <VirtualHost 1.2.3.4>
    Port 21
    ServerAlias example.com
    ...
  </VirtualHost>
(assuming that "example.com" resolved to 1.2.3.4, of course).


ServerIdent

Syntax: ServerIdent off|on "identification string"
Default: ServerIdent on "ProFTPD 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.

As of proftpd-1.3.6rc3 and later, the default message changed, such that the version information is omitted, becoming:

  "ProFTPD Server (server name) [hostname]"

An example of a custom identification string might be:

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

Note that the following variables can be used in the configured ServerIdent text:

For example:
  ServerIdent on "Welcome to %v"


ServerName

Syntax: ServerName "standalone"|"inetd"
Default: ServerName "ProFTPD" Context: server config, <VirtualHost>
Module: mod_core
Compatibility: 0.99.0 and later

The ServerName directive configures the text that will be displayed to a client connecting to the server. This text will be displayed to the client e.g. as part of the response for a HELP or STAT command.


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.


SetEnv

Syntax: SetEnv name value
Default: None
Context: server config, <Virtual>, <Global>
Module: mod_core
Compatibility: 1.2.10rc1 and later

The SetEnv directive is used to set the environment variable name to value in session processes. Note that if SetEnv is used in the "server config" configuration context, the configured environment value will be set for the ProFTPD daemon process as well.

Examples:

  # Set the TZ environment variable
  SetEnv TZ GMT

See also: UnsetEnv


SocketBindTight

Syntax: SocketBindTight on|off
Default: off
Context: server config
Module: mod_core
Compatibility: 0.99.0pl6 and later

The SocketBindTight directive controls how proftpd creates and binds its initial TCP listening sockets in "ServerType standalone" mode (see ServerType). This directive has no effect upon servers running with "ServerType inetd", because the TCP listening sockets in that mode are not needed or created by proftpd.

When SocketBindTight is set to off (the default), a single TCP listening socket is created for each port that the server must listen on, regardless of the number of IP addresses being used by <VirtualHost> configurations. This has the benefit of requiring a relatively small number of file descriptors (one for each socket) for the master daemon process, even if a large number of virtual servers are configured. Each of these listening sockets is bound to the "wildcard" address, meaning that on all IP addresses on that port (e.g. "*:21").

When SocketBindTight is set to on, a TCP listening socket is created and bound to a specific IP address for the main "server config" server and all configured virtual servers. This allows for situations where an administrator may wish to have a particular port be used by both proftpd (on one IP address) and another daemon (on a different IP address). The drawback is that considerably more file descriptors will be required if a large number of virtual servers must be supported.

Here's an example. Two servers have been configured (one "server config" and one <VirtualHost>), with the IP addresses 10.0.0.1 and 10.0.0.2, respectively. The 10.0.0.1 server runs on port 21, while 10.0.0.2 runs on port 2001.

If we use:

  SocketBindTight off
then proftpd creates two sockets, both bound to all available addresses; one socket listens on port 21 (i.e. "*:21"), the other on port 2001 (i.e. "*.2001"). Since each socket is bound to all available addresses, no other daemon or process will be allowed to bind to ports 21 or 2001.

On the other hand, if we use:

  SocketBindTight on
then proftpd again creates two sockets. However one is bound to 10.0.0.1, port 21 (i.e. "10.0.0.1:21") and the other is bound to 10.0.0.2, port 2001 (i.e. "10.0.0.2:2001"). Thus these sockets are tightly bound to the IP addresses. This means that port 21 can be reused on any address other than 10.0.0.1, and similarly for port 2001 and 10.0.0.2.

One side effect of setting SocketBindTight to on is that connections to non-bound addresses will result in a "connection refused" message rather than the more common (assuming no DefaultServer directive):

  500 Sorry, no server available to handle request on a.b.c.d.
due to the fact that no TCP listening socket has been bound to the particular address/port pair. This may or may not be aesthetically desirable, depending on your circumstances.

See also: DefaultServer


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:

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.


TCPNoDelay

Syntax: TCPNoDelay on|off
Default: TCPNoDelay on
Context: server config, <VirtualHost>, <Global>
Module: mod_core
Compatibility: 1.2.0 and later

The TCPNoDelay directive affects the use of the Nagle algorithm. Note that most sites will never need this.


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: 10
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.


TimesGMT

Syntax: TimesGMT on|off
Default: TimesGMT on
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_core
Compatibility: 1.2.0 and later

The TimesGMT directive configures whether ProFTPD will use timestamps in GMT, not local time, for directory listings (via LIST and NLST commands) and the MDTM command.

To configure ProFTPD to use local time, use:

  TimesGMT off


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:

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.


UnsetEnv

Syntax: UnsetEnv name
Default: None
Context: server config, <Virtual>, <Global>
Module: mod_core
Compatibility: 1.2.10rc1 and later

The UnsetEnv directive is used to unset/remove the name environment variable from the environment for sessions. Note that if the UnsetEnv directive is used in the "server config" configuration context, the name variable is removed from the environment for the ProFTPD daemon process as well.

Examples:

  # Unset the USER and HOME environment variables for sessions
  UnsetEnv USER
  UnsetEnv HOME

See also: SetEnv


UseIPv6

Syntax: UseIPv6 on|off
Default: UseIPv6 on
Context: server config
Module: mod_core
Compatibility: 1.3.1rc1 and later

The UseIPv6 directive enables/disables the use of IPv6.

IPv6 support can also be controlled via command-line options:


User

Syntax: User name
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_core
Compatibility: 0.99.0 and later

The User directive configures the UID that ProFTPD will use when running.

By default, ProFTPD runs as "root"; this is considered undesirable in all but the most trusted network configurations. The User directive, used in conjunction with the Group directive, instructs ProFTPD to switch to the specified UID/GID as quickly as possible after startup.

On some Unix variants, ProFTPD will occasionally switch back to "root" in order to accomplish a task which requires superuser access. Once that task is completed, root privileges are relinquished and the server returns to running as the specified UID/GID. When applied to a <VirtualHost> section, ProFTPD will run as the specified UID/GID on connections destined for the virtual server's address and port. If either User or Group is applied to an <Anonymous> section, ProFTPD will establish an anonymous login when a client attempts to authenticate with that specified User name, as well as permanently switching to the corresponding UID/GID after authentication.


UseReverseDNS

Syntax: UseReverseDNS on|off
Default: UseReverseDNS on
Context: server config
Module: mod_core
Compatibility: 1.1.7 and later

The UseReverseDNS directive is used to control whether ProFTPD performs a reverse DNS lookup on connecting clients, both for control and for data connections. When reverse DNS lookups are enabled, the LogFormat %h variable will use the IP address, rather than the remote hostname.

Normally, incoming active mode data connections and outgoing passive mode data connections have reverse DNS lookups performed on the remote host's IP address. However, when the session is chrooted (e.g. due to the DefaultRoot directive or an <Anonymous> login), the local /etc/hosts file cannot be checked, and the only possible resolution is via DNS. If for some reason, DNS is not available or improperly configured for that remote host, this can result in ProFTPD blocking/stalling until the DNS resolution times out.

Note that using:

  UseReverseDNS on
can lead to delays when connecting to ProFTPD, due to the time needed to perform the forward and reverse DNS resolutions.


UserOwner

Syntax: UserOwner user-name
Default: None
Context: <Anonymous>, <Directory>
Module: mod_core
Compatibility: 1.2pre11 and later

The UserOwner directive is used to specify the user-name which will own all created files and directories within the <Anonymous> or <Directory> section contain the UserOwner directive; the default behavior is that all created files/directories will be owned by the logged-in user, of course.

When the UserOwner directive is used, the GroupOwner directive is not restricted to groups to which the logged-in user belongs.

See also: GroupOwner


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

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.


Frequently Asked Questions

Question: How do I configure proftpd to only listen to connections on one address, e.g. 127.0.0.1? If I use the following in my proftpd.conf:

  DefaultAddress localhost
I am still able to connect to proftpd from another machine.
Answer: The solution is to use the
SocketBindTight, like this:
  DefaultAddress localhost
  SocketBindTight on
The SocketBindTight directive tells proftpd to listen only on that 'localhost' IP address, rather than on all addresses.

Question: When I connect to ProFTPD using FileZilla, I see FileZilla log the following warning:

  Status: Server does not support non-ASCII characters.
even though I used the --enable-nls build option, and my ProFTPD supports UTF8. What is wrong?
Answer: FileZilla parses the FEAT response to determine whether the FTP server supports the UTF-8 encoding. However, the format of the FEAT response can confuse FileZilla's detection code. For example, if your proftpd.conf uses:
  MultilineRFC2228 on
this causes ProFTPD's FEAT response format to be different than FileZilla expects, which can lead to the above "does not support non-ASCII characters" message.

The solution is to use:

  MultilineRFC2228 off
in your proftpd.conf (or simply remove that directive entirely).


© Copyright 2000-2017 The ProFTPD Project
All Rights Reserved