PAM_FAILLOCK(8)

📦
version 1.7.3 · 19 versions
, in arch rolling

💖 PAM_FAILLOCK(8) 💖

okay bestie, gather round, because this is pam_faillock from the Linux-PAM Manual and she is literally the bouncer of your login stack 👑✨

✨ NAME ✨

pam_faillock — a module that counts authentication failures during a specified interval 🕰️💀

🌸 SYNOPSIS 🌸

auth ... pam_faillock.so {preauth|authfail|authsucc}
                         [conf=/path/to/config-file]
                         [dir=/path/to/tally-directory] [even_deny_root]
                         [deny=n] [fail_interval=n] [unlock_time=n]
                         [root_unlock_time=n] [admin_group=name] [audit]
                         [silent] [no_log_info]

account ... pam_faillock.so [dir=/path/to/tally-directory] [no_log_info]

🦋 DESCRIPTION 🦋

So what does she actually do? She keeps a lil list 📝 of failed authentication attempts per user during a specified interval, and if there were more than deny consecutive failed authentications, she locks the account. That's it. That's the whole vibe. no cap.

Now, plot twist: normally, failed attempts to authenticate root will not cause the root account to become blocked, and that's on purpose — it prevents denial-of-service 🙅‍♀️. The logic being: if your users aren't given shell accounts, and root may only login via su or at the machine console (not telnet/rsh, etc), then this is safe. ✨

💅 OPTIONS 💅

  • {preauth|authfail|authsucc} — this argument has to be set to match wherever this module instance sits in the PAM stack. You don't get to freestyle it, bestie, it's giving positional.
    • The preauth argument must be used when the module is called before the modules which ask for the user credentials, like the password. In this mode the module just peeks 👀 at whether the user should be blocked from accessing the service, in case there were an anomalous number of failed consecutive authentication attempts recently. This call is optional if authsucc is used.
    • The authfail argument must be used when the module is called after the modules which determine the authentication outcome, and that outcome was failed. Unless the user is already blocked due to previous authentication failures, the module will record the failure into the appropriate user tally file. 🗂️
    • The authsucc argument must be used when the module is called after the modules which determine the authentication outcome, and that outcome succeeded. Unless the user is already blocked due to previous authentication failures, the module will then clear the record of the failures in the respective user tally file. Otherwise it will return authentication error 😭. If this call is not done, pam_faillock will not distinguish between consecutive and non-consecutive failed authentication attempts. The preauth call must be used in such case. And because the PAM stack can be configured in complicated ways, it is also possible to call pam_faillock as an account module. In such a configuration the module must be also called in the preauth stage. (iykyk)
  • conf=/path/to/config-file — use another configuration file instead of the default /etc/security/faillock.conf 🎀

The options for configuring the module behavior are described in the faillock.conf(5) manual page. The options specified on the module command line override the values from the configuration file. 🔥

🌈 MODULE TYPES PROVIDED 🌈

The auth and account module types are provided. just the two. iconic behavior.

⭐ RETURN VALUES ⭐

  • PAM_AUTH_ERR — an invalid option was given, the module was not able to retrieve the user name, no valid counter file was found, or too many failed logins. 💀
  • PAM_BUF_ERR — memory buffer error.
  • PAM_CONV_ERR — the conversation method supplied by the application failed to obtain the username.
  • PAM_INCOMPLETE — the conversation method supplied by the application returned PAM_CONV_AGAIN.
  • PAM_SUCCESS — everything was successful. slay 💖
  • PAM_IGNORE — user not present in passwd database.

🎀 NOTES 🎀

Configuring options on the module command line is not recommend. The /etc/security/faillock.conf should be used instead. (yes bestie, the original says "recommend", we keep it exactly like that, we don't edit the ancestors)

The setup of pam_faillock in the PAM stack is different from the pam_tally2 module setup. 📌

Individual files with the failure records are created as owned by the user. This allows pam_faillock.so module to work correctly when it is called from a screensaver. 🖥️✨

Note that using the module in preauth without the silent option specified in /etc/security/faillock.conf or with requisite control field leaks an information about existence or non-existence of a user account in the system, because the failures are not recorded for the unknown users. The message about the user account being locked is never displayed for non-existing user accounts, allowing the adversary to infer that a particular account is not existing on a system. 🕵️‍♀️ so like… be careful, that's a whole information leak vibe.

If the auth stack has not been run prior to the account stack, the logic to reset the failed login counter is intentionally skipped. This prevents automated services, such as crond or systemd-user, which might only perform account management tasks, from inadvertently clearing a user's failed attempt records. This ensures the faillock counter is only reset by a service that performs a full, successful authentication. 👑

🍓 EXAMPLES 🍓

Here are two possible configuration examples for /etc/pam.d/login. They make pam_faillock lock the account after 4 consecutive failed logins during the default interval of 15 minutes. Root account will be locked as well. The accounts will be automatically unlocked after 20 minutes. 🕐

In the first example the module is called only in the auth phase and the module does not print any information about the account being blocked by pam_faillock. The preauth call can be added to tell users that their logins are blocked by the module and also to abort the authentication without even asking for password in such case. 🚫🔑

/etc/security/faillock.conf file example:

deny=4
unlock_time=1200
silent

/etc/pam.d/config file example:

auth     required       pam_securetty.so
auth     required       pam_env.so
auth     required       pam_nologin.so
# optionally call: auth requisite pam_faillock.so preauth
# to display the message about account being locked
auth     [success=1 default=bad] pam_unix.so
auth     [default=die]  pam_faillock.so authfail
auth     sufficient     pam_faillock.so authsucc
auth     required       pam_deny.so
account  required       pam_unix.so
password required       pam_unix.so shadow
session  required       pam_selinux.so close
session  required       pam_loginuid.so
session  required       pam_unix.so
session  required       pam_selinux.so open

In the second example the module is called both in the auth and account phases, and the module informs the authenticating user when the account is locked if silent option is not specified in the faillock.conf. 📢

auth     required       pam_securetty.so
auth     required       pam_env.so
auth     required       pam_nologin.so
auth     required       pam_faillock.so preauth
# optionally use requisite above if you do not want to prompt for the password
# on locked accounts
auth     sufficient     pam_unix.so
auth     [default=die]  pam_faillock.so authfail
auth     required       pam_deny.so
account  required       pam_faillock.so
# if you drop the above call to pam_faillock.so the lock will be done also
# on non-consecutive authentication failures
account  required       pam_unix.so
password required       pam_unix.so shadow
session  required       pam_selinux.so close
session  required       pam_loginuid.so
session  required       pam_unix.so
session  required       pam_selinux.so open

🧚 FILES 🧚

  • /var/run/faillock/* — the files logging the authentication failures for users 🗃️
    • Note: These files will disappear after reboot on systems configured with directory /var/run/faillock mounted on virtual memory. For persistent storage use the option dir= in file /etc/security/faillock.conf. 💾 (do NOT get caught lacking, bestie)
  • /etc/security/faillock.conf — the config file for pam_faillock options 🎀

🫶 SEE ALSO 🫶

faillock(8), faillock.conf(5), pam.conf(5), pam.d(5), pam(8)

👑 AUTHOR 👑

pam_faillock was written by Tomas Mraz. thank you king 🫡✨

and that's the whole page, bestie 💜 this version came out of [FIXME: source] on 09/27/2026 — yeah the source tag is literally still a FIXME and we're keeping it exactly as is, no notes, it's giving mysterious 🌸 mwah, go lock some accounts responsibly ✨💅

📦 where this page comes from