Clear and Inspect PAM Login Failure Records with faillock

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.

1. Confirm the installed command

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.7

This 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.

2. Inspect one user's tally

Replace LOGIN_NAME with the exact local account name. Start with the default tally directory:

$ sudo faillock --user LOGIN_NAME

A 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                                           Valid

The 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.

3. Inspect a non-default tally directory

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_NAME

Do 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-directory

4. Reset one account after checking the target

Resetting 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 --reset

The 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                                           Valid

There 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.

5. Set sensible lockout defaults

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.conf

A restrained example is:

# Four consecutive failures in fifteen minutes cause a lock.
deny=4
fail_interval=900
unlock_time=1200
silent

In 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.

6. Roll back a configuration change

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_NAME

The 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.

Common traps

• Wrong directory: a command-line --dir overrides both the file and the default. An empty result can simply mean you inspected the wrong store.
• Wrong user: use getent passwd before resetting. A display or reset command does not replace your account lookup.
• Centralised users: local_users_only makes the module track only users in local /etc/passwd. The command may then stop tracking directory-service accounts locally.
• Root lockout: even_deny_root and root_unlock_time can affect recovery. Keep a tested privileged route available before enabling them.
• Reboot assumptions: the usual /var/run/faillock directory may be cleared at boot. Do not treat a reboot as a deliberate reset policy.