Set a Per-Application PAM Failure Delay Safely

You will add a controlled delay after failed authentication for one PAM service, verify the configuration without changing it again, and know how to undo the change. The examples use the installed Linux-PAM package version 1.5.3-5ubuntu5.7 and its pam_faildelay(8) manpage.

Allow about fifteen minutes, plus a maintenance window if the service is remote login. You need root access to edit a PAM configuration and a second session or console for recovery. The module is already installed as /lib/x86_64-linux-gnu/security/pam_faildelay.so on this machine.

1. Identify the PAM service before editing

PAM configuration is per service. A login service may be named sshd, login or something supplied by an application. Do not put this line into a random file or assume that all authentication paths share one stack.

List the service files first. This is a read-only command and does not need elevated privileges:

$ ls /etc/pam.d/

Choose the file for the application whose failed logins should be delayed. For the examples below, replace SERVICE_FILE with an actual path such as /etc/pam.d/sshd. Check the application documentation if its PAM service name is unclear.

2. Back up the stack and inspect its authentication section

Back up the selected file before making a security-sensitive change. This requires elevated privileges:

# SERVICE_FILE=/etc/pam.d/SERVICE_NAME
# cp --preserve=mode,ownership,timestamps "$SERVICE_FILE" "$SERVICE_FILE.bak.$(date +%Y%m%d-%H%M%S)"
# sed -n '/^[[:space:]]*auth[[:space:]]/p' "$SERVICE_FILE"

The backup name includes the time, so it will not silently overwrite an earlier backup. Do not edit a generated file if the application or distribution says that another configuration tool owns it.

3. Add the module with an explicit delay

Add one auth line to the chosen service file. The delay value is in microseconds, so ten seconds is 10000000. The module only provides the auth interface. A straightforward entry is:

auth  optional  pam_faildelay.so  delay=10000000

Use the real module name as shown above, not a command to run in a shell. The optional control flag matches the installed manpage example: the module adjusts PAM's failure delay and returns PAM_IGNORE when that adjustment succeeds, so it is not the module that decides whether the password is accepted. The surrounding stack still controls authentication.

Insert the line in the auth section, normally before the modules that can reject the credentials. The delay is a PAM application setting, not a pause in the configuration file. A ten-second value is deliberately noticeable during testing; choose a value appropriate for the service and its users.

Use an editor with root privileges, or append only after checking the file and line carefully:

# editor "$SERVICE_FILE"
# grep -nF 'pam_faildelay.so' "$SERVICE_FILE"

Expected output is one numbered line containing the module entry. Avoid adding duplicate entries while troubleshooting, because multiple modules can contribute to PAM's failure-delay handling.

4. Understand the fallback to /etc/login.defs

If you omit delay=, the module reads FAIL_DELAY from /etc/login.defs. That setting is expressed in seconds, unlike the module argument, which is expressed in microseconds:

auth  optional  pam_faildelay.so

Do not assume that a missing setting means a particular delay. On this machine, FAIL_DELAY is commented out, so an omitted argument does not provide a useful configured value. Inspect it before relying on the fallback:

$ grep -nE '^[[:space:]]*FAIL_DELAY([[:space:]]|$)' /etc/login.defs || echo 'FAIL_DELAY is not set'

Prefer an explicit delay= in the service stack when the policy is meant for one application. Change /etc/login.defs only when you intentionally want its value as the fallback for services using this module.

5. Test a failed login without losing access

Keep the existing session open and test the affected service from a separate session. Use a test account if the service permits one. Deliberately use one incorrect password, then a correct password, and confirm that the first attempt takes roughly the configured delay. Do not repeatedly guess passwords against a production account.

For an SSH service, an ordinary client command is:

$ time ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no TEST_USER@HOSTNAME

The client output and elapsed time vary with the service and network. The delay is applied by PAM when the authentication stack records a failure, so network latency and other modules affect what you observe. A successful login does not prove that every failed path uses the file you edited; test the exact application and authentication method you changed.

6. Recover by restoring the previous stack

If the service rejects every login, remove the new line or restore the timestamped backup. This changes authentication behaviour immediately for subsequent attempts and requires elevated privileges:

# cp --preserve=mode,ownership,timestamps /etc/pam.d/SERVICE_NAME.bak.YYYYMMDD-HHMMSS /etc/pam.d/SERVICE_NAME
# grep -nF 'pam_faildelay.so' /etc/pam.d/SERVICE_NAME || echo 'pam_faildelay entry removed'

Replace the backup placeholder with the exact file created in step 2. Do not delete the backup until a fresh login has succeeded. If the service is managed by a configuration system, make the same correction there or the bad line may return.

7. Know what the module does not do

pam_faildelay does not count failures, lock accounts, block IP addresses or replace pam_faillock. It asks PAM to delay the result of a failed authentication for the application stack. It also does not provide a general shell command for changing a user's login policy.

The module accepts debug, which sends debugging messages to syslog, and delay=N. An invalid delay is a configuration error; the installed manpage documents PAM_SYSTEM_ERR for an invalid value. Do not enable debugging on a busy authentication service without checking your logging policy first.