1PAM_FAILLOCK(8) Linux-PAM Manual PAM_FAILLOCK(8)
2
6 pam_faillock - Module counting authentication failures during a
7 specified interval
8
10 auth ... pam_faillock.so {preauth|authfail|authsucc}
11 [dir=/path/to/tally-directory]
12 [even_deny_root] [deny=n] [fail_interval=n]
13 [unlock_time=n] [root_unlock_time=n]
14 [admin_group=name] [audit] [silent]
15 [no_log_info]
16 account ... pam_faillock.so [dir=/path/to/tally-directory]
18 [no_log_info]
19
21 This module maintains a list of failed authentication attempts per user
22 during a specified interval and locks the account in case there were
23 more than deny consecutive failed authentications.
24 Normally, failed attempts to authenticate root will not cause the root
26 account to become blocked, to prevent denial-of-service: if your users
27 aren't given shell accounts and root may only login via su or at the
28 machine console (not telnet/rsh, etc), this is safe.
29
31 {preauth|authfail|authsucc}
32 This argument must be set accordingly to the position of this
33 module instance in the PAM stack.
34 The preauth argument must be used when the module is called before
36 the modules which ask for the user credentials such as the
37 password. The module just examines whether the user should be
38 blocked from accessing the service in case there were anomalous
39 number of failed consecutive authentication attempts recently. This
40 call is optional if authsucc is used.
41 The authfail argument must be used when the module is called after
43 the modules which determine the authentication outcome, failed.
44 Unless the user is already blocked due to previous authentication
45 failures, the module will record the failure into the appropriate
46 user tally file.
47 The authsucc argument must be used when the module is called after
49 the modules which determine the authentication outcome, succeded.
50 Unless the user is already blocked due to previous authentication
51 failures, the module will then clear the record of the failures in
52 the respective user tally file. Otherwise it will return
53 authentication error. If this call is not done, the pam_faillock
54 will not distinguish between consecutive and non-consecutive failed
55 authentication attempts. The preauth call must be used in such
56 case. Due to complications in the way the PAM stack can be
57 configured it is also possible to call pam_faillock as an account
58 module. In such configuration the module must be also called in the
59 preauth stage.
60 The options for configuring the module behavior are described in the
62 faillock.conf(5) manual page. The options specified on the module
63 command line override the values from the configuration file.
64
66 The auth and account module types are provided.
67
69 PAM_AUTH_ERR
70 A invalid option was given, the module was not able to retrieve the
71 user name, no valid counter file was found, or too many failed
72 logins.
73 PAM_SUCCESS
75 Everything was successful.
76 PAM_IGNORE
78 User not present in passwd database.
79
81 Configuring options on the module command line is not recommend. The
82 /etc/security/faillock.conf should be used instead.
83 The setup of pam_faillock in the PAM stack is different from the
85 pam_tally2 module setup.
86 Individual files with the failure records are created as owned by the
88 user. This allows pam_faillock.so module to work correctly when it is
89 called from a screensaver.
90 Note that using the module in preauth without the silent option
92 specified in /etc/security/faillock.conf or with requisite control
93 field leaks an information about existence or non-existence of an user
94 account in the system because the failures are not recorded for the
95 unknown users. The message about the user account being locked is never
96 displayed for nonexisting user accounts allowing the adversary to infer
97 that a particular account is not existing on a system.
98
100 Here are two possible configuration examples for /etc/pam.d/login. They
101 make pam_faillock to lock the account after 4 consecutive failed logins
102 during the default interval of 15 minutes. Root account will be locked
103 as well. The accounts will be automatically unlocked after 20 minutes.
104 In the first example the module is called only in the auth phase and
106 the module does not print any information about the account blocking by
107 pam_faillock. The preauth call can be added to tell the user that his
108 login is blocked by the module and also to abort the authentication
109 without even asking for password in such case.
110 /etc/security/faillock.conf file example:
112 deny=4
114 unlock_time=1200
115 silent
116 /etc/pam.d/config file example:
119 auth required pam_securetty.so
121 auth required pam_env.so
122 auth required pam_nologin.so
123 # optionally call: auth requisite pam_faillock.so preauth
124 # to display the message about account being locked
125 auth [success=1 default=bad] pam_unix.so
126 auth [default=die] pam_faillock.so authfail
127 auth sufficient pam_faillock.so authsucc
128 auth required pam_deny.so
129 account required pam_unix.so
130 password required pam_unix.so shadow
131 session required pam_selinux.so close
132 session required pam_loginuid.so
133 session required pam_unix.so
134 session required pam_selinux.so open
135 In the second example the module is called both in the auth and account
138 phases and the module gives the authenticating user message when the
139 account is locked if silent option is not specified in the
140 faillock.conf.
141 auth required pam_securetty.so
143 auth required pam_env.so
144 auth required pam_nologin.so
145 auth required pam_faillock.so preauth
146 # optionally use requisite above if you do not want to prompt for the password
147 # on locked accounts
148 auth sufficient pam_unix.so
149 auth [default=die] pam_faillock.so authfail
150 auth required pam_deny.so
151 account required pam_faillock.so
152 # if you drop the above call to pam_faillock.so the lock will be done also
153 # on non-consecutive authentication failures
154 account required pam_unix.so
155 password required pam_unix.so shadow
156 session required pam_selinux.so close
157 session required pam_loginuid.so
158 session required pam_unix.so
159 session required pam_selinux.so open
160
163 /var/run/faillock/*
164 the files logging the authentication failures for users
165 /etc/security/faillock.conf
167 the config file for pam_faillock options
168
170 faillock(8), faillock.conf(5), pam.conf(5), pam.d(5), pam(8)
171
173 pam_faillock was written by Tomas Mraz.
174Linux-PAM Manual 03/09/2020 PAM_FAILLOCK(8)