Adding upstream version 1.3.1.upstream/1.3.1upstream

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

1 files changed, 450 insertions, 0 deletions

diff --git a/modules/pam_tally2/pam_tally2.8.xml b/modules/pam_tally2/pam_tally2.8.xml
new file mode 100644
index 0000000..cf5d76d
--- /dev/null
+++ b/modules/pam_tally2/pam_tally2.8.xml
@@ -0,0 +1,450 @@
+<?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_tally2">
+
+  <refmeta>
+    <refentrytitle>pam_tally2</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_tally2-name">
+    <refname>pam_tally2</refname>
+    <refpurpose>The login counter (tallying) module</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_tally2-cmdsynopsis1">
+      <command>pam_tally2.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
+      </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">
+        root_unlock_time=<replaceable>n</replaceable>
+      </arg>
+      <arg choice="opt">
+        serialize
+      </arg>
+      <arg choice="opt">
+        audit
+      </arg>
+      <arg choice="opt">
+        silent
+      </arg>
+      <arg choice="opt">
+        no_log_info
+      </arg>
+      <arg choice="opt">
+        debug
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis id="pam_tally2-cmdsynopsis2">
+      <command>pam_tally2</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_tally2-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_tally2 comes in two parts:
+      <emphasis remap='B'>pam_tally2.so</emphasis> and
+      <command>pam_tally2</command>. The former is the PAM module and
+      the latter, a stand-alone program. <command>pam_tally2</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.
+    </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_tally2-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/tallylog</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>
+            <varlistentry>
+              <term>
+                <option>debug</option>
+              </term>
+              <listitem>
+                <para>
+                  Always log tally count when it is incremented as a debug level message to the system log.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          AUTH OPTIONS
+        </term>
+        <listitem>
+          <para>
+            Authentication phase first increments attempted login counter and
+            checks if user should be denied access. If the user is authenticated
+            and the login process continues 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>even_deny_root</option>
+              </term>
+              <listitem>
+                <para>
+                  Root account can become unavailable.
+                </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 failed attempt. If this option is used
+                  the root user will be locked out for the specified amount of
+                  time after he exceeded his maximum allowed attempts.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>serialize</option>
+              </term>
+              <listitem>
+                <para>
+                  Serialize access to the tally file using locks. This option might
+                  be used only for non-multithreaded services because it depends on
+                  the fcntl locking of the tally file. Also it is a good idea to use
+                  this option only in such configurations where the time between auth
+                  phase and account or setcred phase is not dependent on the
+                  authenticating client. Otherwise the authenticating client will be
+                  able to prevent simultaneous authentications by the same user by
+                  simply artificially prolonging the time the file record lock is held.
+                </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 changed. The sysadmin should use this
+                  for user launched services, like <command>su</command>,
+                  otherwise this argument should be omitted.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_tally2-types">
+    <title>MODULE TYPES PROVIDED</title>
+    <para>
+      The <option>auth</option> and <option>account</option>
+      module types are provided.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_tally2-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_tally2-notes'>
+    <title>NOTES</title>
+    <para>
+      pam_tally2 is not compatible with the old pam_tally faillog file format.
+      This is caused by requirement of compatibility of the tallylog file
+      format between 32bit and 64bit architectures on multiarch systems.
+    </para>
+    <para>
+      There is no setuid wrapper for access to the data file such as when the
+      <emphasis remap='B'>pam_tally2.so</emphasis> module is called from
+      xscreensaver. As this would make it impossible to share PAM configuration
+      with such services the following workaround is used: If the data file
+      cannot be opened because of insufficient permissions
+      (<errorcode>EACCES</errorcode>) the module returns
+      <errorcode>PAM_IGNORE</errorcode>.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_tally2-examples'>
+    <title>EXAMPLES</title>
+    <para>
+      Add the following line to <filename>/etc/pam.d/login</filename> to
+      lock the account after 4 failed logins. Root account will be locked
+      as well. The accounts will be automatically unlocked after 20 minutes.
+      The module does not have to be called in the account phase because the
+      <command>login</command> calls <citerefentry>
+	<refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry> correctly.
+    </para>
+    <programlisting>
+auth     required       pam_securetty.so
+auth     required       pam_tally2.so deny=4 even_deny_root unlock_time=1200
+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_tally2-files">
+    <title>FILES</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>/var/log/tallylog</filename></term>
+        <listitem>
+          <para>failure count logging file</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_tally2-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <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_tally2-author'>
+    <title>AUTHOR</title>
+      <para>
+        pam_tally2 was written by Tim Baverstock and Tomas Mraz.
+      </para>
+  </refsect1>
+
+</refentry>