summaryrefslogtreecommitdiff
path: root/modules/pam_faillock/faillock.conf.5
diff options
context:
space:
mode:
Diffstat (limited to 'modules/pam_faillock/faillock.conf.5')
-rw-r--r--modules/pam_faillock/faillock.conf.5166
1 files changed, 166 insertions, 0 deletions
diff --git a/modules/pam_faillock/faillock.conf.5 b/modules/pam_faillock/faillock.conf.5
new file mode 100644
index 00000000..7870153d
--- /dev/null
+++ b/modules/pam_faillock/faillock.conf.5
@@ -0,0 +1,166 @@
+'\" t
+.\" Title: faillock.conf
+.\" Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\" Date: 06/08/2020
+.\" Manual: Linux-PAM Manual
+.\" Source: Linux-PAM Manual
+.\" Language: English
+.\"
+.TH "FAILLOCK\&.CONF" "5" "06/08/2020" "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"
+faillock.conf \- pam_faillock configuration file
+.SH "DESCRIPTION"
+.PP
+\fBfaillock\&.conf\fR
+provides a way to configure the default settings for locking the user after multiple failed authentication attempts\&. This file is read by the
+\fIpam_faillock\fR
+module and is the preferred method over configuring
+\fIpam_faillock\fR
+directly\&.
+.PP
+The file has a very simple
+\fIname = value\fR
+format with possible comments starting with
+\fI#\fR
+character\&. The whitespace at the beginning of line, end of line, and around the
+\fI=\fR
+sign is ignored\&.
+.SH "OPTIONS"
+.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 to the user\&. Please note that when this option is not used there will be difference in the authentication behavior for users which exist on the system and non\-existing users\&.
+.RE
+.PP
+\fBno_log_info\fR
+.RS 4
+Don\*(Aqt log informative messages via
+\fBsyslog\fR(3)\&.
+.RE
+.PP
+\fBlocal_users_only\fR
+.RS 4
+Only track failed user authentications attempts for local users in /etc/passwd and ignore centralized (AD, IdM, LDAP, etc\&.) users\&. The
+\fBfaillock\fR(8)
+command will also no longer track user failed authentication attempts\&. Enabling this option will prevent a double\-lockout scenario where a user is locked out locally and in the centralized mechanism\&.
+.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 re\-enabled after
+\fIn\fR
+seconds after the lock out\&. The value 0 has the same meaning as value
+\fInever\fR
+\- the access will not be re\-enabled without resetting the faillock entries by the
+\fBfaillock\fR(8)
+command\&. The default is 600 (10 minutes)\&.
+.sp
+Note that the default directory that
+\fIpam_faillock\fR
+uses is usually cleared on system boot so the access will be also re\-enabled 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 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 "EXAMPLES"
+.PP
+/etc/security/faillock\&.conf file example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+deny=4
+unlock_time=1200
+silent
+
+.fi
+.if n \{\
+.RE
+.\}
+.SH "FILES"
+.PP
+/etc/security/faillock\&.conf
+.RS 4
+the config file for custom options
+.RE
+.SH "SEE ALSO"
+.PP
+\fBfaillock\fR(8),
+\fBpam_faillock\fR(8),
+\fBpam.conf\fR(5),
+\fBpam.d\fR(5),
+\fBpam\fR(8)
+.SH "AUTHOR"
+.PP
+pam_faillock was written by Tomas Mraz\&. The support for faillock\&.conf was written by Brian Ward\&.