Relevant BUGIDs:

Purpose of commit: new feature

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

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

        * modules/pam_debug/Makefile.am: Include Make.xml.rules.
        * modules/pam_debug/pam_debug.8.xml: New.
        * modules/pam_debug/pam_debug.8: New, generated from xml file.
        * modules/pam_debug/README.xml: New.
        * modules/pam_debug/README: Regenerated from xml file.

5 files changed, 449 insertions, 8 deletions

diff --git a/modules/pam_debug/Makefile.am b/modules/pam_debug/Makefile.am
index 66b9fbe0..889d7877 100644
--- a/modules/pam_debug/Makefile.am
+++ b/modules/pam_debug/Makefile.am
@@ -1,10 +1,13 @@
 #
-# Copyright (c) 2005 Thorsten Kukuk <kukuk@suse.de>
+# Copyright (c) 2005, 2006 Thorsten Kukuk <kukuk@thkukuk.de>
 #
 
 CLEANFILES = *~
 
-EXTRA_DIST = README tst-pam_debug
+EXTRA_DIST = README $(MANS) $(XMLS) tst-pam_debug
+
+man_MANS = pam_debug.8
+XMLS = README.xml pam_debug.8.xml
 
 securelibdir = $(SECUREDIR)
 secureconfdir = $(SCONFIGDIR)
@@ -19,3 +22,10 @@ endif
 securelib_LTLIBRARIES = pam_debug.la
 
 TESTS = tst-pam_debug
+
+if ENABLE_REGENERATE_MAN
+noinst_DATA = README
+README: pam_debug.8.xml
+-include $(top_srcdir)/Make.xml.rules
+endif
+
diff --git a/modules/pam_debug/README b/modules/pam_debug/README
index b537e3a7..4afff114 100644
--- a/modules/pam_debug/README
+++ b/modules/pam_debug/README
@@ -1,15 +1,64 @@
-# $Id$
-#
+pam_debug — PAM module to debug the PAM stack
 
-This module returns what its module arguments tell it to return. It
-can be used for debugging libpam and/or an application.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Here are some example ways to use it:
+DESCRIPTION
 
-auth	requisite	pam_permit.so
+The pam_debug PAM module is intended as a debugging aide for determining how
+the PAM stack is operating. This module returns what its module arguments tell
+it to return.
+
+OPTIONS
+
+auth=value
+
+    The pam_sm_authenticate(3) function will return value.
+
+cred=value
+
+    The pam_sm_setcred(3) function will return value.
+
+acct=value
+
+    The pam_sm_acct_mgmt(3) function will return value.
+
+prechauthtok=value
+
+    The pam_sm_chauthtok(3) function will return value if the PAM_PRELIM_CHECK
+    flag is set.
+
+chauthtok=value
+
+    The pam_sm_chauthtok(3) function will return value if the PAM_PRELIM_CHECK
+    flag is not set.
+
+open_session=value
+
+    The pam_sm_open_session(3) function will return value.
+
+close_session=value
+
+    The pam_sm_close_session(3) function will return value.
+
+Where value can be one of: success, open_err, symbol_err, service_err,
+system_err, buf_err, perm_denied, auth_err, cred_insufficient,
+authinfo_unavail, user_unknown, maxtries, new_authtok_reqd, acct_expired,
+session_err, cred_unavail, cred_expired, cred_err, no_module_data, conv_err,
+authtok_err, authtok_recover_err, authtok_lock_busy, authtok_disable_aging,
+try_again, ignore, abort, authtok_expired, module_unknown, bad_item,
+conv_again, incomplete.
+
+EXAMPLES
+
+auth    requisite       pam_permit.so
 auth    [success=2 default=ok]  pam_debug.so auth=perm_denied cred=success
 auth    [default=reset]         pam_debug.so auth=success cred=perm_denied
 auth    [success=done default=die] pam_debug.so
 auth    optional        pam_debug.so auth=perm_denied cred=perm_denied
 auth    sufficient      pam_debug.so auth=success cred=success
 
+
+AUTHOR
+
+pam_debug was written by Andrew G. Morgan <morgan@kernel.org>.
+
diff --git a/modules/pam_debug/README.xml b/modules/pam_debug/README.xml
new file mode 100644
index 00000000..ef41911b
--- /dev/null
+++ b/modules/pam_debug/README.xml
@@ -0,0 +1,41 @@
+<?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 pamaccess SYSTEM "pam_debug.8.xml">
+-->
+]>
+
+<article>
+
+  <articleinfo>
+
+    <title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_debug.8.xml" xpointer='xpointer(//refnamediv[@id = "pam_debug-name"]/*)'/>
+    </title>
+
+  </articleinfo>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_debug.8.xml" xpointer='xpointer(//refsect1[@id = "pam_debug-description"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_debug.8.xml" xpointer='xpointer(//refsect1[@id = "pam_debug-options"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_debug.8.xml" xpointer='xpointer(//refsect1[@id = "pam_debug-examples"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_debug.8.xml" xpointer='xpointer(//refsect1[@id = "pam_debug-author"]/*)'/>
+  </section>
+
+</article>
diff --git a/modules/pam_debug/pam_debug.8 b/modules/pam_debug/pam_debug.8
new file mode 100644
index 00000000..5bce51e3
--- /dev/null
+++ b/modules/pam_debug/pam_debug.8
@@ -0,0 +1,110 @@
+.\"     Title: pam_debug
+.\"    Author: 
+.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
+.\"      Date: 06/17/2006
+.\"    Manual: Linux\-PAM Manual
+.\"    Source: Linux\-PAM Manual
+.\"
+.TH "PAM_DEBUG" "8" "06/17/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_debug \- PAM module to debug the PAM stack
+.SH "SYNOPSIS"
+.HP 13
+\fBpam_debug.so\fR [auth=\fIvalue\fR] [cred=\fIvalue\fR] [acct=\fIvalue\fR] [prechauthtok=\fIvalue\fR] [chauthtok=\fIvalue\fR] [auth=\fIvalue\fR] [open_session=\fIvalue\fR] [close_session=\fIvalue\fR]
+.SH "DESCRIPTION"
+.PP
+The pam_debug PAM module is intended as a debugging aide for determining how the PAM stack is operating. This module returns what its module arguments tell it to return.
+.SH "OPTIONS"
+.TP 3n
+\fBauth=\fR\fB\fIvalue\fR\fR
+The
+\fBpam_sm_authenticate\fR(3)
+function will return
+\fIvalue\fR.
+.TP 3n
+\fBcred=\fR\fB\fIvalue\fR\fR
+The
+\fBpam_sm_setcred\fR(3)
+function will return
+\fIvalue\fR.
+.TP 3n
+\fBacct=\fR\fB\fIvalue\fR\fR
+The
+\fBpam_sm_acct_mgmt\fR(3)
+function will return
+\fIvalue\fR.
+.TP 3n
+\fBprechauthtok=\fR\fB\fIvalue\fR\fR
+The
+\fBpam_sm_chauthtok\fR(3)
+function will return
+\fIvalue\fR
+if the
+\fIPAM_PRELIM_CHECK\fR
+flag is set.
+.TP 3n
+\fBchauthtok=\fR\fB\fIvalue\fR\fR
+The
+\fBpam_sm_chauthtok\fR(3)
+function will return
+\fIvalue\fR
+if the
+\fIPAM_PRELIM_CHECK\fR
+flag is
+\fBnot\fR
+set.
+.TP 3n
+\fBopen_session=\fR\fB\fIvalue\fR\fR
+The
+\fBpam_sm_open_session\fR(3)
+function will return
+\fIvalue\fR.
+.TP 3n
+\fBclose_session=\fR\fB\fIvalue\fR\fR
+The
+\fBpam_sm_close_session\fR(3)
+function will return
+\fIvalue\fR.
+.PP
+Where
+\fIvalue\fR
+can be one of: success, open_err, symbol_err, service_err, system_err, buf_err, perm_denied, auth_err, cred_insufficient, authinfo_unavail, user_unknown, maxtries, new_authtok_reqd, acct_expired, session_err, cred_unavail, cred_expired, cred_err, no_module_data, conv_err, authtok_err, authtok_recover_err, authtok_lock_busy, authtok_disable_aging, try_again, ignore, abort, authtok_expired, module_unknown, bad_item, conv_again, incomplete.
+.SH "MODULE SERVICES PROVIDED"
+.PP
+The services
+\fBauth\fR,
+\fBaccount\fR,
+\fBpassword\fR
+and
+\fBsession\fR
+are supported.
+.SH "RETURN VALUES"
+.TP 3n
+PAM_SUCCESS
+Default return code if no other value was specified, else specified return value.
+.SH "EXAMPLES"
+.sp
+.RS 3n
+.nf
+auth    requisite       pam_permit.so
+auth    [success=2 default=ok]  pam_debug.so auth=perm_denied cred=success
+auth    [default=reset]         pam_debug.so auth=success cred=perm_denied
+auth    [success=done default=die] pam_debug.so
+auth    optional        pam_debug.so auth=perm_denied cred=perm_denied
+auth    sufficient      pam_debug.so auth=success cred=success
+    
+.fi
+.RE
+.SH "SEE ALSO"
+.PP
+
+\fBpam.conf\fR(5),
+\fBpam.d\fR(8),
+\fBpam\fR(8)
+.SH "AUTHOR"
+.PP
+pam_debug was written by Andrew G. Morgan <morgan@kernel.org>.
diff --git a/modules/pam_debug/pam_debug.8.xml b/modules/pam_debug/pam_debug.8.xml
new file mode 100644
index 00000000..65519852
--- /dev/null
+++ b/modules/pam_debug/pam_debug.8.xml
@@ -0,0 +1,231 @@
+<?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="pam_debug">
+
+  <refmeta>
+    <refentrytitle>pam_debug</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_debug-name">
+    <refname>pam_debug</refname>
+    <refpurpose>PAM module to debug the PAM stack</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_debug-cmdsynopsis">
+      <command>pam_debug.so</command>
+      <arg choice="opt">
+	auth=<replaceable>value</replaceable>
+      </arg>
+      <arg choice="opt">
+	cred=<replaceable>value</replaceable>
+      </arg>
+      <arg choice="opt">
+	acct=<replaceable>value</replaceable>
+      </arg>
+      <arg choice="opt">
+	prechauthtok=<replaceable>value</replaceable>
+      </arg>
+      <arg choice="opt">
+	chauthtok=<replaceable>value</replaceable>
+      </arg>
+      <arg choice="opt">
+	auth=<replaceable>value</replaceable>
+      </arg>
+      <arg choice="opt">
+	open_session=<replaceable>value</replaceable>
+      </arg>
+      <arg choice="opt">
+	close_session=<replaceable>value</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id="pam_debug-description">
+    <title>DESCRIPTION</title>
+    <para>
+      The pam_debug PAM module is intended as a debugging aide for
+      determining how the PAM stack is operating. This module returns
+      what its module arguments tell it to return.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_debug-options">
+    <title>OPTIONS</title>
+    <variablelist>
+      <varlistentry>
+        <term>
+          <option>auth=<replaceable>value</replaceable></option>
+        </term>
+        <listitem>
+          <para>
+            The
+	    <citerefentry>
+              <refentrytitle>pam_sm_authenticate</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> function will return
+            <replaceable>value</replaceable>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>cred=<replaceable>value</replaceable></option>
+        </term>
+        <listitem>
+          <para>
+            The
+	    <citerefentry>
+              <refentrytitle>pam_sm_setcred</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> function will return
+            <replaceable>value</replaceable>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>acct=<replaceable>value</replaceable></option>
+        </term>
+        <listitem>
+          <para>
+            The
+	    <citerefentry>
+              <refentrytitle>pam_sm_acct_mgmt</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> function will return
+            <replaceable>value</replaceable>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>prechauthtok=<replaceable>value</replaceable></option>
+        </term>
+        <listitem>
+          <para>
+            The
+	    <citerefentry>
+              <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> function will return
+            <replaceable>value</replaceable> if the
+            <emphasis>PAM_PRELIM_CHECK</emphasis> flag is set.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>chauthtok=<replaceable>value</replaceable></option>
+        </term>
+        <listitem>
+          <para>
+            The
+	    <citerefentry>
+              <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> function will return
+            <replaceable>value</replaceable> if the
+            <emphasis>PAM_PRELIM_CHECK</emphasis> flag is
+            <emphasis remap='B'>not</emphasis> set.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>open_session=<replaceable>value</replaceable></option>
+        </term>
+        <listitem>
+          <para>
+            The
+	    <citerefentry>
+              <refentrytitle>pam_sm_open_session</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> function will return
+            <replaceable>value</replaceable>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>close_session=<replaceable>value</replaceable></option>
+        </term>
+        <listitem>
+          <para>
+            The
+	    <citerefentry>
+              <refentrytitle>pam_sm_close_session</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> function will return
+            <replaceable>value</replaceable>.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <para>
+      Where <replaceable>value</replaceable> can be one of: success,
+      open_err, symbol_err, service_err, system_err, buf_err, perm_denied,
+      auth_err, cred_insufficient, authinfo_unavail, user_unknown,
+      maxtries, new_authtok_reqd, acct_expired, session_err, cred_unavail,
+      cred_expired, cred_err, no_module_data, conv_err, authtok_err,
+      authtok_recover_err, authtok_lock_busy, authtok_disable_aging,
+      try_again, ignore, abort, authtok_expired, module_unknown,
+      bad_item, conv_again, incomplete.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_debug-services">
+    <title>MODULE SERVICES PROVIDED</title>
+    <para>
+      The services <option>auth</option>, <option>account</option>,
+      <option>password</option> and <option>session</option> are supported.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_debug-return_values'>
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+          <para>
+            Default return code if no other value was specified,
+            else specified return value.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_debug-examples'>
+    <title>EXAMPLES</title>
+    <programlisting>
+auth    requisite       pam_permit.so
+auth    [success=2 default=ok]  pam_debug.so auth=perm_denied cred=success
+auth    [default=reset]         pam_debug.so auth=success cred=perm_denied
+auth    [success=done default=die] pam_debug.so
+auth    optional        pam_debug.so auth=perm_denied cred=perm_denied
+auth    sufficient      pam_debug.so auth=success cred=success
+    </programlisting>
+  </refsect1>
+
+  <refsect1 id='pam_debug-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+	<refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam.d</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_debug-author'>
+    <title>AUTHOR</title>
+      <para>
+        pam_debug was written by Andrew G. Morgan &lt;morgan@kernel.org&gt;.
+      </para>
+  </refsect1>
+
+</refentry>