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

Andrew Bartlett

1 files changed, 122 insertions, 18 deletions

diff --git a/docs/docbook/manpages/ntlm_auth.1.xml b/docs/docbook/manpages/ntlm_auth.1.xml
index 77794f0f3fd..d769297c8f1 100644
--- 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,6 +176,14 @@
 	<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;
 	
@@ -109,6 +191,27 @@
 </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>
 
 	<para>This man page is correct for version 3.0 of the Samba 
@@ -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>