Relevant BUGIDs:

Purpose of commit: bugfix

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

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

        * modules/pam_access/access.conf.5.xml: Fix syntax for SAG.
        * modules/pam_access/pam_access.8.xml: Likewise.
        * modules/pam_deny/pam_deny.8.xml: Likewise.
        * modules/pam_echo/pam_echo.8.xml: Likewise.
        * modules/pam_env/pam_env.8.xml: Likewise.
        * modules/pam_env/pam_env.conf.5.xml: Likewise.
        * modules/pam_group/group.conf.5.xml: Likewise.
        * modules/pam_group/pam_group.8.xml: Likewise.
        * modules/pam_limits/limits.conf.5.xml: Likewise.
        * modules/pam_listfile/pam_listfile.8.xml: Likewise.
        * modules/pam_succeed_if/pam_succeed_if.8.xml: Likewise.
        * modules/pam_time/pam_time.8.xml: Likewise.
        * modules/pam_time/time.conf.5.xml: Likewise.

        * modules/pam_access/access.conf.5: Regenerate.
        * modules/pam_access/pam_access.8: Likewise.
        * modules/pam_deny/pam_deny.8: Likewise.
        * modules/pam_echo/README: Likewise.
        * modules/pam_echo/pam_echo.8: Likewise.
        * modules/pam_env/pam_env.8: Likewise.
        * modules/pam_env/pam_env.conf.5: Likewise.
        * modules/pam_group/README: Likewise.
        * modules/pam_group/group.conf.5: Likewise.
        * modules/pam_group/pam_group.8: Likewise.
        * modules/pam_limits/limits.conf.5: Likewise.
        * modules/pam_listfile/README: Likewise.
        * modules/pam_listfile/pam_listfile.8: Likewise.
        * modules/pam_succeed_if/pam_succeed_if.8: Likewise.
        * modules/pam_time/pam_time.8: Likewise.
        * modules/pam_time/time.conf.5: Likewise.

        * doc/man/Makefile.am: Add pam.conf-desc.xml, pam.conf-dir.xml
        and pam.conf-syntax.xml.
        * doc/man/pam.conf.5.xml: Split into different pieces for SAG.
        * doc/man/pam.conf.5: Regenerated.
	* doc/man/pam.conf-desc.xml: New.
	* doc/man/pam.conf-dir.xml: New.
	* doc/man/pam.conf-syntax.xml: New.

6 files changed, 449 insertions, 406 deletions

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 3ce244a9..78b9e66c 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -36,10 +36,12 @@ XMLS = pam.3.xml pam.8.xml \
 	pam_sm_close_session.3.xml pam_sm_open_session.3.xml \
 	pam_sm_setcred.3.xml pam_start.3.xml pam_strerror.3.xml \
 	pam_sm_chauthtok.3.xml \
-	pam_item_types.inc.xml
+	pam_item_types.inc.xml \
+	pam.conf-desc.xml pam.conf-dir.xml pam.conf-syntax.xml
 
 if ENABLE_REGENERATE_MAN
 pam_get_item.3: pam_item_types.inc.xml
 pam_set_data.3: pam_item_types.inc.xml
+pam.conf.5: pam.conf-desc.xml pam.conf-dir.xml pam.conf-syntax.xml
 -include $(top_srcdir)/Make.xml.rules
 endif
diff --git a/doc/man/pam.conf-desc.xml b/doc/man/pam.conf-desc.xml
new file mode 100644
index 00000000..909dcdbe
--- /dev/null
+++ b/doc/man/pam.conf-desc.xml
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<section id='pam.conf-desc'>
+  <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>
+</section>
diff --git a/doc/man/pam.conf-dir.xml b/doc/man/pam.conf-dir.xml
new file mode 100644
index 00000000..8446cf35
--- /dev/null
+++ b/doc/man/pam.conf-dir.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<section id='pam.conf-dir'>
+    <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>
+
+    <programlisting>
+type  control  module-path  module-arguments
+    </programlisting>
+
+    <para>
+      The only difference being that the service-name is not present. The
+      service-name is of course the name of the given configuration file.
+      For example, <filename>/etc/pam.d/login</filename> contains the
+      configuration for the <emphasis remap='B'>login</emphasis> service.
+    </para>
+</section>
diff --git a/doc/man/pam.conf-syntax.xml b/doc/man/pam.conf-syntax.xml
new file mode 100644
index 00000000..b422cba9
--- /dev/null
+++ b/doc/man/pam.conf-syntax.xml
@@ -0,0 +1,372 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<section id='pam.conf-syntax'>
+  <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>
+
+</section>
diff --git a/doc/man/pam.conf.5 b/doc/man/pam.conf.5
index fcedd7d7..11f8737d 100644
--- a/doc/man/pam.conf.5
+++ b/doc/man/pam.conf.5
@@ -1,11 +1,11 @@
 .\"     Title: pam.conf
 .\"    Author: 
 .\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
-.\"      Date: 06/19/2006
+.\"      Date: 06/21/2006
 .\"    Manual: Linux\-PAM Manual
 .\"    Source: Linux\-PAM Manual
 .\"
-.TH "PAM.CONF" "5" "06/19/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.TH "PAM.CONF" "5" "06/21/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
@@ -244,9 +244,19 @@ directory. In this case the directory is filled with files each of which has a f
 The syntax of each file in /etc/pam.d/ is similar to that of the
 \fI/etc/pam.conf\fR
 file and is made up of lines of the following form:
+.sp
+.RS 3n
+.nf
+type  control  module\-path  module\-arguments
+    
+.fi
+.RE
 .PP
-
-\fB type control module\-path module\-arguments\fR
+The only difference being that the service\-name is not present. The service\-name is of course the name of the given configuration file. For example,
+\fI/etc/pam.d/login\fR
+contains the configuration for the
+\fBlogin\fR
+service.
 .SH "SEE ALSO"
 .PP
 
diff --git a/doc/man/pam.conf.5.xml b/doc/man/pam.conf.5.xml
index d744dac0..68f576af 100644
--- a/doc/man/pam.conf.5.xml
+++ b/doc/man/pam.conf.5.xml
@@ -19,409 +19,17 @@
 
   <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>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="pam.conf-desc.xml"
+     xpointer='xpointer(//section[@id = "pam.conf-desc"]/*)' />
 
-    <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>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="pam.conf-syntax.xml"
+     xpointer='xpointer(//section[@id = "pam.conf-syntax"]/*)' />
 
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+     href="pam.conf-dir.xml"
+     xpointer='xpointer(//section[@id = "pam.conf-dir"]/*)' />
   </refsect1>
 
   <refsect1 id='pam.conf-see_also'>