Configure pam_unix Safely for Linux Password Authentication

One wrong line in a pam_unix rule can lock every account out of ssh, sudo and the console at once. This guide has you identify the installed pam_unix module, read the PAM stack that actually controls a service, and make a narrowly scoped change without locking yourself out. Allow 20 minutes for the inspection and a further 15 minutes for a tested change. The examples target Ubuntu's libpam-modules 1.5.3-5ubuntu5.7 package installed on this machine; other distributions can ship different defaults.

1. Confirm the module and the configuration style

pam_unix is a PAM module, not a command you run directly. It supplies the account, auth, password and session management types, and normally reads account and password data from /etc/passwd and /etc/shadow when shadow passwords are enabled.

$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules:amd64
libpam-modules 1.5.3-5ubuntu5.7
$ ls -l /usr/lib/x86_64-linux-gnu/security/pam_unix.so
-rw-r--r-- 1 root root ... /usr/lib/x86_64-linux-gnu/security/pam_unix.so

Your file size, owner and timestamp will differ; the useful checks are the package version and the module's existence. Read the installed manual too, because option support and distribution defaults are version-specific.

In a /etc/pam.d/ file, each rule has a management type, control value, module path and optional arguments, and the service name is the file name. A line such as auth required pam_unix.so asks the Unix module to authenticate the user, while password required pam_unix.so yescrypt concerns password changes.

2. Find the stack used by your service

Start with the service that needs changing. Direct service files often include shared files such as /etc/pam.d/common-auth and /etc/pam.d/common-password. Inspect the complete relevant files before editing them:

$ rg -n 'pam_unix|include|substack' /etc/pam.d/login /etc/pam.d/common-auth /etc/pam.d/common-account /etc/pam.d/common-password /etc/pam.d/common-session
/etc/pam.d/common-auth:12:auth [success=1 default=ignore] pam_unix.so nullok
/etc/pam.d/common-account:12:account [success=1 new_authtok_reqd=done default=ignore] pam_unix.so
/etc/pam.d/common-password:16:password [success=1 default=ignore] pam_unix.so obscure yescrypt
/etc/pam.d/common-session:25:session required pam_unix.so

Those lines show this host's stack, not a universal template. The square-bracket control values decide what happens after a module returns a result. Do not replace them with required just because it looks simpler: changing stack control can alter the behaviour of other authentication modules.

3. Know the two defaults that cause most surprises

• Blank passwords are rejected by default. pam_unix refuses a user whose official password is blank unless nullok is present. This machine's Ubuntu-generated common-auth line already includes nullok, so the effective policy also depends on the surrounding stack. A blank password is a security risk; do not add nullok to make a failing login convenient.
• Hash changes are not retroactive. This host uses yescrypt for password changes. The option selects yescrypt for the next password change only, it does not convert existing hashes immediately. The manual states the default encryption hash comes from ENCRYPT_METHOD in /etc/login.defs. Confirm supported algorithms before switching if systems must share hashes with older releases.
• The failure delay is deliberate. The module requests roughly a two-second delay after a failed authentication by default. nodelay suppresses it. Avoid disabling the delay unless the application has a measured compatibility problem, since it can make password guessing cheaper.

4. Make a reversible, focused change

Before editing a PAM file, make a root-owned backup with restrictive permissions. The command below changes state and needs elevated privileges:

$ sudo install -o root -g root -m 0600 /etc/pam.d/common-password /etc/pam.d/common-password.before-pam-unix
$ sudoedit /etc/pam.d/common-password

Keep the existing control field and change only the module argument you have a reason to change. For example, the documented password line may look like this:

password [success=1 default=ignore] pam_unix.so obscure yescrypt

• obscure adds checks against weak changes, such as a palindrome, a case-only change or a rotated version of the old password.
• remember=n stores old password hashes in /etc/security/opasswd, but the manual recommends the separate pam_pwhistory module instead. Do not add password-history storage casually: it creates another sensitive file that needs appropriate protection.
• try_first_pass reuses a password already supplied by an earlier stacked module if possible.
• use_first_pass never prompts, and fails when no suitable earlier password exists. Both options depend on the order and behaviour of the whole stack, so test them with every authentication method the service supports.

5. Test without closing your safety net

There is no general PAM compiler that proves a stack is safe for every application. First inspect the edited file and verify its backup:

$ sudo sed -n '1,120p' /etc/pam.d/common-password
$ sudo cmp -s /etc/pam.d/common-password /etc/pam.d/common-password.before-pam-unix; printf 'same as backup: %s\n' "$?"
same as backup: 1

A status of 1 here only means the file differs from the backup, it is not a PAM test. Use the least disruptive operation that exercises the changed management type. For a password policy change, test a controlled password change for a disposable local account from the open root session, then authenticate with the new password in a second session. Do not test by changing the only administrator account first.

$ sudo useradd --create-home pam-test-user
$ sudo passwd pam-test-user
$ su - pam-test-user -c 'id -un'
pam-test-user

The account creation and password commands alter the system and need root privileges. Remove the disposable account only after the test is complete and you have confirmed it owns no data you need:

$ sudo userdel --remove pam-test-user

Do not run that removal against a real account. If you changed an authentication line and a test fails, leave the existing root session open, restore the backup, and test again:

$ sudo install -o root -g root -m 0600 /etc/pam.d/common-password.before-pam-unix /etc/pam.d/common-password

6. Diagnose failures by management type

• Authentication failure: a wrong password, a blank-password rule, a preceding module's result, or a stack control decision.
• Account failure: shadow expiry fields such as expire, last_change, max_change, min_change or warn_change.
• Password failure: usually a policy, token or hashing issue.
• Session failure: opening or closing the session, and can appear even after authentication succeeded.

Invalid pam_unix arguments are logged through syslog. If you used debug or audit, expect more authentication-related logging and treat it as sensitive operational data; remove diagnostic arguments after testing. Never paste password prompts, tokens or complete authentication logs into a public ticket.

When a remote service stops accepting logins, use the still-open console or root shell to restore the last known-good file. Do not restart unrelated services while investigating: PAM is loaded by applications, so the affected process may need a new session before a change is observable.