Adding upstream version 1.3.1.upstream/1.3.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 459 insertions, 0 deletions

diff --git a/modules/pam_tally/pam_tally.8.xml b/modules/pam_tally/pam_tally.8.xml
new file mode 100644
index 0000000..48230a2
--- /dev/null
+++ b/modules/pam_tally/pam_tally.8.xml
@@ -0,0 +1,459 @@
+<?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="pam_tally">
+
+  <refmeta>
+    <refentrytitle>pam_tally</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_tally-name">
+    <refname>pam_tally</refname>
+    <refpurpose>The login counter (tallying) module</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_tally-cmdsynopsis1">
+      <command>pam_tally.so</command>
+      <arg choice="opt">
+	file=<replaceable>/path/to/counter</replaceable>
+      </arg>
+      <arg choice="opt">
+        onerr=[<replaceable>fail</replaceable>|<replaceable>succeed</replaceable>]
+      </arg>
+      <arg choice="opt">
+        magic_root
+      </arg>
+      <arg choice="opt">
+        even_deny_root_account
+      </arg>
+      <arg choice="opt">
+        deny=<replaceable>n</replaceable>
+      </arg>
+      <arg choice="opt">
+        lock_time=<replaceable>n</replaceable>
+      </arg>
+      <arg choice="opt">
+        unlock_time=<replaceable>n</replaceable>
+      </arg>
+      <arg choice="opt">
+        per_user
+      </arg>
+      <arg choice="opt">
+        no_lock_time
+      </arg>
+      <arg choice="opt">
+        no_reset
+      </arg>
+      <arg choice="opt">
+        audit
+      </arg>
+      <arg choice="opt">
+        silent
+      </arg>
+      <arg choice="opt">
+        no_log_info
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis id="pam_tally-cmdsynopsis2">
+      <command>pam_tally</command>
+      <arg choice="opt">
+	--file <replaceable>/path/to/counter</replaceable>
+      </arg>
+      <arg choice="opt">
+	--user <replaceable>username</replaceable>
+      </arg>
+      <arg choice="opt">
+	--reset[=<replaceable>n</replaceable>]
+      </arg>
+      <arg choice="opt">
+        --quiet
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id="pam_tally-description">
+
+    <title>DESCRIPTION</title>
+
+    <para>
+      This module maintains a count of attempted accesses, can
+      reset count on success, can deny access if too many attempts
+      fail.
+    </para>
+    <para>
+      pam_tally has several limitations, which are solved with
+      pam_tally2. For this reason pam_tally is deprecated and
+      will be removed in a future release.
+    </para>
+    <para>
+      pam_tally comes in two parts:
+      <emphasis remap='B'>pam_tally.so</emphasis> and
+      <command>pam_tally</command>. The former is the PAM module and
+      the latter, a stand-alone program. <command>pam_tally</command>
+      is an (optional) application which can be used to interrogate and
+      manipulate the counter file. It can display user counts, set
+      individual counts, or clear all counts. Setting artificially high
+      counts may be useful for blocking users without changing their
+      passwords. For example, one might find it useful to clear all counts
+      every midnight from a cron job. The
+      <citerefentry>
+	<refentrytitle>faillog</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry> command can be used instead of pam_tally to to
+      maintain the counter file.
+    </para>
+    <para>
+      Normally, failed attempts to access <emphasis>root</emphasis> will
+      <emphasis remap='B'>not</emphasis> cause the root account to become
+      blocked, to prevent denial-of-service: if your users aren't given
+      shell accounts and root may only login via <command>su</command> or
+      at the machine console (not telnet/rsh, etc), this is safe.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_tally-options">
+
+    <title>OPTIONS</title>
+    <variablelist>
+      <varlistentry>
+        <term>
+          GLOBAL OPTIONS
+        </term>
+        <listitem>
+          <para>
+            This can be used for <emphasis>auth</emphasis> and
+            <emphasis>account</emphasis> module types.
+          </para>
+          <variablelist>
+            <varlistentry>
+              <term>
+                <option>onerr=[<replaceable>fail</replaceable>|<replaceable>succeed</replaceable>]</option>
+              </term>
+              <listitem>
+                <para>
+                  If something weird happens (like unable to open the file),
+                  return with <errorcode>PAM_SUCCESS</errorcode> if
+                  <option>onerr=<replaceable>succeed</replaceable></option>
+                  is given, else with the corresponding PAM error code.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>file=<replaceable>/path/to/counter</replaceable></option>
+              </term>
+              <listitem>
+                <para>
+                  File where to keep counts. Default is
+                  <filename>/var/log/faillog</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.
+                </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>
+          </variablelist>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          AUTH OPTIONS
+        </term>
+        <listitem>
+          <para>
+            Authentication phase first checks if user should be denied
+            access and if not it increments attempted login counter. Then
+            on call to <citerefentry>
+	      <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> it resets the attempts counter.
+          </para>
+          <variablelist>
+            <varlistentry>
+              <term>
+                <option>deny=<replaceable>n</replaceable></option>
+              </term>
+              <listitem>
+                <para>
+                  Deny access if tally for this user exceeds
+                  <replaceable>n</replaceable>.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>lock_time=<replaceable>n</replaceable></option>
+              </term>
+              <listitem>
+                <para>
+                  Always deny for <replaceable>n</replaceable> seconds
+                  after failed attempt.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>unlock_time=<replaceable>n</replaceable></option>
+              </term>
+              <listitem>
+                <para>
+                  Allow access after <replaceable>n</replaceable> seconds
+                  after failed attempt. If this option is used the user will
+                  be locked out for the specified amount of time after he
+                  exceeded his maximum allowed attempts. Otherwise the
+                  account is locked until the lock is removed by a manual
+                  intervention of the system administrator.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>magic_root</option>
+              </term>
+              <listitem>
+                <para>
+                  If the module is invoked by a user with uid=0 the
+                  counter is not incremented. The sysadmin should use this
+                  for user launched services, like <command>su</command>,
+                  otherwise this argument should be omitted.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>no_lock_time</option>
+              </term>
+              <listitem>
+                <para>
+                  Do not use the .fail_locktime field in
+                  <filename>/var/log/faillog</filename> for this user.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>no_reset</option>
+              </term>
+              <listitem>
+                <para>
+                  Don't reset count on successful entry, only decrement.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>even_deny_root_account</option>
+              </term>
+              <listitem>
+                <para>
+                  Root account can become unavailable.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>per_user</option>
+              </term>
+              <listitem>
+                <para>
+                  If <filename>/var/log/faillog</filename> contains a non-zero
+                  .fail_max/.fail_locktime field for this user then use it
+                  instead of <option>deny=<replaceable>n</replaceable></option>/
+                  <option>lock_time=<replaceable>n</replaceable></option> parameter.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>no_lock_time</option>
+              </term>
+              <listitem>
+                <para>
+                  Don't use .fail_locktime filed in
+                  <filename>/var/log/faillog</filename> for this user.
+                </para>
+              </listitem>
+            </varlistentry>
+
+          </variablelist>
+        </listitem>
+      </varlistentry>
+
+
+      <varlistentry>
+        <term>
+          ACCOUNT OPTIONS
+        </term>
+        <listitem>
+          <para>
+            Account phase resets attempts counter if the user is
+            <emphasis remap='B'>not</emphasis> magic root.
+            This phase can be used optionally for services which don't call
+            <citerefentry>
+	      <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> correctly or if the reset should be done regardless
+            of the failure of the account phase of other modules.
+          </para>
+          <variablelist>
+            <varlistentry>
+              <term>
+                <option>magic_root</option>
+              </term>
+              <listitem>
+                <para>
+                  If the module is invoked by a user with uid=0 the
+                  counter is not incremented. The sysadmin should use this
+                  for user launched services, like <command>su</command>,
+                  otherwise this argument should be omitted.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>no_reset</option>
+              </term>
+              <listitem>
+                <para>
+                  Don't reset count on successful entry, only decrement.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_tally-types">
+    <title>MODULE TYPES PROVIDED</title>
+    <para>
+      The <option>auth</option> and <option>account</option>
+      module types are provided.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_tally-return_values'>
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_AUTH_ERR</term>
+        <listitem>
+          <para>
+            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.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+          <para>
+            Everything was successful.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_USER_UNKNOWN</term>
+        <listitem>
+          <para>
+	    User not known.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_tally-examples'>
+    <title>EXAMPLES</title>
+    <para>
+      Add the following line to <filename>/etc/pam.d/login</filename> to
+      lock the account after too many failed logins. The number of
+      allowed fails is specified by <filename>/var/log/faillog</filename>
+      and needs to be set with pam_tally or <citerefentry>
+	<refentrytitle>faillog</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry> before.
+    </para>
+    <programlisting>
+auth     required       pam_securetty.so
+auth     required       pam_tally.so per_user
+auth     required       pam_env.so
+auth     required       pam_unix.so
+auth     required       pam_nologin.so
+account  required       pam_unix.so
+password required       pam_unix.so
+session  required       pam_limits.so
+session  required       pam_unix.so
+session  required       pam_lastlog.so nowtmp
+session  optional       pam_mail.so standard
+    </programlisting>
+  </refsect1>
+
+  <refsect1 id="pam_tally-files">
+    <title>FILES</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>/var/log/faillog</filename></term>
+        <listitem>
+          <para>failure logging file</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_tally-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+	<refentrytitle>faillog</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='pam_tally-author'>
+    <title>AUTHOR</title>
+      <para>
+        pam_tally was written by Tim Baverstock and Tomas Mraz.
+      </para>
+  </refsect1>
+
+</refentry>