PAM-modules Manual (split by chapter):   Section:   Chapter:FastBack: pamck   Up: Top   FastForward: regex   Contents: Table of ContentsIndex: Concept Index

3 Authentication against an alternative shadow file.

The pam_fshadow module provides authentication against an alternative shadow file, or passwd / shadow pair (or pairs). There are two main operation modes: plain mode, in which pam_fshadow uses only one passwd/shadow pair, and virtual domain mode, which allows to select the pair to use based on the authentication token (the user name). First, let’s describe the plain mode.

3.1 Using pam_fshadow in plain mode.

Plain mode is the default operation mode for pam_fshadow. In this mode, the module checks the supplied user name and authentication token against the passwd/shadow pair located in the system configuration directory (which is set when configuring the package and defaults to prefix/etc). This default location can be changed using the sysconfdir option (see below). The authentication is performed as follows:

First, the user name is looked up in passwd file and the corresponding record is fetched. If this record contains a valid password hash (i.e. its second field is at least 2 characters long), the system crypt function is called on the supplied authentication token with the retrieved hash as its second argument (the seed) and its result is compared with the hash. If the two strings compare equal, the user is authenticated successfully.

Otherwise, if passwd contains no password, the shadow file is examined and hash retrieved from there is used. If the record retrieved from the shadow file has not expired, and if its password hash field matches the authentication token (using the algorithm described above), the user is authenticated successfully.

Several options are provided to alter the default behavior. All of them, except sysconfdir, have the same effect in the virtual domain mode as well. The table below summarizes these options.


Do not require passwd file to be present. Only shadow is used for authentication.


Do not require shadow file to be present. Only passwd is used for authentication. Notice, that it is an error to specify both nopasswd and noshadow.


Set full name of the directory where shadow and passwd are located. By default the system configuration directory will be used.


Do not prompt the user for password, take it from the saved authentication tokens. This option is useful when pam_fshadow is used as a non-first module in a stack of authentication modules.

The following example illustrates the use of pam_fshadow in plain mode in pam.conf file:

tuhs auth  required \
                      sysconfdir=/home/tuhs/tuhs/etc nopasswd use_authtok

3.2 Using pam_fshadow in virtual domain mode.

In virtual domain mode, pam_fshadow uses the user name to determine where to look for the passwd/shadow file pair. The name is split into user name proper and authentication domain. The configuration directory name is then constructed by concatenating the system configuration directory, a directory separator character (‘/’), and the name of the authentication domain. Then, authentication proceeds as described above for the plain mode. If the supplied user name does not match the regular expression, pam_fshadow proceeds as in plain mode.

This mode is enabled by the option regex, which supplies a regular expression to split user names. This regular expression must contain two parenthesized groups. First of them is used to extract the user name, and the second one is used to extract the authentication domain. For example, the following option:


instructs pam_fshadow to use any characters before the ‘@’ as the user name, and anything following it as the authentication domain.

Several options are provided, that control the type of regular expression and the way of retrieving authentication data from the user name. These options are:


Use basic regular expression.


Use extended regular expression. This is the default.


Use case-insensitive regular expression.


Use case-sensitive regular expressions (default).


Use group #2 as the user name and group #1 as the authentication domain.

As an example, consider the following pam.conf entry:

check auth required \
   sysconfdir=/etc/auth regex=(.*)@(.*) extended 

It instructs pam_fshadow to use ‘@’ as the username/domain separator and to look up password databases under the /etc/auth directory. For example, if the supplied user name was ‘smith@ftp’, then the module will look for the user name ‘smith’ in files /etc/auth/ftp/passwd and /etc/auth/ftp/shadow.

3.3 Summary of pam_fshadow options

This section summarizes all pam_fshadow command line options:


Use basic regular expressions. See virtual domain mode.


Use extended regular expression (default). See virtual domain mode.


Use case-insensitive regular expressions. See virtual domain mode.


Use only shadow for authentication. See nopasswd.


Use only passwd for authentication. See noshadow.


Define a regular expression for splitting user name into the proper name and authentication domain.


In the regular expression introduced by regex, group #1 selects authentication domain, and group #2 selects user name. See revert-index.


Assume dir as the system configuration directory. See sysconfdir.


Do not prompt the user for password, take it from the saved authentication tokens.

See use_authtok.

PAM-modules Manual (split by chapter):   Section:   Chapter:FastBack: fshadow   Up: fshadow   FastForward: regex   Contents: Table of ContentsIndex: Concept Index