Debian Codegraph @

upstream/opensuse-tumbleweed/man8/pam_faillock.8

raw
1 '\" t
2 .\" Title: pam_faillock
3 .\" Author: [see the "AUTHOR" section]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 05/26/2026
6 .\" Manual: Linux-PAM Manual
7 .\" Source: [FIXME: source]
8 .\" Language: English
9 .\"
10 .TH "PAM_FAILLOCK" "8" "05/26/2026" "[FIXME: source]" "Linux\-PAM Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 pam_faillock \- Module counting authentication failures during a specified interval
32 .SH "SYNOPSIS"
33 .HP \w'\fBauth\ \&.\&.\&.\ pam_faillock\&.so\fR\ 'u
34 \fBauth \&.\&.\&. pam_faillock\&.so\fR {preauth|authfail|authsucc} [conf=\fI/path/to/config\-file\fR] [dir=\fI/path/to/tally\-directory\fR] [even_deny_root] [deny=\fIn\fR] [fail_interval=\fIn\fR] [unlock_time=\fIn\fR] [root_unlock_time=\fIn\fR] [admin_group=\fIname\fR] [audit] [silent] [no_log_info]
35 .HP \w'\fBaccount\ \&.\&.\&.\ pam_faillock\&.so\fR\ 'u
36 \fBaccount \&.\&.\&. pam_faillock\&.so\fR [dir=\fI/path/to/tally\-directory\fR] [no_log_info]
37 .SH "DESCRIPTION"
38 .PP
39 This module maintains a list of failed authentication attempts per user during a specified interval and locks the account in case there were more than
40 \fIdeny\fR
41 consecutive failed authentications\&.
42 .PP
43 Normally, failed attempts to authenticate
44 \fIroot\fR
45 will
46 \fBnot\fR
47 cause the root account to become blocked, to prevent denial\-of\-service: if your users aren\*(Aqt given shell accounts and root may only login via
48 \fBsu\fR
49 or at the machine console (not telnet/rsh, etc), this is safe\&.
50 .SH "OPTIONS"
51 .PP
52 {preauth|authfail|authsucc}
53 .RS 4
54 This argument must be set accordingly to the position of this module instance in the PAM stack\&.
55 .sp
56 The
57 \fIpreauth\fR
58 argument must be used when the module is called before the modules which ask for the user credentials such as the password\&. The module just examines whether the user should be blocked from accessing the service in case there were anomalous number of failed consecutive authentication attempts recently\&. This call is optional if
59 \fIauthsucc\fR
60 is used\&.
61 .sp
62 The
63 \fIauthfail\fR
64 argument must be used when the module is called after the modules which determine the authentication outcome, failed\&. Unless the user is already blocked due to previous authentication failures, the module will record the failure into the appropriate user tally file\&.
65 .sp
66 The
67 \fIauthsucc\fR
68 argument must be used when the module is called after the modules which determine the authentication outcome, succeeded\&. Unless the user is already blocked due to previous authentication failures, the module will then clear the record of the failures in the respective user tally file\&. Otherwise it will return authentication error\&. If this call is not done, the pam_faillock will not distinguish between consecutive and non\-consecutive failed authentication attempts\&. The
69 \fIpreauth\fR
70 call must be used in such case\&. Due to complications in the way the PAM stack can be configured it is also possible to call
71 \fIpam_faillock\fR
72 as an account module\&. In such configuration the module must be also called in the
73 \fIpreauth\fR
74 stage\&.
75 .RE
76 .PP
77 conf=/path/to/config\-file
78 .RS 4
79 Use another configuration file instead of the default which is to use the file
80 /etc/security/faillock\&.conf
81 or, if that one is not present, the file
82 /usr/etc/security/faillock\&.conf\&.
83 .RE
84 .PP
85 The options for configuring the module behavior are described in the
86 \fBfaillock.conf\fR(5)
87 manual page\&. The options specified on the module command line override the values from the configuration file\&.
88 .SH "MODULE TYPES PROVIDED"
89 .PP
90 The
91 \fBauth\fR
92 and
93 \fBaccount\fR
94 module types are provided\&.
95 .SH "RETURN VALUES"
96 .PP
97 PAM_AUTH_ERR
98 .RS 4
99 An invalid option was given, the module was not able to retrieve the user name, no valid counter file was found, or too many failed logins\&.
100 .RE
101 .PP
102 PAM_BUF_ERR
103 .RS 4
104 Memory buffer error\&.
105 .RE
106 .PP
107 PAM_CONV_ERR
108 .RS 4
109 The conversation method supplied by the application failed to obtain the username\&.
110 .RE
111 .PP
112 PAM_INCOMPLETE
113 .RS 4
114 The conversation method supplied by the application returned PAM_CONV_AGAIN\&.
115 .RE
116 .PP
117 PAM_SUCCESS
118 .RS 4
119 Everything was successful\&.
120 .RE
121 .PP
122 PAM_IGNORE
123 .RS 4
124 User not present in passwd database\&.
125 .RE
126 .SH "NOTES"
127 .PP
128 Configuring options on the module command line is not recommend\&. The
129 /etc/security/faillock\&.conf
130 should be used instead\&.
131 .PP
132 The setup of
133 \fIpam_faillock\fR
134 in the PAM stack is different from the
135 \fIpam_tally2\fR
136 module setup\&.
137 .PP
138 Individual files with the failure records are created as owned by the user\&. This allows
139 \fBpam_faillock\&.so\fR
140 module to work correctly when it is called from a screensaver\&.
141 .PP
142 Note that using the module in
143 \fBpreauth\fR
144 without the
145 \fBsilent\fR
146 option specified in
147 /etc/security/faillock\&.conf
148 or with
149 \fIrequisite\fR
150 control field leaks an information about existence or non\-existence of a user account in the system because the failures are not recorded for the unknown users\&. The message about the user account being locked is never displayed for non\-existing user accounts allowing the adversary to infer that a particular account is not existing on a system\&.
151 .PP
152 If the
153 \fBauth\fR
154 stack has not been run prior to the
155 \fBaccount\fR
156 stack, the logic to reset the failed login counter is intentionally skipped\&. This prevents automated services, such as
157 \fIcrond\fR
158 or
159 \fIsystemd\-user\fR, which might only perform account management tasks, from inadvertently clearing a user\*(Aqs failed attempt records\&. This ensures the faillock counter is only reset by a service that performs a full, successful authentication\&.
160 .SH "EXAMPLES"
161 .PP
162 Here are two possible configuration examples for
163 /etc/pam\&.d/login\&. They make
164 \fIpam_faillock\fR
165 to lock the account after 4 consecutive failed logins during the default interval of 15 minutes\&. Root account will be locked as well\&. The accounts will be automatically unlocked after 20 minutes\&.
166 .PP
167 In the first example the module is called only in the
168 \fIauth\fR
169 phase and the module does not print any information about the account being blocked by
170 \fIpam_faillock\fR\&. The
171 \fIpreauth\fR
172 call can be added to tell users that their logins are blocked by the module and also to abort the authentication without even asking for password in such case\&.
173 .PP
174 /etc/security/faillock\&.conf
175 file example:
176 .sp
177 .if n \{\
178 .RS 4
179 .\}
180 .nf
181 deny=4
182 unlock_time=1200
183 silent
184
185 .fi
186 .if n \{\
187 .RE
188 .\}
189 .PP
190 /etc/pam\&.d/config file example:
191 .sp
192 .if n \{\
193 .RS 4
194 .\}
195 .nf
196 auth required pam_securetty\&.so
197 auth required pam_env\&.so
198 auth required pam_nologin\&.so
199 # optionally call: auth requisite pam_faillock\&.so preauth
200 # to display the message about account being locked
201 auth [success=1 default=bad] pam_unix\&.so
202 auth [default=die] pam_faillock\&.so authfail
203 auth sufficient pam_faillock\&.so authsucc
204 auth required pam_deny\&.so
205 account required pam_unix\&.so
206 password required pam_unix\&.so shadow
207 session required pam_selinux\&.so close
208 session required pam_loginuid\&.so
209 session required pam_unix\&.so
210 session required pam_selinux\&.so open
211
212 .fi
213 .if n \{\
214 .RE
215 .\}
216 .PP
217 In the second example the module is called both in the
218 \fIauth\fR
219 and
220 \fIaccount\fR
221 phases and the module informs the authenticating user when the account is locked if
222 \fBsilent\fR
223 option is not specified in the
224 faillock\&.conf\&.
225 .sp
226 .if n \{\
227 .RS 4
228 .\}
229 .nf
230 auth required pam_securetty\&.so
231 auth required pam_env\&.so
232 auth required pam_nologin\&.so
233 auth required pam_faillock\&.so preauth
234 # optionally use requisite above if you do not want to prompt for the password
235 # on locked accounts
236 auth sufficient pam_unix\&.so
237 auth [default=die] pam_faillock\&.so authfail
238 auth required pam_deny\&.so
239 account required pam_faillock\&.so
240 # if you drop the above call to pam_faillock\&.so the lock will be done also
241 # on non\-consecutive authentication failures
242 account required pam_unix\&.so
243 password required pam_unix\&.so shadow
244 session required pam_selinux\&.so close
245 session required pam_loginuid\&.so
246 session required pam_unix\&.so
247 session required pam_selinux\&.so open
248
249 .fi
250 .if n \{\
251 .RE
252 .\}
253 .SH "FILES"
254 .PP
255 /var/run/faillock/*
256 .RS 4
257 the files logging the authentication failures for users
258 .sp
259 Note: These files will disappear after reboot on systems configured with directory
260 /var/run/faillock
261 mounted on virtual memory\&. For persistent storage use the option
262 \fIdir=\fR
263 in file
264 /etc/security/faillock\&.conf\&.
265 .RE
266 .PP
267 /etc/security/faillock\&.conf
268 .RS 4
269 the config file for pam_faillock options
270 .RE
271 .PP
272 /usr/etc/security/faillock\&.conf
273 .RS 4
274 the config file for pam_faillock options\&. It will be used if
275 /etc/security/faillock\&.conf
276 does not exist\&.
277 .RE
278 .SH "SEE ALSO"
279 .PP
280 \fBfaillock\fR(8),
281 \fBfaillock.conf\fR(5),
282 \fBpam.conf\fR(5),
283 \fBpam.d\fR(5),
284 \fBpam\fR(8)
285 .SH "AUTHOR"
286 .PP
287 pam_faillock was written by Tomas Mraz\&.