Use pam_extrausers for a separate PAM password store

You will add pam_extrausers to a PAM stack so that the selected PAM operation can use /var/lib/extrausers/passwd and /var/lib/extrausers/shadow instead of the ordinary /etc/passwd and /etc/shadow files. Allow about 20 minutes for a review-only change, or longer if you must test a real login. Keep an existing administrator session open while changing authentication.

This guide covers the PAM module installed with Ubuntu's libpam-modules package. It does not create extrausers records and it does not enable the module for every service automatically.

1. Confirm the installed module and version

Check the package and shared object before editing any configuration. This guide was checked with version 1.5.3-5ubuntu5.7 of the amd64 package; your output may differ after an update.

$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules:amd64
libpam-modules 1.5.3-5ubuntu5.7
$ test -r /usr/lib/x86_64-linux-gnu/security/pam_extrausers.so && echo module-present
module-present
$ man 8 pam_extrausers

If the package query fails, stop and install the package through your normal package-management process. Do not copy a module from another host: the PAM ABI, architecture and package version must match the system using it.

2. Choose one PAM service

PAM configuration is service-specific. A file such as /etc/pam.d/login, /etc/pam.d/sshd or /etc/pam.d/sudo has its own stack, and changing one does not change the others. Find the service you intend to change without modifying anything:

$ sudo grep -nH 'pam_\(unix\|extrausers\)' /etc/pam.d/sshd /etc/pam.d/login /etc/pam.d/sudo 2>/dev/null
$ sudo sed -n '1,160p' /etc/pam.d/sshd

Replace sshd in these examples with the actual service. If the file includes a common stack, inspect that included file as well. The first question is which operation you need: auth checks credentials, account checks account status, password changes a password, and session records login or logout activity. pam_extrausers provides all four module types.

3. Back up the service configuration

Changing PAM can prevent logins or privilege escalation if the stack becomes invalid. Before editing, make a root-owned backup beside the file. This is an elevated command and should be run only after checking the path.

$ sudo cp --preserve=mode,ownership,timestamps /etc/pam.d/sshd /etc/pam.d/sshd.before-pam-extrausers
$ sudo ls -l /etc/pam.d/sshd /etc/pam.d/sshd.before-pam-extrausers

The backup is the recovery point for this example. If you need to undo the change, restore it with sudo cp --preserve=mode,ownership /etc/pam.d/sshd.before-pam-extrausers /etc/pam.d/sshd, then test a new connection from the still-open administrator session.

4. Add the module to the intended stack

Use the module on the line matching the PAM operation you selected. For example, an authentication line can be written as:

auth    required    pam_extrausers.so

For a password-changing stack, the module's manual gives a more complete pattern. Its first line uses obscure and sha512, then permits the normal Unix module to be tried if the first module does not succeed:

password        [success=2 default=ignore] pam_extrausers.so obscure sha512
password        [success=1 default=ignore] pam_unix.so obscure sha512
password        requisite                  pam_deny.so
password        required                   pam_permit.so

Do not paste that password example into an unrelated service without understanding its existing control flags and additional lines. In particular, required, requisite and bracketed jump rules affect how later modules are reached. Preserve distribution-managed comments and included files where possible.

The module's default authentication policy rejects a blank official password. Adding nullok changes that to permit blank passwords; nullok_secure limits that exception to terminals named in /etc/securetty. Treat either option as a deliberate security decision, not a compatibility fix. try_first_pass reuses a password from an earlier stacked module where possible, while use_first_pass refuses to prompt if that password is unavailable or unsuitable.

5. Validate the edit before testing a login

First check the file as text and confirm that the module path is still present. A syntax check cannot prove that the complete stack will authenticate successfully, but it catches the common error of editing the wrong service or misspelling the module.

$ sudo grep -n 'pam_extrausers\.so' /etc/pam.d/sshd
12:auth    required    pam_extrausers.so
$ sudo test -s /var/lib/extrausers/passwd && echo passwd-file-present
$ sudo test -s /var/lib/extrausers/shadow && echo shadow-file-present
passwd-file-present
shadow-file-present

The module reads the extrausers files directly. A missing or unreadable record is not repaired by changing PAM control flags. Check ownership and permissions with sudo stat /var/lib/extrausers/passwd /var/lib/extrausers/shadow; do not make the shadow file world-readable.

6. Test without closing your recovery path

Keep the original administrator shell open and test the affected service in a second terminal or a separate console. For SSH, create a new connection rather than reusing an existing one. Test an expected valid account and an intentionally invalid password, then check the client result and the service log. Do not test by logging out first.

$ ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no USER_NAME@HOST_NAME
$ sudo journalctl -u ssh --since '5 minutes ago' --no-pager

Replace USER_NAME and HOST_NAME with values you have verified. The exact log unit may be ssh or sshd on your system. PAM failures often identify the service and module but should not be treated as proof that a password file is healthy. Check the account data and the complete stack if the result is surprising.

Authentication failures normally incur a delay of about two seconds from this module. The nodelay option suppresses that request, but removing a failure delay can make password guessing cheaper. Leave it out unless you have a specific operational reason and compensating controls.

7. Change passwords only with a planned rollback

The password component updates the extrausers password. Its default hash choice comes from ENCRYPT_METHOD in /etc/login.defs; options such as sha256, sha512 and rounds= affect passwords changed next. These settings do not convert existing hashes. Check the effective policy before asking a user to change a password, and avoid putting passwords in shell history or test transcripts.

Do not use md5, bigcrypt or a blank-password exception merely to make an old client work. They are compatibility options with security consequences. If a password change breaks the intended service, restore the backed-up PAM file first; do not delete or hand-edit /var/lib/extrausers/shadow as a recovery shortcut.