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 [conf=/path/to/config-file]
12 [dir=/path/to/tally-directory]
13 [even_deny_root] [deny=n] [fail_interval=n]
14 [unlock_time=n] [root_unlock_time=n]
15 [admin_group=name] [audit] [silent]
16 [no_log_info]
17 account ... pam_faillock.so [dir=/path/to/tally-directory]
19 [no_log_info]
20
22 This module maintains a list of failed authentication attempts per user
23 during a specified interval and locks the account in case there were
24 more than deny consecutive failed authentications.
25 Normally, failed attempts to authenticate root will not cause the root
27 account to become blocked, to prevent denial-of-service: if your users
28 aren't given shell accounts and root may only login via su or at the
29 machine console (not telnet/rsh, etc), this is safe.
30
32 {preauth|authfail|authsucc}
33 This argument must be set accordingly to the position of this
34 module instance in the PAM stack.
35 The preauth argument must be used when the module is called before
37 the modules which ask for the user credentials such as the
38 password. The module just examines whether the user should be
39 blocked from accessing the service in case there were anomalous
40 number of failed consecutive authentication attempts recently. This
41 call is optional if authsucc is used.
42 The authfail argument must be used when the module is called after
44 the modules which determine the authentication outcome, failed.
45 Unless the user is already blocked due to previous authentication
46 failures, the module will record the failure into the appropriate
47 user tally file.
48 The authsucc argument must be used when the module is called after
50 the modules which determine the authentication outcome, succeeded.
51 Unless the user is already blocked due to previous authentication
52 failures, the module will then clear the record of the failures in
53 the respective user tally file. Otherwise it will return
54 authentication error. If this call is not done, the pam_faillock
55 will not distinguish between consecutive and non-consecutive failed
56 authentication attempts. The preauth call must be used in such
57 case. Due to complications in the way the PAM stack can be
58 configured it is also possible to call pam_faillock as an account
59 module. In such configuration the module must be also called in the
60 preauth stage.
61 conf=/path/to/config-file
63 Use another configuration file instead of the default
64 /etc/security/faillock.conf.
65 The options for configuring the module behavior are described in the
67 faillock.conf(5) manual page. The options specified on the module
68 command line override the values from the configuration file.
69
71 The auth and account module types are provided.
72
74 PAM_AUTH_ERR
75 An invalid option was given, the module was not able to retrieve
76 the user name, no valid counter file was found, or too many failed
77 logins.
78 PAM_BUF_ERR
80 Memory buffer error.
81 PAM_CONV_ERR
83 The conversation method supplied by the application failed to
84 obtain the username.
85 PAM_INCOMPLETE
87 The conversation method supplied by the application returned
88 PAM_CONV_AGAIN.
89 PAM_SUCCESS
91 Everything was successful.
92 PAM_IGNORE
94 User not present in passwd database.
95
97 Configuring options on the module command line is not recommend. The
98 /etc/security/faillock.conf should be used instead.
99 The setup of pam_faillock in the PAM stack is different from the
101 pam_tally2 module setup.
102 Individual files with the failure records are created as owned by the
104 user. This allows pam_faillock.so module to work correctly when it is
105 called from a screensaver.
106 Note that using the module in preauth without the silent option
108 specified in /etc/security/faillock.conf or with requisite control
109 field leaks an information about existence or non-existence of a user
110 account in the system because the failures are not recorded for the
111 unknown users. The message about the user account being locked is never
112 displayed for non-existing user accounts allowing the adversary to
113 infer that a particular account is not existing on a system.
114
116 Here are two possible configuration examples for /etc/pam.d/login. They
117 make pam_faillock to lock the account after 4 consecutive failed logins
118 during the default interval of 15 minutes. Root account will be locked
119 as well. The accounts will be automatically unlocked after 20 minutes.
120 In the first example the module is called only in the auth phase and
122 the module does not print any information about the account being
123 blocked by pam_faillock. The preauth call can be added to tell users
124 that their logins are blocked by the module and also to abort the
125 authentication without even asking for password in such case.
126 /etc/security/faillock.conf file example:
128 deny=4
130 unlock_time=1200
131 silent
132 /etc/pam.d/config file example:
135 auth required pam_securetty.so
137 auth required pam_env.so
138 auth required pam_nologin.so
139 # optionally call: auth requisite pam_faillock.so preauth
140 # to display the message about account being locked
141 auth [success=1 default=bad] pam_unix.so
142 auth [default=die] pam_faillock.so authfail
143 auth sufficient pam_faillock.so authsucc
144 auth required pam_deny.so
145 account required pam_unix.so
146 password required pam_unix.so shadow
147 session required pam_selinux.so close
148 session required pam_loginuid.so
149 session required pam_unix.so
150 session required pam_selinux.so open
151 In the second example the module is called both in the auth and account
154 phases and the module informs the authenticating user when the account
155 is locked if silent option is not specified in the faillock.conf.
156 auth required pam_securetty.so
158 auth required pam_env.so
159 auth required pam_nologin.so
160 auth required pam_faillock.so preauth
161 # optionally use requisite above if you do not want to prompt for the password
162 # on locked accounts
163 auth sufficient pam_unix.so
164 auth [default=die] pam_faillock.so authfail
165 auth required pam_deny.so
166 account required pam_faillock.so
167 # if you drop the above call to pam_faillock.so the lock will be done also
168 # on non-consecutive authentication failures
169 account required pam_unix.so
170 password required pam_unix.so shadow
171 session required pam_selinux.so close
172 session required pam_loginuid.so
173 session required pam_unix.so
174 session required pam_selinux.so open
175
178 /var/run/faillock/*
179 the files logging the authentication failures for users
180 /etc/security/faillock.conf
182 the config file for pam_faillock options
183
185 faillock(8), faillock.conf(5), pam.conf(5), pam.d(5), pam(8)
186
188 pam_faillock was written by Tomas Mraz.
189Linux-PAM Manual 09/03/2021 PAM_FAILLOCK(8)