Relevant BUGIDs:

Purpose of commit: new feature

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

More manual pages

2006-03-12  Thorsten Kukuk  <kukuk@thkukuk.de>

        * doc/man/Makefile.am: Add new manual pages.

        * doc/man/pam.conf.5.xml: Replace link with content
        of PAM admin guide.
        * doc/man/pam.conf.5: Regenerated from XML file.

        * doc/man/pam_info.3.xml: New.
        * doc/man/pam_info.3: New, generated from XML file.
        * doc/man/pam_vinfo.3: New, generated from XML file.

        * doc/man/pam_conv.3.xml: New.
        * doc/man/pam_conv.3: New, generated from XML file.

        * doc/man/pam_putenv.3.xml: New.
        * doc/man/pam_putenv.3: New, generated from XML file.

        * doc/man/pam_getenv.3.xml: New.
        * doc/man/pam_getenv.3: New, generated from XML file.

        * doc/man/pam_getenvlist.3.xml: New.
        * doc/man/pam_getenvlist.3: New, generated from XML file.

1 files changed, 442 insertions, 0 deletions

diff --git a/doc/man/pam.conf.5.xml b/doc/man/pam.conf.5.xml
new file mode 100644
index 00000000..9f267b79
--- /dev/null
+++ b/doc/man/pam.conf.5.xml
@@ -0,0 +1,442 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<refentry id='pam.conf'>
+
+  <refmeta>
+    <refentrytitle>pam.conf</refentrytitle>
+    <manvolnum>5</manvolnum>
+    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id='pam.conf-name'>
+    <refname>pam.conf</refname>
+    <refname>pam.d</refname>
+    <refpurpose>PAM configuration files</refpurpose>
+  </refnamediv>
+
+<!-- body begins here -->
+
+  <refsect1 id='pam.conf-description'>
+    <title>DESCRIPTION</title>
+    <para>
+      When a <emphasis>PAM</emphasis> aware privilege granting application
+      is started, it activates its attachment to the PAM-API. This
+      activation performs a number of tasks, the most important being the
+      reading of the configuration file(s): <filename>/etc/pam.conf</filename>.
+      Alternatively, this may be the contents of the
+      <filename>/etc/pam.d/</filename> directory. The presence of this
+      directory will cause Linux-PAM to ignore
+      <filename>/etc/pam.conf</filename>.
+    </para>
+
+    <para>
+      These files list the <emphasis>PAM</emphasis>s that will do the
+      authentication tasks required by this service, and the appropriate
+      behavior of the PAM-API in the event that individual
+      <emphasis>PAM</emphasis>s fail.
+    </para>
+
+    <para>
+      The syntax of the <filename>/etc/pam.conf</filename>
+      configuration file is as follows. The file is made up of a list
+      of rules, each rule is typically placed on a single line,
+      but may be extended with an escaped end of line: `\&lt;LF&gt;'.
+      Comments are preceded with `#' marks and extend to the next end of
+      line.
+    </para>
+
+    <para>
+      The format of each rule is a space separated collection of tokens,
+      the first three being case-insensitive:
+    </para>
+
+    <para>
+      <emphasis remap='B'> service  type  control  module-path  module-arguments</emphasis>
+    </para>
+
+    <para>
+      The syntax of files contained in the <filename>/etc/pam.d/</filename>
+      directory, are identical except for the absence of any
+      <emphasis>service</emphasis> field. In this case, the
+      <emphasis>service</emphasis> is the name of the file in the
+      <filename>/etc/pam.d/</filename> directory. This filename must be
+      in lower case.
+    </para>
+
+    <para>
+      An important feature of <emphasis>PAM</emphasis>, is that a
+      number of rules may be <emphasis>stacked</emphasis> to combine
+      the services of a number of PAMs for a given authentication task.
+    </para>
+
+    <para>
+      The <emphasis>service</emphasis> is typically the familiar name of
+      the corresponding application: <emphasis>login</emphasis> and
+      <emphasis>su</emphasis> are good examples. The
+      <emphasis>service</emphasis>-name, <emphasis>other</emphasis>,
+      is reserved for giving <emphasis>default</emphasis> rules.
+      Only lines that mention the current service (or in the absence
+      of such, the <emphasis>other</emphasis> entries) will be associated
+      with the given service-application.
+    </para>
+
+    <para>
+      The <emphasis>type</emphasis> is the management group that the rule
+      corresponds to. It is used to specify which of the management groups
+      the subsequent module is to be associated with. Valid entries are:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term>account</term>
+        <listitem>
+          <para>
+            this module type performs non-authentication based account
+            management. It is typically used to restrict/permit access
+            to a service based on the time of day, currently available
+            system resources (maximum number of users) or perhaps the
+            location of  the applicant user -- 'root' login only on the
+            console.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>auth</term>
+        <listitem>
+          <para>
+            this module type provides two aspects of authenticating
+            the user. Firstly, it establishes that the user is who they
+            claim to be, by instructing the application to prompt the user
+            for a password or other means of identification. Secondly, the
+            module can grant group membership or other privileges through
+            its credential granting properties.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>password</term>
+        <listitem>
+          <para>
+            this module type is required for updating the authentication
+            token associated with the user. Typically, there is one module
+            for each 'challenge/response' based authentication (auth) type.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>session</term>
+        <listitem>
+          <para>
+            this module type is associated with doing things that need to
+            be done for the user before/after they can be given service.
+            Such things include the logging of information concerning the
+            opening/closing of some data exchange with a user, mounting
+            directories, etc.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>
+      The third field, <emphasis>control</emphasis>, indicates the
+      behavior of the PAM-API should the module fail to succeed in its
+      authentication task. There are two types of syntax for this control
+      field: the simple one has a single simple keyword; the more
+      complicated one involves a square-bracketed selection of
+      <emphasis>value=action</emphasis> pairs.
+    </para>
+
+    <para>
+      For the simple (historical) syntax valid <emphasis>control</emphasis>
+      values are:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term>required</term>
+        <listitem>
+          <para>
+            failure of such a PAM will ultimately lead to the PAM-API
+            returning failure but only after the remaining
+            <emphasis>stacked</emphasis> modules (for this
+            <emphasis>service</emphasis> and <emphasis>type</emphasis>)
+            have been invoked.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>requisite</term>
+        <listitem>
+          <para>
+            like <emphasis>required</emphasis>, however, in the case that
+            such a module returns a failure, control is directly returned
+            to the application. The return value is that associated with
+            the first required or requisite module to fail. Note, this flag
+            can be used to protect against the possibility of a user getting
+            the opportunity to enter a password over an unsafe medium. It is
+            conceivable that such behavior might inform an attacker of valid
+            accounts on a system. This possibility should be weighed against
+            the not insignificant concerns of exposing a sensitive password
+            in a hostile environment.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>sufficient</term>
+        <listitem>
+          <para>
+            success of such a module is enough to satisfy the
+            authentication requirements of the stack of modules (if a
+            prior <emphasis>required</emphasis> module has failed the
+            success of this one is <emphasis>ignored</emphasis>). A failure
+            of this module is not deemed as fatal to satisfying the
+            application that this type has succeeded.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>optional</term>
+        <listitem>
+          <para>
+            the success or failure of this module is only important if
+            it is the only module in the stack associated with this
+            <emphasis>service</emphasis>+<emphasis>type</emphasis>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>include</term>
+        <listitem>
+          <para>
+            include all lines of given type from the configuration
+            file specified as an argument to this control.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>
+      For the more complicated syntax valid <emphasis>control</emphasis>
+      values have the following form:
+    </para>
+    <programlisting>
+      [value1=action1 value2=action2 ...]
+    </programlisting>
+
+    <para>
+      Where <emphasis>valueN</emphasis> corresponds to the return code
+      from the function invoked in the module for which the line is
+      defined. It is selected from one of these:
+      <emphasis>success</emphasis>, <emphasis>open_err</emphasis>,
+      <emphasis>symbol_err</emphasis>, <emphasis>service_err</emphasis>,
+      <emphasis>system_err</emphasis>, <emphasis>buf_err</emphasis>,
+      <emphasis>perm_denied</emphasis>, <emphasis>auth_err</emphasis>,
+      <emphasis>cred_insufficient</emphasis>,
+      <emphasis>authinfo_unavail</emphasis>,
+      <emphasis>user_unknown</emphasis>, <emphasis>maxtries</emphasis>,
+      <emphasis>new_authtok_reqd</emphasis>,
+      <emphasis>acct_expired</emphasis>, <emphasis>session_err</emphasis>,
+      <emphasis>cred_unavail</emphasis>, <emphasis>cred_expired</emphasis>,
+      <emphasis>cred_err</emphasis>, <emphasis>no_module_data</emphasis>,
+      <emphasis>conv_err</emphasis>, <emphasis>authtok_err</emphasis>,
+      <emphasis>authtok_recover_err</emphasis>,
+      <emphasis>authtok_lock_busy</emphasis>,
+      <emphasis>authtok_disable_aging</emphasis>,
+      <emphasis>try_again</emphasis>, <emphasis>ignore</emphasis>,
+      <emphasis>abort</emphasis>, <emphasis>authtok_expired</emphasis>,
+      <emphasis>module_unknown</emphasis>, <emphasis>bad_item</emphasis>
+      and <emphasis>default</emphasis>.
+    </para>
+    <para>
+      The last of these, <emphasis>default</emphasis>, implies 'all
+      <emphasis>valueN</emphasis>'s not mentioned explicitly. Note, the
+      full list of PAM errors is available in
+      <filename>/usr/include/security/_pam_types.h</filename>. The
+      <emphasis>actionN</emphasis> can be: an unsigned integer,
+      <emphasis>n</emphasis>, signifying an action of 'jump over the
+      next <emphasis>n</emphasis> modules in the stack', or take one
+      of the following forms:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term>ignore</term>
+        <listitem>
+           <para>
+             when used with a stack of modules, the module's return
+             status will not contribute to the return code the application
+             obtains.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>bad</term>
+        <listitem>
+           <para>
+             this action indicates that the return code should be thought
+             of as indicative of the module failing. If this module is the
+             first in the stack to fail, its status value will be used for
+             that of the whole stack.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>die</term>
+        <listitem>
+           <para>
+             equivalent to bad with the side effect of terminating the
+             module stack and PAM immediately returning to the application.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>ok</term>
+        <listitem>
+           <para>
+             this tells PAM that the administrator thinks this return code
+             should contribute directly to the return code of the full
+             stack of modules. In other words, if the former state of the
+             stack would lead to a return of <emphasis>PAM_SUCCESS</emphasis>,
+             the module's return code will override this value. Note, if
+             the former state of the stack holds some value that is
+             indicative of a modules failure, this 'ok' value will not be
+             used to override that value.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>done</term>
+        <listitem>
+           <para>
+             equivalent to ok with the side effect of terminating the module
+             stack and PAM immediately returning to the application.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>reset</term>
+        <listitem>
+           <para>
+             clear all memory of the state of the module stack and
+             start again with the next stacked module.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>
+      Each of the four keywords: required; requisite; sufficient; and
+      optional, have an equivalent expression in terms of the [...]
+      syntax. They are as follows:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term>required</term>
+        <listitem>
+           <para>
+             [success=ok new_authtok_reqd=ok ignore=ignore default=bad]
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>requisite</term>
+        <listitem>
+           <para>
+             [success=ok new_authtok_reqd=ok ignore=ignore default=die]
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>sufficient</term>
+        <listitem>
+           <para>
+             [success=done new_authtok_reqd=done default=ignore]
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>optional</term>
+        <listitem>
+           <para>
+             [success=ok new_authtok_reqd=ok default=ignore]
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>
+      <emphasis>module-path</emphasis> is either the full filename
+      of the PAM to be used by the application (it begins with a '/'),
+      or a relative pathname from the default module location:
+      <filename>/lib/security/</filename> or
+      <filename>/lib64/security/</filename>, depending on the architecture.
+    </para>
+
+    <para>
+      <emphasis>module-arguments</emphasis> are a space separated list
+      of tokens that can be used to modify the specific behavior of the
+      given PAM. Such arguments will be documented for each individual
+      module. Note, if you wish to include spaces in an argument, you
+      should surround that argument with square brackets.
+    </para>
+    <programlisting>
+    squid auth required pam_mysql.so user=passwd_query passwd=mada \
+          db=eminence [query=select user_name from internet_service \
+          where user_name='%u' and password=PASSWORD('%p') and \
+        service='web_proxy']
+    </programlisting>
+    <para>
+      When using this convention, you can include `[' characters
+      inside the string, and if you wish to include a `]' character
+      inside the string that will survive the argument parsing, you
+      should use `\['. In other words:
+    </para>
+    <programlisting>
+    [..[..\]..]    -->   ..[..]..
+    </programlisting>
+
+    <para>
+      Any line in (one of) the configuration file(s), that is not formatted
+      correctly, will generally tend (erring on the side of caution) to make
+      the authentication process fail.  A corresponding error is written to
+      the system log files with a call to
+      <citerefentry>
+        <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>.
+    </para>
+
+    <para>
+      More flexible than the single configuration file is it to
+      configure libpam via the contents of the
+      <filename>/etc/pam.d/</filename> directory. In this case the
+      directory is filled with files each of which has a filename
+      equal to a service-name (in lower-case): it is the personal
+      configuration file for the named service.
+    </para>
+
+    <para>
+      The syntax of each file in /etc/pam.d/ is similar to that of the
+      <filename>/etc/pam.conf</filename> file and is made up of lines
+      of the following form:
+    </para>
+
+    <para>
+      <emphasis remap='B'> type  control  module-path  module-arguments</emphasis>
+    </para>
+
+  </refsect1>
+
+  <refsect1 id='pam.conf-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>
+    </para>
+
+  </refsect1>
+</refentry>