Configure pam_faillock Without Locking Yourself Out

By the end of this guide, failed logins will be counted by PAM, accounts will be locked after a defined threshold, and you will know how to inspect or reset a tally. The examples use the settings documented by the installed Linux-PAM 1.5.3-5ubuntu5.7 package on this machine.

Allow about 15 minutes for a careful configuration review. You need root access, a second administrative session or console access, and a service whose PAM stack you understand. This is security-sensitive work: a syntax or ordering error in PAM can deny logins, including administrative logins.

Checkpoint 1: establish the current state

First identify the service you intend to protect. Do not copy a login example into every PAM file. SSH, local login, a display manager and sudo can have different stacks.

dpkg-query -W -f='${Package} ${Version}\n' libpam-modules:amd64
sudo sed -n '1,220p' /etc/security/faillock.conf
sudo faillock --user USERNAME

The configuration file may be absent or empty. The command prints the recorded failures for the named user when a tally exists; an empty result is a useful baseline. Replace USERNAME with a real account name. The faillock utility accepts --dir, --user, --reset and --legacy-output; it does not provide a general --help option on this installation.

Keep a root shell or console session open while changing PAM. Checkpoint complete means you know the target service, the installed package version, and the current tally directory.

Checkpoint 2: choose a bounded policy

Put policy in /etc/security/faillock.conf. Module command-line options can override this file, but the installed manpage recommends the configuration file instead of placing policy in each PAM line.

The following policy records four consecutive failures in the default 15-minute interval and unlocks the account automatically after 20 minutes. silent suppresses information about a locked account during the pre-authentication check.

deny=4
unlock_time=1200
silent

These values are an example, not a universal answer. A low deny value can be used for denial of service against a real account. Root is normally exempt from being blocked; enabling even_deny_root changes that boundary and deserves a separate recovery plan. The tally files are normally under /var/run/faillock/, which can be temporary storage. If failures must survive a reboot, set a persistent dir= in this configuration file and ensure the directory has suitable ownership and permissions.

Checkpoint 3: back up and edit the policy

Before changing the file, make a root-only backup. This command works whether the file already exists or not.

sudo cp -a /etc/security/faillock.conf /etc/security/faillock.conf.bak
sudoedit /etc/security/faillock.conf

Replace or merge the relevant settings, preserving unrelated site policy. Then inspect the result:

sudo sed -n '1,220p' /etc/security/faillock.conf

There is no separate daemon to restart for this file. If you need to undo this change before testing, restore the backup with sudo cp -a /etc/security/faillock.conf.bak /etc/security/faillock.conf. Do not delete tally files as a first response: reset a named account after confirming which account is affected.

Checkpoint 4: verify the PAM stack

The policy file only supplies options. The PAM service must call pam_faillock.so in the correct positions. The installed manpage describes three arguments:

• preauth checks whether a user is already blocked before a credential module asks for a password. It is optional when authsucc is used.
• authfail records a failure after the authentication module has returned a failure.
• authsucc clears the recorded failures after successful authentication, unless the user is already blocked.

A representative auth sequence is shown below. Adapt it to the existing service file and its control flags. The surrounding modules are significant, so do not replace a complete distribution-managed PAM file with this fragment.

auth     required       pam_faillock.so preauth
auth     sufficient     pam_unix.so
auth     [default=die]  pam_faillock.so authfail
auth     sufficient     pam_faillock.so authsucc
auth     required       pam_deny.so

The account phase can also call pam_faillock.so, but the manpage warns that the auth stack must have run before the account stack or its reset logic is intentionally skipped. A pre-auth call without silent, or with a requisite control field, can reveal whether a username exists. Treat that as an account-enumeration consideration, not merely a display preference.

After editing a service file, review it as root and test the target service from the second session. There is no universal PAM syntax checker in the installed interface, so a successful controlled authentication and a still-working administrative session are the meaningful checks.

Checkpoint 5: inspect and recover a tally

Inspect a user before deciding whether a lock is expected:

sudo faillock --user USERNAME

To clear that user's recorded failures, use the explicit reset operation:

sudo faillock --user USERNAME --reset
sudo faillock --user USERNAME

The second command should show no remaining recorded failures for that user. Resetting is a privileged, security-sensitive action because it removes the evidence and lets authentication proceed again. Record why you did it, and do not use a blanket reset when only one account is affected.

If a legitimate user is locked, automatic recovery follows unlock_time when it is set. If the tally disappears after a reboot, check whether /var/run/faillock is mounted as temporary storage and whether a persistent dir= was intended. If the service now rejects every login, use the open root session or console to restore faillock.conf.bak, repair the service's PAM file, and test again before closing the recovery session.