Relevant BUGIDs:

Purpose of commit: new feature

Commit summary:
---------------

2006-06-09  Thorsten Kukuk  <kukuk@thkukuk.de>

        * modules/pam_wheel/Makefile.am: Include Make.xml.rules.
        * modules/pam_wheel/pam_wheel.8.xml: New.
        * modules/pam_wheel/pam_wheel.8: New, generated from xml file.
        * modules/pam_wheel/README.xml: New.
        * modules/pam_wheel/README: Regenerated from xml file.

        * modules/pam_xauth/Makefile.am: Include Make.xml.rules.
        * modules/pam_xauth/pam_xauth.8.xml: New.
        * modules/pam_xauth/pam_xauth.8: Regenerated from xml file.
        * modules/pam_xauth/README.xml: New.
        * modules/pam_xauth/README: Regenerated from xml file.

        * modules/pam_deny/pam_deny.8.xml: Fix syntax errors.
        * modules/pam_deny/pam_deny.8: Regenerate from xml file.
        * modules/pam_deny/README: Likewise.

        * modules/pam_warn/Makefile.am: Include Make.xml.rules.
        * modules/pam_warn/pam_warn.8.xml: New.
        * modules/pam_warn/pam_warn.8: New, generated from xml file.
        * modules/pam_warn/README.xml: New.
        * modules/pam_warn/README: Regenerated from xml file.

        * modules/pam_userdb/Makefile.am: Include Make.xml.rules.
        * modules/pam_userdb/pam_userdb.8.xml: New.
        * modules/pam_userdb/pam_userdb.8: New, generated from xml file.
        * modules/pam_userdb/README.xml: New.
        * modules/pam_userdb/README: Regenerated from xml file.

1 files changed, 242 insertions, 0 deletions

diff --git a/modules/pam_wheel/pam_wheel.8.xml b/modules/pam_wheel/pam_wheel.8.xml
new file mode 100644
index 00000000..f3d2fb42
--- /dev/null
+++ b/modules/pam_wheel/pam_wheel.8.xml
@@ -0,0 +1,242 @@
+<?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_wheel">
+
+  <refmeta>
+    <refentrytitle>pam_wheel</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_wheel-name">
+    <refname>pam_wheel</refname>
+    <refpurpose>Only permit root access to members of group wheel</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_wheel-cmdsynopsis">
+      <command>pam_wheel.so</command>
+      <arg choice="opt">
+	debug
+      </arg>
+      <arg choice="opt">
+        deny
+      </arg>
+      <arg choice="opt">
+	group=<replaceable>name</replaceable>
+      </arg>
+      <arg choice="opt">
+	root_only
+      </arg>
+      <arg choice="opt">
+	trust
+      </arg>
+      <arg choice="opt">
+	use_uid
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id="pam_wheel-description">
+    <title>DESCRIPTION</title>
+    <para>
+      The pam_wheel PAM module is used to enforce the so-called
+      <emphasis>wheel</emphasis> group. By default it permits root
+      access to the system if the applicant user is a member of the
+      <emphasis>wheel</emphasis> group. If no group with this name exist,
+      the module is using the group with the group-ID
+      <emphasis remap='B'>0</emphasis>.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_wheel-options">
+    <title>OPTIONS</title>
+    <variablelist>
+      <varlistentry>
+        <term>
+          <option>debug</option>
+        </term>
+        <listitem>
+          <para>
+            Print debug information.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>deny</option>
+        </term>
+        <listitem>
+          <para>
+            Reverse the sense of the auth operation: if the user
+            is trying to get UID 0 access and is a member of the
+            wheel group (or the group of the <option>group</option> option),
+            deny access. Conversely, if the user is not in the group, return
+            PAM_IGNORE (unless <option>trust</option> was also specified,
+            in which case we return PAM_SUCCESS).
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>group=<replaceable>name</replaceable></option>
+        </term>
+        <listitem>
+          <para>
+            Instead of checking the wheel or GID 0 groups, use
+            the <option><replaceable>name</replaceable></option> group
+            to perform the authentification.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>root_only</option>
+        </term>
+        <listitem>
+          <para>
+            The check for wheel membership is done only.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>trust</option>
+        </term>
+        <listitem>
+          <para>
+            The pam_wheel module will return PAM_SUCCESS instead
+            of PAM_IGNORE if the user is a member of the wheel group
+            (thus with a little play stacking the modules the wheel
+            members may be able to su to root without being prompted
+            for a passwd).
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>use_uid</option>
+        </term>
+        <listitem>
+          <para>
+            The check for wheel membership will be done against
+            the current uid instead of the original one (useful when
+            jumping with su from one account to another for example).
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_wheel-services">
+    <title>MODULE SERVICES PROVIDED</title>
+    <para>
+      The <emphasis remap='B'>auth</emphasis> and
+      <emphasis remap='B'>account</emphasis> services are supported.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_wheel-return_values'>
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_AUTH_ERR</term>
+        <listitem>
+           <para>
+             Authentication failure.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_BUF_ERR</term>
+        <listitem>
+           <para>
+             Memory buffer error.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_IGNORE</term>
+        <listitem>
+          <para>
+            The return value should be ignored by PAM dispatch.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_PERM_DENY</term>
+        <listitem>
+          <para>
+            Permission denied.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SERVICE_ERR</term>
+        <listitem>
+          <para>
+	    Cannot determine the user name.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+          <para>
+            Success.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>PAM_USER_UNKNOWN</term>
+        <listitem>
+          <para>
+            User not known.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_wheel-examples'>
+    <title>EXAMPLES</title>
+    <para>
+      The root account gains access by default (rootok), only wheel
+      members can become root (wheel) but Unix authenticate non-root
+      applicants.
+      <programlisting>
+su      auth     sufficient     pam_rootok.so
+su      auth     required       pam_wheel.so
+su      auth     required       pam_unix.so
+      </programlisting>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_wheel-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+	<refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam.d</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_wheel-author'>
+    <title>AUTHOR</title>
+      <para>
+        pam_wheel was written by Cristian Gafton &lt;gafton@redhat.com&gt;.
+      </para>
+  </refsect1>
+
+</refentry>