From 1180bde923a22605fe8075cd1fe7992ed7513411 Mon Sep 17 00:00:00 2001
From: Iker Pedrosa <ipedrosa@redhat.com>
Date: Fri, 8 Jul 2022 15:40:40 +0200
Subject: pam_pwhistory: document config load from file

* modules/pam_pwhistory/pam_pwhistory.8.xml: Add new option to select
configuration file to read.
* modules/pam_pwhistory/pwhistory.conf.5.xml: Document configuration
options for the file.
* modules/pam_pwhistory/Makefile.am (dist_man_MANS): Add pwhistory.conf.5.
(XMLS): Add pwhistory.conf.5.xml.

Signed-off-by: Iker Pedrosa <ipedrosa@redhat.com>
---
 modules/pam_pwhistory/Makefile.am          |   5 +-
 modules/pam_pwhistory/pam_pwhistory.8.xml  |  27 ++++-
 modules/pam_pwhistory/pwhistory.conf.5.xml | 155 +++++++++++++++++++++++++++++
 3 files changed, 184 insertions(+), 3 deletions(-)
 create mode 100644 modules/pam_pwhistory/pwhistory.conf.5.xml

(limited to 'modules/pam_pwhistory')

diff --git a/modules/pam_pwhistory/Makefile.am b/modules/pam_pwhistory/Makefile.am
index a50fdc74..c29a8e11 100644
--- a/modules/pam_pwhistory/Makefile.am
+++ b/modules/pam_pwhistory/Makefile.am
@@ -9,9 +9,10 @@ MAINTAINERCLEANFILES = $(MANS) README
 EXTRA_DIST = $(XMLS)
 
 if HAVE_DOC
-dist_man_MANS = pam_pwhistory.8 pwhistory_helper.8
+dist_man_MANS = pam_pwhistory.8 pwhistory_helper.8 pwhistory.conf.5
 endif
-XMLS = README.xml pam_pwhistory.8.xml pwhistory_helper.8.xml
+XMLS = README.xml pam_pwhistory.8.xml pwhistory_helper.8.xml \
+  pwhistory.conf.5.xml
 dist_check_SCRIPTS = tst-pam_pwhistory
 TESTS = $(dist_check_SCRIPTS)
 
diff --git a/modules/pam_pwhistory/pam_pwhistory.8.xml b/modules/pam_pwhistory/pam_pwhistory.8.xml
index df16a776..2a8fa7f6 100644
--- a/modules/pam_pwhistory/pam_pwhistory.8.xml
+++ b/modules/pam_pwhistory/pam_pwhistory.8.xml
@@ -39,6 +39,9 @@
       <arg choice="opt">
 	      file=<replaceable>/path/filename</replaceable>
       </arg>
+      <arg choice="opt">
+	      conf=<replaceable>/path/to/config-file</replaceable>
+      </arg>
 
     </cmdsynopsis>
   </refsynopsisdiv>
@@ -107,7 +110,7 @@
         <listitem>
           <para>
             The last <replaceable>N</replaceable> passwords for each
-            user are saved in <filename>/etc/security/opasswd</filename>.
+            user are saved.
             The default is <emphasis>10</emphasis>. Value of
             <emphasis>0</emphasis> makes the module to keep the existing
             contents of the <filename>opasswd</filename> file unchanged.
@@ -153,7 +156,26 @@
           </listitem>
         </varlistentry>
 
+        <varlistentry>
+          <term>
+            <option>conf=<replaceable>/path/to/config-file</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              Use another configuration file instead of the default
+              <filename>/etc/security/pwhistory.conf</filename>.
+            </para>
+          </listitem>
+        </varlistentry>
+
     </variablelist>
+    <para>
+      The options for configuring the module behavior are described in the
+      <citerefentry><refentrytitle>pwhistory.conf</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry> manual page. The options
+      specified on the module command line override the values from the
+      configuration file.
+    </para>
   </refsect1>
 
   <refsect1 id="pam_pwhistory-types">
@@ -238,6 +260,9 @@ password     required       pam_unix.so        use_authtok
   <refsect1 id='pam_pwhistory-see_also'>
     <title>SEE ALSO</title>
     <para>
+      <citerefentry>
+	<refentrytitle>pwhistory.conf</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
       <citerefentry>
 	<refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
       </citerefentry>,
diff --git a/modules/pam_pwhistory/pwhistory.conf.5.xml b/modules/pam_pwhistory/pwhistory.conf.5.xml
new file mode 100644
index 00000000..bac5ffed
--- /dev/null
+++ b/modules/pam_pwhistory/pwhistory.conf.5.xml
@@ -0,0 +1,155 @@
+<?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="pwhistory.conf">
+
+  <refmeta>
+    <refentrytitle>pwhistory.conf</refentrytitle>
+    <manvolnum>5</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pwhistory.conf-name">
+    <refname>pwhistory.conf</refname>
+    <refpurpose>pam_pwhistory configuration file</refpurpose>
+  </refnamediv>
+
+  <refsect1 id="pwhistory.conf-description">
+
+    <title>DESCRIPTION</title>
+    <para>
+       <emphasis remap='B'>pwhistory.conf</emphasis> provides a way to configure the
+       default settings for saving the last passwords for each user.
+       This file is read by the <emphasis>pam_pwhistory</emphasis> module and is the
+       preferred method over configuring <emphasis>pam_pwhistory</emphasis> directly.
+    </para>
+    <para>
+       The file has a very simple <emphasis>name = value</emphasis> format with possible comments
+       starting with <emphasis>#</emphasis> character. The whitespace at the beginning of line, end
+       of line, and around the <emphasis>=</emphasis> sign is ignored.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pwhistory.conf-options">
+
+    <title>OPTIONS</title>
+         <variablelist>
+            <varlistentry>
+              <term>
+                <option>debug</option>
+              </term>
+              <listitem>
+                <para>
+                  Turns on debugging via
+                  <citerefentry>
+                    <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
+                  </citerefentry>.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>enforce_for_root</option>
+              </term>
+              <listitem>
+                <para>
+                  If this option is set, the check is enforced for root, too.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>remember=<replaceable>N</replaceable></option>
+              </term>
+              <listitem>
+                <para>
+                  The last <replaceable>N</replaceable> passwords for each
+                  user are saved.
+                  The default is <emphasis>10</emphasis>. Value of
+                  <emphasis>0</emphasis> makes the module to keep the existing
+                  contents of the <filename>opasswd</filename> file unchanged.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>retry=<replaceable>N</replaceable></option>
+              </term>
+              <listitem>
+                <para>
+                  Prompt user at most <replaceable>N</replaceable> times
+                  before returning with error. The default is 1.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>file=<replaceable>/path/filename</replaceable></option>
+              </term>
+              <listitem>
+                <para>
+                  Store password history in file
+                  <replaceable>/path/filename</replaceable> rather than the default
+                  location. The default location is
+	                <filename>/etc/security/opasswd</filename>.
+                </para>
+              </listitem>
+            </varlistentry>
+        </variablelist>
+  </refsect1>
+
+  <refsect1 id='pwhistory.conf-examples'>
+    <title>EXAMPLES</title>
+    <para>
+      /etc/security/pwhistory.conf file example:
+    </para>
+    <programlisting>
+debug
+remember=5
+file=/tmp/opasswd
+    </programlisting>
+  </refsect1>
+
+  <refsect1 id="pwhistory.conf-files">
+    <title>FILES</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>/etc/security/pwhistory.conf</filename></term>
+        <listitem>
+          <para>the config file for custom options</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pwhistory.conf-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>pwhistory</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_pwhistory</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <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='pwhistory.conf-author'>
+    <title>AUTHOR</title>
+      <para>
+        pam_pwhistory was written by Thorsten Kukuk. The support for
+        pwhistory.conf was written by Iker Pedrosa.
+      </para>
+  </refsect1>
+
+</refentry>
-- 
cgit v1.2.3