Add new gssproxy-mech.8 manpage to describe the interposer plugin

Signed-off-by: Günther Deschner <gdeschner@redhat.com>
Reviewed-by: Simo Sorce <simo@redhat.com>

4 files changed, 150 insertions, 4 deletions

diff --git a/proxy/man/Makefile.am b/proxy/man/Makefile.am
index 0d06c86..5028ca4 100644
--- a/proxy/man/Makefile.am
+++ b/proxy/man/Makefile.am
@@ -12,7 +12,7 @@ XMLLINT_FLAGS = --catalogs --postvalid --nonet --xinclude --noout
 XSLTPROC_FLAGS = --catalogs --xinclude --nonet
 
 man_MANS = \
-    gssproxy.8 gssproxy.conf.5
+    gssproxy.8 gssproxy.conf.5 gssproxy-mech.8
 
 EXTRA_DIST = $(man_MANS:%=%.xml) $(wildcard $(srcdir)/include/*.xml)
 
diff --git a/proxy/man/gssproxy-mech.8.xml b/proxy/man/gssproxy-mech.8.xml
new file mode 100644
index 0000000..b2d008c
--- /dev/null
+++ b/proxy/man/gssproxy-mech.8.xml
@@ -0,0 +1,133 @@
+<?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>GssProxy GSSAPI mechanism manual page</title>
+<refentry>
+    <refentryinfo>
+        <productname>GSS Proxy</productname>
+        <orgname>GSS-Proxy - http://fedorahosted.org/gss-proxy</orgname>
+    </refentryinfo>
+
+    <refmeta>
+        <refentrytitle>gssproxy-mech</refentrytitle>
+        <manvolnum>8</manvolnum>
+    </refmeta>
+
+    <refnamediv id='name'>
+        <refname>gssproxy-mech</refname>
+        <refpurpose>GssProxy GSSAPI mechanism plugin</refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv id='synopsis'>
+        <cmdsynopsis>
+            <command>proxymech_v1 2.16.840.1.113730.3.8.15.1 /usr/lib64/gssproxy/proxymech.so </command>
+            <arg choice='opt'>
+                <replaceable>options</replaceable>
+            </arg>
+        </cmdsynopsis>
+    </refsynopsisdiv>
+
+    <refsect1 id='description'>
+        <title>DESCRIPTION</title>
+        <para>
+            The gssproxy proxymech module is a interposer plugin that is
+            loaded by GSSAPI. It is enabled by
+            <filename>/etc/gss/mech</filename> configuration file.
+        </para>
+        <para>
+            The interposer plugin allows to intercept the entire GSSAPI
+            communication and detour to the <command>gssproxy</command>
+            daemon. When the interposer plugin is installed two other
+            conditions need to be met in order to activate it:
+        </para>
+	<variablelist>
+            <varlistentry>
+                <term>a) interposer configuration file</term>
+                <listitem>
+                    <para>The plugin needs to be manually enabled in the
+                        <filename>/etc/gss/mech</filename> file.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>b) gssproxy environment variable</term>
+                <listitem>
+                    <para>
+                        The interposer plugin will not forward to the
+                        gssproxy daemon unless the environment variable
+                        named <emphasis>GSS_USE_PROXY=yes</emphasis> is set.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+        <para>
+            Furthermore, the interposer plugin can be configured to behave in
+            different ways when called from the GSSAPI. This behavior is
+            controlled via the <emphasis>GSSPROXY_BEHAVIOR</emphasis>
+            environment variable. It accepts four different values:
+        </para>
+        <variablelist>
+            <varlistentry>
+                <term>LOCAL_ONLY</term>
+                <listitem>
+                    <para>All commands received with this setting will cause
+                        to immediately reenter the GSSAPI w/o any interaction
+                        with the gssproxy daemon. When the request cannot be
+                        processed it will just fail. This is the default
+                        behavior when the
+                        <emphasis>GSSPROXY_BEHAVIOR</emphasis> environment
+                        variable is not set at all.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>LOCAL_FIRST</term>
+                <listitem>
+                    <para>All commands received with this setting will cause
+                        to immediately reenter the GSSAPI. When the local
+                        GSSAPI cannot process the request, it will resend the
+                        request to the gssproxy daemon.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>REMOTE_FIRST</term>
+                <listitem>
+                    <para>All commands received with this setting will be
+                        forwarded to the gssproxy daemon first. If the request
+                        cannot be handled there, the request will reenter the
+                        local GSSAPI.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>REMOTE_ONLY</term>
+                <listitem>
+                    <para>This setting is currently not fully implemented and
+                        therefor not supported.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+        <para>
+            Finally the interposer may need to use a special per-service
+            socket in order to communicate with gssproxy. The path to this
+            socket is set via the <emphasis>GSSPROXY_SOCKET</emphasis>
+            environment variable.
+        </para>
+    </refsect1>
+
+    <refsect1 id='see_also'>
+        <title>SEE ALSO</title>
+        <para>
+            <citerefentry>
+                <refentrytitle>gssproxy.conf</refentrytitle><manvolnum>5</manvolnum>
+            </citerefentry> and
+            <citerefentry>
+                <refentrytitle>gssproxy</refentrytitle><manvolnum>8</manvolnum>
+            </citerefentry>.
+        </para>
+    </refsect1>
+</refentry>
+</reference>
diff --git a/proxy/man/gssproxy.8.xml b/proxy/man/gssproxy.8.xml
index c391aa3..ec76af8 100644
--- a/proxy/man/gssproxy.8.xml
+++ b/proxy/man/gssproxy.8.xml
@@ -31,8 +31,15 @@
     <refsect1 id='description'>
         <title>DESCRIPTION</title>
         <para>
-            <command>gssproxy</command> provides a daemons to manage access to
-            GSSAPI credetnials.
+            <command>gssproxy</command> provides a daemon to manage access to
+            GSSAPI credentials.
+        </para>
+        <para>
+            <command>gssproxy</command> consists of the <command>gssproxy</command> daemon
+            (configured by the <citerefentry><refentrytitle>gssproxy.conf</refentrytitle>
+            <manvolnum>5</manvolnum></citerefentry> file) and a GSSAPI interposer plugin
+            (<citerefentry><refentrytitle>gssproxy-mech</refentrytitle><manvolnum>8</manvolnum>
+            </citerefentry>).
         </para>
     </refsect1>
 
@@ -131,6 +138,9 @@
         <para>
             <citerefentry>
                 <refentrytitle>gssproxy.conf</refentrytitle><manvolnum>5</manvolnum>
+            </citerefentry> and
+            <citerefentry>
+                <refentrytitle>gssproxy-mech</refentrytitle><manvolnum>8</manvolnum>
             </citerefentry>.
         </para>
     </refsect1>
diff --git a/proxy/man/gssproxy.conf.5.xml b/proxy/man/gssproxy.conf.5.xml
index b733876..6103f1e 100644
--- a/proxy/man/gssproxy.conf.5.xml
+++ b/proxy/man/gssproxy.conf.5.xml
@@ -198,7 +198,10 @@
         <para>
             <citerefentry>
                 <refentrytitle>gssproxy</refentrytitle><manvolnum>8</manvolnum>
-            </citerefentry>
+            </citerefentry> and
+            <citerefentry>
+                <refentrytitle>gssproxy-mech</refentrytitle><manvolnum>8</manvolnum>
+            </citerefentry>.
         </para>
     </refsect1>