pam_stress: create man page

Resolves: https://github.com/linux-pam/linux-pam/issues/148
Signed-off-by: Lucas Ramage <ramage.lucas@protonmail.com>

* modules/pam_stress/README: Remove.
* modules/pam_stress/README.xml: New file.
* modules/pam_stress/pam_stress.8.xml: Likewise.
* modules/pam_stress/Makefile.am (MAINTAINERCLEANFILES): Add
$(MANS) and README.
(EXTRA_DIST): Add $(XMLS).
(XMLS): Add README.xml and pam_stress.8.xml.
[HAVE_DOC] (dist_man_MANS): Add pam_stress.8.
[ENABLE_REGENERATE_MAN] (dist_noinst_DATA): Add README.
[ENABLE_REGENERATE_MAN]: Include $(top_srcdir)/Make.xml.rules.
* modules/pam_stress/.gitignore: Remove.

Resolves: https://github.com/linux-pam/linux-pam/pull/184

5 files changed, 398 insertions, 66 deletions

diff --git a/modules/pam_stress/.gitignore b/modules/pam_stress/.gitignore
deleted file mode 100644
index a164aea3..00000000
--- a/modules/pam_stress/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-!README
diff --git a/modules/pam_stress/Makefile.am b/modules/pam_stress/Makefile.am
index 10671ad4..e964fcc4 100644
--- a/modules/pam_stress/Makefile.am
+++ b/modules/pam_stress/Makefile.am
@@ -3,9 +3,14 @@
 #
 
 CLEANFILES = *~
+MAINTAINERCLEANFILES = $(MANS) README
 
-EXTRA_DIST =
+EXTRA_DIST = $(XMLS)
 
+if HAVE_DOC
+dist_man_MANS = pam_stress.8
+endif
+XMLS = README.xml pam_stress.8.xml
 dist_check_SCRIPTS = tst-pam_stress
 TESTS = $(dist_check_SCRIPTS)
 
@@ -20,3 +25,8 @@ if HAVE_VERSIONING
 endif
 securelib_LTLIBRARIES = pam_stress.la
 pam_stress_la_LIBADD = $(top_builddir)/libpam/libpam.la
+
+if ENABLE_REGENERATE_MAN
+dist_noinst_DATA = README
+-include $(top_srcdir)/Make.xml.rules
+endif
diff --git a/modules/pam_stress/README b/modules/pam_stress/README
deleted file mode 100644
index ed56ae58..00000000
--- a/modules/pam_stress/README
+++ /dev/null
@@ -1,64 +0,0 @@
-#
-# This describes the behavior of this module with respect to the
-# /etc/pam.conf file.
-#
-# written by Andrew Morgan <morgan@parc.power.net>
-#
-
-This module recognizes the following arguments.
-
-debug		put lots of information in syslog.
-		*NOTE* this option writes passwords to syslog, so
-		don't use anything sensitive when testing.
-
-no_warn		don't give warnings about things (otherwise warnings are issued
-		via the conversation function)
-
-use_first_pass	don't prompt for a password, for pam_sm_authentication
-		function just use item PAM_AUTHTOK.
-
-try_first_pass	don't prompt for a password unless there has been no
-		previous authentication token (item PAM_AUTHTOK is NULL)
-
-rootok		This is intended for the pam_sm_chauthtok function and
-		it instructs this function to permit root to change
-		the user's password without entering the old password.
-
-The following arguments are acted on by the module. They are intended
-to make the module give the impression of failing as a fully
-functioning module might.
-
-expired 	an argument intended for the account and chauthtok module
-		parts. It instructs the module to act as if the user's
-		password has expired
-
-fail_1		this instructs the module to make its first function fail.
-
-fail_2		this instructs the module to make its second function (if there
-		is one) fail.
-
-		The function break up is indicated in the Module
-		Developers' Guide. Listed here it is:
-
-		service		function 1		function 2
-		-------		----------		----------
-		auth		pam_sm_authenticate	pam_sm_setcred
-		password	pam_sm_chauthtok
-		session		pam_sm_open_session	pam_sm_close_session
-		account		pam_sm_acct_mgmt
-
-prelim		for pam_sm_chauthtok, means fail on PAM_PRELIM_CHECK.
-
-required	for pam_sm_chauthtok, means fail if the user hasn't already
-		been authenticated by this module. (See stress_new_pwd data
-		item below.)
-
-#
-# data strings that this module uses are the following:
-#
-
-data name		value(s)	Comments
----------		--------	--------
-stress_new_pwd		yes		tells pam_sm_chauthtok that
-					pam_sm_acct_mgmt says we need a new
-					password
diff --git a/modules/pam_stress/README.xml b/modules/pam_stress/README.xml
new file mode 100644
index 00000000..6f94685e
--- /dev/null
+++ b/modules/pam_stress/README.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.docbook.org/xml/4.3/docbookx.dtd"
+[
+<!--
+<!ENTITY pamstress SYSTEM "pam_stress.8.xml">
+-->
+]>
+
+<article>
+
+  <articleinfo>
+
+    <title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_stress.8.xml" xpointer='xpointer(//refnamediv[@id = "pam_stress-name"]/*)'/>
+    </title>
+
+  </articleinfo>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_stress.8.xml" xpointer='xpointer(//refsect1[@id = "pam_stress-description"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_stress.8.xml" xpointer='xpointer(//refsect1[@id = "pam_stress-options"]/*)'/>
+  </section>
+
+</article>
diff --git a/modules/pam_stress/pam_stress.8.xml b/modules/pam_stress/pam_stress.8.xml
new file mode 100644
index 00000000..98888b1c
--- /dev/null
+++ b/modules/pam_stress/pam_stress.8.xml
@@ -0,0 +1,356 @@
+<?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_stress'>
+
+  <refmeta>
+    <refentrytitle>pam_stress</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id='pam_stress-name'>
+    <refname>pam_stress</refname>
+    <refpurpose>The stress-testing PAM module</refpurpose>
+  </refnamediv>
+
+<!-- body begins here -->
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_stress-cmdsynopsis">
+      <command>pam_stress.so</command>
+      <arg choice="opt">
+        debug
+      </arg>
+      <arg choice="opt">
+        no_warn
+      </arg>
+      <arg choice="opt">
+        use_first_pass
+      </arg>
+      <arg choice="opt">
+        try_first_pass
+      </arg>
+      <arg choice="opt">
+        rootok
+      </arg>
+      <arg choice="opt">
+        expired
+      </arg>
+      <arg choice="opt">
+        fail_1
+      </arg>
+      <arg choice="opt">
+        fail_2
+      </arg>
+      <arg choice="opt">
+        prelim
+      </arg>
+      <arg choice="opt">
+        required
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id="pam_stress-description">
+    <title>DESCRIPTION</title>
+    <para>
+      The pam_stress PAM module is mainly intended to give the impression of failing as a fully
+functioning module might.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_stress-options">
+    <title>OPTIONS</title>
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <option>debug</option>
+        </term>
+        <listitem>
+          <para>
+            Put lots of information in syslog.
+            *NOTE* this option writes passwords to syslog, so don't use anything sensitive when testing.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>no_warn</option>
+        </term>
+        <listitem>
+          <para>
+            Do not give warnings about things (otherwise warnings are issued
+            via the conversation function)
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>use_first_pass</option>
+        </term>
+        <listitem>
+          <para>
+            Do not prompt for a password, for pam_sm_authentication
+            function just use item PAM_AUTHTOK.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>try_first_pass</option>
+        </term>
+        <listitem>
+          <para>
+            Do not prompt for a password unless there has been no
+            previous authentication token (item PAM_AUTHTOK is NULL)
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>rootok</option>
+        </term>
+        <listitem>
+          <para>
+            This is intended for the pam_sm_chauthtok function and
+            it instructs this function to permit root to change
+            the user's password without entering the old password.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>expired</option>
+        </term>
+        <listitem>
+          <para>
+            An argument intended for the account and chauthtok module
+            parts. It instructs the module to act as if the user's
+            password has expired
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>fail_1</option>
+        </term>
+        <listitem>
+          <para>
+            This instructs the module to make its first function fail.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>fail_2</option>
+        </term>
+        <listitem>
+          <para>
+            This instructs the module to make its second function (if there
+            is one) fail.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>prelim</option>
+        </term>
+        <listitem>
+          <para>
+            For pam_sm_chauthtok, means fail on PAM_PRELIM_CHECK.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>required</option>
+        </term>
+        <listitem>
+          <para>
+            For pam_sm_chauthtok, means fail if the user hasn't already
+            been authenticated by this module. (See stress_new_pwd data
+            string in the NOTES.)
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_stress-types">
+    <title>MODULE TYPES PROVIDED</title>
+    <para>
+      All module types (<option>auth</option>, <option>account</option>,
+      <option>password</option> and <option>session</option>) are provided.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_stress-return_values">
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_BUF_ERR</term>
+        <listitem>
+           <para>
+             Memory buffer error.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_PERM_DENIED</term>
+        <listitem>
+           <para>
+             Permission denied.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_AUTH_ERR</term>
+        <listitem>
+           <para>
+             Access to the system was denied.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_CONV_ERR</term>
+        <listitem>
+           <para>
+             Conversation failure.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+           <para>
+             The function passes all checks.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_USER_UNKNOWN</term>
+        <listitem>
+           <para>
+             The user is not known to the system.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_CRED_ERR</term>
+        <listitem>
+           <para>
+             Failure involving user credentials.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_NEW_AUTHTOK_REQD</term>
+        <listitem>
+           <para>
+             Authentication token is no longer valid; new one required.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SESSION_ERR</term>
+        <listitem>
+           <para>
+             Session failure.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_TRY_AGAIN</term>
+        <listitem>
+           <para>
+             Failed preliminary check by service.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_AUTHTOK_LOCK_BUSY</term>
+        <listitem>
+           <para>
+             Authentication token lock busy.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_AUTHTOK_ERR</term>
+        <listitem>
+           <para>
+             Authentication token manipulation error.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SYSTEM_ERR</term>
+        <listitem>
+           <para>
+             System error.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_stress-notes'>
+    <title>NOTES</title>
+    <para>
+      This module uses the stress_new_pwd data string which tells
+      pam_sm_chauthtok that pam_sm_acct_mgmt says we need a new password.
+      The only possible value for this data string is 'yes'.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_stress-examples'>
+    <title>EXAMPLES</title>
+    <programlisting>
+#%PAM-1.0
+#
+# Any of the following will suffice
+account  required pam_stress.so
+auth     required pam_stress.so
+password required pam_stress.so
+session  required pam_stress.so
+    </programlisting>
+  </refsect1>
+
+  <refsect1 id="pam_stress-see_also">
+    <title>SEE ALSO</title>
+    <para>
+      <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="pam_stress-authors">
+    <title>AUTHORS</title>
+    <para>
+      The pam_stress PAM module was developed by
+      Andrew Morgan &lt;morgan@linux.kernel.org&gt;.
+      The man page for pam_stress was written by
+      Lucas Ramage &lt;ramage.lucas@protonmail.com&gt;.
+    </para>
+  </refsect1>
+</refentry>