Start to put some real 'meat' into the ntlm_auth docs.

Andrew Bartlett
(This used to be commit 227c7daf36f82f6b7935add09b37f44a9965335b)

diff --git a/docs/docbook/manpages/ntlm_auth.1.xml b/docs/docbook/manpages/ntlm_auth.1.xml
index 77794f0f3fdb7b9f3b0f8ff44e98e7258dab6114..d769297c8f11d704c3756b64a5d2ea62d05efafd 100644 (file)
--- a/docs/docbook/manpages/ntlm_auth.1.xml
+++ b/docs/docbook/manpages/ntlm_auth.1.xml
@@ -34,11 +34,28 @@
        <para><command>ntlm_auth</command> is a helper utility that authenticates 
        users using NT/LM authentication. It returns 0 if the users is authenticated
        successfully and 1 if access was denied. ntlm_auth uses winbind to access 
-       the user and authentication data for a domain. This utility 
-       is only to be used by other programs (currently squid).
+       the user and authentication data for a domain.  This utility 
+       is only indended to be used by other programs (currently squid).
        </para>
 </refsect1>
 
+<refsect1>
+       <title>OPERATIONAL REQUIREMENTS</title>
+
+    <para>
+    The <citerefentry><refentrytitle>winbindd</refentrytitle>
+    <manvolnum>8</manvolnum></citerefentry> daemon must be operational
+    for many of these commands to function.</para>
+
+    <para>Some of these commands also require access to the directory 
+    <filename>winbindd_privileged</filename> in
+    <filename>$LOCKDIR</filename>.  This should be done either by running
+    this command as root or providing group access
+    to the <filename>winbindd_privileged</filename> directory.  For
+    security reasons, this directory should not be world-accessable. </para>
+
+</refsect1>
+
 
 <refsect1>
        <title>OPTIONS</title>
@@ -47,49 +64,106 @@
        <varlistentry>
        <term>--helper-protocol=PROTO</term>
        <listitem><para>
-       Operate as a stdio-based helper
-       </para></listitem>
-       </varlistentry>
-
-       <varlistentry>
+       Operate as a stdio-based helper.  Valid helper protocols are:
+        </para> 
+        <variablelist>
+             <varlistentry>
+               <term>squid-2.4-basic</term>
+               <listitem><para>
+                Server-side helper for use with Squid 2.4's basic (plaintext)
+               authentication.  </para>
+                </listitem>
+               </varlistentry>
+             <varlistentry>
+               <term>squid-2.5-basic</term>
+               <listitem><para>
+                Server-side helper for use with Squid 2.5's basic (plaintext)
+               authentication. </para>
+                </listitem>
+               </varlistentry>
+             <varlistentry>
+               <term>squid-2.5-ntlmssp</term>
+               <listitem><para>
+                Server-side helper for use with Squid 2.5's NTLMSSP 
+               authentication. </para>
+                 <para>Requires access to the directory 
+                <filename>winbindd_privileged</filename> in
+               <filename>$LOCKDIR</filename>.  The protocol used is
+               described here: <ulink
+               url="http://devel.squid-cache.org/ntlm/squid_helper_protocol.html">http://devel.squid-cache.org/ntlm/squid_helper_protocol.html</ulink>
+                </para>
+                </listitem>
+             </varlistentry>
+
+             <varlistentry>
+               <term>gss-spengo</term>
+               <listitem><para>
+                Server-side helper that implements GSS-SPNEGO.  This
+               also uses the same as
+               <command>squid-2.5-ntlmssp</command> and is described
+               here: 
+                <ulink
+               url="http://devel.squid-cache.org/ntlm/squid_helper_protocol.html">http://devel.squid-cache.org/ntlm/squid_helper_protocol.html</ulink>
+                </para>
+                </listitem>
+               </varlistentry>
+                 
+               <varlistentry>
+               <term>gss-spengo-client</term>
+               <listitem><para>
+                Client-side helper that implements GSS-SPNEGO.  This
+               also uses a protocol similar to the above helpers, but
+               is currently undocumented.
+                </para>
+                </listitem>
+               </varlistentry>
+       </variablelist>
+       </listitem>
+      </varlistentry>
+      
+      <varlistentry>
        <term>--username=USERNAME</term>
        <listitem><para>
        Specify username of user to authenticate
        </para></listitem>
-       </varlistentry>
-
-       <varlistentry>
+       
+      </varlistentry>
+      
+      <varlistentry>
        <term>--domain=DOMAIN</term>
        <listitem><para>
        Specify domain of user to authenticate
        </para></listitem>
-       </varlistentry>
+      </varlistentry>
 
-       <varlistentry>
+      <varlistentry>
        <term>--workstation=WORKSTATION</term>
        <listitem><para>
        Specify the workstation the user authenticated from
        </para></listitem>
-       </varlistentry>
+      </varlistentry>
 
        <varlistentry>
        <term>--challenge=STRING</term>
-       <listitem><para>challenge (HEX encoded)</para></listitem>
+       <listitem><para>NTLM challenge (in HEXADECIMAL)</para>
+       </listitem>
        </varlistentry>
 
        <varlistentry>
        <term>--lm-response=RESPONSE</term>
-       <listitem><para>LM Response to the challenge (HEX encoded)</para></listitem>
+       <listitem><para>LM Response to the challenge (in HEXADECIMAL)</para></listitem>
        </varlistentry>
 
        <varlistentry>
        <term>--nt-response=RESPONSE</term>
-       <listitem><para>NT or NTLMv2 Response to the challenge (HEX encoded)</para></listitem>
+       <listitem><para>NT or NTLMv2 Response to the challenge (in HEXADECIMAL)</para></listitem>
        </varlistentry>
 
        <varlistentry>
        <term>--password=PASSWORD</term>
-       <listitem><para>User's plaintext password</para></listitem>
+       <listitem><para>User's plaintext password</para><para>If 
+       not specified on the command line, this is prompted for when
+       required.  </para></listitem>
        </varlistentry>
 
        <varlistentry>
@@ -102,12 +176,41 @@
        <listitem><para>Request NT key</para></listitem>
        </varlistentry>
 
+      <varlistentry>
+       <term>--diagnostics</term>
+       <listitem><para>Perform Diagnostics on the authentication
+       chain.  Uses the password from <command>--password</command>
+       or prompts for one.</para>
+        </listitem>
+        </varlistentry>
+
          &popt.common.samba;
          &stdarg.help;
        
        </variablelist>
 </refsect1>
 
+<refsect1>
+       <title>EXAMPLE SETUP</title>
+
+        <para>To setup ntlm_auth for use by squid 2.5, with both basic and
+       NTLMSSP authentication, the following
+       should be placed in the <filename>squid.conf</filename> file.
+<programlisting>
+auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
+auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
+auth_param basic children 5
+auth_param basic realm Squid proxy-caching web server
+auth_param basic credentialsttl 2 hours
+</programlisting></para>
+
+<note><para>This example assumes that ntlm_auth has been installed into your
+      path, and that the group permissions on
+      <filename>winbindd_privileged</filename> are as described above.</para></note>
+
+</refsect1>
+
+
 <refsect1>
        <title>VERSION</title>
 
@@ -123,7 +226,8 @@
        by the Samba Team as an Open Source project similar 
        to the way the Linux kernel is developed.</para>
        
-       <para>The ntlm_auth manpage was written by Jelmer Vernooij.</para>
+       <para>The ntlm_auth manpage was written by Jelmer Vernooij and
+       Andrew Bartlett.</para>
 </refsect1>
 
 </refentry>