Previous Table of Contents Next

The required Flag

When the required flag is used, the module must return success for the overall result to be successful.

  If all of the modules are labeled as required, then authentication through all modules must succeed for the user to be authenticated.
  If some of the modules fail, then an error value from the first failed module is reported.
  If a failure occurs for a module flagged as required, all modules in the stack are still tried, but failure is returned.
  If none of the modules are flagged as required, then at least one of the entries for that service must succeed for the user to be authenticated.

The requisite Flag

When the requisite flag is used, the module must return success for additional authentication to occur.

  If a module flagged as requisite fails, an error is immediately returned to the application, and no additional authentication is performed.
  If the stack does not include prior modules labeled as required that failed, then the error from this module is returned.
  If an earlier module labeled as required fails, the error message from the required module is returned.

The optional Flag

When the optional flag is used and a module fails, the overall result can be successful if another module in the stack returns success. Use the optional flag only when one success in the stack is enough for a user to be authenticated. Only use this flag if it is not important for the particular mechanism to succeed.

NOTE:  If your users need to have permission associated with a specific mechanism to get their work done, you should not label it as optional.

The sufficient Flag

When the sufficient flag is used and the module returns success, skip the remaining modules in the stack, even if they are labeled as required. The sufficient flag indicates that one successful authentication is enough for the user to be granted access.

An example of the generic /etc/pam.conf file is shown below:

#ident  "@(#)pam.conf 1.19     95/11/30 SMI"
# PAM configuration
# Authentication management
login   auth required   /usr/lib/security/
login   auth required   /usr/lib/security/
rlogin  auth sufficient /usr/lib/security/
rlogin  auth required   /usr/lib/security/
dtlogin auth required   /usr/lib/security/
rsh     auth required   /usr/lib/security/
other   auth required   /usr/lib/security/
# Account management
login   account required        /usr/lib/security/
dtlogin account required        /usr/lib/security/
other   account required        /usr/lib/security/
# Session management
other   session required        /usr/lib/security/
# Password management
other   password required       /usr/lib/security/

The generic pam.conf file specifies:

  When running login, authentication must succeed for both the pam_unix and the pam_dial_auth modules.
  For rlogin, authentication through the pam_unix module must succeed, if authentication through pam_rhost_auth fails.
  The sufficient control flag indicates that for rlogin, the successful authentication provided by the pam_rhost_auth module is sufficient and the next entry is ignored.
  Most of the other commands require successful authentication through the pam_unix module.
  Authentication for rsh must succeed through the pam_rhost_auth module.

The other service name enables a default to be set for any other commands requiring authentication that are not included in the file. The other option makes it easier to administer the file, because many commands that are using the same module can be covered using only one entry. Also, the other service name, when used as a catch-all, can ensure that each access is covered by one module. By convention, the other entry is included at the bottom of the section for each module type.

The rest of the entries in the file control the account, session, and password management.

Normally the entry for <module_path> is "root-relative." If the filename you enter for <module_path> does not begin with a slash (/), the path /usr/lib/security/ is prepended to the filename. You must use a full pathname for modules located in other directories.

You can find the values for <module_options> in the manual page for the specific module; for example, pam_unix(5) provides the following options:


If login specifies authentication through both pam_local and pam_unix, then the user is prompted to enter a password for each module. For situations in which the passwords are the same, the use_first_pass module option prompts for only one password and uses that password to authenticate the user for both modules. If the passwords are different, the authentication fails. In general, you should use this option with an optional control flag to make sure that the user can still log in, as shown in the following example:

# Authentication management
login auth required /usr/lib/security/
login auth optional /usr/lib/security/ use_first_pass

If you use the try_first_pass module option instead, the local module prompts for a second password if the passwords do not match or if an error is made. If both methods of authentication are needed for a user to get access to all the tools needed, using this option could cause some confusion for the user because the user could get access with only one type of authentication.

Previous Table of Contents Next