'\" t
.\"     Title: pam_faillock
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 09/10/2025
.\"    Manual: Linux-PAM Manual
.\"    Source: Linux-PAM Manual
.\"  Language: English
.\"
.TH "PAM_FAILLOCK" "8" "09/10/2025" "Linux-PAM Manual" "Linux\-PAM Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pam_faillock \- Module counting authentication failures during a specified interval
.SH "SYNOPSIS"
.HP \w'\fBauth\ \&.\&.\&.\ pam_faillock\&.so\fR\ 'u
\fBauth \&.\&.\&. pam_faillock\&.so\fR {preauth|authfail|authsucc} [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]
.HP \w'\fBaccount\ \&.\&.\&.\ pam_faillock\&.so\fR\ 'u
\fBaccount \&.\&.\&. pam_faillock\&.so\fR [dir=\fI/path/to/tally\-directory\fR] [no_log_info]
.SH "DESCRIPTION"
.PP
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
\fIdeny\fR
consecutive failed authentications\&.
.PP
Normally, failed attempts to authenticate
\fIroot\fR
will
\fBnot\fR
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
\fBsu\fR
or at the machine console (not telnet/rsh, etc), this is safe\&.
.SH "OPTIONS"
.PP
\fB{preauth|authfail|authsucc}\fR
.RS 4
This argument must be set accordingly to the position of this module instance in the PAM stack\&.
.sp
The
\fIpreauth\fR
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
\fIauthsucc\fR
is used\&.
.sp
The
\fIauthfail\fR
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\&.
.sp
The
\fIauthsucc\fR
argument must be used when the module is called after the modules which determine the authentication outcome, succeded\&. 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
\fIpreauth\fR
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
\fIpam_faillock\fR
as an account module\&. In such configuration the module must be also called in the
\fIpreauth\fR
stage\&.
.RE
.PP
\fBdir=\fR\fB\fI/path/to/tally\-directory\fR\fR
.RS 4
The directory where the user files with the failure records are kept\&. The default is
/var/run/faillock\&.
.RE
.PP
\fBaudit\fR
.RS 4
Will log the user name into the system log if the user is not found\&.
.RE
.PP
\fBsilent\fR
.RS 4
Don\*(Aqt print informative messages\&. This option is implicite in the
\fIauthfail\fR
and
\fIauthsucc\fR
functions\&.
.RE
.PP
\fBno_log_info\fR
.RS 4
Don\*(Aqt log informative messages via
\fBsyslog\fR(3)\&.
.RE
.PP
\fBdeny=\fR\fB\fIn\fR\fR
.RS 4
Deny access if the number of consecutive authentication failures for this user during the recent interval exceeds
\fIn\fR\&. The default is 3\&.
.RE
.PP
\fBfail_interval=\fR\fB\fIn\fR\fR
.RS 4
The length of the interval during which the consecutive authentication failures must happen for the user account lock out is
\fIn\fR
seconds\&. The default is 900 (15 minutes)\&.
.RE
.PP
\fBunlock_time=\fR\fB\fIn\fR\fR
.RS 4
The access will be reenabled after
\fIn\fR
seconds after the lock out\&. The default is 600 (10 minutes)\&.
.sp
If the
\fIn\fR
is set to never or 0 the access will not be reenabled at all until administrator explicitly reenables it with the
\fBfaillock\fR
command\&. Note though that the default directory that
\fIpam_faillock\fR
uses is usually cleared on system boot so the access will be also reenabled after system reboot\&. If that is undesirable a different tally directory must be set with the
\fBdir\fR
option\&.
.sp
Also note that it is usually undesirable to permanently lock out the users as they can become easily a target of denial of service attack unless the usernames are random and kept secret to potential attackers\&.
.RE
.PP
\fBeven_deny_root\fR
.RS 4
Root account can become locked as well as regular accounts\&.
.RE
.PP
\fBroot_unlock_time=\fR\fB\fIn\fR\fR
.RS 4
This option implies
\fBeven_deny_root\fR
option\&. Allow access after
\fIn\fR
seconds to root account after the account is locked\&. In case the option is not specified the value is the same as of the
\fBunlock_time\fR
option\&.
.RE
.PP
\fBadmin_group=\fR\fB\fIname\fR\fR
.RS 4
If a group name is specified with this option, members of the group will be handled by this module the same as the root account (the options
\fBeven_deny_root>\fR
and
\fBroot_unlock_time\fR
will apply to them\&. By default the option is not set\&.
.RE
.SH "MODULE TYPES PROVIDED"
.PP
The
\fBauth\fR
and
\fBaccount\fR
module types are provided\&.
.SH "RETURN VALUES"
.PP
PAM_AUTH_ERR
.RS 4
A 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\&.
.RE
.PP
PAM_SUCCESS
.RS 4
Everything was successful\&.
.RE
.PP
PAM_IGNORE
.RS 4
User not present in passwd database\&.
.RE
.SH "NOTES"
.PP
\fIpam_faillock\fR
setup in the PAM stack is different from the
\fIpam_tally2\fR
module setup\&.
.PP
The individual files with the failure records are created as owned by the user\&. This allows
\fBpam_faillock\&.so\fR
module to work correctly when it is called from a screensaver\&.
.PP
Note that using the module in
\fBpreauth\fR
without the
\fBsilent\fR
option or with
\fIrequisite\fR
control field leaks an information about existence or non\-existence of an 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 nonexisting user accounts allowing the adversary to infer that a particular account is not existing on a system\&.
.SH "EXAMPLES"
.PP
Here are two possible configuration examples for
/etc/pam\&.d/login\&. They make
\fIpam_faillock\fR
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\&.
.PP
In the first example the module is called only in the
\fIauth\fR
phase and the module does not print any information about the account blocking by
\fIpam_faillock\fR\&. The
\fIpreauth\fR
call can be added to tell the user that his login is blocked by the module and also to abort the authentication without even asking for password in such case\&.
.sp
.if n \{\
.RS 4
.\}
.nf
auth     required       pam_securetty\&.so
auth     required       pam_env\&.so
auth     required       pam_nologin\&.so
# optionally call: auth requisite pam_faillock\&.so preauth deny=4 even_deny_root unlock_time=1200
# to display the message about account being locked
auth     [success=1 default=bad] pam_unix\&.so
auth     [default=die]  pam_faillock\&.so authfail deny=4 even_deny_root unlock_time=1200
auth     sufficient     pam_faillock\&.so authsucc deny=4 even_deny_root unlock_time=1200
auth     required       pam_deny\&.so
account  required       pam_unix\&.so
password required       pam_unix\&.so shadow
session  required       pam_selinux\&.so close
session  required       pam_loginuid\&.so
session  required       pam_unix\&.so
session  required       pam_selinux\&.so open
    
.fi
.if n \{\
.RE
.\}
.PP
In the second example the module is called both in the
\fIauth\fR
and
\fIaccount\fR
phases and the module gives the authenticating user message when the account is locked
.sp
.if n \{\
.RS 4
.\}
.nf
auth     required       pam_securetty\&.so
auth     required       pam_env\&.so
auth     required       pam_nologin\&.so
auth     required       pam_faillock\&.so preauth silent deny=4 even_deny_root unlock_time=1200
# optionally use requisite above if you do not want to prompt for the password
# on locked accounts, possibly with removing the silent option as well
auth     sufficient     pam_unix\&.so
auth     [default=die]  pam_faillock\&.so authfail deny=4 even_deny_root unlock_time=1200
auth     required       pam_deny\&.so
account  required       pam_faillock\&.so
# if you drop the above call to pam_faillock\&.so the lock will be done also
# on non\-consecutive authentication failures
account  required       pam_unix\&.so
password required       pam_unix\&.so shadow
session  required       pam_selinux\&.so close
session  required       pam_loginuid\&.so
session  required       pam_unix\&.so
session  required       pam_selinux\&.so open
    
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.PP
/var/run/faillock/*
.RS 4
the files logging the authentication failures for users
.RE
.SH "SEE ALSO"
.PP
\fBfaillock\fR(8),
\fBpam.conf\fR(5),
\fBpam.d\fR(5),
\fBpam\fR(8)
.SH "AUTHOR"
.PP
pam_faillock was written by Tomas Mraz\&.
