Add all the source files from the old CVS tree,

add the 5 missing chapters from the HOWTO
and add jht's Samba by Example book.
(This used to be commit 9fb5bcb93e57c5162b3ee6f9c7d777dc0269d100)

1 files changed, 990 insertions, 0 deletions

diff --git a/docs/howto/PDC.xml b/docs/howto/PDC.xml
new file mode 100644
index 0000000000..6d3fa64a24
--- /dev/null
+++ b/docs/howto/PDC.xml
@@ -0,0 +1,990 @@
+<chapter id="samba-pdc">
+
+<chapterinfo>
+	&author.jht;
+	&author.jerry;
+	&author.dbannon;
+	<author>&person.gd; <contrib>LDAP updates</contrib></author>
+</chapterinfo>
+
+<title>Domain Control</title>
+
+<para>
+There are many who approach MS Windows networking with incredible misconceptions.
+That's okay, because it gives the rest of us plenty of opportunity to be of assistance.
+Those who really want help would be well advised to become familiar with information
+that is already available.
+</para>
+
+<para>
+The reader is advised not to tackle this section without having first understood
+and mastered some basics. MS Windows networking is not particularly forgiving of
+mis-configuration. Users of MS Windows networking are likely to complain 
+of persistent niggles that may be caused by a broken network configuration.
+To a great many people, however, MS Windows networking starts with a Domain Controller
+that in some magical way is expected to solve all network operational ills.
+</para>
+
+<para>
+<link linkend="domain-example">The diagram</link> shows a typical MS Windows Domain Security
+network environment. Workstations A, B and C are representative of many physical MS Windows
+network clients.
+</para>
+
+<figure id="domain-example"><title>An Example Domain.</title>
+<mediaobject>
+<imageobject role="latex"><imagedata fileref="projdoc/imagefiles/domain" width="4in" height="3in" scalefit="1"/></imageobject>
+<imageobject><imagedata fileref="projdoc/imagefiles/domain.png" scale="50" scalefit="1"/></imageobject>
+</mediaobject>
+</figure>
+
+
+<?latex \newpage ?>
+
+<para>
+From the Samba mailing list one can readily identify many common networking issues.
+If you are not clear on the following subjects, then it will do much good to read the 
+sections of this HOWTO that deal with it. These are the most common causes of MS Windows
+networking problems:
+</para>
+
+<itemizedlist>
+	<listitem><para>Basic TCP/IP configuration.</para></listitem>
+	<listitem><para>NetBIOS name resolution.</para></listitem>
+	<listitem><para>Authentication configuration.</para></listitem>
+	<listitem><para>User and group configuration.</para></listitem>
+	<listitem><para>Basic file and directory permission control in UNIX/Linux.</para></listitem>
+	<listitem><para>Understanding how MS Windows clients interoperate in a network
+		environment.</para></listitem>
+</itemizedlist>
+
+<para>
+Do not be put off; on the surface of it MS Windows networking seems so simple that anyone 
+can do it. In fact, it is not a good idea to set up an MS Windows network with
+inadequate training and preparation. But let's get our first indelible principle out of the
+way: <emphasis>It is perfectly okay to make mistakes!</emphasis> In the right place and at
+the right time, mistakes are the essence of learning. It is very much not okay to make
+mistakes that cause loss of productivity and impose an avoidable financial burden on an
+organization.
+</para>
+
+<para>
+Where is the right place to make mistakes? Only out of harms way. If you are going to
+make mistakes, then please do it on a test network, away from users and in such a way as
+to not inflict pain on others. Do your learning on a test network.
+</para>
+
+<sect1>
+<title>Features and Benefits</title>
+
+<para>
+<indexterm><primary>domain security</primary></indexterm>
+<emphasis>What is the key benefit of Microsoft Domain Security?</emphasis>
+</para>
+
+<para>
+In a word, <emphasis>Single Sign On</emphasis>, or SSO for short. To many, this is the Holy
+Grail of MS Windows NT and beyond networking. SSO allows users in a well-designed network
+to log onto any workstation that is a member of the domain that their user account is in
+(or in a domain that has an appropriate trust relationship with the domain they are visiting)
+and they will be able to log onto the network and access resources (shares, files and printers)
+as if they are sitting at their home (personal) workstation. This is a feature of the Domain
+Security protocols.
+</para>
+
+<para>
+<indexterm><primary>SID</primary></indexterm>
+The benefits of Domain Security are available to those sites that deploy a Samba PDC.
+A Domain provides a unique network security identifier (SID). Domain user and group security
+identifiers are comprised of the network SID plus a relative identifier (RID) that is unique to
+the account. User and Group SIDs (the network SID plus the RID) can be used to create Access Control
+Lists (ACLs) attached to network resources to provide organizational access control. UNIX systems
+recognize only local security identifiers.
+</para>
+
+<note><para>
+Network clients of an MS Windows Domain Security Environment must be Domain Members to be
+able to gain access to the advanced features provided. Domain Membership involves more than just
+setting the workgroup name to the Domain name. It requires the creation of a Domain trust account
+for the workstation (called a machine account). Refer to <link linkend="domain-member">Domain Membership</link>
+for more information.
+</para></note>
+
+<para>
+The following functionalities are new to the Samba-3 release:
+</para>
+
+<itemizedlist>
+	<listitem><para>
+	Windows NT4 domain trusts.
+	</para></listitem>
+	
+	<listitem><para>
+	<indexterm><primary>Nexus.exe</primary></indexterm>
+	Adding users via the User Manager for Domains. This can be done on any MS Windows
+	client using the <filename>Nexus.exe</filename> toolkit for Windows 9x/Me, or using
+	the SRVTOOLS.EXE package for MS Windows NT4/200x/XP platforms. These packages are
+	available from Microsoft's Web site.
+	</para></listitem>
+
+	<listitem><para>
+	Introduces replaceable and multiple user account (authentication)
+	backends. In the case where the backend is placed in an LDAP database,
+	Samba-3 confers the benefits of a backend that can be distributed, replicated
+	and is highly scalable.
+	</para></listitem>
+
+	<listitem><para>
+	Implements full Unicode support. This simplifies cross locale internationalization
+	support. It also opens up the use of protocols that Samba-2.2.x had but could not use due
+	to the need to fully support Unicode.
+	</para></listitem>
+</itemizedlist>
+
+<para>
+The following functionalities are not provided by Samba-3:
+</para>
+<itemizedlist>
+	<listitem><para>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>replication</primary></indexterm>
+	SAM replication with Windows NT4 Domain Controllers
+	(i.e., a Samba PDC and a Windows NT BDC or vice versa). This means Samba 
+	cannot operate as a BDC when the PDC is Microsoft-based or 
+	replicate account data to Windows BDCs.
+	</para></listitem>
+	
+	<listitem><para>
+	Acting as a Windows 2000 Domain Controller (i.e., Kerberos and 
+	Active Directory). In point of fact, Samba-3 does have some
+	Active Directory Domain Control ability that is at this time
+	purely experimental that is certain to change as it becomes a
+	fully supported feature some time during the Samba-3 (or later)
+	life cycle. However, Active Directory is more then just SMB &smbmdash;
+	it's also LDAP, Kerberos, DHCP, and other protocols (with proprietary
+	extensions, of course).
+	</para></listitem>
+
+	<listitem><para>
+	The Windows 200x/XP MMC (Computer Management) Console can not be used
+	to manage a Samba-3 server. For this you can use only the MS Windows NT4
+	Domain Server manager and the MS Windows NT4 Domain User Manager. Both are
+	part of the SVRTOOLS.EXE package mentioned later.
+	</para></listitem>
+</itemizedlist>
+
+<para>
+Windows 9x/Me/XP Home clients are not true members of a domain for reasons outlined
+in this chapter. The protocol for support of Windows 9x/Me style network (domain) logons
+is completely different from NT4/Windows 200x type domain logons and has been officially supported
+for some time. These clients use the old LanMan Network Logon facilities that are supported
+in Samba since approximately the Samba-1.9.15 series.
+</para>
+
+<para>
+Samba-3 implements group mapping between Windows NT groups
+and UNIX groups (this is really quite complicated to explain in a short space). This is 
+discussed more fully in <link linkend="groupmapping">Group Mapping &smbmdash; MS Windows and UNIX</link>.
+</para>
+
+<para>
+<indexterm><primary>Machine Trust Accounts</primary></indexterm>
+Samba-3, like an MS Windows NT4 PDC or a Windows 200x Active Directory, needs to store
+user and Machine Trust Account information in a suitable backend data-store. 
+Refer to <link linkend="machine-trust-accounts">MS Windows Workstation/Server Machine Trust Accounts</link>. With Samba-3 there can be multiple
+backends for this. A complete discussion of account database backends can be found in
+<link linkend="passdb">Account Information Databases</link>.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Basics of Domain Control</title>
+
+<para>
+Over the years, public perceptions of what Domain Control really is has taken on an
+almost mystical nature. Before we branch into a brief overview of Domain Control,
+there are three basic types of Domain Controllers.
+</para>
+
+<sect2>
+<title>Domain Controller Types</title>
+
+<itemizedlist>
+	<listitem><para>Primary Domain Controller</para></listitem>
+	<listitem><para>Backup Domain Controller</para></listitem>
+	<listitem><para>ADS Domain Controller</para></listitem>
+</itemizedlist>
+
+<para>
+The <emphasis>Primary Domain Controller</emphasis> or PDC plays an important role in MS 
+Windows NT4. In Windows 200x Domain Control architecture, this role is held by Domain Controllers.
+Folklore dictates that because of its role in the MS Windows
+network, the Domain Controller should be the most powerful and most capable machine in the network.
+As strange as it may seem to say this here, good overall network performance dictates that
+the entire infrastructure needs to be balanced. It is advisable to invest more in Stand-alone
+(Domain Member) servers than in the Domain Controllers.
+</para>
+
+<para>
+<indexterm><primary>SAM</primary></indexterm>
+In the case of MS Windows NT4-style domains, it is the PDC that initiates a new Domain Control database.
+This forms a part of the Windows registry called the Security Account Manager (SAM). It plays a key
+part in NT4-type domain user authentication and in synchronization of the domain authentication
+database with Backup Domain Controllers. 
+</para>
+
+<para>
+With MS Windows 200x Server-based Active Directory domains, one Domain Controller initiates a potential
+hierarchy of Domain Controllers, each with their own area of delegated control. The master domain
+controller has the ability to override any downstream controller, but a down-line controller has
+control only over its down-line. With Samba-3, this functionality can be implemented using an
+LDAP-based user and machine account backend.
+</para>
+
+<para>
+New to Samba-3 is the ability to use a backend database that holds the same type of data as
+the NT4-style SAM database (one of the registry files)<footnote>See also <link linkend="passdb">Account Information Databases</link>.</footnote>.
+</para>
+
+<para>
+The <emphasis>Backup Domain Controller</emphasis> or BDC plays a key role in servicing network
+authentication requests. The BDC is biased to answer logon requests in preference to the PDC.
+On a network segment that has a BDC and a PDC, the BDC will most likely service network
+logon requests. The PDC will answer network logon requests when the BDC is too busy (high load).
+A BDC can be promoted to a PDC. If the PDC is online at the time that a BDC is promoted to
+PDC, the previous PDC is automatically demoted to a BDC. With Samba-3, this is not an automatic
+operation; the PDC and BDC must be manually configured and changes also need to be made.
+</para>
+
+<para>
+With MS Windows NT4, a decision is made at installation to determine what type of machine the server will be.
+It is possible to promote a BDC to a PDC and vice versa. The only way
+to convert a Domain Controller to a Domain Member server or a Stand-alone Server is to
+reinstall it. The install time choices offered are:
+</para>
+
+<itemizedlist>
+	<listitem><para><emphasis>Primary Domain Controller</emphasis> &smbmdash; the one that seeds the domain SAM.</para></listitem>
+	<listitem><para><emphasis>Backup Domain Controller</emphasis> &smbmdash; one that obtains a copy of the domain SAM.</para></listitem>
+	<listitem><para><emphasis>Domain Member Server</emphasis> &smbmdash; one that has no copy of the domain SAM, rather it obtains authentication from a Domain Controller for all access controls.</para></listitem>
+	<listitem><para><emphasis>Stand-alone Server</emphasis> &smbmdash; one that plays no part is SAM synchronization, has its own authentication database and plays no role in Domain Security.</para></listitem>
+</itemizedlist>
+
+<para>
+With MS Windows 2000, the configuration of Domain Control is done after the server has been
+installed. Samba-3 is capable of acting fully as a native member of a Windows 200x server
+Active Directory domain.
+</para>
+
+<para>
+<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+New to Samba-3 is the ability to function fully as an MS Windows NT4-style Domain Controller,
+excluding the SAM replication components. However, please be aware that Samba-3 also supports the
+MS Windows 200x Domain Control protocols.
+</para>
+
+<para>
+At this time any appearance that Samba-3 is capable of acting as an
+<emphasis>Domain Controller</emphasis> in native ADS mode is limited and experimental in nature.
+This functionality should not be used until the Samba Team offers formal support for it.
+At such a time, the documentation will be revised to duly reflect all configuration and
+management requirements. Samba can act as a NT4-style DC in a Windows 2000/XP 
+environment. However, there are certain compromises:
+
+<itemizedlist>
+	<listitem>No machine policy files.</listitem>
+	<listitem>No Group Policy Objects.</listitem>
+	<listitem>No synchronously executed AD logon scripts.</listitem>
+	<listitem>Can't use Active Directory management tools to manage users and machines.</listitem>
+	<listitem>Registry changes tattoo the main registry, while with AD they do not leave permanent changes in effect.</listitem>
+	<listitem>Without AD you cannot perform the function of exporting specific applications to specific users or groups.</listitem>
+</itemizedlist>
+</para>
+
+</sect2>
+
+<sect2>
+<title>Preparing for Domain Control</title>
+
+<para>
+There are two ways that MS Windows machines may interact with each other, with other servers
+and with Domain Controllers: either as <emphasis>Stand-alone</emphasis> systems, more commonly
+called <emphasis>Workgroup</emphasis> members, or as full participants in a security system,
+more commonly called <emphasis>Domain</emphasis> members.
+</para>
+
+<para>
+It should be noted that <emphasis>Workgroup</emphasis> membership involves no special configuration
+other than the machine being configured so the network configuration has a commonly used name
+for its workgroup entry. It is not uncommon for the name WORKGROUP to be used for this. With this
+mode of configuration, there are no Machine Trust Accounts and any concept of membership as such
+is limited to the fact that all machines appear in the network neighborhood to be logically
+grouped together. Again, just to be clear: <emphasis>workgroup mode does not involve security machine 
+accounts</emphasis>.
+</para>
+
+<para>
+Domain Member machines have a machine account in the Domain accounts database. A special procedure
+must be followed on each machine to effect Domain Membership. This procedure, which can be done
+only by the local machine Administrator account, will create the Domain machine account (if it does
+not exist), and then initializes that account. When the client first logs onto the
+Domain it triggers a machine password change.
+</para>
+
+<note><para>
+When Samba is configured as a Domain Controller, secure network operation demands that
+all MS Windows NT4/200x/XP Professional clients should be configured as Domain Members.
+If a machine is not made a member of the Domain, then it will operate like a workgroup
+(Stand-alone) machine. Please refer to <link linkend="domain-member">Domain Membership</link> chapter for
+information regarding Domain Membership.
+</para></note>
+
+<para>
+The following are necessary for configuring Samba-3 as an MS Windows NT4-style PDC for MS Windows
+NT4/200x/XP clients:
+</para>
+
+<itemizedlist>
+	<listitem><para>Configuration of basic TCP/IP and MS Windows networking.</para></listitem>
+	<listitem><para>Correct designation of the Server Role (<smbconfoption><name>security</name><value>user</value></smbconfoption>).</para></listitem>
+	<listitem><para>Consistent configuration of Name Resolution<footnote><para>See <link linkend="NetworkBrowsing">Network Browsing</link>, and 
+		<link linkend="integrate-ms-networks">Integrating MS Windows Networks with Samba</link>.</para></footnote>.</para></listitem>
+	<listitem><para>Domain logons for Windows NT4/200x/XP Professional clients.</para></listitem>
+	<listitem><para>Configuration of Roaming Profiles or explicit configuration to force local profile usage.</para></listitem>
+	<listitem><para>Configuration of network/system policies.</para></listitem>
+	<listitem><para>Adding and managing domain user accounts.</para></listitem>
+	<listitem><para>Configuring MS Windows client machines to become Domain Members.</para></listitem>
+</itemizedlist>
+
+<para>
+The following provisions are required to serve MS Windows 9x/Me clients:
+</para>
+
+<itemizedlist>
+	<listitem><para>Configuration of basic TCP/IP and MS Windows networking.</para></listitem>
+	<listitem><para>Correct designation of the server role (<smbconfoption><name>security</name><value>user</value></smbconfoption>).</para></listitem>
+	<listitem><para>Network Logon Configuration (since Windows 9x/Me/XP Home are not technically domain
+	members, they do not really participate in  the security aspects of Domain logons as such).</para></listitem>
+	<listitem><para>Roaming Profile Configuration.</para></listitem>
+	<listitem><para>Configuration of System Policy handling.</para></listitem>
+	<listitem><para>Installation of the network driver <quote>Client for MS Windows Networks</quote> and configuration
+	to log onto the domain.</para></listitem>
+	<listitem><para>Placing Windows 9x/Me clients in User Level Security &smbmdash; if it is desired to allow
+	all client share access to be controlled according to domain user/group identities.</para></listitem>
+	<listitem><para>Adding and managing domain user accounts.</para></listitem>
+</itemizedlist>
+
+<note><para>
+Roaming Profiles and System/Network policies are advanced network administration topics
+that are covered in the <link linkend="ProfileMgmt">Desktop Profile Management</link> and 
+<link linkend="PolicyMgmt">System and Account Policies</link> chapters of this document. However, these are not
+necessarily specific to a Samba PDC as much as they are related to Windows NT networking concepts.
+</para></note>
+
+<para>
+A Domain Controller is an SMB/CIFS server that:
+</para>
+
+<itemizedlist>
+	<listitem><para>
+	Registers and advertises itself as a Domain Controller (through NetBIOS broadcasts
+	as well as by way of name registrations either by Mailslot Broadcasts over UDP broadcast,
+	to a WINS server over UDP uni-cast, or via DNS and Active Directory).
+	</para></listitem>
+
+	<listitem><para>
+	Provides the NETLOGON service. (This is actually a collection of services that runs over
+	multiple protocols. These include the LanMan Logon service, the Netlogon service,
+	the Local Security Account service, and variations of them.)
+	</para></listitem>
+
+	<listitem><para>
+	Provides a share called NETLOGON.
+	</para></listitem>
+</itemizedlist>
+
+<para>
+It is rather easy to configure Samba to provide these. Each Samba Domain Controller must provide
+the NETLOGON service that Samba calls the <smbconfoption><name>domain logons</name></smbconfoption> functionality
+(after the name of the parameter in the &smb.conf; file). Additionally, one server in a Samba-3
+Domain must advertise itself as the Domain Master Browser<footnote>See <link linkend="NetworkBrowsing">Network Browsing</link>.</footnote>.
+This causes the Primary Domain Controller to claim a domain-specific NetBIOS name that identifies it as a
+Domain Master Browser for its given domain or workgroup. Local master browsers in the same domain or workgroup on
+broadcast-isolated subnets then ask for a complete copy of the browse list for the whole wide area network.
+Browser clients will then contact their Local Master Browser, and will receive the domain-wide browse list,
+instead of just the list for their broadcast-isolated subnet.
+</para>
+
+</sect2>
+</sect1>
+
+<sect1>
+<title>Domain Control &smbmdash; Example Configuration</title>
+
+<para>
+The first step in creating a working Samba PDC is to understand the parameters necessary
+in &smb.conf;. An example &smb.conf; for acting as a PDC can be found in <link linkend="pdc-example">the next example</link>. 
+</para>
+
+<para>
+<smbconfexample id="pdc-example">
+<title>smb.conf for being a PDC</title>
+<smbconfsection>[global]</smbconfsection>
+<smbconfoption><name>netbios name</name><value><replaceable>BELERIAND</replaceable></value></smbconfoption>
+<smbconfoption><name>workgroup</name><value><replaceable>&example.workgroup;</replaceable></value></smbconfoption>
+<smbconfoption><name>passdb backend</name><value>tdbsam</value></smbconfoption>
+<smbconfoption><name>os level</name><value>33</value></smbconfoption>
+<smbconfoption><name>preferred master</name><value>yes</value></smbconfoption>
+<smbconfoption><name>domain master</name><value>yes</value></smbconfoption>
+<smbconfoption><name>local master</name><value>yes</value></smbconfoption>
+<smbconfoption><name>security</name><value>user</value></smbconfoption>
+<smbconfoption><name>domain logons</name><value>yes</value></smbconfoption>
+<smbconfoption><name>logon path</name><value>\\%N\profiles\%u</value></smbconfoption>
+<smbconfoption><name>logon drive</name><value>H:</value></smbconfoption>
+<smbconfoption><name>logon home</name><value>\\homeserver\%u\winprofile</value></smbconfoption>
+<smbconfoption><name>logon script</name><value>logon.cmd</value></smbconfoption>
+
+<smbconfsection>[netlogon]</smbconfsection>
+<smbconfoption><name>path</name><value>/var/lib/samba/netlogon</value></smbconfoption>
+<smbconfoption><name>read only</name><value>yes</value></smbconfoption>
+<smbconfoption><name>write list</name><value><replaceable>ntadmin</replaceable></value></smbconfoption>
+
+<smbconfsection>[profiles]</smbconfsection>
+<smbconfoption><name>path</name><value>/var/lib/samba/profiles</value></smbconfoption>
+<smbconfoption><name>read only</name><value>no</value></smbconfoption>
+<smbconfoption><name>create mask</name><value>0600</value></smbconfoption>
+<smbconfoption><name>directory mask</name><value>0700</value></smbconfoption>
+</smbconfexample>
+</para>
+
+<para>
+The basic options shown in <link linkend="pdc-example">this example</link> are explained as follows:
+</para>
+
+<variablelist>
+	<varlistentry><term>passdb backend </term>
+		<listitem><para>
+		This contains all the user and group account information. Acceptable values for a PDC
+		are: <emphasis>smbpasswd, tdbsam, and ldapsam</emphasis>. The <quote>guest</quote> entry provides
+		default accounts and is included by default, there is no need to add it explicitly.</para>
+
+		<para>
+		Where use of backup Domain Controllers (BDCs) is intended, the only logical choice is
+		to use LDAP so the passdb backend can be distributed. The tdbsam and smbpasswd files
+		cannot effectively be distributed and therefore should not be used.
+		</para></listitem>
+	</varlistentry>
+	<varlistentry><term>Domain Control Parameters </term>
+		<listitem><para>
+		The parameters <emphasis>os level, preferred master, domain master, security, 
+		encrypt passwords, and domain logons</emphasis> play a central role in assuring domain
+		control and network logon support.</para>
+
+		<para>
+		The <emphasis>os level</emphasis> must be set at or above a value of 32. A Domain Controller
+		must be the Domain Master Browser, must be set in <emphasis>user</emphasis> mode security,
+		must support Microsoft-compatible encrypted passwords, and must provide the network logon
+		service (domain logons). Encrypted passwords must be enabled. For more details on how 
+		to do this, refer to <link linkend="passdb">Account Information Databases</link>.
+		</para></listitem>
+	</varlistentry>
+	<varlistentry><term>Environment Parameters </term>
+		<listitem><para>
+		The parameters <emphasis>logon path, logon home, logon drive, and logon script</emphasis> are
+		environment support settings that help to facilitate client logon operations and that help
+		to provide automated control facilities to ease network management overheads. Please refer
+		to the man page information for these parameters.
+		</para></listitem>
+	</varlistentry>
+	<varlistentry><term>NETLOGON Share </term>
+		<listitem><para>
+		The NETLOGON share plays a central role in domain logon and Domain Membership support.
+		This share is provided on all Microsoft Domain Controllers. It is used to provide logon
+		scripts, to store Group Policy files (NTConfig.POL), as well as to locate other common
+		tools that may be needed for logon processing. This is an essential share on a Domain Controller.
+		</para></listitem>
+	</varlistentry>
+	<varlistentry><term>PROFILE Share </term>
+		<listitem><para>
+		This share is used to store user desktop profiles. Each user must have a directory at the root
+		of this share. This directory must be write-enabled for the user and must be globally read-enabled.
+		Samba-3 has a VFS module called <quote>fake_permissions</quote> that may be installed on this share. This will
+		allow a Samba administrator to make the directory read-only to everyone. Of course this is useful
+		only after the profile has been properly created.
+		</para></listitem>
+	</varlistentry>
+</variablelist>
+
+<note><para>
+The above parameters make for a full set of parameters that may define the server's mode
+of operation. The following &smb.conf; parameters are the essentials alone:
+</para>
+
+<para>
+<smbconfblock>
+<smbconfoption><name>netbios name</name><value>BELERIAND</value></smbconfoption>
+<smbconfoption><name>workgroup</name><value>&example.workgroup;</value></smbconfoption>
+<smbconfoption><name>domain logons</name><value>Yes</value></smbconfoption>
+<smbconfoption><name>domain master</name><value>Yes</value></smbconfoption>
+<smbconfoption><name>security</name><value>User</value></smbconfoption>
+</smbconfblock>
+</para>
+
+<para>
+The additional parameters shown in the longer listing above just makes for
+a more complete explanation.
+</para></note>
+
+</sect1>
+
+<sect1>
+<title>Samba ADS Domain Control</title>
+
+<para>
+Samba-3 is not, and cannot act as, an Active Directory Server. It cannot truly function as
+an Active Directory Primary Domain Controller. The protocols for some of the functionality
+of Active Directory Domain Controllers has been partially implemented on an experimental
+only basis. Please do not expect Samba-3 to support these protocols. Do not depend
+on any such functionality either now or in the future. The Samba Team may remove these
+experimental features or may change their behavior. This is mentioned for the benefit of those
+who have discovered secret capabilities in Samba-3 and who have asked when this functionality will be
+completed. The answer is maybe or maybe never!
+</para>
+
+<para>
+To be sure, Samba-3 is designed to provide most of the functionality that Microsoft Windows NT4-style
+Domain Controllers have. Samba-3 does not have all the capabilities of Windows NT4, but it does have
+a number of features that Windows NT4 domain controllers do not have. In short, Samba-3 is not NT4 and it
+is not Windows Server 200x, it is not an Active Directory server. We hope this is plain and simple
+enough for all to understand.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Domain and Network Logon Configuration</title>
+
+<para>
+The subject of Network or Domain Logons is discussed here because it forms
+an integral part of the essential functionality that is provided by a Domain Controller.
+</para>
+
+<sect2>
+<title>Domain Network Logon Service</title>
+
+<para>
+All Domain Controllers must run the netlogon service (<emphasis>domain logons</emphasis>
+in Samba). One Domain Controller must be configured with <smbconfoption><name>domain master</name><value>Yes</value></smbconfoption>
+(the Primary Domain Controller); on all Backup Domain Controllers <smbconfoption><name>domain master</name><value>No</value></smbconfoption>
+must be set.
+</para>
+
+<sect3>
+<title>Example Configuration</title>
+
+<smbconfexample id="PDC-config">
+<title>smb.conf for being a PDC</title>
+<smbconfsection>[global]</smbconfsection>
+<smbconfoption><name>domain logons</name><value>Yes</value></smbconfoption>
+<smbconfoption><name>domain master</name><value>(Yes on PDC, No on BDCs)</value></smbconfoption>
+
+<smbconfsection>[netlogon]</smbconfsection>
+<smbconfoption><name>comment</name><value>Network Logon Service</value></smbconfoption>
+<smbconfoption><name>path</name><value>/var/lib/samba/netlogon</value></smbconfoption>
+<smbconfoption><name>guest ok</name><value>Yes</value></smbconfoption>
+<smbconfoption><name>browseable</name><value>No</value></smbconfoption>
+</smbconfexample>
+
+</sect3>
+<sect3>
+<title>The Special Case of MS Windows XP Home Edition</title>
+
+<para>
+To be completely clear: If you want MS Windows XP Home Edition to integrate with your
+MS Windows NT4 or Active Directory Domain Security, understand it cannot be done.
+The only option is to purchase the upgrade from MS Windows XP Home Edition to
+MS Windows XP Professional.
+</para>
+
+<note><para>
+MS Windows XP Home Edition does not have the ability to join any type of Domain
+Security facility. Unlike MS Windows 9x/Me, MS Windows XP Home Edition also completely
+lacks the ability to log onto a network.
+</para></note>
+
+<para>
+Now that this has been said, please do not ask the mailing list or email any of the
+Samba Team members with your questions asking how to make this work. It can't be done.
+If it can be done, then to do so would violate your software license agreement with
+Microsoft, and we recommend that you do not do that.
+</para>
+
+</sect3>
+
+<sect3>
+<title>The Special Case of Windows 9x/Me</title>
+
+<para>
+A domain and a workgroup are exactly the same in terms of network
+browsing. The difference is that a distributable authentication
+database is associated with a domain, for secure login access to a
+network. Also, different access rights can be granted to users if they
+successfully authenticate against a domain logon server. Samba-3 does this
+now in the same way as MS Windows NT/200x.
+</para>
+
+<para>
+The SMB client logging on to a domain has an expectation that every other
+server in the domain should accept the same authentication information.
+Network browsing functionality of domains and workgroups is identical and
+is explained in this documentation under the browsing discussions.
+It should be noted that browsing is totally orthogonal to logon support.
+</para>
+
+<para>
+Issues related to the single-logon network model are discussed in this
+section. Samba supports domain logons, network logon scripts and user
+profiles for MS Windows for workgroups and MS Windows 9X/ME clients,
+which are the focus of this section.
+</para>
+
+<para>
+When an SMB client in a domain wishes to logon, it broadcasts requests for a
+logon server. The first one to reply gets the job, and validates its
+password using whatever mechanism the Samba administrator has installed.
+It is possible (but ill advised ) to create a domain where the user
+database is not shared between servers, i.e., they are effectively workgroup
+servers advertising themselves as participating in a domain. This
+demonstrates how authentication is quite different from but closely
+involved with domains.
+</para>
+
+<para>
+Using these features you can make your clients verify their logon via
+the Samba server; make clients run a batch file when they logon to
+the network and download their preferences, desktop and start menu.
+</para>
+
+<para><emphasis>
+MS Windows XP Home edition is not able to join a domain and does not permit
+the use of domain logons.
+</emphasis></para>
+
+<para>
+Before launching into the configuration instructions, it is 
+worthwhile to look at how a Windows 9x/Me client performs a logon:
+</para>
+
+<orderedlist>
+<listitem>
+	<para>
+	The client broadcasts (to the IP broadcast address of the subnet it is in)
+	a NetLogon request. This is sent to the NetBIOS name DOMAIN&lt;#1c&gt; at the
+	NetBIOS layer. The client chooses the first response it receives, which
+	contains the NetBIOS name of the logon server to use in the format of 
+	<filename>\\SERVER</filename>.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	The client connects to that server, logs on (does an SMBsessetupX) and
+	then connects to the IPC$ share (using an SMBtconX).
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	The client does a NetWkstaUserLogon request, which retrieves the name
+	of the user's logon script. 
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	The client then connects to the NetLogon share and searches for said script.	
+	If it is found and can be read, it is retrieved and executed by the client.
+	After this, the client disconnects from the NetLogon share.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	The client sends a NetUserGetInfo request to the server to retrieve
+	the user's home share, which is used to search for profiles. Since the
+	response to the NetUserGetInfo request does not contain much more than	
+	the user's home share, profiles for Windows 9x clients must reside in the user
+	home directory.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	The client connects to the user's home share and searches for the 
+	user's profile. As it turns out, you can specify the user's home share as
+	a share name and path. For example, <filename>\\server\fred\.winprofile</filename>.
+	If the profiles are found, they are implemented.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	The client then disconnects from the user's home share and reconnects to
+	the NetLogon share and looks for <filename>CONFIG.POL</filename>, the policies file. If this is
+	found, it is read and implemented.
+	</para>
+</listitem>
+</orderedlist>
+
+<para>
+The main difference between a PDC and a Windows 9x/Me logon server configuration is:
+</para>
+
+<itemizedlist>
+<listitem><para>
+	Password encryption is not required for a Windows 9x/Me logon server. But note
+	that beginning with MS Windows 98 the default setting is that plain-text
+	password support is disabled. It can be re-enabled with the registry
+	changes that are documented in <link linkend="PolicyMgmt">System and Account Policies</link>.
+	</para></listitem>
+
+	<listitem><para>
+	Windows 9x/Me clients do not require and do not use Machine Trust Accounts.
+	</para></listitem>
+</itemizedlist>
+
+<para>
+A Samba PDC will act as a Windows 9x/Me logon server; after all, it does provide the
+network logon services that MS Windows 9x/Me expect to find.
+</para>
+
+<note><para>
+Use of plain-text passwords is strongly discouraged. Where used they are easily detected
+using a sniffer tool to examine network traffic.
+</para></note>
+
+</sect3>
+</sect2>
+
+<sect2>
+<title>Security Mode and Master Browsers</title>
+
+<para>
+There are a few comments to make in order to tie up some loose ends. There has been
+much debate over the issue of whether it is okay to configure Samba as a Domain
+Controller in security modes other than user. The only security mode that will
+not work due to technical reasons is share-mode security. Domain and server mode
+security are really just a variation on SMB User Level Security.
+</para>
+
+<para>
+Actually, this issue is also closely tied to the debate on whether 
+Samba must be the Domain Master Browser for its workgroup
+when operating as a DC. While it may technically be possible
+to configure a server as such (after all, browsing and domain logons
+are two distinctly different functions), it is not a good idea to do
+so. You should remember that the DC must register the DOMAIN&lt;#1b&gt; NetBIOS 
+name. This is the name used by Windows clients to locate the DC.
+Windows clients do not distinguish between the DC and the DMB.
+A DMB is a Domain Master Browser &smbmdash; see <link linkend="DMB">Configuring WORKGROUP Browsing</link> section.
+For this reason, it is wise to configure the Samba DC as the DMB.
+</para>
+
+<para>
+Now back to the issue of configuring a Samba DC to use a mode other than
+<smbconfoption><name>security</name><value>user</value></smbconfoption>. If a Samba host is
+configured to use another SMB server or DC in order to validate user connection requests,
+it is a fact that some other machine on the network (the <smbconfoption><name>password server</name></smbconfoption>)
+knows more about the user than the Samba host. About 99% of the time, this other host is
+a Domain Controller. Now to operate in domain mode security, the <smbconfoption><name>workgroup</name></smbconfoption>
+parameter must be set to the name of the Windows NT domain (which already has a Domain Controller).
+If the domain does not already have a Domain Controller, you do not yet have a Domain.
+</para>
+
+<para>
+Configuring a Samba box as a DC for a domain that already by definition has a
+PDC is asking for trouble. Therefore, you should always configure the Samba DC
+to be the DMB for its domain and set <smbconfoption><name>security</name><value>user</value></smbconfoption>.
+This is the only officially supported mode of operation.
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+<sect2>
+	<title><quote>$</quote> Cannot Be Included in Machine Name</title>
+<para>
+A machine account, typically stored in <filename>/etc/passwd</filename>, takes the form of the machine
+name with a <quote>$</quote> appended. FreeBSD (and other BSD systems) will not create a user with a
+<quote>$</quote> in the name.
+</para>
+
+<para>
+The problem is only in the program used to make the entry. Once made, it works perfectly.
+Create a user without the <quote>$</quote>. Then use <command>vipw</command> to edit the entry, adding
+the <quote>$</quote>. Or create the whole entry with vipw if you like; make sure you use a unique user login ID.
+</para>
+
+<para><note>The machine account must have the exact name that the workstation has.</note></para>
+
+<note><para>
+The UNIX tool <command>vipw</command> is a common tool for directly editing the <filename>/etc/passwd</filename> file.
+</para></note>
+
+</sect2>
+
+<sect2>
+<title>Joining Domain Fails Because of Existing Machine Account</title>
+		
+<para>
+<quote>I get told, `You already have a connection to the Domain....' or `Cannot join domain, the
+credentials supplied conflict with an existing set...' when creating a Machine Trust Account.</quote>
+</para>
+
+<para>
+This happens if you try to create a Machine Trust Account from the machine itself and already have a
+connection (e.g., mapped drive) to a share (or IPC$) on the Samba PDC. The following command
+will remove all network drive connections:
+<screen>
+&dosprompt;<userinput>net use * /d</userinput>
+</screen>
+</para>
+
+<para>
+Further, if the machine is already a <quote>member of a workgroup</quote> that 
+is the same name as the domain you are joining (bad idea) you will 
+get this message. Change the workgroup name to something else, it 
+does not matter what, reboot, and try again.
+</para>
+</sect2>
+
+<sect2>
+<title>The System Cannot Log You On (C000019B)</title>
+
+<para><quote>I joined the domain successfully but after upgrading 
+to a newer version of the Samba code I get the message, <errorname>`The system 
+cannot log you on (C000019B), Please try again or consult your 
+system administrator</errorname> when attempting to logon.'</quote>
+</para>
+
+<para>
+<indexterm><primary>SID</primary></indexterm>
+This occurs when the domain SID stored in the secrets.tdb database
+is changed. The most common cause of a change in domain SID is when
+the domain name and/or the server name (NetBIOS name) is changed.
+The only way to correct the problem is to restore the original domain 
+SID or remove the domain client from the domain and rejoin. The domain
+SID may be reset using either the net or rpcclient utilities.
+</para>
+
+<para>
+To reset or change the domain SID you can use the net command as follows:
+
+<screen>
+&rootprompt;<userinput>net getlocalsid 'OLDNAME'</userinput>
+&rootprompt;<userinput>net setlocalsid 'SID'</userinput>
+</screen>
+</para>
+
+<para>
+Workstation Machine Trust Accounts work only with the Domain (or network) SID. If this SID changes
+Domain Members (workstations) will not be able to log onto the domain. The original Domain SID
+can be recovered from the secrets.tdb file. The alternative is to visit each workstation to re-join
+it to the domain.
+</para>
+
+</sect2>
+
+<sect2>
+<title>The Machine Trust Account Is Not Accessible</title>
+
+<para>
+<quote>When I try to join the domain I get the message, <errorname>`The machine account 
+for this computer either does not exist or is not accessible'</errorname>. What's 
+wrong?</quote>
+</para>
+
+<para>
+This problem is caused by the PDC not having a suitable Machine Trust Account. 
+If you are using the <smbconfoption><name>add machine script</name></smbconfoption> method to create 
+accounts then this would indicate that it has not worked. Ensure the domain 
+admin user system is working.
+</para>
+
+<para>
+Alternately, if you are creating account entries manually then they 
+have not been created correctly. Make sure that you have the entry 
+correct for the Machine Trust Account in <filename>smbpasswd</filename> file on the Samba PDC. 
+If you added the account using an editor rather than using the smbpasswd 
+utility, make sure that the account name is the machine NetBIOS name 
+with a <quote>$</quote> appended to it (i.e., computer_name$). There must be an entry 
+in both /etc/passwd and the smbpasswd file.
+</para>
+
+<para>
+Some people have also reported that inconsistent subnet masks between the Samba server and the NT 
+client can cause this problem.  Make sure that these are consistent for both client and server.
+</para>
+</sect2>
+
+<sect2>
+<title>Account Disabled</title>
+
+<para><quote>When I attempt to login to a Samba Domain from a NT4/W200x workstation,
+I get a message about my account being disabled.</quote></para>
+
+<para>
+Enable the user accounts with <userinput>smbpasswd -e <replaceable>username</replaceable>
+</userinput>. This is normally done as an account is created.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Domain Controller Unavailable</title>
+		
+<para><quote>Until a few minutes after Samba has started, clients get the error `Domain Controller Unavailable'</quote></para>
+
+<para>
+A Domain Controller has to announce its role on the network. This usually takes a while. Be patient for up to fifteen minutes,
+then try again.
+</para>
+</sect2>
+
+<sect2>
+<title>Cannot Log onto Domain Member Workstation After Joining Domain</title>
+
+<para>
+<indexterm><primary>schannel</primary></indexterm>
+<indexterm><primary>signing</primary></indexterm>
+After successfully joining the domain, user logons fail with one of two messages: one to the
+effect that the Domain Controller cannot be found; the other claims that the account does not
+exist in the domain or that the password is incorrect. This may be due to incompatible
+settings between the Windows client and the Samba-3 server for <emphasis>schannel</emphasis>
+(secure channel) settings or <emphasis>smb signing</emphasis> settings. Check your Samba
+settings for <emphasis> client schannel, server schannel, client signing, server signing</emphasis>
+by executing:
+<screen>
+<command>testparm -v | more</command> and looking for the value of these parameters.
+</screen>
+</para>
+
+<para>
+Also use the Microsoft Management Console &smbmdash; Local Security Settings. This tool is available from the
+Control Panel. The Policy settings are found in the Local Policies/Security Options area and are prefixed by
+<emphasis>Secure Channel: ..., and Digitally sign ....</emphasis>.
+</para>
+
+<para>
+It is important that these be set consistently with the Samba-3 server settings.
+</para>
+
+</sect2>
+
+</sect1>
+</chapter>