pam_faillock(8) - Module counting authentication failures during a specified interval



  • PAM_FAILLOCK(8)		       Linux-PAM Manual		       PAM_FAILLOCK(8)
    
    
    
    NAME
           pam_faillock - Module counting authentication failures during a
           specified interval
    
    SYNOPSIS
           auth ... pam_faillock.so {preauth|authfail|authsucc}
    				[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
           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.
    
    MODULE TYPES PROVIDED
           The auth and account module types are provided.
    
    RETURN VALUES
           PAM_AUTH_ERR
    	   A 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_SUCCESS
    	   Everything was successful.
    
           PAM_IGNORE
    	   User not present in passwd database.
    
    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
    
    
    FILES
           /var/run/faillock/*
    	   the files logging the authentication failures for users
    
    SEE ALSO
           faillock(8), pam.conf(5), pam.d(5), pam(8)
    
    AUTHOR
           pam_faillock was written by Tomas Mraz.
    
    
    
    Linux-PAM Manual		  04/11/2018		       PAM_FAILLOCK(8)
    

Log in to reply
 

© Lightnetics 2024