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

MODULE TYPES PROVIDED

66       The auth and account module types are provided.
67

RETURN VALUES

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
74       PAM_SUCCESS
75           Everything was successful.
76
77       PAM_IGNORE
78           User not present in passwd database.
79

NOTES

81       Configuring options on the module command line is not recommend. The
82       /etc/security/faillock.conf should be used instead.
83
84       The setup of pam_faillock in the PAM stack is different from the
85       pam_tally2 module setup.
86
87       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
91       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

EXAMPLES

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
105       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
111       /etc/security/faillock.conf file example:
112
113           deny=4
114           unlock_time=1200
115           silent
116
117
118       /etc/pam.d/config file example:
119
120           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
136
137       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
142           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
161

FILES

163       /var/run/faillock/*
164           the files logging the authentication failures for users
165
166       /etc/security/faillock.conf
167           the config file for pam_faillock options
168

SEE ALSO

170       faillock(8), faillock.conf(5), pam.conf(5), pam.d(5), pam(8)
171

AUTHOR

173       pam_faillock was written by Tomas Mraz.
174
175
176
177Linux-PAM Manual                  03/09/2020                   PAM_FAILLOCK(8)
Impressum