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

DESCRIPTION

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

OPTIONS

32       {preauth|authfail|authsucc}
33           This argument must be set accordingly to the position of this
34           module instance in the PAM stack.
35
36           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
43           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
49           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
62       conf=/path/to/config-file
63           Use another configuration file instead of the default
64           /etc/security/faillock.conf.
65
66       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

MODULE TYPES PROVIDED

71       The auth and account module types are provided.
72

RETURN VALUES

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
79       PAM_BUF_ERR
80           Memory buffer error.
81
82       PAM_CONV_ERR
83           The conversation method supplied by the application failed to
84           obtain the username.
85
86       PAM_INCOMPLETE
87           The conversation method supplied by the application returned
88           PAM_CONV_AGAIN.
89
90       PAM_SUCCESS
91           Everything was successful.
92
93       PAM_IGNORE
94           User not present in passwd database.
95

NOTES

97       Configuring options on the module command line is not recommend. The
98       /etc/security/faillock.conf should be used instead.
99
100       The setup of pam_faillock in the PAM stack is different from the
101       pam_tally2 module setup.
102
103       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
107       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

EXAMPLES

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
121       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
127       /etc/security/faillock.conf file example:
128
129           deny=4
130           unlock_time=1200
131           silent
132
133
134       /etc/pam.d/config file example:
135
136           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
152
153       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
157           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
176

FILES

178       /var/run/faillock/*
179           the files logging the authentication failures for users
180
181       /etc/security/faillock.conf
182           the config file for pam_faillock options
183

SEE ALSO

185       faillock(8), faillock.conf(5), pam.conf(5), pam.d(5), pam(8)
186

AUTHOR

188       pam_faillock was written by Tomas Mraz.
189
190
191
192Linux-PAM Manual                  09/03/2021                   PAM_FAILLOCK(8)
Impressum