From 6b49cfcfe626ccbd06f4944dc11427735524ba9b Mon Sep 17 00:00:00 2001
From: Thorsten Kukuk <kukuk@suse.com>
Date: Wed, 15 Feb 2023 14:51:35 +0100
Subject: manual pages: enhance pam.d documentation

Make /usr/lib/pam.d and <vendordir>/pam.d more visible in the standard
manual pages, so that people don't assume there is only /etc/pam.d

* doc/man/pam.8.xml: Don't always speak about /etc/pam.d only
* doc/man/pam.conf-desc.xml: Don't always speak about /etc/pam.d only
* doc/man/pam.conf-dir.xml: Explain search path for pam config files
* doc/man/pam.conf.5.xml: Add filelist with all pam.d directories
---
 doc/man/pam.8.xml         | 16 ++++++++--------
 doc/man/pam.conf-desc.xml | 11 ++++++-----
 doc/man/pam.conf-dir.xml  | 20 +++++++++++++++-----
 doc/man/pam.conf.5.xml    | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 73 insertions(+), 19 deletions(-)

(limited to 'doc')

diff --git a/doc/man/pam.8.xml b/doc/man/pam.8.xml
index 20cd19d9..7f3b051c 100644
--- a/doc/man/pam.8.xml
+++ b/doc/man/pam.8.xml
@@ -41,9 +41,9 @@
       service-providing applications will authenticate users. This dynamic
       configuration is set by the contents of the single
       <emphasis remap="B">Linux-PAM</emphasis> configuration file
-      <filename>/etc/pam.conf</filename>. Alternatively, the configuration
-      can be set by individual configuration files located in the
-      <filename>/etc/pam.d/</filename> directory. The presence of this
+      <filename>/etc/pam.conf</filename>. Alternatively and preferably,
+      the configuration can be set by individual configuration files
+      located in a <filename>pam.d</filename> directory. The presence of this
       directory will cause <emphasis remap="B">Linux-PAM</emphasis> to
       <emphasis remap="I">ignore</emphasis> <filename>/etc/pam.conf</filename>.
     </para>
@@ -159,10 +159,10 @@ closing hook for modules to affect the services available to a user.</para>
         <term>%vendordir%/pam.d</term>
         <listitem>
           <para>
-            the <emphasis remap="B">Linux-PAM</emphasis> vendor configuration
-	    directory. Files in <filename>/etc/pam.d</filename> and
-	    <filename>/usr/lib/pam.d</filename> override files with the same
-	    name in this directory.
+	    additional <emphasis remap="B">Linux-PAM</emphasis> vendor
+	    configuration directory. Files in <filename>/etc/pam.d</filename>
+	    and <filename>/usr/lib/pam.d</filename> override files with the
+	    same name in this directory.
           </para>
         </listitem>
       </varlistentry>
@@ -209,4 +209,4 @@ closing hook for modules to affect the services available to a user.</para>
       </citerefentry>
     </para>
   </refsect1>
-</refentry>
\ No newline at end of file
+</refentry>
diff --git a/doc/man/pam.conf-desc.xml b/doc/man/pam.conf-desc.xml
index 5dca89fe..60c2d71d 100644
--- a/doc/man/pam.conf-desc.xml
+++ b/doc/man/pam.conf-desc.xml
@@ -4,10 +4,11 @@
     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>.
+    Alternatively and preferably, the configuration can be set by individual
+    configuration files located in a <filename>pam.d</filename> directory.
+    The presence of this directory will cause
+    <emphasis remap="B">Linux-PAM</emphasis> to
+    <emphasis remap="I">ignore</emphasis> <filename>/etc/pam.conf</filename>.
   </para>
   <para>
     These files list the <emphasis>PAM</emphasis>s that will do the
@@ -15,4 +16,4 @@
     behavior of the PAM-API in the event that individual
     <emphasis>PAM</emphasis>s fail.
   </para>
-</section>
\ No newline at end of file
+</section>
diff --git a/doc/man/pam.conf-dir.xml b/doc/man/pam.conf-dir.xml
index 8272337b..57b2991c 100644
--- a/doc/man/pam.conf-dir.xml
+++ b/doc/man/pam.conf-dir.xml
@@ -1,15 +1,25 @@
 <section xmlns="http://docbook.org/ns/docbook" version="5.0" xml: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
+      configure libpam via the contents of
+      <filename>pam.d</filename> directories. In this case the
+      directories are 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
+      Vendor-supplied PAM configuration files might be installed in
+      the system directory <filename>/usr/lib/pam.d/</filename> or
+      a configurable vendor specific directory instead
+      of the machine configuration directory <filename>/etc/pam.d/</filename>.
+      If no machine configuration file is found, the vendor-supplied file
+      is used. All files in <filename>/etc/pam.d/</filename> override
+      files with the same name in other directories.
+    </para>
+
+    <para>
+      The syntax of each file in 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>
@@ -24,4 +34,4 @@ type  control  module-path  module-arguments
       For example, <filename>/etc/pam.d/login</filename> contains the
       configuration for the <emphasis remap="B">login</emphasis> service.
     </para>
-</section>
\ No newline at end of file
+</section>
diff --git a/doc/man/pam.conf.5.xml b/doc/man/pam.conf.5.xml
index 62a2b410..997776bb 100644
--- a/doc/man/pam.conf.5.xml
+++ b/doc/man/pam.conf.5.xml
@@ -24,6 +24,49 @@
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam.conf-dir.xml" xpointer='xpointer(id("pam.conf-dir")/*)' />
   </refsect1>
 
+  <refsect1 xml:id="pam8-files">
+    <title>FILES</title>
+    <variablelist>
+      <varlistentry>
+        <term>/etc/pam.conf</term>
+        <listitem>
+          <para>the configuration file</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>/etc/pam.d</term>
+        <listitem>
+          <para>
+            the <emphasis remap="B">Linux-PAM</emphasis> configuration
+            directory. Generally, if this directory is present, the
+            <filename>/etc/pam.conf</filename> file is ignored.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>/usr/lib/pam.d</term>
+        <listitem>
+          <para>
+            the <emphasis remap="B">Linux-PAM</emphasis> vendor configuration
+            directory. Files in <filename>/etc/pam.d</filename> override
+            files with the same name in this directory.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry condition="with_vendordir">
+        <term>%vendordir%/pam.d</term>
+        <listitem>
+          <para>
+            additional <emphasis remap="B">Linux-PAM</emphasis> vendor
+            configuration directory. Files in <filename>/etc/pam.d</filename>
+            and <filename>/usr/lib/pam.d</filename> override files with the
+            same name in this directory.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
   <refsect1 xml:id="pam.conf-see_also">
     <title>SEE ALSO</title>
     <para>
@@ -39,4 +82,4 @@
     </para>
 
   </refsect1>
-</refentry>
\ No newline at end of file
+</refentry>
-- 
cgit v1.2.3