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

   dir=/path/to/tally-directory

           The directory where the user files with the failure records are
           kept. The default is /var/run/faillock.

   audit

           Will log the user name into the system log if the user is not
           found.

   silent

           Don't print informative messages. This option is implicite in the
           authfail and authsucc functions.

   no_log_info

           Don't log informative messages via syslog(3).

   deny=n

           Deny access if the number of consecutive authentication failures
           for this user during the recent interval exceeds n. The default is
           3.

   fail_interval=n

           The length of the interval during which the consecutive
           authentication failures must happen for the user account lock out
           is n seconds. The default is 900 (15 minutes).

   unlock_time=n

           The access will be reenabled after n seconds after the lock out.
           The default is 600 (10 minutes).

           If the n is set to never or 0 the access will not be reenabled at
           all until administrator explicitly reenables it with the faillock
           command. Note though that the default directory that pam_faillock
           uses is usually cleared on system boot so the access will be also
           reenabled after system reboot. If that is undesirable a different
           tally directory must be set with the dir option.

           Also note that it is usually undesirable to permanently lock out
           the users as they can become easily a target of denial of service
           attack unless the usernames are random and kept secret to
           potential attackers.

   even_deny_root

           Root account can become locked as well as regular accounts.

   root_unlock_time=n

           This option implies even_deny_root option. Allow access after n
           seconds to root account after the account is locked. In case the
           option is not specified the value is the same as of the
           unlock_time option.

   admin_group=name

           If a group name is specified with this option, members of the
           group will be handled by this module the same as the root account
           (the options even_deny_root> and root_unlock_time will apply to
           them. By default the option is not set.

NOTES

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

   The 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 or with
   requisite control field leaks an information about existence or
   non-existence of an 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 nonexisting user accounts allowing the
   adversary to infer that a particular account is not existing on a system.

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 blocking by
   pam_faillock. The preauth call can be added to tell the user that his
   login is blocked by the module and also to abort the authentication
   without even asking for password in such case.

 auth     required       pam_securetty.so
 auth     required       pam_env.so
 auth     required       pam_nologin.so
 # optionally call: auth requisite pam_faillock.so preauth deny=4 even_deny_root unlock_time=1200
 # to display the message about account being locked
 auth     [success=1 default=bad] pam_unix.so
 auth     [default=die]  pam_faillock.so authfail deny=4 even_deny_root unlock_time=1200
 auth     sufficient     pam_faillock.so authsucc deny=4 even_deny_root unlock_time=1200
 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 gives the authenticating user message when the
   account is locked

 auth     required       pam_securetty.so
 auth     required       pam_env.so
 auth     required       pam_nologin.so
 auth     required       pam_faillock.so preauth silent deny=4 even_deny_root unlock_time=1200
 # optionally use requisite above if you do not want to prompt for the password
 # on locked accounts, possibly with removing the silent option as well
 auth     sufficient     pam_unix.so
 auth     [default=die]  pam_faillock.so authfail deny=4 even_deny_root unlock_time=1200
 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.