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 dir=/path/to/tally-directory
62 The directory where the user files with the failure records are
63 kept. The default is /var/run/faillock.
64 audit
66 Will log the user name into the system log if the user is not
67 found.
68 silent
70 Don't print informative messages. This option is implicite in the
71 authfail and authsucc functions.
72 no_log_info
74 Don't log informative messages via syslog(3).
75 deny=n
77 Deny access if the number of consecutive authentication failures
78 for this user during the recent interval exceeds n. The default is
79 3.
80 fail_interval=n
82 The length of the interval during which the consecutive
83 authentication failures must happen for the user account lock out
84 is n seconds. The default is 900 (15 minutes).
85 unlock_time=n
87 The access will be reenabled after n seconds after the lock out.
88 The value 0 has the same meaning as value never - the access will
89 not be reenabled without resetting the faillock entries by the
90 faillock(8) command. The default is 600 (10 minutes).
91 Note that the default directory that pam_faillock uses is usually
93 cleared on system boot so the access will be also reenabled after
94 system reboot. If that is undesirable a different tally directory
95 must be set with the dir option.
96 Also note that it is usually undesirable to permanently lock out
98 the users as they can become easily a target of denial of service
99 attack unless the usernames are random and kept secret to potential
100 attackers.
101 even_deny_root
103 Root account can become locked as well as regular accounts.
104 root_unlock_time=n
106 This option implies even_deny_root option. Allow access after n
107 seconds to root account after the account is locked. In case the
108 option is not specified the value is the same as of the unlock_time
109 option.
110 admin_group=name
112 If a group name is specified with this option, members of the group
113 will be handled by this module the same as the root account (the
114 options even_deny_root> and root_unlock_time will apply to them. By
115 default the option is not set.
116
118 The auth and account module types are provided.
119
121 PAM_AUTH_ERR
122 A invalid option was given, the module was not able to retrieve the
123 user name, no valid counter file was found, or too many failed
124 logins.
125 PAM_SUCCESS
127 Everything was successful.
128 PAM_IGNORE
130 User not present in passwd database.
131
133 pam_faillock setup in the PAM stack is different from the pam_tally2
134 module setup.
135 The individual files with the failure records are created as owned by
137 the user. This allows pam_faillock.so module to work correctly when it
138 is called from a screensaver.
139 Note that using the module in preauth without the silent option or with
141 requisite control field leaks an information about existence or
142 non-existence of an user account in the system because the failures are
143 not recorded for the unknown users. The message about the user account
144 being locked is never displayed for nonexisting user accounts allowing
145 the adversary to infer that a particular account is not existing on a
146 system.
147
149 Here are two possible configuration examples for /etc/pam.d/login. They
150 make pam_faillock to lock the account after 4 consecutive failed logins
151 during the default interval of 15 minutes. Root account will be locked
152 as well. The accounts will be automatically unlocked after 20 minutes.
153 In the first example the module is called only in the auth phase and
155 the module does not print any information about the account blocking by
156 pam_faillock. The preauth call can be added to tell the user that his
157 login is blocked by the module and also to abort the authentication
158 without even asking for password in such case.
159 auth required pam_securetty.so
161 auth required pam_env.so
162 auth required pam_nologin.so
163 # optionally call: auth requisite pam_faillock.so preauth deny=4 even_deny_root unlock_time=1200
164 # to display the message about account being locked
165 auth [success=1 default=bad] pam_unix.so
166 auth [default=die] pam_faillock.so authfail deny=4 even_deny_root unlock_time=1200
167 auth sufficient pam_faillock.so authsucc deny=4 even_deny_root unlock_time=1200
168 auth required pam_deny.so
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 In the second example the module is called both in the auth and account
178 phases and the module gives the authenticating user message when the
179 account is locked
180 auth required pam_securetty.so
182 auth required pam_env.so
183 auth required pam_nologin.so
184 auth required pam_faillock.so preauth silent deny=4 even_deny_root unlock_time=1200
185 # optionally use requisite above if you do not want to prompt for the password
186 # on locked accounts, possibly with removing the silent option as well
187 auth sufficient pam_unix.so
188 auth [default=die] pam_faillock.so authfail deny=4 even_deny_root unlock_time=1200
189 auth required pam_deny.so
190 account required pam_faillock.so
191 # if you drop the above call to pam_faillock.so the lock will be done also
192 # on non-consecutive authentication failures
193 account required pam_unix.so
194 password required pam_unix.so shadow
195 session required pam_selinux.so close
196 session required pam_loginuid.so
197 session required pam_unix.so
198 session required pam_selinux.so open
199
202 /var/run/faillock/*
203 the files logging the authentication failures for users
204
206 faillock(8), pam.conf(5), pam.d(5), pam(8)
207
209 pam_faillock was written by Tomas Mraz.
210Linux-PAM Manual 05/11/2019 PAM_FAILLOCK(8)