Edit PAM Stacks Safely with pam.conf and pam.d

You will identify the PAM configuration that this machine actually reads, understand the four stack types and the controls that decide whether a module failure matters, then make a reversible change to one service file. Allow about 20 minutes, plus a maintenance window if the change affects logins. The examples use Linux-PAM 1.5.3 from Ubuntu package libpam-runtime 1.5.3-5ubuntu5.7.

PAM changes are security-sensitive. A malformed line or an unsuitable control flag can deny logins, sudo or remote access. Keep an already authenticated root shell open while testing, and do not close your only recovery session until the new behaviour is proven.

1. Find the active configuration layout

Linux-PAM can read the single file /etc/pam.conf, but it prefers individual service files in /etc/pam.d/. When that directory exists, the library ignores /etc/pam.conf. Service files omit the service column: the filename supplies it. Their names must be lower case.

$ test -d /etc/pam.d && echo "pam.d is active" || echo "/etc/pam.conf is active"
pam.d is active
$ ls -l /etc/pam.d/login /etc/pam.d/common-auth
-rw-r--r-- 1 root root ... /etc/pam.d/common-auth
-rw-r--r-- 1 root root ... /etc/pam.d/login

The file listing varies by system. The useful result is the first line: with pam.d present, editing /etc/pam.conf will not change normal service behaviour.

$ sudo sed -n '1,220p' /etc/pam.d/SERVICE_NAME

Replace SERVICE_NAME with a real lower-case filename. Reading does not require privilege when the file is world-readable on this machine, so omit sudo if ordinary sed works.

2. Read a rule as a stack entry

In /etc/pam.conf, a rule has five fields: service type control module-path module-arguments. In /etc/pam.d/SERVICE_NAME, remove the service field:

type  control  module-path  module-arguments

The type selects the PAM management group. auth establishes identity and may grant credentials. account applies non-authentication access rules such as expiry. password updates an authentication token. session performs work when a session opens or closes, such as logging or mounting resources.

For example, this existing-style rule asks pam_unix.so to take part in authentication:

auth  required  pam_unix.so  nullok

The module path may be an absolute filename or a relative name resolved from the PAM module directory, commonly /lib/security/ or /lib64/security/ depending on architecture. Module arguments belong to the individual module, so read that module's manual page before adding one. Do not copy an option from an unrelated module.

3. Understand the control flag before changing it

Control flags describe what happens when the module returns a result. required records a failure but lets the remaining entries run, then returns failure. requisite returns immediately on failure. That can reduce unnecessary prompts, but it can also reveal whether an account passed an earlier test. sufficient can return success immediately when it succeeds and no earlier required module has failed; its failure is ignored. optional matters only when it is the only module for that service and type.

The square-bracket form gives more precise actions. This common-looking entry means that a successful pam_unix.so result skips one following module, while other results use the fallback:

auth  [success=1 default=ignore]  pam_unix.so  nullok

Here, success=1 is a stack jump, not a Boolean value. A jump over zero modules is treated as ignore. Other actions include ignore, bad, die, ok, done and reset. If a return value is not listed and there is no default, its action defaults to bad.

Trap: a line can be syntactically valid and still produce the wrong policy. Count the entries affected by a numeric jump, and review the whole stack in order. PAM does not interpret a rule in isolation.

4. Back up the exact file you will edit

This is the first state-changing step and needs elevated privilege. Substitute the actual service name. The backup stays beside the original with its metadata preserved:

$ sudo cp --preserve=all /etc/pam.d/SERVICE_NAME /etc/pam.d/SERVICE_NAME.before-change
$ sudo ls -l /etc/pam.d/SERVICE_NAME /etc/pam.d/SERVICE_NAME.before-change

Do not use a shell wildcard for this backup. It is easy to save the wrong file or overwrite an earlier recovery copy. If the edit fails, restore the known-good file while the recovery shell remains open:

$ sudo cp --preserve=all /etc/pam.d/SERVICE_NAME.before-change /etc/pam.d/SERVICE_NAME
$ sudo chmod --reference=/etc/pam.d/SERVICE_NAME.before-change /etc/pam.d/SERVICE_NAME

Restoring does not undo a session already denied by a bad stack, which is why the open root shell and a tested local console matter.

5. Make the smallest possible edit

Use the package's supported configuration tool when the file says it is managed by one. On this installation, the common authentication files identify pam-auth-update as their manager. Run it interactively as root and review its proposed changes:

$ sudo pam-auth-update

For a service-specific local rule, edit only the relevant file with an editor running as root. Preserve the existing order and add one complete line. Do not replace the stack with a short example from a blog. A missing account, password or session rule can affect more than the login test you had in mind.

Comments start with #. A rule normally occupies one line, although an escaped line ending can continue it. Arguments are separated by spaces. To keep spaces inside one argument, surround that argument with square brackets and escape a literal closing bracket as the manual describes.

6. Test without locking out the administrator

First inspect the edited file for accidental truncation or a misplaced field:

$ sudo sed -n '1,220p' /etc/pam.d/SERVICE_NAME
$ sudo diff -u /etc/pam.d/SERVICE_NAME.before-change /etc/pam.d/SERVICE_NAME

There is no universal syntax-only command in pam.conf(5). PAM reads a stack when the application starts its PAM transaction, and a badly formatted line generally causes the authentication process to fail while reporting an error through syslog. Test the actual service using a second session or a harmless operation supported by that service. Keep the original session open until the new session succeeds.

For SSH, use a second terminal and a separate connection. For sudo, run a command that confirms your normal authorisation without ending the root shell. For a display or login manager, use a local console or scheduled maintenance window. Do not test a new password rule by changing the only administrator password first.

If the test fails, stop making further edits. Restore the backup, retry the same test, and inspect the system log from the recovery shell for the module and service named in the error.