In order to implement its design goals, PAM uses one or more configuration files: either a file called /etc/pam.conf or files in the /etc/pam.d directory named after the particular systems they control. The /etc/pam.d directory is more common in Linux; this approach enables packages to add files to the directory for their services, without having to modify /etc/pam.conf.

The /etc/pam.conf file entries are similar to the contents of files in /etc/pam.d. The principle difference is that the /etc/pam.conf entries begin with a service name field, which is missing from individual service files. The overall format for the lines in /etc/pam.d files is:

                  management_group  control_flag  module  [options]

Each field has a specific meaning:

In addition to configuration lines, PAM configuration files can contain comments. These begin with a hash mark (#). Entire lines can be comments, or comments can come at the end of a line that serves some other purpose.

A configuration for a single authentication tool can combine several PAM modules. This happens in two ways. First, each of the four management groups (auth, account, session, and password) requires its own configuration. Second, with each management group, multiple modules can be called. When multiple modules are called, the result is referred to as a module stack. For instance, a login service might have separate auth and account stacks. These stacks are likely to have some modules in common (they perform different actions depending upon the calling stack), but each may also have some unique modules.

Individual modules in a stack deliver return values that can be classified as failures or successes. In this context, these terms don’t refer to program bugs or the lack thereof, but to failures or successes in authentication or other actions. For instance, if a user enters the wrong password, an authentication module will fail.

Modules in a stack are called in the order in which they’re specified. This order is unimportant if all of the modules are of the required variety, but if you use other control flags—particularly requisite or sufficient—order can become important, as described shortly.

Understanding the operation of module stacks can be tricky, because the different control flags can have confusing implications. Table A-1 summarizes the consequences of successes and failures of modules called with particular control flags.

These rules can become quite confusing in the event of conflicting outcomes. For instance, consider the following stack:

auth required   pam_unix.so try_first_pass
auth sufficient pam_krb5.so try_first_pass
auth required   pam_env.so

For now, you need only know that the pam_unix.so and pam_krb5.so modules authenticate users, while pam_env.so sets environment variables but never returns a failure code. Because this stack provides two login modules, each with two possible outcomes, you must consider four possibilities—both succeed, both fail, pam_unix.so succeeds while pam_krb5.so fails, or pam_unix.so fails while pam_krb5.so succeeds. In practice, this stack as a whole succeeds if and only if pam_unix.so succeeds; if it fails, its required status overrides the sufficient status of pam_krb5.so, and if it succeeds, that success won’t be overridden by a failure of the sufficient pam_krb5.so. What happens if the two authentication modules’ order is reversed, though?

auth sufficient pam_krb5.so try_first_pass
auth required   pam_unix.so try_first_pass
auth required   pam_env.so

In this case, because the sufficient pam_krb5.so module comes first, its success bypasses the later required pam_unix.so module, so this stack succeeds if either module succeeds. A success of pam_krb5.so, though, bypasses the pam_env.so module, which may not be desirable.