Configure Password History Without Calling pwhistory_helper Directly

You will configure and verify local password history through pam_pwhistory, while keeping pwhistory_helper in its proper role. The helper is an internal binary, not an administration command: it moves password hashes between the PAM module and the opasswd history file, and checks supplied passwords against that history when the module needs it.

Allow about fifteen minutes, plus a few minutes to arrange a recovery session. This guide assumes Ubuntu or Debian package management, an account with sudo, and a test user whose password you can change. The installed package checked for this guide is libpam-modules-bin 1.5.3-5ubuntu5.7. Your package revision may differ even when the upstream Linux-PAM release is the same.

1. Confirm the helper and module are installed

First check the package and the paths without changing anything:

$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules-bin libpam-modules
libpam-modules-bin 1.5.3-5ubuntu5.7
libpam-modules 1.5.3-5ubuntu5.7
$ command -v pwhistory_helper
/usr/sbin/pwhistory_helper

The exact version and path can vary. The pwhistory_helper(8) manual describes its interface as internal to pam_pwhistory and says applications should not call it directly. That means there is no supported set of command-line arguments to build a script around.

Checkpoint: if the command is missing, stop here and install or repair the normal PAM package using your distribution's package process. Do not download a replacement helper or copy one from another host.

2. Inspect the current PAM password stack

Find the password rules before editing them. Common services have their own files under /etc/pam.d; the exact file depends on the login or password-changing path you intend to protect:

$ sudo grep -R -n --include='*' -E 'pam_(pwhistory|unix|passwdqc)' /etc/pam.d /etc/pam.conf 2>/dev/null

This reads configuration as root because some files are not readable by ordinary users. It does not change PAM. Look for an existing pam_pwhistory.so line before adding another one. Two history modules can produce confusing prompts and policy results.

The module supplies only the password type. It is normally stacked before pam_unix.so use_authtok, so the history check sees the new token and the Unix password module then writes it:

password required pam_pwhistory.so
password required pam_unix.so use_authtok

Do not paste this blindly into every file. Use the PAM service file that owns the password change you are testing, and preserve any distribution-managed comments and surrounding rules. If your stack already obtains a token from another password module, its ordering and use of use_authtok need to remain coherent.

3. Choose the history file and count

By default, the module stores password history in /etc/security/opasswd. The default remembered count is ten passwords. A remember=N module option overrides that count; remember=0 leaves the existing opasswd contents unchanged. The module also accepts a file=/path/filename option and a separate conf=/path/to/config-file option.

For a small, explicit policy, add the count to the module line. This example remembers the last five passwords:

password required pam_pwhistory.so remember=5
password required pam_unix.so use_authtok

The module's command-line options override values from /etc/security/pwhistory.conf. Keep one source of truth where possible. A setting in the PAM line can otherwise hide a carefully reviewed configuration-file value.

$ sudo stat -c '%A %U:%G %n' /etc/security/opasswd
-rw------- root:root /etc/security/opasswd

The displayed mode is an example of a suitably restricted file, not a promise about every installation. If the file has unexpectedly broad permissions, stop and investigate the package's intended ownership and local security policy before changing it. Avoid manually editing its contents.

4. Make one controlled PAM change

Back up the one service file you are about to edit, then use your normal editor with elevated privileges:

$ sudo cp --preserve=mode,ownership,timestamps /etc/pam.d/SERVICE /etc/pam.d/SERVICE.before-pwhistory
$ sudoedit /etc/pam.d/SERVICE

Replace SERVICE with the real PAM service file, such as a file used by the password-changing command on your system. Add or adjust the password stack deliberately. Save the file, then inspect the relevant lines:

$ sudo sed -n '/^password[[:space:]]/p' /etc/pam.d/SERVICE
password required pam_pwhistory.so remember=5
password required pam_unix.so use_authtok

There is no general syntax-check command that makes an arbitrary PAM stack safe. A typo can affect the next password change or login path. Do not test by closing your only privileged session.

5. Test with a disposable account

Use a test account that does not own important data. Creating an account is a state change and requires root:

$ sudo useradd --create-home pam-history-test
$ sudo passwd pam-history-test

Choose a temporary test password interactively. Change it once more with sudo passwd pam-history-test, using a different temporary value, and then try to reuse the first value. With remember=5, the reuse should be rejected after it has entered the history. Exact wording depends on the surrounding PAM stack.

Verify the command status after each change:

$ sudo passwd pam-history-test
New password:
Retype new password:
passwd: password updated successfully
$ printf 'status: %s\n' "$?"
status: 0

A successful change proves that this particular path accepted the new password. It does not prove that every PAM service uses the same file or stack. If the reuse test is accepted, inspect the service file, the effective remember value and the history file path before making more changes.

6. Recover from a failed test

If a password change fails unexpectedly, leave the recovery session open and restore only the backup you created:

$ sudo cp --preserve=mode,ownership,timestamps /etc/pam.d/SERVICE.before-pwhistory /etc/pam.d/SERVICE
$ sudo sed -n '/^password[[:space:]]/p' /etc/pam.d/SERVICE

This restores the service file, but it does not remove password history already written to opasswd. Do not delete or edit that file as a first response. Correct the stack, test again, and retain the history unless your documented security procedure says otherwise.

When the test is complete, remove the disposable account only if you are certain it is not needed:

$ sudo userdel --remove pam-history-test

That command deletes the test account's home directory and is irreversible without a backup. It is not required for PAM to work.