To write more complex PAM rules, you can use valid control-flags in the following form:

type [value1=action1 value2=action2 …] module module-arguments

Where valueN corresponds to the return code from the function invoked in the module for which the line is defined.

You can find supported values from the on-line PAM Administrator’s Guide.

A special value is default, which implies all valueN’s not mentioned explicitly.

The actionN can take one of the following forms:

• ignore: if this action is used with a stack of modules, the module’s return status will not contribute to the return code the application obtains.
• bad: indicates that the return code should be thought of as indicative of the module failing. If this module is the first in the stack to fail, its status value will be used for that of the whole stack.
• die: equivalent to bad but may terminate the module stack and PAM immediately returning to the application.
• ok: this instructs PAM that the system administrator thinks this return code should contribute directly to the return code of the full stack of modules.
• done: equivalent to ok but may terminate the module stack and PAM immediately returning to the application.
• N (an unsigned integer): equivalent to ok but may jump over the next N modules in the stack.
• Reset: this action clears all memory of the state of the module stack and restart with the next stacked module.

Each of the four keywords: required; requisite; sufficient; and optional, have an equivalent expression in terms of the […] syntax, which allow you to write more complicated rules and they are:

• required: [success=ok new_authtok_reqd=ok ignore=ignore default=bad]
• requisite: [success=ok new_authtok_reqd=ok ignore=ignore default=die]
• sufficient: [success=done new_authtok_reqd=done default=ignore]
• optional: [success=ok new_authtok_reqd=ok default=ignore]

The following is an example from a modern CentOS 7 system. Let’s consider these rules from the /etc/pam.d/postlogin PAM file:

#%PAM-1.0
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
session     [success=1 default=ignore] pam_succeed_if.so service !~ gdm* service !~ su* quiet
session     [default=1]   pam_lastlog.so nowtmp showfailed
session     optional      pam_lastlog.so silent noupdate showfailed

Here is another example configuration from the /etc/pam.d/smartcard-auth PAM file:

#%PAM-1.0
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
auth        required      pam_env.so
auth        [success=done ignore=ignore default=die] pam_pkcs11.so nodebug wait_for_card
auth        required      pam_deny.so
 
account     required      pam_unix.so
account     sufficient    pam_localuser.so
account     sufficient    pam_succeed_if.so uid < 1000 quiet
account     required      pam_permit.so
 
password    required      pam_pkcs11.so
 
session     optional      pam_keyinit.so revoke
session     required      pam_limits.so
-session     optional      pam_systemd.so
session     [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
session     required      pam_unix.so

For more information, see the pam.d man page:

man pam.d

A comprehensive description of the Configuration file syntax and all PAM modules can be found in the documentation for Linux-PAM.

PAM is a powerful high-level API that allows programs that rely on authentication to authentic users to applications in a Linux system.

It’s powerful but very challenging to understand and use.