A few more little fixes, a few more edits, a bit lost here, and a lot gained there! :)

This documentation process is tedious, but noone will notice it anyhow! :)
(This used to be commit b8666c39493383566b3f108dfdf0328e7a5a92a9)

1 files changed, 221 insertions, 1 deletions

diff --git a/docs/docbook/projdoc/DOMAIN_MEMBER.xml b/docs/docbook/projdoc/DOMAIN_MEMBER.xml
index 6a3ef28b55..f12936a215 100644
--- a/docs/docbook/projdoc/DOMAIN_MEMBER.xml
+++ b/docs/docbook/projdoc/DOMAIN_MEMBER.xml
@@ -179,7 +179,227 @@ 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>Machine Trust Accounts and Domain Membership</title>
+
+<para>
+A machine trust account is an account that is used to authenticate a client machine
+(rather than a user) to the Domain Controller server.  In Windows terminology,
+this is known as a "Computer Account."</para>
+
+<para>
+The password of a machine trust account acts as the shared secret for
+secure communication with the Domain Controller.  This is a security
+feature to prevent an unauthorized machine with the same NetBIOS name
+from joining the domain and gaining access to domain user/group
+accounts.  Windows NT, 200x, XP Professional clients use machine trust
+accounts, but Windows 9x / Me / XP Home clients do not.  Hence, a
+Windows 9x / Me / XP Home  client is never a true member of a domain
+because it does not possess a machine trust account, and thus has no
+shared secret with the domain controller.
+</para>
+
+<para>A Windows NT4 PDC stores each machine trust account in the Windows
+Registry. The introduction of MS Windows 2000 saw the introduction of Active Directory,
+the new repository for machine trust accounts.
+</para>
+
+<para>
+A Samba PDC, however, stores each machine trust account in two parts,
+as follows:
+
+<itemizedlist>
+    <listitem><para>A Samba account, stored in the same location as user
+    LanMan and NT password hashes (currently <filename>smbpasswd</filename>).
+    The Samba account possesses and uses only the NT password hash.</para></listitem>
+
+    <listitem><para>A corresponding Unix account, typically stored in
+    <filename>/etc/passwd</filename>. (Future releases will alleviate the need to
+    create <filename>/etc/passwd</filename> entries.) </para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+There are two ways to create machine trust accounts:
+</para>
+
+<itemizedlist>
+	<listitem><para> Manual creation. Both the Samba and corresponding
+	Unix account are created by hand.</para></listitem>
+	
+	<listitem><para> "On-the-fly" creation. The Samba machine trust
+	account is automatically created by Samba at the time the client
+	is joined to the domain. (For security, this is the
+	recommended method.) The corresponding Unix account may be
+	created automatically or manually. </para>
+	</listitem>
+
+</itemizedlist>
+
+<sect2>
+<title>Manual Creation of Machine Trust Accounts</title>
+
+<para>
+The first step in manually creating a machine trust account is to
+manually create the corresponding Unix account in
+<filename>/etc/passwd</filename>.  This can be done using
+<command>vipw</command> or other 'add user' command that is normally
+used to create new Unix accounts.  The following is an example for a
+Linux based Samba server:
+</para>
+
+<para>
+  <prompt>root# </prompt><command>/usr/sbin/useradd -g 100 -d /dev/null -c <replaceable>"machine 
+nickname"</replaceable> -s /bin/false <replaceable>machine_name</replaceable>$ </command>
+</para>
+<para>
+<prompt>root# </prompt><command>passwd -l <replaceable>machine_name</replaceable>$</command>
+</para>
+
+<para>On *BSD systems, this can be done using the 'chpass' utility:</para>
+
+<para>
+<prompt>root# </prompt><command>chpass -a "<replaceable>machine_name</replaceable>$:*:101:100::0:0:Workstation <replaceable>machine_name</replaceable>:/dev/null:/sbin/nologin"</command>
+</para>
+
+<para>
+The <filename>/etc/passwd</filename> entry will list the machine name 
+with a "$" appended, won't have a password, will have a null shell and no 
+home directory. For example a machine named 'doppy' would have an 
+<filename>/etc/passwd</filename> entry like this:
+</para>
+
+<para><programlisting>
+doppy$:x:505:501:<replaceable>machine_nickname</replaceable>:/dev/null:/bin/false
+</programlisting></para>
+
+<para>
+Above, <replaceable>machine_nickname</replaceable> can be any
+descriptive name for the client, i.e., BasementComputer.
+<replaceable>machine_name</replaceable> absolutely must be the NetBIOS
+name of the client to be joined to the domain.  The "$" must be
+appended to the NetBIOS name of the client or Samba will not recognize
+this as a machine trust account.
+</para>
+
+<para>
+Now that the corresponding Unix account has been created, the next step is to create 
+the Samba account for the client containing the well-known initial 
+machine trust account password.  This can be done using the <ulink 
+url="smbpasswd.8.html"><command>smbpasswd(8)</command></ulink> command 
+as shown here:
+</para>
+
+<para>
+<prompt>root# </prompt><userinput>smbpasswd -a -m <replaceable>machine_name</replaceable></userinput>
+</para>
 
+<para>
+where <replaceable>machine_name</replaceable> is the machine's NetBIOS
+name.  The RID of the new machine account is generated from the UID of 
+the corresponding Unix account.
+</para>
+
+<warning>
+	<title>Join the client to the domain immediately</title>
+
+	<para>
+	Manually creating a machine trust account using this method is the 
+	equivalent of creating a machine trust account on a Windows NT PDC using 
+	the "Server Manager".  From the time at which the account is created
+	to the time which the client joins the domain and changes the password,
+	your domain is vulnerable to an intruder joining your domain using
+	a machine with the same NetBIOS name.  A PDC inherently trusts
+	members of the domain and will serve out a large degree of user 
+	information to such clients.  You have been warned!
+	</para>
+</warning>
+</sect2>
+
+
+<sect2>
+<title>"On-the-Fly" Creation of Machine Trust Accounts</title>
+
+<para>
+The second (and recommended) way of creating machine trust accounts is
+simply to allow the Samba server to create them as needed when the client
+is joined to the domain. </para>
+
+<para>Since each Samba machine trust account requires a corresponding
+Unix account, a method for automatically creating the
+Unix account is usually supplied; this requires configuration of the
+<ulink url="smb.conf.5.html#ADDMACHINESCRIPT">add machine script</ulink> 
+option in <filename>smb.conf</filename>.  This
+method is not required, however; corresponding Unix accounts may also
+be created manually.
+</para>
+
+
+<para>
+Below is an example for a RedHat Linux system.
+</para>
+
+<para><programlisting>
+[global]
+   # &lt;...remainder of parameters...&gt;
+   add machine script = /usr/sbin/useradd -d /dev/null -g 100 -s /bin/false -M %u 
+</programlisting></para>
+
+</sect2>
+
+
+<sect2><title>Joining the Client to the Domain</title>
+
+<para>
+The procedure for joining a client to the domain varies with the version of Windows.
+</para>
+
+<itemizedlist>
+<listitem><para><emphasis>Windows 2000</emphasis></para>
+
+	<para>
+	When the user elects to join the client to a domain, Windows prompts for
+	an account and password that is privileged to join the domain. A Samba administrative
+	account (i.e., a Samba account that has root privileges on the Samba server) must be
+	entered here; the operation will fail if an ordinary user account is given. 
+	The password for this account should be set to a different password than the associated
+	<filename>/etc/passwd</filename> entry, for security reasons.
+	</para>
+
+	<para>
+	The session key of the Samba administrative account acts as an
+	encryption key for setting the password of the machine trust
+	account. The machine trust account will be created on-the-fly, or
+	updated if it already exists.
+	</para>
+
+</listitem>
+
+<listitem><para><emphasis>Windows NT</emphasis></para>
+
+    <para> If the machine trust account was created manually, on the
+	Identification Changes menu enter the domain name, but do not
+	check the box "Create a Computer Account in the Domain."  In this case,
+	the existing machine trust account is used to join the machine to
+	the domain.</para>
+
+    <para> If the machine trust account is to be created
+	on-the-fly, on the Identification Changes menu enter the domain
+	name, and check the box "Create a Computer Account in the Domain."  In
+	this case, joining the domain proceeds as above for Windows 2000
+	(i.e., you must supply a Samba administrative account when
+	prompted).</para>
+</listitem>
+
+<listitem><para><emphasis>Samba</emphasis></para>
+	<para>Joining a samba client to a domain is documented in 
+	the <link linkend="domain-member">Domain Member</link> chapter.
+</para></listitem>
+</itemizedlist>
+
+</sect2>
 </sect1>
 
 <sect1>
@@ -196,7 +416,7 @@ Windows2000 KDC.
 <para>You must use at least the following 3 options in smb.conf:</para>
 
 <para><programlisting>
-	realm = YOUR.KERBEROS.REALM
+	realm = your.kerberos.REALM
 	security = ADS
 	encrypt passwords = yes
 </programlisting></para>