summaryrefslogtreecommitdiffstats
path: root/modules/pam_faillock/faillock.conf.5.xml
diff options
context:
space:
mode:
Diffstat (limited to 'modules/pam_faillock/faillock.conf.5.xml')
-rw-r--r--modules/pam_faillock/faillock.conf.5.xml253
1 files changed, 253 insertions, 0 deletions
diff --git a/modules/pam_faillock/faillock.conf.5.xml b/modules/pam_faillock/faillock.conf.5.xml
new file mode 100644
index 0000000..04a8410
--- /dev/null
+++ b/modules/pam_faillock/faillock.conf.5.xml
@@ -0,0 +1,253 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<refentry id="faillock.conf">
+
+ <refmeta>
+ <refentrytitle>faillock.conf</refentrytitle>
+ <manvolnum>5</manvolnum>
+ <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="faillock.conf-name">
+ <refname>faillock.conf</refname>
+ <refpurpose>pam_faillock configuration file</refpurpose>
+ </refnamediv>
+
+ <refsect1 id="faillock.conf-description">
+
+ <title>DESCRIPTION</title>
+ <para>
+ <emphasis remap='B'>faillock.conf</emphasis> provides a way to configure the
+ default settings for locking the user after multiple failed authentication attempts.
+ This file is read by the <emphasis>pam_faillock</emphasis> module and is the
+ preferred method over configuring <emphasis>pam_faillock</emphasis> directly.
+ </para>
+ <para>
+ The file has a very simple <emphasis>name = value</emphasis> format with possible comments
+ starting with <emphasis>#</emphasis> character. The whitespace at the beginning of line, end
+ of line, and around the <emphasis>=</emphasis> sign is ignored.
+ </para>
+ </refsect1>
+
+ <refsect1 id="faillock.conf-options">
+
+ <title>OPTIONS</title>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>dir=<replaceable>/path/to/tally-directory</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ The directory where the user files with the failure records are kept. The
+ default is <filename>/var/run/faillock</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>audit</option>
+ </term>
+ <listitem>
+ <para>
+ Will log the user name into the system log if the user is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>silent</option>
+ </term>
+ <listitem>
+ <para>
+ Don't 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>no_log_info</option>
+ </term>
+ <listitem>
+ <para>
+ Don't log informative messages via <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>local_users_only</option>
+ </term>
+ <listitem>
+ <para>
+ Only track failed user authentications attempts for local users
+ in /etc/passwd and ignore centralized (AD, IdM, LDAP, etc.) users.
+ The <citerefentry><refentrytitle>faillock</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>nodelay</option>
+ </term>
+ <listitem>
+ <para>
+ Don't enforce a delay after authentication failures.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>deny=<replaceable>n</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ Deny access if the number of consecutive authentication failures
+ for this user during the recent interval exceeds
+ <replaceable>n</replaceable>. The default is 3.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>fail_interval=<replaceable>n</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ The length of the interval during which the consecutive
+ authentication failures must happen for the user account
+ lock out is <replaceable>n</replaceable> seconds.
+ The default is 900 (15 minutes).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>unlock_time=<replaceable>n</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ The access will be re-enabled after
+ <replaceable>n</replaceable> seconds after the lock out.
+ The value 0 has the same meaning as value
+ <emphasis>never</emphasis> - the access
+ will not be re-enabled without resetting the faillock
+ entries by the <citerefentry><refentrytitle>faillock</refentrytitle><manvolnum>8</manvolnum></citerefentry> command.
+ The default is 600 (10 minutes).
+ </para>
+ <para>
+ Note that the default directory that <emphasis>pam_faillock</emphasis>
+ 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 <option>dir</option> option.
+ </para>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>even_deny_root</option>
+ </term>
+ <listitem>
+ <para>
+ Root account can become locked as well as regular accounts.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>root_unlock_time=<replaceable>n</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ This option implies <option>even_deny_root</option> option.
+ Allow access after <replaceable>n</replaceable> seconds
+ to root account after the account is locked. In case the
+ option is not specified the value is the same as of the
+ <option>unlock_time</option> option.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>admin_group=<replaceable>name</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ 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 <option>even_deny_root</option>
+ and <option>root_unlock_time</option> will apply to them.
+ By default the option is not set.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id='faillock.conf-examples'>
+ <title>EXAMPLES</title>
+ <para>
+ /etc/security/faillock.conf file example:
+ </para>
+ <programlisting>
+deny=4
+unlock_time=1200
+silent
+ </programlisting>
+ </refsect1>
+
+ <refsect1 id="faillock.conf-files">
+ <title>FILES</title>
+ <variablelist>
+ <varlistentry>
+ <term><filename>/etc/security/faillock.conf</filename></term>
+ <listitem>
+ <para>the config file for custom options</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id='faillock.conf-see_also'>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>faillock</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_faillock</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+ <refsect1 id='faillock.conf-author'>
+ <title>AUTHOR</title>
+ <para>
+ pam_faillock was written by Tomas Mraz. The support for faillock.conf was written by Brian Ward.
+ </para>
+ </refsect1>
+
+</refentry>