1PAM_FAILLOCK(8)                Linux-PAM Manual                PAM_FAILLOCK(8)
2
3
4

NAME

6       pam_faillock - Module counting authentication failures during a
7       specified interval
8

SYNOPSIS

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
17       account ... pam_faillock.so [dir=/path/to/tally-directory]
18                                   [no_log_info]
19

DESCRIPTION

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
25       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

OPTIONS

31       {preauth|authfail|authsucc}
32           This argument must be set accordingly to the position of this
33           module instance in the PAM stack.
34
35           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
42           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
48           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
61       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
65       audit
66           Will log the user name into the system log if the user is not
67           found.
68
69       silent
70           Don't print informative messages. This option is implicite in the
71           authfail and authsucc functions.
72
73       no_log_info
74           Don't log informative messages via syslog(3).
75
76       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
81       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
86       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
92           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
97           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
102       even_deny_root
103           Root account can become locked as well as regular accounts.
104
105       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
111       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

MODULE TYPES PROVIDED

118       The auth and account module types are provided.
119

RETURN VALUES

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
126       PAM_SUCCESS
127           Everything was successful.
128
129       PAM_IGNORE
130           User not present in passwd database.
131

NOTES

133       pam_faillock setup in the PAM stack is different from the pam_tally2
134       module setup.
135
136       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
140       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

EXAMPLES

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
154       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
160           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
176
177       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
181           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
200

FILES

202       /var/run/faillock/*
203           the files logging the authentication failures for users
204

SEE ALSO

206       faillock(8), pam.conf(5), pam.d(5), pam(8)
207

AUTHOR

209       pam_faillock was written by Tomas Mraz.
210
211
212
213Linux-PAM Manual                  05/11/2019                   PAM_FAILLOCK(8)
Impressum