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] [audit]
14 [silent] [no_log_info]
15 account ... pam_faillock.so [dir=/path/to/tally-directory]
17 [no_log_info]
18
20 This module maintains a list of failed authentication attempts per user
21 during a specified interval and locks the account in case there were
22 more than deny consecutive failed authentications.
23 Normally, failed attempts to authenticate root will not cause the root
25 account to become blocked, to prevent denial-of-service: if your users
26 aren´t given shell accounts and root may only login via su or at the
27 machine console (not telnet/rsh, etc), this is safe.
28
30 {preauth|authfail|authsucc}
31 This argument must be set accordingly to the position of this
32 module instance in the PAM stack.
33 The preauth argument must be used when the module is called before
35 the modules which ask for the user credentials such as the
36 password. The module just examines whether the user should be
37 blocked from accessing the service in case there were anomalous
38 number of failed consecutive authentication attempts recently. This
39 call is optional if authsucc is used.
40 The authfail argument must be used when the module is called after
42 the modules which determine the authentication outcome, failed.
43 Unless the user is already blocked due to previous authentication
44 failures, the module will record the failure into the appropriate
45 user tally file.
46 The authsucc argument must be used when the module is called after
48 the modules which determine the authentication outcome, succeded.
49 Unless the user is already blocked due to previous authentication
50 failures, the module will then clear the record of the failures in
51 the respective user tally file. Otherwise it will return
52 authentication error. If this call is not done, the pam_faillock
53 will not distinguish between consecutive and non-consecutive failed
54 authentication attempts. The preauth call must be used in such
55 case. Due to complications in the way the PAM stack can be
56 configured it is also possible to call pam_faillock as an account
57 module. In such configuration the module must be also called in the
58 preauth stage.
59 dir=/path/to/tally-directory
61 The directory where the user files with the failure records are
62 kept. The default is /var/run/faillock.
63 audit
65 Will log the user name into the system log if the user is not
66 found.
67 silent
69 Don´t print informative messages. This option is implicite in the
70 authfail and authsucc functions.
71 no_log_info
73 Don´t log informative messages via syslog(3).
74 deny=n
76 Deny access if the number of consecutive authentication failures
77 for this user during the recent interval exceeds n. The default is
78 3.
79 fail_interval=n
81 The length of the interval during which the consecutive
82 authentication failures must happen for the user account lock out
83 is n seconds. The default is 900 (15 minutes).
84 unlock_time=n
86 The access will be reenabled after n seconds after the lock out.
87 The default is 600 (10 minutes).
88 If the n is set to never or 0 the access will not be reenabled at
90 all until administrator explicitly reenables it with the faillock
91 command. Note though that the default directory that pam_faillock
92 uses is usually cleared on system boot so the access will be also
93 reenabled after system reboot. If that is undesirable a different
94 tally directory must be set with the dir option.
95 Also note that it is usually undesirable to permanently lock out
97 the users as they can become easily a target of denial of service
98 attack unless the usernames are random and kept secret to potential
99 attackers.
100 even_deny_root
102 Root account can become locked as well as regular accounts.
103 root_unlock_time=n
105 This option implies even_deny_root option. Allow access after n
106 seconds to root account after the account is locked. In case the
107 option is not specified the value is the same as of the unlock_time
108 option.
109
111 The auth and account module types are provided.
112
114 PAM_AUTH_ERR
115 A invalid option was given, the module was not able to retrieve the
116 user name, no valid counter file was found, or too many failed
117 logins.
118 PAM_SUCCESS
120 Everything was successful.
121 PAM_IGNORE
123 User not present in passwd database.
124
126 pam_faillock setup in the PAM stack is different from the pam_tally2
127 module setup.
128 The individual files with the failure records are created as owned by
130 the user. This allows pam_faillock.so module to work correctly when it
131 is called from a screensaver.
132 Note that using the module in preauth without the silent option or with
134 requisite control field leaks an information about existence or
135 non-existence of an user account in the system because the failures are
136 not recorded for the unknown users. The message about the user account
137 being locked is never displayed for nonexisting user accounts allowing
138 the adversary to infer that a particular account is not existing on a
139 system.
140
142 Here are two possible configuration examples for /etc/pam.d/login. They
143 make pam_faillock to lock the account after 4 consecutive failed logins
144 during the default interval of 15 minutes. Root account will be locked
145 as well. The accounts will be automatically unlocked after 20 minutes.
146 In the first example the module is called only in the auth phase and
148 the module does not print any information about the account blocking by
149 pam_faillock. The preauth call can be added to tell the user that his
150 login is blocked by the module and also to abort the authentication
151 without even asking for password in such case.
152 auth required pam_securetty.so
154 auth required pam_env.so
155 auth required pam_nologin.so
156 # optionally call: auth requisite pam_faillock.so preauth deny=4 even_deny_root unlock_time=1200
157 # to display the message about account being locked
158 auth [success=1 default=bad] pam_unix.so
159 auth [default=die] pam_faillock.so authfail deny=4 even_deny_root unlock_time=1200
160 auth sufficient pam_faillock.so authsucc deny=4 even_deny_root unlock_time=1200
161 auth required pam_deny.so
162 account required pam_unix.so
163 password required pam_unix.so shadow
164 session required pam_selinux.so close
165 session required pam_loginuid.so
166 session required pam_unix.so
167 session required pam_selinux.so open
168 In the second example the module is called both in the auth and account
171 phases and the module gives the authenticating user message when the
172 account is locked
173 auth required pam_securetty.so
175 auth required pam_env.so
176 auth required pam_nologin.so
177 auth required pam_faillock.so preauth silent deny=4 even_deny_root unlock_time=1200
178 # optionally use requisite above if you do not want to prompt for the password
179 # on locked accounts, possibly with removing the silent option as well
180 auth sufficient pam_unix.so
181 auth [default=die] pam_faillock.so authfail deny=4 even_deny_root unlock_time=1200
182 auth required pam_deny.so
183 account required pam_faillock.so
184 # if you drop the above call to pam_faillock.so the lock will be done also
185 # on non-consecutive authentication failures
186 account required pam_unix.so
187 password required pam_unix.so shadow
188 session required pam_selinux.so close
189 session required pam_loginuid.so
190 session required pam_unix.so
191 session required pam_selinux.so open
192
195 /var/run/faillock/*
196 the files logging the authentication failures for users
197
199 faillock(8), pam.conf(5), pam.d(5), pam(8)
200
202 pam_faillock was written by Tomas Mraz.
203Linux-PAM Manual 03/22/2017 PAM_FAILLOCK(8)