PAM_PWHISTORY(8)

📦
version 1.7.3 · 18 versions
, in arch rolling

💖 PAM_PWHISTORY 💖

okay bestie, welcome to pam_pwhistory — it's a Linux-PAM manual page and it's literally the bouncer at the password club 🎀

✨ NAME ✨

pam_pwhistory — the PAM module that remembers your last passwords (yes, all of them, it's keeping receipts 💅)

✨ SYNOPSIS ✨

pam_pwhistory.so [debug] [use_authtok] [enforce_for_root] [remember=N]
                 [retry=N] [authtok_type=STRING] [file=/path/filename]
                 [conf=/path/to/config-file]

✨ DESCRIPTION ✨

So basically this module keeps the last passwords of each user on file so it can force a password change history and stop people from just vibing back and forth between the same two passwords forever. It's giving "you can't sit with us" but for your old password 🌸

Important: this module does not work together with kerberos. And honestly? Using it with NIS or LDAP doesn't make much sense either, because the old passwords live on the local machine and are not available on another machine for password history checking. So like, the lore only exists locally, no cap 🫶

✨ OPTIONS ✨

  • debug — turns on debugging via syslog(3). Very "let me see what's happening in here" energy 🔍
  • use_authtok — when you're changing a password, this forces the module to use the new password that a previously stacked password module handed over. (This is exactly what's happening in the stacking example with pam_passwdqc down below, iykyk.)
  • enforce_for_root — if you set this, the check gets enforced for root too. No exceptions, no nepo baby privilege 👑
  • remember=N — the last N passwords for each user get saved. Default is 10. And listen — a value of 0 makes the module keep the existing contents of the opasswd file unchanged. Like, untouched, frozen, periodt.
  • retry=N — prompt the user at most N times before it returns with an error. Default is 1. One shot, one opportunity 🎯
  • authtok_type=STRING — go read pam_get_authtok(3) for more details on this one bestie.
  • file=/path/filename — store the password history in /path/filename instead of the default location. The default location is /etc/security/opasswd 📁
  • conf=/path/to/config-file — use another configuration file instead of the default /etc/security/pwhistory.conf.

The options for configuring the module behavior are described in the pwhistory.conf(5) manual page. And here's the tea: the options specified on the module command line override the values from the configuration file. Command line wins, always 💅

✨ MODULE TYPES PROVIDED ✨

Only the password module type is provided. That's it. That's the whole list. She's specialized 🎀

✨ RETURN VALUES ✨

  • PAM_AUTHTOK_ERR — no new password was entered, the user aborted the password change, or the new password couldn't be set. It's giving "never mind, forget it" 😭
  • PAM_IGNORE — password history was disabled. The module said "not my problem today" 🙈
  • PAM_MAXTRIES — password was rejected too often. Too many tries, bestie, the door is closed 🔥
  • PAM_USER_UNKNOWN — user is not known to system. Who? Never heard of her 💀

✨ EXAMPLES ✨

An example password section would be:

#%PAM-1.0
password     required       pam_pwhistory.so
password     required       pam_unix.so        use_authtok

And in combination with pam_passwdqc:

#%PAM-1.0
password     required       pam_passwdqc.so    config=/etc/passwdqc.conf
password     required       pam_pwhistory.so   use_authtok
password     required       pam_unix.so        use_authtok

Look at that stacking. Iconic behavior, honestly 🌈

✨ FILES ✨

  • /etc/security/opasswd — default file with password history 🗂️
  • /etc/security/pwhistory.conf — config file for pam_pwhistory options ⚙️

✨ SEE ALSO ✨

pwhistory.conf(5), pam.conf(5), pam.d(5), pam(8), pam_get_authtok(3)

Go read them, they're all part of the same friend group 🦋

✨ AUTHOR ✨

pam_pwhistory was written by Thorsten Kukuk <kukuk@thkukuk.de> — king behavior, we stan 👑

and that's the whole page bestie!! this was the Linux-PAM Manual's PAM_PWHISTORY(8), and the footer tea is: <b>Linux-PAM</b>, dated <b>09/27/2026</b> 💖 mwah, go change your password (to something new, obviously, the module is watching 💅✨)

📦 where this page comes from