ProFTPD module mod_auth



This module is contained in the mod_auth.c file for ProFTPD 1.3.x, and is compiled by default.

Directives


AccessDenyMsg

Syntax: AccessDenyMsg message
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 1.2.2 and later

When an FTP client attempts to authenticate and fails, the client is sent the following FTP response:

  530 Login failed
This "Login failed" response message can be replaced/customized by using this AccessDenyMsg directive. In the configured message text, the %u variable will be resolved to the user name used by the FTP client in its authentication attempt.

Example:

  AccessDenyMsg "%u is not authorized"


AccessGrantMsg

Syntax: AccessGrantMsg message
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 1.2.2 and later

When an FTP client succeeds in authenticating, it will receive an FTP response with the 230 response code, and a message. This successful authentication response message can be replaced/customized by using this AccessGrantMsg directive. In the configured message text, the %u variable will be resolved to the user name used by the FTP client in its authentication attempt.

Example:

  AccessGrantMsg "Welcome, %u!"

AllowChrootSymlinks

Syntax: AllowChrootSymlinks on|off
Default: AllowChrootSymlinks on
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.3.5rc1 and later

The AllowChrootSymlinks directive configures whether proftpd will follow a symlink to the destination directory when performing a chroot(2) call. This applies both to DefaultRoot directives and to <Anonymous> sections.

Security note: If you permit your users the ability to remove directories which might be FTP users' home directories (or <Anonymous> directories) and create symlinks, then you should use:

  AllowChrootSymlinks off
This includes sites which are hosting providers, i.e. which allow users to run their untrusted webapps (e.g. PHP, Perl, Ruby, Python, etc apps) on the servers.


AllowEmptyPasswords

Syntax: AllowEmptyPasswords on|off
Default: AllowEmptyPasswords on
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 1.3.6rc2 and later

The AllowEmptyPasswords directive configures whether proftpd will accept empty passwords or not. For backward compatibility, the default is on.

Note that this applies to mod_sftp password-based logins as well.


AnonAllowRobots

Syntax: AnonAllowRobots on|off
Default: AnonAllowRobots off
Context: <Anonymous>
Module: mod_auth
Compatibility: 1.3.6rc2 and later

The AnonAllowRobots directive configures whether the mod_auth should provide a fake "robots.txt" file to web crawlers/spiders.

Normally such web crawlers/spiders make HTTP requests only. However, Google is known to crawl FTP sites, using anonymous logins only.

To prevent such web crawlers from indexing your FTP site unexpectedly, the mod_auth module will automatically provide a fake "robots.txt" file for anonymous logins, containing:

  User-agent: *
  Disallow: /

If your FTP site deliberately provides its own separate "robots.txt" file already, then mod_auth will serve that existing file as expected. Alternatively, you can disable this behavior using:

  # Restore previous behavior
  AnonAllowRobots on


AnonRejectPasswords

Syntax: AnonRejectPasswords pattern [flags]
Default: None
Context: <Anonymous>
Module: mod_auth
Compatibility: 1.2.9rc1 and later

The AnonRejectPasswords directive configures a regular expression pattern filter for passwords given for anonymous logins. If the given anonymous password matches the configured regular expression pattern, the anonymous login is denied.

Example:

  # Reject all <Anonymous> logins that use "evil.org" as part of the password
  AnonRejectPasswords @evil\.org$

The optional flags parameter can be used to specify flags for the given regular expression; currently the supported flags are:

Thus for a case-insensitive pattern, you would use:
  # Reject all <Anonymous> logins that use "evil.org" as part of the password
  AnonRejectPasswords @evil\.org$ [NC]
or:
  # Reject all <Anonymous> logins that use "evil.org" as part of the password
  AnonRejectPasswords @evil\.org$ [nocase]

If you want to reject any anonymous passwords which do not match the pattern, then prefix your pattern with the ! (exclamation point) character:

  # Reject all <Anonymous> logins that do NOT use "good.org" as part of the password
  AnonRejectPasswords !@good\.org$ [nocase]
Note that this also allows you to use AnonRejectPasswords to require that your anonymous logins use email-like passwords:
  # Require anonymous passwords that look like email addresses.  See:
  #  http://www.regular-expressions.info/email.html
  AnonRejectPasswords !^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$ [NC]


AnonRequirePassword

Syntax: AnonRequirePassword off|on
Default: AnonRequirePassword off
Context: <Anonymous>
Module: mod_auth
Compatibility: 0.99.0 and later

Normally, anonymous FTP logins do not require the client to authenticate themselves using real passwords; instead, anonymous FTP logins are expected to provide their email address as the password. Using AnonRequirePassword on, however, will require a real password for that login. The provided password will be matched against the <Anonymous> user's password.

This functionality, in conjunction with the AuthUsingAlias directive, can be used to create "guest" accounts, which function exactly as normal anonymous logins do, but which require a valid password on the server's host system.

See also: AuthUsingAlias, UserAlias


AuthAliasOnly

Syntax: AuthAliasOnly off|on
Default: AuthAliasOnly off
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.1.3 and later

The AuthAliasOnly directive restricts authentication to "aliased" logins only, i.e. those usernames provided by clients which are "mapped" to a real username by the UserAlias directive. Using AuthAliasOnly on in a particular configuration context will cause ProFTPD to completely ignore all non-aliased logins for the entire context.

See also: AuthUsingAlias, UserAlias


AuthUsingAlias

Syntax: AuthUsingAlias off|on
Default: AuthUsingAlias off
Context: <Anonymous>
Module: mod_auth
Compatibility: 1.2.0pre9 and later

The AuthUsingAlias directive disables the resolving of aliased usernames (via UserAlias) for authentication purposes. For example, if you have aliased the username "anonymous" to the real user "ftp", the password gets checked against the user "anonymous". When AuthUsingAlias is disabled, the checked username would be "ftp".

Here is an example of an <Anonymous> section where only the aliased usernames are allowed to login:

  <Anonymous ~ftp>
    AuthUsingAlias on
    UserAlias anonymous nobody
    UserAlias ftp nobody

    # Make this a read-only anonymous login
    <Limit WRITE>
      DenyAll
    </Limit>
  </Anonymous>
and here, by contrast, is an <Anonymous> section where certain real users are allowed to login using their own passwords (even though it will still be considered an anonymous login):
  <Anonymous ~ftp>
    # Require real passwords for these logins
    AnonRequirePassword on

    AuthAliasOnly on
    AuthUsingAlias on

    # This is the list of authorized users; password checks will occur
    # using their own respective passwords, not user "nobody".
    UserAlias fred nobody
    UserAlias jenn nobody
  </Anonymous>

See also: AnonRequirePassword, UserAlias


CreateHome

Syntax: CreateHome off|on [mode] [skel path] [dirmode mode]...
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.2.8rc2 and later

The CreateHome directive configures the server to automatically create a user's home directory, if that directory does not exist, during the login process.

The mode parameter is used to configure the absolute mode of the home directory created. If not specified, the mode will default to 700.

The optional skel path parameters can be used to configure an /etc/skel-like directory containing account initialization files and directories. The parameter must be the full path to the skeleton directory. The directory must not be world-writeable. Files copied from this directory into the new home directory will have ownership set to the UID and GID of the logging-in user. Note that sockets and FIFOs in the skeleton directory will not be copied; any setuid or setgid bits on files will be removed from the copied files in the target home directory.

The optional dirmode parameter can be used to specify the mode for intermediate directories that may need to be created in order to create the target home directory. By default, the mode for such intermediate directories will be 711. Note: using a mode that does not include the execute bit to be enabled can cause havoc. You have been warned.

Examples:

  # Use the CreateHome default settings
  CreateHome on

  # Specify a skeleton directory
  CreateHome on skel /etc/ftpd/skel

  # No skeleton, but make sure that intermediate directories have 755
  # permissions.
  CreateHome on dirmode 755

  # Skeleton directory, with 700 intermediate directories
  CreateHome on skel /etc/ftpd/skel dirmode 700

A fuller description of the CreateHome directive and its uses, with more examples, can be read here.


DefaultChdir

Syntax: DefaultChdir path [group-expression]
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.2.0rc1

The DefaultChdir directive determines the directory path into which a user is placed, after logging in.

By default, the user is put into their home directory. The specified path can be relative to the user's home directory. Note that if the specified path is not available, then DefaultChdir will be ignored; the direction in which the user is placed will be determined by other directives.

Examples:

  # Admin users start off in /var/www
  DefaultChdir /var/www admin

  # ..and others start off in their respective public FTP folders
  DefaultChdir ~/public_ftp

See also: DefaultRoot


DefaultRoot

Syntax: DefaultRoot path [group-expression]
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.2.0rc1

The DefaultRoot directive is used to chroot() the session process for the connecting client. A fuller explanation can be found in the Chroot howto.


DisplayLogin

Syntax: DisplayLogin path
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 0.99.0

The DisplayLogin directive specifies a file path which will be displayed to the user when they initially login. The path can be either relative or absolute. For relative paths, the file is searched for in the initial directory in which a user is placed immediately after authentication, e.g. the home directory for normal users, or the <Anonymous> directory for anonymous logins. If the file cannot be found or accessed, no error occurs and nothing is displayed to the client.

The DisplayFiles howto covers such files in greater detail.


MaxClients

Syntax: MaxClients count|"none" [message]
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 0.99.0 and later

The MaxClients directive configures the maximum number of authenticated clients which may be logged into a server or <Anonymous> account. Once the count limit is reached, additional clients attempting to authenticate will be disconnected. The special count parameter value of "none" may be used, which disables all other applicable MaxClients directives.

Additionally, an optional message parameter may be used; this message will be displayed to a client attempting to exceed the maximum value, immediately before disconnection. The message parameter is parsed for the variable "%m", which is replaced with the configured maximum value. If a message is not supplied, then following default message is used:

  "Sorry, the maximum number of allowed clients (%m) are already connected."

For example, using:

  MaxClients 5
will result in this FTP response, when the limit is reached:
  "530 Sorry, the maximum number of allowed users are already connected (5)"

See also: MaxClientsPerClass, MaxClientsPerHost, MaxClientsPerUser, MaxHostsPerUser


MaxClientsPerClass

Syntax: MaxClientsPerClass class count|"none" [message]
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.2.10rc1 and later

The MaxClientsPerClass directive configures the maximum number of clients that may be connected at any given time from the same Class. The optional message parameter may be used, which will be displayed to a client attempting to exceed the count maximum value. If message is not supplied, then the following default message is used:

  "Sorry, the maximum number of clients (%m) from your class are already connected."

For example:

  MaxClientsPerClass foo 1 "Only one such client at a time."
results in this FTP response, to a client exceeding the limit:
  "530 Only one such client at a time."

See also: MaxClients, MaxClientsPerHost, MaxClientsPerUser, MaxHostsPerUser


MaxClientsPerHost

Syntax: MaxClientsPerHost count|"none" [message]
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 1.1.7 and later

The MaxClientsPerHost directive configures the maximum number of clients allowed to connect from a host. The optional message parameter may be used, which will be displayed to a client attempting to exceed the count maximum value. If message is not supplied, this default message is used:

  "Sorry, the maximum number clients (%m) from your host are already connected." is used. 

For example:

  MaxClientsPerHost 1 "Sorry, you may not connect more than one time."
results in this FTP response, to a client exceeding the limit:
  "530 Sorry, you may not connect more than one time."

See also: MaxClients, MaxClientsPerClass, MaxClientsPerUser, MaxHostsPerUser


MaxClientsPerUser

Syntax: MaxClientsPerUser count|"none" [message]
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 1.2.7rc1 and later

The MaxClientsPerUser directive configures the maximum number of clients that may be connected at any given time using the same user name. The optional message parameter may be used, which will be displayed to a client attempting to exceed the count maximum value. If message is not supplied, the following default message is used:

  "Sorry, the maximum number of clients (%m) for this user already connected."

For example:

  MaxClientsPerUser 1 "Only one such user at a time."
results in this FTP response, to a client exceeding the limit:
  "530 Only one such user at a time."

See also: MaxClients, MaxClientsPerClass, MaxClientsPerHost, MaxHostsPerUser


MaxConnectionsPerHost

Syntax: MaxConnectionsPerHost count|"none" [message]
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.2.11 and later

The MaxConnectionsPerHost directive configures the maximum number of unauthenticated clients allowed to connect from a given host. The optional message parameter may be used, to be displayed to a client attempting to exceed the maximum value. If message is not supplied, a default message of "Sorry, the maximum number of connections (%m) from your host are already connected." is used.

For example:

  MaxConnectionsPerHost 1 "Sorry, you may not connect more than one time."
results in additional FTP login attempts from that same host to receive the following FTP response:
  530 Sorry, you may not connect more than one time.


MaxHostsPerUser

Syntax: MaxHostsPerUser count|"none" [message]
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 1.2.4 and later

The MaxHostsPerUser directive configures the maximum number of times different hosts, using a given login, can connect at any given time. The optional message parameter may be used, which will be displayed to a client attempting to exceed the maximum value. If message is not supplied, the following message is used by default:

  "Sorry, the maximum number of hosts (%m) for this user already connected."

For example:

  MaxHostsPerUser 1 "Sorry, you may not connect more than one time."
Will result in the following FTP response, when the count limit is exceeded:
  "530 Sorry, you may not connect more than one time."

See also: MaxClients, MaxClientsPerHost


MaxLoginAttempts

Syntax: MaxLoginAttempts count
Default: 3
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 0.99.0 and later

The MaxLoginAttempts directive configures the maximum number of times a client may attempt to authenticate to the server on the same TCP connection. After the number of attempts exceeds the configured count, the client is disconnected and an appropriate message is logged.


MaxPasswordSize

Syntax: MaxPasswordSize length
Default: 1024
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.3.6rc3 and later

The MaxPasswordSize directive configures the maximum length (in bytes) of a password that ProFTPD will accept. Passwords longer than the configured length will be ignored.

This directive is provided as a defensive measure, to protect against CPU resource consumption attacks by feeding large amounts of data to e.g. the crypt(3) function.


RequireValidShell

Syntax: RequireValidShell on|off
Default: RequireValidShell on
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 0.99.0 and later

The RequireValidShell directive configures the server, virtual host or anonymous login to allow or deny logins which do not have a shell listed in /etc/shells. By default, proftpd will not allow a login unless the user's default shell is listed in /etc/shells. If /etc/shells cannot be found, all default shells are assumed to be valid.


RewriteHome

Syntax: RewriteHome on|off
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.3.3rc1 and later

The RewriteHome directive can be used to support rewriting the home directory for a user, based on regular expression rules. One such use case is where some portion of the home directory is retrieved e.g. from an LDAP directory, but you need to apply some custom prefix to the LDAP attribute. Note that this feature requires that the mod_rewrite module also be present in your proftpd daemon.

To enable this feature, first you need to add the following to your proftpd.conf:

  RewriteHome on
Next, you need to configure the mod_rewrite rules for rewriting your home directory; this feature depends on the mod_rewrite module for the rewriting. The pseudo-command used by mod_rewrite for rewriting home directories is "REWRITE_HOME". Thus would you use:
  <IfModule mod_rewrite.c>
    RewriteEngine on
    RewriteLog /path/to/rewrite.log

    RewriteCondition %m REWRITE_HOME
    RewriteRule (.*) /my/new/prefix$1
 </IfModule>


RootLogin

Syntax: RootLogin on|off
Default: RootLogin off
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 1.1.5 and later

Normally, proftpd does not allow root logins under any circumstance. If a client attempts to login as root, using the correct password, a special security message is logged:

  SECURITY VIOLATION: Root login attempted
When RootLogin on is used, the root user may authenticate just as any other user could (assuming no other access control measures deny access); however the root login security message is still logged:
  ROOT FTP login successful.
Obviously, extreme care should be taken when using this directive.

The use of RootLogin in the <Anonymous> context is only valid when the User/Group defined in the <Anonymous> section is set to 'root'.


RootRevoke

Syntax: RootRevoke on|off|UseNonCompliantActiveTransfers
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 1.2.9rc1 and later

The RootRevoke directive causes all root privileges to be dropped once a user is authenticated. This will also cause active data transfers (e.g. via the PORT/EPRT FTP commands) to be disabled if the server is listening on a port less than 1024. Note that this only affects active data transfers; passive transfers will not be blocked.

The reason for rejecting active data transfers in these cases is because of a requirement in RFC 959 (which defines the File Transfer Protocol) that for active data transfers, the data connection must have a source port of L-1, where L is the control connection port (see RFC 959, Section 3.2 "Establishing Data Connections"). Thus if the FTP server listens on port 21, then a client requesting an active data transfer from that server will have a data connection whose source port (on the server) is port 20 (L = 21, L-1 = 20).

Even though passive data transfers are highly preferable, many FTP clients may still require/expect to be able to do an active data transfer. One question, though, is how many FTP clients actually check that the source port of the active data transfer connection is actually L-1. Or how many networking appliances along the way (i.e. firewalls, NATs, routers, etc) enforce this restriction as well.

If not for that requirement, then with "RootRevoke on" in the proftpd.conf, proftpd would not be required to use root privileges for binding to a privileged port like port 20.

Thus the RootRevoke directive also accepts (as of ProFTPD 1.3.5rc1) a parameter of "UseNonCompliantActiveTransfers", e.g.:

  # Drop root privs, but allow active data transfers (only use a non-standard
  # source port for the active data connection).
  RootRevoke UseNonCompliantActiveTranfers
With this configuration, proftpd will drop root privileges, but would not reject PORT/EPRT commands at all. Instead, the active data transfers would be allowed as per normal, except that proftpd would not try to bind to the L-1 port for those active transfers.

This RootRevoke parameter is valuable because it helps in getting proftpd to drop root privileges for sessions more often, which is a far more secure configuration. Exploits such as the "Roaring Beast" attack would not be possible in a session where root privileges have been dropped completely.

Note: In ProFTPD 1.3.7rc1 and later, the default value for RootRevoke became on, meaning that root privileges are dropped by default, unless explicitly configured via this directive. The default behavior is that of the UseNonCompliantActiveTransfers parameter, so that PORT and EPRT commands are not rejected.


TimeoutLogin

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

The TimeoutLogin directive configures the maximum number of seconds a client is allowed to spend authenticating, i.e. from the time when the client connects to the time when the client has successfully authenticated. The login timer is not reset when a client transmits data, and is only removed once a client has transmitted an acceptable combination of USER/PASS commands. The maximum allowed seconds value is 65535 (18 hours).

See also: TimeoutIdle, TimeoutNoTransfer, TimeoutStalled


TimeoutSession

Syntax: TimeoutSessions seconds
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 1.2.6rc1 and later

The TimeoutSession directive sets the maximum number of seconds a control connection between the proftpd server and client can exist, after the client has successfully authenticated. If the seconds argument is set to zero, sessions are allowed to last indefinitely; this is the default. There is no maximum value for the seconds parameter.


UseFtpUsers

Syntax: UseFtpUsers on|off
Default: UseFtpUsers on
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 0.99.0 and later

Legacy FTP servers generally check a special authorization file (typically /etc/ftpusers) when a client attempts to authenticate. If the user's name is found in this file, FTP access is denied. For compatibility of behavior, proftpd defaults to checking this same file during authentication. This behavior can be suppressed using the UseFtpUsers directive, e.g.:

  # Do not check /etc/ftpusers
  UseFtpUsers off


UseLastlog

Syntax: UseLastlog on|off
Default: UseLastlog off
Context: server config, <VirtualHost>, <Global>
Module: mod_auth
Compatibility: 1.3.1 and later

The UseLastlog directive configures whether ProFTPD will update the /var/log/lastlog file for FTP logins.

Example:

  # Enable recording FTP logins in /var/log/lastlog
  UseLastlog on


UserAlias

Syntax: UserAlias alias real-user
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 0.99.0 and later

ProFTPD requires a real username (i.e. known via /etc/passwd, AuthUserFile, LDAP, SQL, RADIUS, etc) when authenticating a client. There are, however, times when an additional alias is required but is undesirable to provide an additional login accounts.

The UserAlias directive provides a mechanism to do just this. A typical and common example of UserAlias is for <Anonymous> configuration sections. It is conventional for the server to use user "ftp" as the primary authentication user; it is common practice to allow users to login using the name "anonymous". This is achieved by using the following in the config file:

  <Anonymous ~ftp>
    ...
    UserAlias anonymous ftp
    ...
  </Anonymous>


UserPassword

Syntax: UserPassword user encrypted-password
Default: None
Context: server config, <VirtualHost>, <Global>, <Anonymous>
Module: mod_auth
Compatibility: 0.99.0pl5 and later

The UserPassword directive creates a password for a particular user; this configured password will override the user's normal password in /etc/passwd (or whichever auth module handles that user). Note that the user configured is a real user, and not a UserAlias.

The encrypted-password parameter is a string which has been passed through the standard Unix crypt(3) function. Do not use a cleartext password. To obtain this encrypted-password value, you can use the ftpasswd script's --hash option, e.g.:

  $ ftpasswd --hash

  Password: 
  Re-type password: 

  ftpasswd: $1$EsnXxyD6$tsO2YwTAT/Tl5u1NYPHIw1

Example configuration:

  # Override user bob's password with a hash version of "password"
  UserPassword bob $1$EsnXxyD6$tsO2YwTAT/Tl5u1NYPHIw1


WtmpLog

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

The WtmpLog directive controls the logging of connections to the host system wtmp file, which used by such commands as last. By default, all connections are logged via wtmp.


Installation

The mod_auth module is compiled by default.


© Copyright 2002-2021
All Rights Reserved