docs: Rewrite 'password server' documentation

I think this new version is more clear.

Andrew Bartlett

1 files changed, 54 insertions, 52 deletions

diff --git a/docs-xml/smbdotconf/security/passwordserver.xml b/docs-xml/smbdotconf/security/passwordserver.xml
index 0e92af9eba..0ac39f103c 100644
--- a/docs-xml/smbdotconf/security/passwordserver.xml
+++ b/docs-xml/smbdotconf/security/passwordserver.xml
@@ -10,54 +10,24 @@
     it is possible to get Samba
     to do all its username/password validation using a specific remote server.</para>
 
-    <para>This option sets the name or IP address of the password server to use. 
-    New syntax has been added to support defining the port to use when connecting 
-    to the server the case of an ADS realm.  To define a port other than the
-    default LDAP port of 389, add the port number using a colon after the 
-    name or IP address (e.g. 192.168.1.100:389).  If you do not specify a port,
-    Samba will use the standard LDAP port of tcp/389.  Note that port numbers
-    have no effect on password servers for Windows NT 4.0 domains or netbios 
-    connections.</para>
-
-    <para>If parameter is a name, it is looked up using the 
-    parameter <smbconfoption name="name resolve order"/> and so may resolved
-    by any method and order described in that parameter.</para>
-
-    <para>The password server must be a machine capable of using 
-    the &quot;LM1.2X002&quot; or the &quot;NT LM 0.12&quot; protocol, and it must be in 
-    user level security mode.</para>
-
-    <note><para>Using a password server  means your UNIX box (running
-    Samba) is only as secure as your  password server. <emphasis>DO NOT
-    CHOOSE A PASSWORD SERVER THAT  YOU DON'T COMPLETELY TRUST</emphasis>.
-    </para></note>
-		
-    <para>Never point a Samba server at itself for password serving.
-    This will cause a loop and could lock up your Samba  server!</para>
-
-    <para>The name of the password server takes the standard 
-    substitutions, but probably the only useful one is <parameter moreinfo="none">%m
-    </parameter>, which means the Samba server will use the incoming 
-    client as the password server. If you use this then you better 
-    trust your clients, and you had better restrict them with hosts allow!</para>
-
     <para>If the <parameter moreinfo="none">security</parameter> parameter is set to
-    <constant>domain</constant> or <constant>ads</constant>, then the list of machines in this 
-    option must be a list of Primary or Backup Domain controllers for the
-    Domain or the character '*', as the Samba server is effectively
-    in that domain, and will use cryptographically authenticated RPC calls
-    to authenticate the user logging on. The advantage of using <command moreinfo="none">
-    security = domain</command> is that if you list several hosts in the 
-    <parameter moreinfo="none">password server</parameter> option then <command moreinfo="none">smbd
-    </command> will try each in turn till it finds one that responds.  This
-    is useful in case your primary server goes down.</para>
+    <constant>domain</constant> or <constant>ads</constant>, then this option 
+    <emphasis>should not</emphasis> be used, as the default '*' indicates to Samba 
+    to determine the best DC to contact dynamically, just as all other hosts in an 
+    AD domain do.  This allows the domain to be maintained without modification to 
+    the smb.conf file.  The cryptograpic protection on the authenticated RPC calls
+    used to verify passwords ensures that this default is safe.</para>
 
-    <para>If the <parameter moreinfo="none">password server</parameter> option is set 
-    to the character '*', then Samba will attempt to auto-locate the 
-    Primary or Backup Domain controllers to authenticate against by 
-    doing a query for the name <constant>WORKGROUP&lt;1C&gt;</constant> 
-    and then contacting each server returned in the list of IP 
-    addresses from the name resolution source. </para>
+    <para><emphasis>It is strongly recommended that you use the
+    default of '*'</emphasis>, however if in your particular
+    environment you have reason to specify a particular DC list, then
+    the list of machines in this option must be a list of names or IP
+    addresses of Domain controllers for the Domain. If you use the
+    default of '*', or list several hosts in the <parameter
+    moreinfo="none">password server</parameter> option then <command
+    moreinfo="none">smbd </command> will try each in turn till it
+    finds one that responds.  This is useful in case your primary
+    server goes down.</para>
 
     <para>If the list of servers contains both names/IP's and the '*'
     character, the list is treated as a list of preferred 
@@ -65,10 +35,12 @@
     will be added to the list as well.  Samba will not attempt to optimize 
     this list by locating the closest DC.</para>
 		
+    <para>If parameter is a name, it is looked up using the 
+    parameter <smbconfoption name="name resolve order"/> and so may resolved
+    by any method and order described in that parameter.</para>
+
     <para>If the <parameter moreinfo="none">security</parameter> parameter is 
-    set to <constant>server</constant>, then there are different
-    restrictions that <command moreinfo="none">security = domain</command> doesn't 
-    suffer from:</para>
+    set to <constant>server</constant>, these additional restrictions apply:</para>
 
     <itemizedlist>
 	<listitem>
@@ -82,12 +54,42 @@
 	</listitem>
 	    
 	<listitem>
-	    <para>If you are using a Windows NT server as your 
-	    password server then you will have to ensure that your users 
+	    <para>You will have to ensure that your users 
 	    are able to login from the Samba server, as when in <command moreinfo="none">
 	    security = server</command>  mode the network logon will appear to 
-	    come from there rather than from the users workstation.</para>
+	    come from the Samba server rather than from the users workstation.</para>
 	</listitem>
+
+	<listitem>
+	    <para>The client must not select NTLMv2 authentication.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The password server must be a machine capable of using 
+	  the &quot;LM1.2X002&quot; or the &quot;NT LM 0.12&quot; protocol, and it must be in 
+	  user level security mode.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Using a password server  means your UNIX box (running
+	  Samba) is only as secure as (a host masqurading as) your password server. <emphasis>DO NOT
+	  CHOOSE A PASSWORD SERVER THAT  YOU DON'T COMPLETELY TRUST</emphasis>.
+	  </para>
+	</listitem>
+		
+	<listitem>
+	  <para>Never point a Samba server at itself for password serving.
+	  This will cause a loop and could lock up your Samba  server!</para>
+	</listitem>
+
+	<listitem>
+	  <para>The name of the password server takes the standard 
+	  substitutions, but probably the only useful one is <parameter moreinfo="none">%m
+	  </parameter>, which means the Samba server will use the incoming 
+	  client as the password server. If you use this then you better 
+	  trust your clients, and you had better restrict them with hosts allow!</para>
+	</listitem>
+
     </itemizedlist>
 </description>