Re-arrangement of Chapters 3-8, merges, updates - first installment only.

(This used to be commit 549b047994bbaacc8e2e847c80bcb307c9f4a565)

1 files changed, 328 insertions, 144 deletions

diff --git a/docs/docbook/projdoc/DOMAIN_MEMBER.xml b/docs/docbook/projdoc/DOMAIN_MEMBER.xml
index a5921e8ce3..6a3ef28b55 100644
--- a/docs/docbook/projdoc/DOMAIN_MEMBER.xml
+++ b/docs/docbook/projdoc/DOMAIN_MEMBER.xml
@@ -3,159 +3,343 @@
 <chapterinfo>
 	&author.jeremy;
 	&author.jerry;
-	<pubdate>16 Apr 2001</pubdate>
+	&author.jht;
 </chapterinfo>
 
-
-<title>Samba as a NT4 or Win2k domain member</title>
+<title>Domain Membership</title>
 
 <sect1>
+<title>Domain Member Server</title>
+
+<para>
+This mode of server operation involves the samba machine being made a member
+of a domain security context. This means by definition that all user authentication
+will be done from a centrally defined authentication regime. The authentication
+regime may come from an NT3/4 style (old domain technology) server, or it may be
+provided from an Active Directory server (ADS) running on MS Windows 2000 or later.
+</para>
+
+<para><emphasis>
+Of course it should be clear that the authentication back end itself could be from any
+distributed directory architecture server that is supported by Samba. This can be
+LDAP (from OpenLDAP), or Sun's iPlanet, of NetWare Directory Server, etc.
+</emphasis></para>
+
+<para>
+Please refer to the section on Howto configure Samba as a Primary Domain Controller
+and for more information regarding how to create a domain machine account for a
+domain member server as well as for information regarding how to enable the samba
+domain member machine to join the domain and to be fully trusted by it.
+</para>
 
-	<title>Joining an NT Domain with Samba 3.0</title>
-	<para><emphasis>Assumptions:</emphasis>
-	<programlisting>
-		NetBIOS name: SERV1
-		Win2K/NT domain name: DOM
-		Domain's PDC NetBIOS name: DOMPDC
-		Domain's BDC NetBIOS names: DOMBDC1 and DOMBDC2
-	</programlisting>
-	</para>
-
-	<para>First, you must edit your &smb.conf; file to tell Samba it should
-	now use domain security.</para>
-	
-	<para>Change (or add) your <ulink url="smb.conf.5.html#SECURITY">
-	<parameter>security =</parameter></ulink> line in the [global] section 
-	of your &smb.conf; to read:</para>
-
-	<para><command>security = domain</command></para>
-
-	<para>Next change the <ulink url="smb.conf.5.html#WORKGROUP"><parameter>
-	workgroup =</parameter></ulink> line in the [global] section to read: </para>
-
-	<para><command>workgroup = DOM</command></para>
-
-	<para>as this is the name of the domain we are joining. </para>
-
-	<para>You must also have the parameter <ulink url="smb.conf.5.html#ENCRYPTPASSWORDS">
-	<parameter>encrypt passwords</parameter></ulink> set to <constant>yes
-	</constant> in order for your users to authenticate to the NT PDC.</para>
-
-	<para>Finally, add (or modify) a <ulink url="smb.conf.5.html#PASSWORDSERVER">
-	<parameter>password server =</parameter></ulink> line in the [global]
-	section to read: </para>
-
-	<para><command>password server = DOMPDC DOMBDC1 DOMBDC2</command></para>
-
-	<para>These are the primary and backup domain controllers Samba 
-	will attempt to contact in order to authenticate users. Samba will 
-	try to contact each of these servers in order, so you may want to 
-	rearrange this list in order to spread out the authentication load 
-	among domain controllers.</para>
-
-	<para>Alternatively, if you want smbd to automatically determine 
-	the list of Domain controllers to use for authentication, you may 
-	set this line to be :</para>
-
-	<para><command>password server = *</command></para>
-
-	<para>This method, allows Samba to use exactly the same
-        mechanism that NT does. This 
-	method either broadcasts or uses a WINS database in order to
-	find domain controllers to authenticate against.</para>
-
-	<para>In order to actually join the domain, you must run this
-        command:</para>
-
-	<para><prompt>root# </prompt><userinput>net join -S DOMPDC
-	-U<replaceable>Administrator%password</replaceable></userinput></para>
-
-	<para>
-	If the <userinput>-S DOMPDC</userinput> argument is not given then
-	the domain name will be obtained from smb.conf.
-	</para>
-
-	<para>as we are joining the domain DOM and the PDC for that domain 
-	(the only machine that has write access to the domain SAM database) 
-	is DOMPDC. The <replaceable>Administrator%password</replaceable> is 
-	the login name and password for an account which has the necessary 
-	privilege to add machines to the domain.  If this is successful 
-	you will see the message:</para>
-
-	<para><computeroutput>Joined domain DOM.</computeroutput>
-	or <computeroutput>Joined 'SERV1' to realm 'MYREALM'</computeroutput>
-	</para>
-
-	<para>in your terminal window. See the <ulink url="net.8.html">
-	net(8)</ulink> man page for more details.</para>
-	
-	<para>This process joins the server to the domain
-	without having to create the machine trust account on the PDC
-	beforehand.</para>
-
-	<para>This command goes through the machine account password 
-	change protocol, then writes the new (random) machine account 
-	password for this Samba server into a file in the same directory 
-	in which an smbpasswd file would be stored - normally :</para>
-
-	<para><filename>/usr/local/samba/private/secrets.tdb</filename></para>
-
-	<para>This file is created and owned by root and is not 
-	readable by any other user. It is the key to the domain-level 
-	security for your system, and should be treated as carefully 
-	as a shadow password file.</para>
-
-	<para>Finally, restart your Samba daemons and get ready for 
-	clients to begin using domain security!</para>
 </sect1>
 
 <sect1>
-	<title>Why is this better than security = server?</title>
-
-	<para>Currently, domain security in Samba doesn't free you from 
-	having to create local Unix users to represent the users attaching 
-	to your server. This means that if domain user <constant>DOM\fred
-	</constant> attaches to your domain security Samba server, there needs 
-	to be a local Unix user fred to represent that user in the Unix 
-	filesystem. This is very similar to the older Samba security mode 
-	<ulink url="smb.conf.5.html#SECURITYEQUALSSERVER">security = server</ulink>, 
-	where Samba would pass through the authentication request to a Windows 
-	NT server in the same way as a Windows 95 or Windows 98 server would.
-	</para>
-	
-	<para>Please refer to the <ulink url="winbind.html">Winbind 
-	paper</ulink> for information on a system to automatically
-	assign UNIX uids and gids to Windows NT Domain users and groups.
-	</para>
-
-	<para>The advantage to domain-level security is that the 
-	authentication in domain-level security is passed down the authenticated 
-	RPC channel in exactly the same way that an NT server would do it. This 
-	means Samba servers now participate in domain trust relationships in 
-	exactly the same way NT servers do (i.e., you can add Samba servers into 
-	a resource domain and have the authentication passed on from a resource
-	domain PDC to an account domain PDC).</para>
-
-	<para>In addition, with <command>security = server</command> every Samba 
-	daemon on a server has to keep a connection open to the 
-	authenticating server for as long as that daemon lasts. This can drain 
-	the connection resources on a Microsoft NT server and cause it to run 
-	out of available connections. With <command>security = domain</command>, 
-	however, the Samba daemons connect to the PDC/BDC only for as long 
-	as is necessary to authenticate the user, and then drop the connection, 
-	thus conserving PDC connection resources.</para>
-
-	<para>And finally, acting in the same manner as an NT server 
-	authenticating to a PDC means that as part of the authentication 
-	reply, the Samba server gets the user identification information such 
-	as the user SID, the list of NT groups the user belongs to, etc. </para>
-
-	<note><para> Much of the text of this document 
-	was first published in the Web magazine <ulink url="http://www.linuxworld.com"> 	
-	LinuxWorld</ulink> as the article <ulink
-	url="http://www.linuxworld.com/linuxworld/lw-1998-10/lw-10-samba.html">Doing 
-	the NIS/NT Samba</ulink>.</para></note>
+<title>Joining an NT4 type Domain with Samba-3</title>
+<para><emphasis>Assumptions:</emphasis>
+<programlisting>
+	NetBIOS name: SERV1
+	Win2K/NT domain name: DOM
+	Domain's PDC NetBIOS name: DOMPDC
+	Domain's BDC NetBIOS names: DOMBDC1 and DOMBDC2
+</programlisting>
+</para>
+
+<para>First, you must edit your &smb.conf; file to tell Samba it should
+now use domain security.</para>
+
+<para>Change (or add) your <ulink url="smb.conf.5.html#SECURITY">
+<parameter>security =</parameter></ulink> line in the [global] section 
+of your &smb.conf; to read:</para>
+
+<para><command>security = domain</command></para>
+
+<para>Next change the <ulink url="smb.conf.5.html#WORKGROUP"><parameter>
+workgroup =</parameter></ulink> line in the [global] section to read: </para>
+
+<para><command>workgroup = DOM</command></para>
+
+<para>as this is the name of the domain we are joining. </para>
+
+<para>You must also have the parameter <ulink url="smb.conf.5.html#ENCRYPTPASSWORDS">
+<parameter>encrypt passwords</parameter></ulink> set to <constant>yes
+</constant> in order for your users to authenticate to the NT PDC.</para>
+
+<para>Finally, add (or modify) a <ulink url="smb.conf.5.html#PASSWORDSERVER">
+<parameter>password server =</parameter></ulink> line in the [global]
+section to read: </para>
+
+<para><command>password server = DOMPDC DOMBDC1 DOMBDC2</command></para>
+
+<para>These are the primary and backup domain controllers Samba 
+will attempt to contact in order to authenticate users. Samba will 
+try to contact each of these servers in order, so you may want to 
+rearrange this list in order to spread out the authentication load 
+among domain controllers.</para>
+
+<para>Alternatively, if you want smbd to automatically determine 
+the list of Domain controllers to use for authentication, you may 
+set this line to be :</para>
+
+<para><command>password server = *</command></para>
+
+<para>This method, allows Samba to use exactly the same
+mechanism that NT does. This 
+method either broadcasts or uses a WINS database in order to
+find domain controllers to authenticate against.</para>
+
+<para>In order to actually join the domain, you must run this
+command:</para>
+
+<para><prompt>root# </prompt><userinput>net join -S DOMPDC
+-U<replaceable>Administrator%password</replaceable></userinput></para>
+
+<para>
+If the <userinput>-S DOMPDC</userinput> argument is not given then
+the domain name will be obtained from smb.conf.
+</para>
+
+<para>as we are joining the domain DOM and the PDC for that domain 
+(the only machine that has write access to the domain SAM database) 
+is DOMPDC. The <replaceable>Administrator%password</replaceable> is 
+the login name and password for an account which has the necessary 
+privilege to add machines to the domain.  If this is successful 
+you will see the message:</para>
+
+<para><computeroutput>Joined domain DOM.</computeroutput>
+or <computeroutput>Joined 'SERV1' to realm 'MYREALM'</computeroutput>
+</para>
+
+<para>in your terminal window. See the <ulink url="net.8.html">
+net(8)</ulink> man page for more details.</para>
+
+<para>This process joins the server to the domain
+without having to create the machine trust account on the PDC
+beforehand.</para>
+
+<para>This command goes through the machine account password 
+change protocol, then writes the new (random) machine account 
+password for this Samba server into a file in the same directory 
+in which an smbpasswd file would be stored - normally :</para>
+
+<para><filename>/usr/local/samba/private/secrets.tdb</filename></para>
+
+<para>This file is created and owned by root and is not 
+readable by any other user. It is the key to the domain-level 
+security for your system, and should be treated as carefully 
+as a shadow password file.</para>
+
+<para>Finally, restart your Samba daemons and get ready for 
+clients to begin using domain security!</para>
+
+<sect2>
+<title>Why is this better than security = server?</title>
+
+<para>Currently, domain security in Samba doesn't free you from 
+having to create local Unix users to represent the users attaching 
+to your server. This means that if domain user <constant>DOM\fred
+</constant> attaches to your domain security Samba server, there needs 
+to be a local Unix user fred to represent that user in the Unix 
+filesystem. This is very similar to the older Samba security mode 
+<ulink url="smb.conf.5.html#SECURITYEQUALSSERVER">security = server</ulink>, 
+where Samba would pass through the authentication request to a Windows 
+NT server in the same way as a Windows 95 or Windows 98 server would.
+</para>
+
+<para>Please refer to the <ulink url="winbind.html">Winbind 
+paper</ulink> for information on a system to automatically
+assign UNIX uids and gids to Windows NT Domain users and groups.
+</para>
+
+<para>The advantage to domain-level security is that the 
+authentication in domain-level security is passed down the authenticated 
+RPC channel in exactly the same way that an NT server would do it. This 
+means Samba servers now participate in domain trust relationships in 
+exactly the same way NT servers do (i.e., you can add Samba servers into 
+a resource domain and have the authentication passed on from a resource
+domain PDC to an account domain PDC).</para>
+
+<para>In addition, with <command>security = server</command> every Samba 
+daemon on a server has to keep a connection open to the 
+authenticating server for as long as that daemon lasts. This can drain 
+the connection resources on a Microsoft NT server and cause it to run 
+out of available connections. With <command>security = domain</command>, 
+however, the Samba daemons connect to the PDC/BDC only for as long 
+as is necessary to authenticate the user, and then drop the connection, 
+thus conserving PDC connection resources.</para>
+
+<para>And finally, acting in the same manner as an NT server 
+authenticating to a PDC means that as part of the authentication 
+reply, the Samba server gets the user identification information such 
+as the user SID, the list of NT groups the user belongs to, etc. </para>
+
+<note><para> Much of the text of this document 
+was first published in the Web magazine <ulink url="http://www.linuxworld.com"> 	
+LinuxWorld</ulink> as the article <ulink
+url="http://www.linuxworld.com/linuxworld/lw-1998-10/lw-10-samba.html">Doing 
+the NIS/NT Samba</ulink>.</para></note>
+</sect2>
 
 </sect1>
 
+<sect1>
+<title>Samba ADS Domain Membership</title>
+
+<para>
+This is a rough guide to setting up Samba 3.0 with kerberos authentication against a
+Windows2000 KDC. 
+</para> 
+
+<sect2>
+<title>Setup your <filename>smb.conf</filename></title>
+
+<para>You must use at least the following 3 options in smb.conf:</para>
+
+<para><programlisting>
+	realm = YOUR.KERBEROS.REALM
+	security = ADS
+	encrypt passwords = yes
+</programlisting></para>
+
+<para>
+In case samba can't figure out your ads server using your realm name, use the 
+<command>ads server</command> option in <filename>smb.conf</filename>:
+<programlisting>
+	ads server = your.kerberos.server
+</programlisting>
+</para>
+
+<note><para>You do *not* need a smbpasswd file, and older clients will
+  be authenticated as if <command>security = domain</command>,
+  although it won't do any harm
+  and allows you to have local users not in the domain.
+  I expect that the above required options will change soon when we get better
+  active directory integration.</para></note>
+
+</sect2>
+  
+<sect2>
+<title>Setup your <filename>/etc/krb5.conf</filename></title>
+
+<para>Note: you will need the krb5 workstation, devel, and libs installed</para>
+
+<para>The minimal configuration for <filename>krb5.conf</filename> is:</para>
+
+<para><programlisting>
+	[realms]
+	    YOUR.KERBEROS.REALM = {
+		kdc = your.kerberos.server
+	    }
+</programlisting></para>
+
+<para>Test your config by doing a <userinput>kinit
+<replaceable>USERNAME</replaceable>@<replaceable>REALM</replaceable></userinput> and
+making sure that your password is accepted by the Win2000 KDC.
+</para>
+
+<note><para>The realm must be uppercase or you will get "Cannot find KDC for requested
+realm while getting initial credentials" error </para></note>
+
+<note><para>Time between the two servers must be synchronized.  You will get a
+"kinit(v5): Clock skew too great while getting initial credentials" if the time
+difference is more than five minutes. </para></note>
+
+<para>
+You also must ensure that you can do a reverse DNS lookup on the IP
+address of your KDC. Also, the name that this reverse lookup maps to
+must either be the netbios name of the KDC (ie. the hostname with no
+domain attached) or it can alternatively be the netbios name
+followed by the realm. 
+</para>
+
+<para>
+The easiest way to ensure you get this right is to add a 
+<filename>/etc/hosts</filename> entry mapping the IP address of your KDC to 
+its netbios name. If you don't get this right then you will get a 
+"local error" when you try to join the realm.
+</para>
+
+<para>
+If all you want is kerberos support in &smbclient; then you can skip
+straight to <link linkend="ads-test-smbclient">Test with &smbclient;</link> now. 
+<link linkend="ads-create-machine-account">Creating a computer account</link> 
+and <link linkend="ads-test-server">testing your servers</link>
+is only needed if you want kerberos support for &smbd; and &winbindd;.
+</para>
+
+</sect2>
+
+<sect2 id="ads-create-machine-account">
+<title>Create the computer account</title>
+
+<para>
+As a user that has write permission on the Samba private directory
+(usually root) run:
+<programlisting>
+	<userinput>net join -U Administrator%password</userinput>
+</programlisting>
+</para>
+
+<sect3>
+<title>Possible errors</title>
+
+<para>
+<variablelist>
+	<varlistentry><term>"ADS support not compiled in"</term>
+	<listitem><para>Samba must be reconfigured (remove config.cache) and recompiled
+	(make clean all install) after the kerberos libs and headers are installed.
+	</para></listitem></varlistentry>
+
+	<varlistentry><term>net join prompts for user name</term>
+	<listitem><para>You need to login to the domain using <userinput>kinit
+	<replaceable>USERNAME</replaceable>@<replaceable>REALM</replaceable></userinput>.
+	<replaceable>USERNAME</replaceable> must be a user who has rights to add a machine
+	to the domain.  </para></listitem></varlistentry>
+</variablelist>
+</para>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="ads-test-server">
+<title>Test your server setup</title>
+
+<para>
+If the join was successful, you will see a new computer account with the
+NetBIOS name of your Samba server in Active Directory (in the "Computers"
+folder under Users and Computers.
+</para>
+
+<para>
+On a Windows 2000 client try <userinput>net use * \\server\share</userinput>. You should
+be logged in with kerberos without needing to know a password. If
+this fails then run <userinput>klist tickets</userinput>. Did you get a ticket for the
+server? Does it have an encoding type of DES-CBC-MD5 ? 
+</para>
+
+</sect2>
+
+<sect2 id="ads-test-smbclient">
+<title>Testing with &smbclient;</title>
+
+<para>
+On your Samba server try to login to a Win2000 server or your Samba
+server using &smbclient; and kerberos. Use &smbclient; as usual, but
+specify the <parameter>-k</parameter> option to choose kerberos authentication.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Notes</title>
+
+<para>You must change administrator password at least once after DC 
+install, to create the right encoding types</para>
+
+<para>w2k doesn't seem to create the _kerberos._udp and _ldap._tcp in
+   their defaults DNS setup. Maybe fixed in service packs?</para>
+</sect2>
+
+</sect1>
 </chapter>