add a man page for pam_sss

5 files changed, 211 insertions, 23 deletions

diff --git a/sss_client/Makefile.am b/sss_client/Makefile.am
index 349e0499e..aeddab435 100644
--- a/sss_client/Makefile.am
+++ b/sss_client/Makefile.am
@@ -65,6 +65,22 @@ dist_noinst_DATA = \
 install-data-hook:
 	mv $(DESTDIR)/$(nsslibdir)/libnss_sss.so $(DESTDIR)/$(nsslibdir)/libnss_sss.so.2
 
+############
+# MANPAGES #
+############
+
+#Special Rules:
+export SGML_CATALOG_FILES
+DOCBOOK_XSLT = http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
+XMLLINT_FLAGS = --catalogs --postvalid --nonet --xinclude --noout
+XSLTPROC_FLAGS = --catalogs --xinclude --nonet
+
+dist_man_MANS = man/pam_sss.8
+
+SUFFIXES = .8.xml .8
+.8.xml.8:
+	$(XMLLINT) $(XMLLINT_FLAGS) $<
+	$(XSLTPROC) -o $@  $(XSLTPROC_FLAGS) $(DOCBOOK_XSLT) $<
 CLEANFILES = *.X
 
 tests: all $(check_PROGRAMS)
diff --git a/sss_client/conf_macros.m4 b/sss_client/conf_macros.m4
new file mode 100644
index 000000000..cff961bc8
--- /dev/null
+++ b/sss_client/conf_macros.m4
@@ -0,0 +1,52 @@
+AC_DEFUN([BUILD_WITH_AUX_INFO],
+  [ AC_ARG_WITH([aux-info],
+                [AC_HELP_STRING([--with-aux-info],
+                                [Build with -aux-info output])])
+  ])
+AM_CONDITIONAL([WANT_AUX_INFO], [test x$with_aux_info = xyes])
+
+AC_DEFUN([WITH_PIPE_PATH],
+  [ AC_ARG_WITH([pipe-path],
+                [AC_HELP_STRING([--with-pipe-path=PATH],
+                                [Where to store pipe files for the SSSD interconnects [/var/lib/sss/pipes]]
+                               )
+                ]
+               )
+    config_pipepath="\"VARDIR\"/lib/sss/pipes"
+    pipepath="${localstatedir}/lib/sss/pipes"
+    if test x"$with_pipe_path" != x; then
+        config_pipepath=$with_pipe_path
+        pipepath=$with_pipe_path
+    fi
+    AC_SUBST(pipepath)
+    AC_DEFINE_UNQUOTED(PIPE_PATH, "$config_pipepath", [Where to store pipe files for the SSSD interconnects])
+  ])
+AC_DEFUN([WITH_MANPAGES],
+  [ AC_ARG_WITH([manpages],
+                [AC_HELP_STRING([--with-manpages],
+                                [Whether to regenerate man pages from DocBook sources [yes]]
+                               )
+                ],
+                [],
+                with_manpages=yes
+               )
+    if test x"$with_manpages" == xyes; then
+        HAVE_MANPAGES=1
+        AC_SUBST(HAVE_MANPAGES)
+    fi
+  ])
+AM_CONDITIONAL([BUILD_MANPAGES], [test x$with_manpages = xyes])
+
+AC_DEFUN([WITH_XML_CATALOG],
+  [ AC_ARG_WITH([xml-catalog-path],
+                [AC_HELP_STRING([--with-xml-catalog-path=PATH],
+                                [Where to look for XML catalog [/etc/xml/catalog]]
+                               )
+                ]
+               )
+    SGML_CATALOG_FILES="/etc/xml/catalog"
+    if test x"$with_xml_catalog_path" != x; then
+        SGML_CATALOG_FILES="$with_xml_catalog_path"
+    fi
+    AC_SUBST([SGML_CATALOG_FILES])
+  ])
diff --git a/sss_client/configure.ac b/sss_client/configure.ac
index f5b2765a1..ab670723a 100644
--- a/sss_client/configure.ac
+++ b/sss_client/configure.ac
@@ -35,31 +35,19 @@ AC_ARG_ENABLE([nsslibdir], [AS_HELP_STRING([--enable-nsslibdir],
               [nsslibdir=$libdir])
 AC_SUBST(nsslibdir)
 
-AC_DEFUN([BUILD_WITH_AUX_INFO],
-  [ AC_ARG_WITH([aux-info],
-                [AC_HELP_STRING([--with-aux-info],
-                                [Build with -aux-info output])])
-  ])
-AM_CONDITIONAL([WANT_AUX_INFO], [test x$with_aux_info = xyes])
+m4_include([conf_macros.m4])
 BUILD_WITH_AUX_INFO
-
-AC_DEFUN([WITH_PIPE_PATH],
-  [ AC_ARG_WITH([pipe-path],
-                [AC_HELP_STRING([--with-pipe-path=PATH],
-                                [Where to store pipe files for the SSSD interconnects [/var/lib/sss/pipes]]
-                               )
-                ]
-               )
-    config_pipepath="\"VARDIR\"/lib/sss/pipes"
-    pipepath="${localstatedir}/lib/sss/pipes"
-    if test x"$with_pipe_path" != x; then
-        config_pipepath=$with_pipe_path
-        pipepath=$with_pipe_path
-    fi
-    AC_SUBST(pipepath)
-    AC_DEFINE_UNQUOTED(PIPE_PATH, "$config_pipepath", [Where to store pipe files for the SSSD interconnects])
-  ])
 WITH_PIPE_PATH
+WITH_MANPAGES
+WITH_XML_CATALOG
+
+m4_include([external/docbook.m4])
+if test x$HAVE_MANPAGES != x; then
+    CHECK_XML_TOOLS
+    CHECK_STYLESHEET([$SGML_CATALOG_FILES],
+                     [http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl],
+                     [Docbook XSL templates])
+fi
 
 AC_CONFIG_FILES([Makefile po/Makefile.in])
 AC_OUTPUT
diff --git a/sss_client/external/docbook.m4 b/sss_client/external/docbook.m4
new file mode 100644
index 000000000..cae89feb1
--- /dev/null
+++ b/sss_client/external/docbook.m4
@@ -0,0 +1,35 @@
+dnl Checks for tools needed to generate manual pages
+AC_DEFUN([CHECK_XML_TOOLS],
+[
+  AC_PATH_PROG([XSLTPROC], [xsltproc])
+  if test ! -x "$XSLTPROC"; then
+    AC_MSG_ERROR([Could not find xsltproc])
+  fi
+
+  AC_PATH_PROG([XMLLINT], [xmllint])
+  if test ! -x "$XMLLINT"; then
+    AC_MSG_ERROR([Could not find xmllint])
+  fi
+
+  AC_PATH_PROG([XMLCATALOG], [xmlcatalog])
+  if test ! -x "$XMLCATALOG"; then
+    AC_MSG_ERROR([Could not find xmlcatalog])
+  fi
+])
+
+dnl Usage:
+dnl   CHECK_STYLESHEET_URI(FILE, URI, [FRIENDLY-NAME])
+dnl Checks if the XML catalog given by FILE exists and
+dnl if a particular URI appears in the XML catalog
+AC_DEFUN([CHECK_STYLESHEET],
+[
+  AC_CHECK_FILE($1, [], [AC_MSG_ERROR([could not find XML catalog])])
+
+  AC_MSG_CHECKING([for ifelse([$3],,[$2],[$3]) in XML catalog])
+  if AC_RUN_LOG([$XMLCATALOG --noout "$1" "$2" >&2]); then
+    AC_MSG_RESULT([yes])
+  else
+    AC_MSG_ERROR([could not find ifelse([$3],,[$2],[$3]) in XML catalog])
+  fi
+])
+
diff --git a/sss_client/man/pam_sss.8.xml b/sss_client/man/pam_sss.8.xml
new file mode 100644
index 000000000..f6ac9f477
--- /dev/null
+++ b/sss_client/man/pam_sss.8.xml
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<reference>
+<title>SSSD Manual pages</title>
+<refentry>
+    <refentryinfo>
+        <productname>SSSD</productname>
+        <orgname>The SSSD upstream - http://fedorahosted.org/sssd</orgname>
+    </refentryinfo>
+
+    <refmeta>
+        <refentrytitle>pam_sss</refentrytitle>
+        <manvolnum>8</manvolnum>
+    </refmeta>
+
+    <refnamediv id='name'>
+        <refname>pam_sss</refname>
+        <refpurpose>PAM module for SSSD</refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv id='synopsis'>
+        <cmdsynopsis>
+            <command>pam_sss.so</command>
+            <arg choice='opt'>
+                <replaceable>forward_pass</replaceable>
+            </arg>
+            <arg choice='opt'>
+                <replaceable>use_first_pass</replaceable>
+            </arg>
+            <arg choice='opt'>
+                <replaceable>use_authtok</replaceable>
+            </arg>
+        </cmdsynopsis>
+    </refsynopsisdiv>
+
+    <refsect1 id='description'>
+        <title>DESCRIPTION</title>
+        <para><command>pam_sss.so</command> is the PAM interface to the System
+        Security Services daemon (SSSD). Errors and results are logged through
+        <command>syslog(3)</command> with the LOG_AUTHPRIV facility.</para>
+    </refsect1>
+
+    <refsect1 id='options'>
+        <title>OPTIONS</title>
+        <variablelist remap='IP'>
+            <varlistentry>
+                <term>
+                    <option>forward_pass</option>
+                </term>
+                <listitem>
+                    <para>If <option>forward_pass</option> is set the entered
+                    password is put on the stack for other PAM modules to use.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>
+                    <option>use_first_pass</option>
+                </term>
+                <listitem>
+                    <para>The argument use_first_pass forces the module to use
+                    a previous stacked modules password and will never prompt
+                    the user - if no password is available or the password is
+                    not appropriate, the user will be denied access.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>
+                    <option>use_authtok</option>
+                </term>
+                <listitem>
+                    <para>When password changing enforce the module to set the
+                    new password to the one provided by a previously stacked
+                    password module.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
+    <refsect1 id='module_types_provides'>
+        <title>MODULE TYPES PROVIDED</title>
+        <para>All module types (<option>account</option>, <option>auth</option>,
+        <option>password</option> and <option>session</option>) are provided.
+        </para>
+    </refsect1>
+
+    <refsect1 id='see_also'>
+        <title>SEE ALSO</title>
+        <para>
+            <citerefentry>
+                <refentrytitle>sssd.conf</refentrytitle><manvolnum>8</manvolnum>
+            </citerefentry>
+        </para>
+    </refsect1>
+</refentry>
+</reference>