Configure pam_unix Safely for Linux Password Authentication

You will identify the installed pam_unix module, read the PAM stack that actually controls a service, and make a narrowly scoped configuration change without locking yourself out. Allow 20 minutes for an 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 Linux distributions can ship different defaults.

1. Confirm the module and the configuration style

pam_unix is a PAM module, not a command that you run directly. It supplies the account, auth, password and session management types. It 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 existence of the module. Read the installed manual as well, 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 module arguments. 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 determine what happens after a module returns a result. Do not replace them with required merely because it looks simpler: changing stack control can alter the behaviour of other authentication modules.

3. Understand the two defaults that cause most surprises

For authentication, pam_unix rejects a user whose official password is blank unless nullok is present. This machine's Ubuntu-generated common-auth line includes nullok, so the effective policy also depends on the surrounding stack and the distribution's configuration tooling. Removing or adding that option changes whether blank-password accounts can pass this module. A blank password is a security risk; do not add nullok to make a failing login convenient.

For password changes, this host uses yescrypt. The option selects yescrypt for the next password change; it does not convert existing hashes immediately. The manual states that the default encryption hash comes from ENCRYPT_METHOD in /etc/login.defs. If systems must share password hashes with older releases, confirm their supported algorithms before selecting an option.

The module also requests roughly a two-second delay after a failed authentication by default. nodelay suppresses that request. Avoid disabling the delay unless the application has a measured compatibility problem, because 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 requires 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.

For authentication, try_first_pass reuses a password supplied by an earlier stacked module if possible. use_first_pass never prompts and fails when no suitable earlier password exists. These options depend on the order and behaviour of the whole stack, so test them with every authentication method the service supports.

5. Test syntax and behaviour 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

An authentication failure can be a wrong password, a blank-password rule, a preceding module's result or a stack control decision. An account failure can come from shadow expiry fields such as expire, last_change, max_change, min_change or warn_change. A password failure is usually a policy, token or hashing issue. A session failure concerns opening or closing the session and can appear 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.