Three wrong passwords and PAM can lock an account solid, and faillock is the command that shows you why and lets you clear it. This guide covers inspecting a user's recent authentication failures, resetting the tally when appropriate, and the settings that control future lockouts. The examples match Ubuntu's installed Linux-PAM 1.5.3-5ubuntu5.7 packages.
Allow about ten minutes. You need a shell and the account name you want to inspect. Reading a tally is normally harmless, but resetting one or changing /etc/security/faillock.conf affects authentication and normally requires root.
Check the binary and package version before relying on examples. These are ordinary, read-only commands:
$ command -v faillock
/usr/sbin/faillock
$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules-bin libpam-modules:amd64
libpam-modules 1.5.3-5ubuntu5.7
libpam-modules-bin 1.5.3-5ubuntu5.7This installed command accepts --dir, --user and --reset. It does not provide a useful --help or --version mode on this installation, so use the installed manpage as the option reference.
Replace LOGIN_NAME with the exact local account name. Start with the default tally directory:
$ sudo faillock --user LOGIN_NAMEA record normally shows a header followed by entries containing the time, source and validity of failed attempts. The exact rows are host-specific. If the user has no recorded failures, you may see only the header or no useful rows. A successful command is not proof that the login name was the one you intended, so check it first:
$ getent passwd LOGIN_NAME
LOGIN_NAME:x:1001:1001:Example User:/home/LOGIN_NAME:/bin/bash
$ sudo faillock --user LOGIN_NAME
When Type Source ValidThe default directory is /var/run/faillock. On systems where that path is mounted in virtual memory, its files disappear during a reboot. That means a reboot can remove the evidence and may also re-enable access, depending on the rest of the PAM configuration.
Checkpoint: Stop here if you only needed to investigate. Nothing has been changed.
The command-line directory takes priority over the configuration file, which takes priority over the built-in default. Use the same directory that pam_faillock is configured to use:
$ sudo faillock --dir /path/to/tally-directory --user LOGIN_NAMEDo not add --dir just to make an empty result look different. Pointing at the wrong directory can make a locked account appear clean while leaving the real tally untouched. Check the directory and its contents without editing them:
$ sudo ls -ld /path/to/tally-directory
$ sudo ls -l /path/to/tally-directoryResetting removes the selected user's failure records and can immediately make a locked account eligible for authentication. It is a security-sensitive action. Confirm the username and, if relevant, the tally directory in the command before pressing Enter:
$ getent passwd LOGIN_NAME
$ sudo faillock --user LOGIN_NAME --resetThe reset command normally prints nothing and returns status 0. Verify the result by displaying the same tally:
$ sudo faillock --user LOGIN_NAME
When Type Source ValidThere is no restore operation in faillock. If you reset the wrong account, preserve the mistake in your incident or change record and let the normal PAM workflow create new records. Do not copy another user's tally file into place: the per-user files are authentication state, not a portable backup format.
The preferred configuration file is /etc/security/faillock.conf. Its format is one option per line, with optional whitespace around = and comments beginning with #. Back up the current file before editing it:
$ sudo cp --preserve=all /etc/security/faillock.conf /etc/security/faillock.conf.bak
$ sudoedit /etc/security/faillock.confA restrained example is:
# Four consecutive failures in fifteen minutes cause a lock.
deny=4
fail_interval=900
unlock_time=1200
silentIn this Linux-PAM version, the defaults are deny=3, fail_interval=900 seconds and unlock_time=600 seconds. Setting unlock_time=0 means the lock never clears on its own; only a faillock --reset removes it. Permanent lockouts can be abused for denial of service, so use that value only with a recovery process.
Do not add even_deny_root casually. It allows root to be locked as well. root_unlock_time implies that option and controls automatic root recovery. Similarly, admin_group=GROUP_NAME applies the root handling to group members. Test any policy change with a second administrative session open so a mistaken rule does not remove your only route back in.
If the change causes an unexpected lockout or authentication behaviour, restore the backup and test from the already-open privileged session:
$ sudo cp --preserve=all /etc/security/faillock.conf.bak /etc/security/faillock.conf
$ sudo faillock --user LOGIN_NAMEThe PAM service may cache or apply configuration at the next authentication attempt, depending on the service. Do not restart a remote access service as a first reaction. Keep an existing session open, verify local access, and use the service's own documented reload procedure only if it is required.
--dir overrides both the file and the default. An empty result can simply mean you inspected the wrong store.getent passwd before resetting. A display or reset command does not replace your account lookup.local_users_only makes the module track only users in local /etc/passwd. The command may then stop tracking directory-service accounts locally.even_deny_root and root_unlock_time can affect recovery. Keep a tested privileged route available before enabling them./var/run/faillock directory may be cleared at boot. Do not treat a reboot as a deliberate reset policy.--reset only after checking the exact account.faillock.conf.