## ProFTPD module `mod_auth_file`

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

## Directives

- AuthFileOptions
- AuthGroupFile
- AuthUserFile

### AuthFileOptions

Syntax: AuthFileOptions opt1 ...
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_auth_file
Compatibility: 1.3.7rc1

The `AuthFileOptions` directive is used to configure various optional behavior of `mod_auth_file`.

Example:

      AuthFileOptions InsecurePerms

The currently implemented options are:

- `InsecurePerms`

  When this option is used, `mod_auth_file` will ignore insecure permissions (i.e. group- or world-readable) on `AuthUserFile` and `AuthGroupFile` files.

  Note that this option must appear before any `AuthUserFile` and `AuthGroupFile` directives in order to function properly, for the option changes the behavior of the `mod_auth_file` module at parse time.

  Note that this option first appeared in `proftpd-1.3.7rc1`.

- `SyntaxCheck`

  When this option is used, `mod_auth_file` will When this option is used, `mod_auth_file` will perform syntax checks on `AuthUserFile` and `AuthGroupFile` files. If any of the files have syntax errors, `mod_auth_file` will cause ProFTPD to fail to start up.

  Note that this option must appear before any `AuthUserFile` and `AuthGroupFile` directives in order to function properly, for the option changes the behavior of the `mod_auth_file` module at parse time.

  Note that this option first appeared in `proftpd-1.3.8rc1`.

### AuthGroupFile

Syntax: AuthGroupFile path [id min-max] [name regex]
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_auth_file
Compatibility: 1.2.7rc2

The `AuthGroupFile` directive configures an alternate group file for providing group membership information; the specified file must have the same format as the system `/etc/group` file, and if specified is used during authentication and group lookups for directory/access control operations. The path argument should be the full path to the specified file. This directive can be configured on a per-server basis, so that virtual FTP servers can each have their own authentication file, often in conjunction with an `AuthUserFile`.

Note that this file does not need to reside inside a `chroot()`ed directory structure for anonymous or `DefaultRoot` logins, as it is held open for the duration of a session.

The optional parameters are used to set restrictions on the contents of the specified file. The id restriction is used to specify a range of GIDs that may appear in the file; when doing a lookup, if a group entry has a GID that is less than the minimum or greater than the maximum is encountered, that entry is ignored. The name restriction is used to specify a regular expression that is applied to the name of a group entry. If the group name does not match the regular expression, the group entry is ignored. A leading `!` in the regular expression can be used to negate the given expression.

Example:

      # This makes an AuthGroupFile that can only have GIDs 2000 to 4000, and
      # whose groups must start with 'cust'
      AuthGroupFile /etc/ftpd/group id 2000-4000 name ^cust

Note: In order to prevent other users from modifying the `AuthGroupFile`, the `mod_auth_file` module requires that the permissions on the file not be world-readable or world-writable, and that the directory containing the file not be world-writable. In addition, if the file is not a file (e.g. the path points to a symlink, or a FIFO, etc), a warning will be logged on server startup/restart.

### AuthUserFile

Syntax: AuthUserFile path [id min-max] [home regex] [name regex]
Default: None
Context: server config, `<VirtualHost>`, `<Global>`
Module: mod_auth_file
Compatibility: 1.2.7rc2

The `AuthUserFile` directive configures an alternate passwd file for providing user account information; the specified file must have the same format as the system `/etc/passwd` file, and if specified is used during authentication and user lookups for directory/access control operations. The path argument should be the full path to the specified file. This directive can be configured on a per-server basis, so that virtual FTP servers can each have their own authentication file, often in conjunction with an `AuthGroupFile`.

Note that this file does not need to reside inside a `chroot()`ed directory structure for anonymous or `DefaultRoot` logins, as it is held open for the duration of a session.

The optional parameters are used to set restrictions on the contents of the specified file. The id restriction is used to specify a range of UIDs that may appear in the file; when doing a lookup, if a user entry has a UID that is less than the minimum or greater than the maximum is encountered, that entry is ignored. The home restriction is used to specify a regular expression that is applied to the home directory of a user entry. If the home does not match the regular expression, the user entry is ignored. The name restriction is used to specify a regular expression that is applied to the name of a user entry. If the user name does not match the regular expression, the user entry is ignored. A leading `!` in these regular expressions can be used to negate the given expression.

Example:

      # This makes an AuthUserFile whose user names must start with 'ftp', and
      # whose homes cannot start with /home.
      AuthUserFile /etc/ftpd/passwd name ^ftp home !^/home

Note: In order to prevent other users from modifying the `AuthUserFile`, the `mod_auth_file` module requires that the permissions on the file not be world-readable or world-writable, and that the directory containing the file not be world-writable. In addition, if the file is not a file (e.g. the path points to a symlink, or a FIFO, etc), a warning will be logged on server startup/restart.

## Installation

The `mod_auth_file` module is compiled by default.

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

- auth.file

Thus for trace logging, to aid in debugging, you would use the following in your `proftpd.conf`:

      TraceLog /path/to/ftpd/trace.log
      Trace auth.file:20

This trace logging can generate large files; it is intended for debugging use only, and should be removed from any production configuration.

Frequently Asked Questions

Question: I found that only the first 8 characters of passwords are used! This is a security bug!
Answer: No, it is not.

The default Unix password hashing scheme uses the Data Encryption Standard (DES) algorithm. As per the `crypt(3)` man page, only the first 8 characters of the password are used. Thus this 8 character limitation comes from the underlying system authentication, not from proftpd. The whole purpose of the PAM system was to enable replacing the use of DES with other authentication algorithms, which do not have this 8 character limitation.

Later, other `crypt(3)` implementations were made which can also support algorithms such as MD5, or Blowfish. Some platforms support these enhanced versions of `crypt(3)`, some do not. The `ftpasswd` script can generate `AuthUserFiles` which use the MD5 algorithm instead of DES.

Question: Why does `mod_auth_file` refuse to use an `AuthUserFile` (or `AuthGroupFile`) that is world-readable/writable? I see messages like the following logged:

      mod_auth_file/1.0: unable to use world-readable AuthUserFile '/etc/proftpd/ftpd.passwd'

or:

      mod_auth_file/1.0: unable to use world-writable AuthUserFile '/etc/proftpd/ftpd.passwd'

Answer: If an `AuthUserFile` or `AuthGroupFile` is world-writable, then any user on the system can edit that file. They can create new users, or change the entries for existing users such that those users have different privileges, perhaps even root privileges. In short, having `AuthUserFile` or `AuthGroupFile` with world-writable permissions is an unsafe configuration, and now `mod_auth_file` prevents this.

If the `AuthUserFile` is world-readable, then any user on the system can read that file, including the hashed password. This can allow for offline dictionary/cracking attempts against those hashes. This is also an unsafe configuration, and thus `mod_auth_file` does not allow world-readable `AuthUserFiles`.

Similarly, `mod_auth_file` will refuse to use an `AuthUserFile` or `AuthGroupFile` if that file lives in a directory, and that directory has world-writable permissions (even if the configured file itself is not world-writable). A world-writable directory would allow any system user to delete the `AuthUserFile`, and add their own, or to add a symlink, etc. It is another unsafe configuration against which `mod_auth_file` now guards.

© Copyright 2002-2021 The ProFTPD Project
All Rights Reserved