pam_faillock -- Module counting authentication failures during a specified
interval
     __________________________________________________________________

DESCRIPTION

   This module maintains a list of failed authentication attempts per user
   during a specified interval and locks the account in case there were
   more than deny consecutive failed authentications.

   Normally, failed attempts to authenticate root will not cause the root
   account to become blocked, to prevent denial-of-service: if your users
   aren't given shell accounts and root may only login via su or at the
   machine console (not telnet/rsh, etc), this is safe.

OPTIONS

   {preauth|authfail|authsucc}
          This argument must be set accordingly to the position of this
          module instance in the PAM stack.

          The preauth argument must be used when the module is called
          before the modules which ask for the user credentials such as
          the password. The module just examines whether the user should
          be blocked from accessing the service in case there were
          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,
          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,
          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, the
          pam_faillock will not distinguish between consecutive and
          non-consecutive failed authentication attempts. The preauth call
          must be used in such case. Due to complications in the way the
          PAM stack can be configured it is also possible to call
          pam_faillock as an account module. In such configuration the
          module must be also called in the preauth stage.

   conf=/path/to/config-file
          Use another configuration file instead of the default
          /etc/security/faillock.conf.

          Use another configuration file instead of the default which is
          to use the file /etc/security/faillock.conf or, if that one is
          not present, the file %vendordir%/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.

NOTES

   Configuring options on the module command line is not recommend. The
   /etc/security/faillock.conf should be used instead.

   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.

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

AUTHOR

   pam_faillock was written by Tomas Mraz.
