Moving docs tree to docs-xml to make room for generated docs in the release tarball.

(This used to be commit 9f672c26d63955f613088489c6efbdc08b5b2d14)

1 files changed, 862 insertions, 0 deletions

diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-BDC.xml b/docs-xml/Samba3-HOWTO/TOSHARG-BDC.xml
new file mode 100644
index 00000000000..35fdd9ee572
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-BDC.xml
@@ -0,0 +1,862 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<chapter id="samba-bdc">
+
+<chapterinfo>
+	&author.jht;
+	&author.vl;
+	<author>&person.gd;<contrib>LDAP updates</contrib></author>
+</chapterinfo>
+
+<title>Backup Domain Control</title>
+
+<para>
+Before you continue reading this section, please make sure that you are comfortable
+with configuring a Samba domain controller as described in <link linkend="samba-pdc">Domain Control</link>.
+</para>
+
+<sect1>
+<title>Features and Benefits</title>
+
+<para>
+This is one of the most difficult chapters to summarize. It does not matter what we say here, for someone will
+still draw conclusions and/or approach the Samba Team with expectations that are either not yet capable of
+being delivered or that can be achieved far more effectively using a totally different approach. In the event
+that you should have a persistent concern that is not addressed in this book, please email <ulink
+url="mailto:jht@samba.org">John H. Terpstra</ulink> clearly setting out your requirements and/or question, and
+we will do our best to provide a solution.
+</para>
+
+<para>
+<indexterm><primary>SAM backend</primary><secondary>LDAP</secondary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>LDAP</primary><secondary>slave</secondary></indexterm>
+<indexterm><primary>scalability</primary></indexterm>
+Samba-3 can act as a Backup Domain Controller (BDC) to another Samba Primary Domain Controller (PDC). A
+Samba-3 PDC can operate with an LDAP account backend. The LDAP backend can be either a common master LDAP
+server or a slave server. The use of a slave LDAP server has the benefit that when the master is down, clients
+may still be able to log onto the network.  This effectively gives Samba a high degree of scalability and is
+an effective solution for large organizations. If you use an LDAP slave server for a PDC, you will need to
+ensure the master's continued availability &smbmdash; if the slave finds its master down at the wrong time,
+you will have stability and operational problems.
+</para>
+
+<para>
+<indexterm><primary>two-way</primary><secondary>propagation</secondary></indexterm>
+<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+<indexterm><primary>non-LDAP</primary><secondary>backend</secondary></indexterm>
+<indexterm><primary>propagate</primary></indexterm>
+While it is possible to run a Samba-3 BDC with a non-LDAP backend, that backend must allow some form of
+"two-way" propagation of changes from the BDC to the master.  At this time only LDAP delivers the capability
+to propagate identity database changes from the BDC to the PDC. The BDC can use a slave LDAP server, while it
+is preferable for the PDC to use as its primary an LDAP master server.
+</para>
+
+<para>
+<indexterm><primary>non-LDAP</primary><secondary>backend</secondary></indexterm>
+<indexterm><primary>SAM backend</primary><secondary>non-LDAP</secondary></indexterm>
+<indexterm><primary>domain</primary><secondary>member</secondary><tertiary>server</tertiary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>trust account password</primary></indexterm>
+<indexterm><primary>domain trust</primary></indexterm>
+The use of a non-LDAP backend SAM database is particularly problematic because domain member
+servers and workstations periodically change the Machine Trust Account password. The new
+password is then stored only locally. This means that in the absence of a centrally stored
+accounts database (such as that provided with an LDAP-based solution) if Samba-3 is running
+as a BDC, the BDC instance of the domain member trust account password will not reach the
+PDC (master) copy of the SAM. If the PDC SAM is then replicated to BDCs, this results in 
+overwriting the SAM that contains the updated (changed) trust account password with resulting
+breakage of the domain trust.
+</para>
+
+<para>
+<indexterm><primary>net</primary><secondary>rpc</secondary></indexterm>
+<indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm>
+<indexterm><primary>SAM backend</primary><secondary>tdbsam</secondary></indexterm>
+<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+Considering the number of comments and questions raised concerning how to configure a BDC,
+let's consider each possible option and look at the pros and cons for each possible solution.
+<link linkend="pdc-bdc-table">The Domain Backend Account Distribution Options table below</link> lists 
+possible design configurations for a PDC/BDC infrastructure.
+</para>
+
+<table frame="all" id="pdc-bdc-table"><title>Domain Backend Account Distribution Options</title>
+<tgroup cols="3">
+        <colspec align="center" colwidth="1*"/>
+        <colspec align="center" colwidth="1*"/>
+        <colspec align="left" colwidth="3*"/>
+
+        <thead>
+        <row><entry>PDC Backend</entry><entry>BDC Backend</entry><entry>Notes/Discussion</entry></row>
+        </thead>
+        <tbody>
+        <row>
+        <entry><para>Master LDAP Server</para></entry>
+        <entry><para>Slave LDAP Server</para></entry>
+        <entry><para>The optimal solution that provides high integrity. The SAM will be
+		replicated to a common master LDAP server.</para></entry>
+        </row>
+        <row>
+        <entry><para>Single Central LDAP Server</para></entry>
+        <entry><para>Single Central LDAP Server</para></entry>
+	<entry><para>
+	A workable solution without failover ability. This is a usable solution, but not optimal. 
+	</para></entry>
+        </row>
+        <row>
+        <entry><para>tdbsam</para></entry>
+        <entry><para>tdbsam + <command>net rpc vampire</command></para></entry>
+        <entry><para>
+	Does not work with Samba-3.0; Samba does not implement the
+        server-side protocols required.
+	</para></entry>
+        </row>
+        <row>
+        <entry><para>tdbsam</para></entry>
+        <entry><para>tdbsam + <command>rsync</command></para></entry>
+        <entry><para>
+	Do not use this configuration.
+	Does not work because the TDB files are live and data may not
+        have been flushed to disk.  Furthermore, this will cause
+        domain trust breakdown.
+	</para></entry>
+        </row>
+        <row>
+        <entry><para>smbpasswd file</para></entry>
+        <entry><para>smbpasswd file</para></entry>
+        <entry><para>
+	Do not use this configuration.
+	Not an elegant solution due to the delays in synchronization
+        and also suffers
+        from the issue of domain trust breakdown.
+	</para></entry>
+        </row>
+        </tbody>
+</tgroup>
+</table>
+
+</sect1>
+
+<sect1>
+<title>Essential Background Information</title>
+
+<para>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>logon requests</primary></indexterm>
+<indexterm><primary>LanMan</primary></indexterm>
+<indexterm><primary>Netlogon</primary></indexterm>
+A domain controller is a machine that is able to answer logon requests from network
+workstations. Microsoft LanManager and IBM LanServer were two early products that
+provided this capability. The technology has become known as the LanMan Netlogon service.
+</para>
+
+<para>
+<indexterm>network<primary></primary><secondary>logon</secondary><tertiary>service</tertiary></indexterm>
+<indexterm><primary>Windows NT3.10</primary></indexterm>
+When MS Windows NT3.10 was first released, it supported a new style of Domain Control
+and with it a new form of the network logon service that has extended functionality.
+This service became known as the NT NetLogon Service. The nature of this service has
+changed with the evolution of MS Windows NT and today provides a complex array of
+services that are implemented over an intricate spectrum of technologies.
+</para>
+
+<sect2>
+<title>MS Windows NT4-style Domain Control</title>
+
+<para>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>authentication server</primary></indexterm>
+<indexterm><primary>username</primary></indexterm>
+<indexterm><primary>password</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>Security Account Manager</primary><see>SAM</see></indexterm>
+<indexterm><primary>domain control database</primary><see>SAM</see></indexterm>
+Whenever a user logs into a Windows NT4/200x/XP Professional workstation,
+the workstation connects to a domain controller (authentication server) to validate that
+the username and password the user entered are valid. If the information entered
+does not match account information that has been stored in the domain
+control database (the SAM, or Security Account Manager database), a set of error
+codes is returned to the workstation that has made the authentication request.
+</para>
+
+<para>
+<indexterm><primary>account information</primary></indexterm>
+<indexterm><primary>machine accounts database</primary></indexterm>
+<indexterm><primary>profile</primary></indexterm>
+<indexterm><primary>network access profile</primary></indexterm>
+<indexterm><primary>desktop profile</primary></indexterm>
+When the username/password pair has been validated, the domain controller
+(authentication server) will respond with full enumeration of the account information
+that has been stored regarding that user in the user and machine accounts database
+for that domain. This information contains a complete network access profile for
+the user but excludes any information that is particular to the user's desktop profile,
+or for that matter it excludes all desktop profiles for groups that the user may
+belong to. It does include password time limits, password uniqueness controls,
+network access time limits, account validity information, machine names from which the
+user may access the network, and much more. All this information was stored in the SAM
+in all versions of MS Windows NT (3.10, 3.50, 3.51, 4.0).
+</para>
+
+<para>
+<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+<indexterm><primary>%SystemRoot%\System32\config</primary></indexterm>
+<indexterm><primary>C:\WinNT\System32\config</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+The account information (user and machine) on domain controllers is stored in two files,
+one containing the security information and the other the SAM. These are stored in files
+by the same name in the <filename>%SystemRoot%\System32\config</filename> directory. 
+This normally translates to the path <filename>C:\WinNT\System32\config</filename>. These
+are the files that are involved in replication of the SAM database where BDCs are present
+on the network.
+</para>
+
+<para>
+There are two situations in which it is desirable to install BDCs:
+</para>
+
+<itemizedlist>
+	<listitem><para>
+	<indexterm><primary>PDC</primary></indexterm>
+	<indexterm><primary>BDC</primary></indexterm>
+	On the local network that the PDC is on, if there are many
+	workstations and/or where the PDC is generally very busy. In this case the BDCs
+	will pick up network logon requests and help to add robustness to network services.
+	</para></listitem>
+
+	<listitem><para>
+	<indexterm><primary>network</primary><secondary>wide-area</secondary></indexterm>
+	At each remote site, to reduce wide-area network traffic and to add stability to
+	remote network operations. The design of the network, and the strategic placement of
+	BDCs, together with an implementation that localizes as much of network to client
+	interchange as possible, will help to minimize wide-area network bandwidth needs
+	(and thus costs).
+	</para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>user account database</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>trigger</primary></indexterm>
+The interoperation of a PDC and its BDCs in a true Windows NT4 environment is worth
+mentioning here. The PDC contains the master copy of the SAM. In the event that an
+administrator makes a change to the user account database while physically present
+on the local network that has the PDC, the change will likely be made directly to
+the PDC instance of the master copy of the SAM. In the event that this update may
+be performed in a branch office, the change will likely be stored in a delta file
+on the local BDC. The BDC will then send a trigger to the PDC to commence the process
+of SAM synchronization. The PDC will then request the delta from the BDC and apply
+it to the master SAM. The PDC will then contact all the BDCs in the domain and
+trigger them to obtain the update and then apply that to their own copy of the SAM.
+</para>
+
+<para>
+<indexterm><primary>SAM</primary><secondary>replication</secondary></indexterm>
+<indexterm><primary>SAM</primary><secondary>delta file</secondary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+Samba-3 cannot participate in true SAM replication and is therefore not able to
+employ precisely the same protocols used by MS Windows NT4. A Samba-3 BDC will
+not create SAM update delta files. It will not interoperate with a PDC (NT4 or Samba)
+to synchronize the SAM from delta files that are held by BDCs.
+</para>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+Samba-3 cannot function as a BDC to an MS Windows NT4 PDC, and Samba-3 cannot
+function correctly as a PDC to an MS Windows NT4 BDC. Both Samba-3 and MS Windows
+NT4 can function as a BDC to its own type of PDC.
+</para>
+
+<para>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>domain security</primary></indexterm>
+The BDC is said to hold a <emphasis>read-only</emphasis> of the SAM from which
+it is able to process network logon requests and authenticate users. The BDC can
+continue to provide this service, particularly while, for example, the wide-area
+network link to the PDC is down. A BDC plays a very important role in both the
+maintenance of domain security as well as in network integrity.
+</para>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>promoted</primary></indexterm>
+<indexterm><primary>demoted</primary></indexterm>
+<indexterm><primary>reconfiguration</primary></indexterm>
+In the event that the NT4 PDC should need to be taken out of service, or if it dies, one of the NT4 BDCs can
+be promoted to a PDC. If this happens while the original NT4 PDC is online, it is automatically demoted to an
+NT4 BDC. This is an important aspect of domain controller management. The tool that is used to effect a
+promotion or a demotion is the Server Manager for Domains. It should be noted that Samba-3 BDCs cannot be
+promoted in this manner because reconfiguration of Samba requires changes to the &smb.conf; file. It is easy
+enough to manuall change the &smb.conf; file and then restart relevant Samba network services.
+</para>
+
+<sect3>
+<title>Example PDC Configuration</title>
+
+<para>
+<indexterm><primary>domain logon</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+Beginning with Version 2.2, Samba officially supports domain logons for all current Windows clients, including
+Windows NT4, 2003, and XP Professional. For Samba to be enabled as a PDC, some parameters in the
+<smbconfsection name="[global]"/> section of the &smb.conf; have to be set.  Refer to <link
+linkend="minimalPDC">the Minimal smb.conf for a PDC in Use with a BDC &smbmdash; LDAP Server on PDC
+section</link> for an example of the minimum required settings.
+</para>
+
+<example id="minimalPDC">
+<title>Minimal smb.conf for a PDC in Use with a BDC &smbmdash; LDAP Server on PDC</title>
+<smbconfblock>
+<smbconfoption name="workgroup">&example.workgroup;</smbconfoption>
+<smbconfoption name="passdb backend">ldapsam://localhost:389</smbconfoption>
+<smbconfoption name="domain master">yes</smbconfoption>
+<smbconfoption name="domain logons">yes</smbconfoption>
+<smbconfoption name="ldap suffix">dc=quenya,dc=org</smbconfoption>
+<smbconfoption name="ldap user suffix">ou=Users</smbconfoption>
+<smbconfoption name="ldap group suffix">ou=Groups</smbconfoption>
+<smbconfoption name="ldap machine suffix">ou=Computers</smbconfoption>
+<smbconfoption name="ldap idmap suffix">ou=Idmap</smbconfoption>
+<smbconfoption name="ldap admin dn">cn=sambadmin,dc=quenya,dc=org</smbconfoption>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>profile path</primary></indexterm>
+<indexterm><primary>home drive</primary></indexterm>
+Several other things like a <smbconfsection name="[homes]"/> and a <smbconfsection name="[netlogon]"/> share
+also need to be set along with settings for the profile path, the user's home drive, and so on. This is not
+covered in this chapter; for more information please refer to <link linkend="samba-pdc">Domain Control</link>.
+Refer to <link linkend="samba-pdc">the Domain Control chapter</link> for specific recommendations for PDC
+configuration. Alternately, fully documented working example network configurations using OpenLDAP and Samba
+as available in the <ulink url="http://www.samba.org/samba/docs/Samba3-ByExample">book</ulink> <quote>Samba-3
+by Example</quote> that may be obtained from local and on-line book stores.
+</para>
+
+</sect3>
+</sect2>
+
+<sect2>
+<title>LDAP Configuration Notes</title>
+
+<para>
+<indexterm><primary>LDAP</primary><secondary>master</secondary></indexterm>
+<indexterm><primary>LDAP</primary><secondary>slave</secondary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+When configuring a master and a slave LDAP server, it is advisable to use the master LDAP server
+for the PDC and slave LDAP servers for the BDCs. It is not essential to use slave LDAP servers; however,
+many administrators will want to do so in order to provide redundant services. Of course, one or more BDCs
+may use any slave LDAP server. Then again, it is entirely possible to use a single LDAP server for the
+entire network.
+</para>
+
+<para>
+<indexterm><primary>LDAP</primary><secondary>master</secondary></indexterm>
+<indexterm><primary>LDAP</primary><secondary>server</secondary></indexterm>
+<indexterm><primary>CN</primary></indexterm>
+<indexterm><primary>DN</primary></indexterm>
+<indexterm><primary>RFC2830</primary></indexterm>
+When configuring a master LDAP server that will have slave LDAP servers, do not forget to configure this in
+the <filename>/etc/openldap/slapd.conf</filename> file. It must be noted that the DN of a server certificate
+must use the CN attribute to name the server, and the CN must carry the servers' fully qualified domain name.
+Additional alias names and wildcards may be present in the subjectAltName certificate extension. More details
+on server certificate names are in RFC2830.
+</para>
+
+<para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>transport layer security</primary><see>TLS</see></indexterm>
+<indexterm><primary>/etc/ssl/certs/slapd.pem</primary></indexterm>
+<indexterm><primary>slapd.pem</primary></indexterm>
+<indexterm><primary>Red Hat Linux</primary></indexterm>
+It does not really fit within the scope of this document, but a working LDAP installation is basic to
+LDAP-enabled Samba operation. When using an OpenLDAP server with Transport Layer Security (TLS), the machine
+name in <filename>/etc/ssl/certs/slapd.pem</filename> must be the same as in
+<filename>/etc/openldap/sldap.conf</filename>. The Red Hat Linux startup script creates the
+<filename>slapd.pem</filename> file with hostname <quote>localhost.localdomain.</quote> It is impossible to
+access this LDAP server from a slave LDAP server (i.e., a Samba BDC) unless the certificate is re-created with
+a correct hostname.
+</para>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>machine account</primary></indexterm>
+<indexterm><primary>credentials</primary></indexterm>
+<indexterm><primary>replication</primary></indexterm>
+<indexterm><primary>duplicate</primary></indexterm>
+Do not install a Samba PDC so that is uses an LDAP slave server. Joining client machines to the domain
+will fail in this configuration because the change to the machine account in the LDAP tree must take place on
+the master LDAP server. This is not replicated rapidly enough to the slave server that the PDC queries. It
+therefore gives an error message on the client machine about not being able to set up account credentials. The
+machine account is created on the LDAP server, but the password fields will be empty.  Unfortunately, some
+sites are unable to avoid such configurations, and these sites should review the <smbconfoption name="ldap
+replication sleep"/> parameter, intended to slow down Samba sufficiently for the replication to catch up.
+This is a kludge, and one that the administrator must manually duplicate in any scripts (such as the
+<smbconfoption name="add machine script"/>) that they use.
+</para>
+
+<para>
+Possible PDC/BDC plus LDAP configurations include:
+</para>
+
+<itemizedlist>
+	<listitem><para>
+	PDC+BDC -> One Central LDAP Server.
+	</para></listitem>
+	<listitem><para>
+	PDC -> LDAP master server, BDC -> LDAP slave server.
+	</para></listitem>
+	<listitem><para>
+	PDC -> LDAP master, with secondary slave LDAP server.
+	</para><para>
+	BDC -> LDAP master, with secondary slave LDAP server.
+	</para></listitem>
+	<listitem><para>
+	PDC -> LDAP master, with secondary slave LDAP server.
+	</para><para>
+	BDC -> LDAP slave server, with secondary master LDAP server.
+	</para></listitem>
+</itemizedlist>
+
+<para>
+In order to have a fallback configuration (secondary) LDAP server, you would specify
+the secondary LDAP server in the &smb.conf; file as shown in <link linkend="mulitldapcfg">the Multiple LDAP
+Servers in &smb.conf; example</link>.
+</para>
+
+<example id="mulitldapcfg">
+<title>Multiple LDAP Servers in &smb.conf;</title>
+<smbconfblock>
+<smbconfoption name="passdb backend">ldapsam:"ldap://master.quenya.org ldap://slave.quenya.org"</smbconfoption>
+</smbconfblock>
+</example>
+
+</sect2>
+
+<sect2>
+<title>Active Directory Domain Control</title>
+
+<para>
+<indexterm><primary>MS Windows 2000</primary></indexterm>
+<indexterm><primary>Active Directory</primary></indexterm>
+<indexterm><primary>directory</primary></indexterm>
+<indexterm><primary>replicated</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+As of the release of MS Windows 2000 and Active Directory, this information is now stored
+in a directory that can be replicated and for which partial or full administrative control
+can be delegated. Samba-3 is not able to be a domain controller within an Active Directory
+tree, and it cannot be an Active Directory server. This means that Samba-3 also cannot
+act as a BDC to an Active Directory domain controller.
+</para>
+
+</sect2>
+
+<sect2>
+<title>What Qualifies a Domain Controller on the Network?</title>
+
+<para>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+Every machine that is a domain controller for the domain MIDEARTH has to register the NetBIOS
+group name MIDEARTH&lt;1C&gt; with the WINS server and/or by broadcast on the local network.
+The PDC also registers the unique NetBIOS name MIDEARTH&lt;1B&gt; with the WINS server.
+The name type &lt;1B&gt; name is normally reserved for the Domain Master Browser (DMB), a role
+that has nothing to do with anything related to authentication, but the Microsoft domain
+implementation requires the DMB to be on the same machine as the PDC.
+</para>
+
+<para>
+<indexterm><primary>broadcast</primary></indexterm>
+<indexterm><primary>name registration</primary></indexterm>
+<indexterm><primary>SMB/CIFS</primary></indexterm>
+Where a WINS server is not used, broadcast name registrations alone must suffice. Refer to
+<link linkend="NetworkBrowsing">Network Browsing</link>,<link linkend="netdiscuss">Discussion</link>
+for more information regarding TCP/IP network protocols and how SMB/CIFS names are handled.
+</para>
+
+</sect2>
+
+<sect2>
+<title>How Does a Workstation find its Domain Controller?</title>
+
+<para>
+<indexterm><primary>locate domain controller</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+There are two different mechanisms to locate a domain controller: one method is used when
+NetBIOS over TCP/IP is enabled and the other when it has been disabled in the TCP/IP
+network configuration.
+</para>
+
+<para>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>broadcast messaging</primary></indexterm>
+Where NetBIOS over TCP/IP is disabled, all name resolution involves the use of DNS, broadcast
+messaging over UDP, as well as Active Directory communication technologies. In this type of
+environment all machines require appropriate DNS entries. More information may be found in
+<link linkend="adsdnstech">DNS and Active Directory</link>.
+</para>
+
+<sect3>
+<title>NetBIOS Over TCP/IP Enabled</title>
+<para>
+<indexterm><primary>Windows NT4/200x/XP</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>logon requests</primary></indexterm>
+<indexterm><primary>credentials validation</primary></indexterm>
+An MS Windows NT4/200x/XP Professional workstation in the domain MIDEARTH that wants a
+local user to be authenticated has to find the domain controller for MIDEARTH. It does this
+by doing a NetBIOS name query for the group name MIDEARTH&lt;1C&gt;. It assumes that each
+of the machines it gets back from the queries is a domain controller and can answer logon
+requests. To not open security holes, both the workstation and the selected domain controller
+authenticate each other. After that the workstation sends the user's credentials (name and
+password) to the local domain controller for validation.
+</para>
+
+</sect3>
+
+<sect3>
+<title>NetBIOS Over TCP/IP Disabled</title>
+
+<para>
+<indexterm><primary>realm</primary></indexterm>
+<indexterm><primary>logon authentication</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>_ldap._tcp.pdc._msdcs.quenya.org</primary></indexterm>
+An MS Windows NT4/200x/XP Professional workstation in the realm <constant>quenya.org</constant>
+that has a need to affect user logon authentication will locate the domain controller by 
+re-querying DNS servers for the <constant>_ldap._tcp.pdc._msdcs.quenya.org</constant> record.
+More information regarding this subject may be found in <link linkend="adsdnstech">DNS and Active Directory</link>.
+</para>
+
+</sect3>
+</sect2>
+</sect1>
+
+<sect1>
+<title>Backup Domain Controller Configuration</title>
+
+<para>
+<indexterm><primary>BDC</primary></indexterm>
+The creation of a BDC requires some steps to prepare the Samba server before
+&smbd; is executed for the first time. These steps are as follows:
+</para>
+
+<itemizedlist>
+	<listitem><para>
+	<indexterm><primary>SID</primary></indexterm>
+	<indexterm><primary>PDC</primary></indexterm>
+	<indexterm><primary>BDC</primary></indexterm>
+	<indexterm><primary>private/secrets.tdb</primary></indexterm>
+	<indexterm><primary>private/MACHINE.SID</primary></indexterm>
+	<indexterm><primary>domain SID</primary></indexterm>
+	The domain SID has to be the same on the PDC and the BDC. In Samba versions pre-2.2.5, the domain SID was
+	stored in the file <filename>private/MACHINE.SID</filename>.  For all versions of Samba released since 2.2.5
+	the domain SID is stored in the file <filename>private/secrets.tdb</filename>. This file is unique to each
+	server and cannot be copied from a PDC to a BDC; the BDC will generate a new SID at startup. It will overwrite
+	the PDC domain SID with the newly created BDC SID.  There is a procedure that will allow the BDC to aquire the
+	domain SID. This is described here.
+	</para>
+
+	<para>
+	<indexterm><primary>domain SID</primary></indexterm>
+	<indexterm><primary>PDC</primary></indexterm>
+	<indexterm><primary>BDC</primary></indexterm>
+	<indexterm><primary>secrets.tdb</primary></indexterm>
+	<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>getsid</tertiary></indexterm>
+	To retrieve the domain SID from the PDC or an existing BDC and store it in the
+	<filename>secrets.tdb</filename>, execute:
+	</para>
+<screen>
+&rootprompt;<userinput>net rpc getsid</userinput>
+</screen>
+	</listitem>
+
+	<listitem><para>
+	<indexterm><primary>secrets.tdb</primary></indexterm>
+	<indexterm><primary>smbpasswd</primary></indexterm>
+	<indexterm><primary>LDAP administration password</primary></indexterm>
+	Specification of the <smbconfoption name="ldap admin dn"/> is obligatory.
+	This also requires the LDAP administration password to be set in the <filename>secrets.tdb</filename>
+	using the <command>smbpasswd -w <replaceable>mysecret</replaceable></command>.
+	</para></listitem>
+
+	<listitem><para>
+	The <smbconfoption name="ldap suffix"/> parameter and the <smbconfoption name="ldap idmap suffix"/>
+	parameter must be specified in the &smb.conf; file.
+	</para></listitem>
+
+	<listitem><para>
+	<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+	<indexterm><primary>user database</primary></indexterm>
+	<indexterm><primary>synchronized</primary></indexterm>
+	<indexterm><primary>NIS</primary></indexterm>
+	The UNIX user database has to be synchronized from the PDC to the
+	BDC. This means that both the <filename>/etc/passwd</filename> and
+	<filename>/etc/group</filename> have to be replicated from the PDC
+	to the BDC. This can be done manually whenever changes are made. 
+	Alternately, the PDC is set up as an NIS master server and the BDC as an NIS slave
+	server. To set up the BDC as a mere NIS client would not be enough,
+	as the BDC would not be able to access its user database in case of
+	a PDC failure. NIS is by no means the only method to synchronize
+	passwords. An LDAP solution would also work.
+	</para>
+	</listitem>
+
+	<listitem><para>
+	<indexterm><primary>password database</primary></indexterm>
+	<indexterm><primary>replicated</primary></indexterm>
+	<indexterm><primary>PDC</primary></indexterm>
+	<indexterm><primary>BDC</primary></indexterm>
+	<indexterm><primary>smbpasswd</primary></indexterm>
+	<indexterm><primary>rsync</primary></indexterm>
+	<indexterm><primary>ssh</primary></indexterm>
+	<indexterm><primary>LDAP</primary></indexterm>
+	The Samba password database must be replicated from the PDC to the BDC.
+	Although it is possible to synchronize the <filename>smbpasswd</filename>
+	file with <command>rsync</command> and <command>ssh</command>, this method
+	is broken and flawed, and is therefore not recommended. A better solution
+	is to set up slave LDAP servers for each BDC and a master LDAP server for the PDC.
+	The use of rsync is inherently flawed by the fact that the data will be replicated
+	at timed intervals. There is no guarantee that the BDC will be operating at all
+	times with correct and current machine and user account information. This means that
+	this method runs the risk of users being inconvenienced by discontinuity of access
+	to network services due to inconsistent security data. It must be born in mind that
+	Windows workstations update (change) the machine trust account password at regular
+	intervals &smbmdash; administrators are not normally aware that this is happening
+	or when it takes place.
+	</para>
+
+	<para>
+	<indexterm><primary>POSIX</primary></indexterm>
+	<indexterm><primary>LDAP</primary></indexterm>
+	<indexterm><primary>SambaSAMAccount</primary></indexterm>
+	<indexterm><primary>synchronize</primary></indexterm>
+	The use of LDAP for both the POSIX (UNIX user and group) accounts and for the
+	SambaSAMAccount data automatically ensures that all account change information
+	will be written to the shared directory. This eliminates the need for any special
+	action to synchronize account information because LDAP will meet that requirement.
+	</para></listitem>
+
+	<listitem><para>
+	<indexterm><primary>netlogon share</primary></indexterm>
+	<indexterm><primary>replicate</primary></indexterm>
+	<indexterm><primary>PDC</primary></indexterm>
+	<indexterm><primary>BDC</primary></indexterm>
+	<indexterm><primary>cron</primary></indexterm>
+	<indexterm><primary>rsync</primary></indexterm>
+	The netlogon share has to be replicated from the PDC to the BDC. This can be done manually whenever login
+	scripts are changed, or it can be done automatically using a <command>cron</command> job that will replicate
+	the directory structure in this share using a tool like <command>rsync</command>. The use of
+	<command>rsync</command> for replication of the netlogon data is not critical to network security and is one
+	that can be manually managed given that the administrator will make all changes to the netlogon share as part
+	of a conscious move.
+	</para></listitem>
+
+</itemizedlist>
+
+<sect2>
+<title>Example Configuration</title>
+
+<para>
+Finally, the BDC has to be capable of being found by the workstations. This can be done by configuring the
+Samba &smb.conf; file <smbconfsection name="[global]"/> section as shown in <link linkend="minim-bdc">Minimal
+Setup for Being a BDC</link>.
+</para>
+
+<example id="minim-bdc">
+<title>Minimal Setup for Being a BDC</title>
+<smbconfblock>
+<smbconfoption name="workgroup">&example.workgroup;</smbconfoption>
+<smbconfoption name="passdb backend">ldapsam:ldap://slave-ldap.quenya.org</smbconfoption>
+<smbconfoption name="domain master">no</smbconfoption>
+<smbconfoption name="domain logons">yes</smbconfoption>
+<smbconfoption name="ldap suffix">dc=abmas,dc=biz</smbconfoption>
+<smbconfoption name="ldap user suffix">ou=Users</smbconfoption>
+<smbconfoption name="ldap group suffix">ou=Groups</smbconfoption>
+<smbconfoption name="ldap machine suffix">ou=Computers</smbconfoption>
+<smbconfoption name="ldap idmap suffix">ou=Idmap</smbconfoption>
+<smbconfoption name="ldap admin dn">cn=sambadmin,dc=quenya,dc=org</smbconfoption>
+<smbconfoption name="idmap backend">ldap:ldap://master-ldap.quenya.org</smbconfoption>
+<smbconfoption name="idmap uid">10000-20000</smbconfoption>
+<smbconfoption name="idmap gid">10000-20000</smbconfoption>
+</smbconfblock>
+</example>
+
+<para>
+Fully documented working example network configurations using OpenLDAP and Samba
+as available in the <ulink url="http://www.samba.org/samba/docs/Samba3-ByExample">book</ulink> <quote>Samba-3
+by Example</quote> that may be obtained from local and on-line book stores.
+</para>
+
+<para>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+<indexterm><primary>group</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+This configuration causes the BDC to register only the name MIDEARTH&lt;1C&gt; with the WINS server. This is
+not a problem, as the name MIDEARTH&lt;1C&gt; is a NetBIOS group name that is meant to be registered by more
+than one machine. The parameter <smbconfoption name="domain master">no</smbconfoption> forces the BDC not to
+register MIDEARTH&lt;1B&gt;, which is a unique NetBIOS name that is reserved for the PDC.
+</para>
+
+<para>
+<indexterm><primary>idmap backend</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>redirect</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>LDAP database</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>nss_ldap</primary></indexterm>
+The <parameter>idmap backend</parameter> will redirect the <command>winbindd</command> utility to use the LDAP
+database to store all mappings for Windows SIDs to  UIDs and GIDs for UNIX accounts in a repository that is
+shared. The BDC will however depend on local resolution of UIDs and GIDs via NSS and the
+<command>nss_ldap</command> utility.
+</para>
+
+<note><para>
+<indexterm><primary>Server Type</primary><secondary>Domain Member</secondary></indexterm>
+<indexterm><primary>ID mapping</primary></indexterm>
+<indexterm><primary>domain member server</primary></indexterm>
+<indexterm><primary>idmap backend</primary></indexterm>
+Samba-3 has introduced a new ID mapping facility. One of the features of this facility is that it
+allows greater flexibility in how user and group IDs are handled in respect to NT domain user and group
+SIDs. One of the new facilities provides for explicitly ensuring that UNIX/Linux UID and GID values
+will be consistent on the PDC, all BDCs, and all domain member servers. The parameter that controls this
+is called <parameter>idmap backend</parameter>. Please refer to the man page for &smb.conf; for more information
+regarding its behavior.
+</para></note>
+
+<para>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>domain member servers</primary></indexterm>
+The use of the <smbconfoption name="idmap backend">ldap:ldap://master.quenya.org</smbconfoption>
+option on a BDC only makes sense where ldapsam is used on a PDC. The purpose of an LDAP-based idmap backend is
+also to allow a domain member (without its own passdb backend) to use winbindd to resolve Windows network users
+and groups to common UID/GIDs. In other words, this option is generally intended for use on BDCs and on domain
+member servers.
+</para>
+
+</sect2>
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+<para>
+<indexterm><primary>domain control</primary></indexterm>
+Domain control was a new area for Samba, but there are now many examples that we may refer to.
+Updated information will be published as they become available and may be found in later Samba releases or
+from the Samba Web <ulink url="http://samba.org">site</ulink>; refer in particular to the
+<filename>WHATSNEW.txt</filename> in the Samba release tarball. The book, <quote>Samba-3 by Example</quote>
+documents well tested and proven configuration examples. You can obtain a copy of this
+<ulink url="http://www.samba.org/samba/docs/Samba3-ByExample.pdf">book</ulink> for the Samba web site.
+</para>
+
+<sect2>
+<title>Machine Accounts Keep Expiring</title>
+
+<para>
+<indexterm><primary>Machine Trust Accounts</primary></indexterm>
+<indexterm><primary>passdb</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>Local Machine Trust Account</primary></indexterm>
+This problem will occur when the passdb (SAM) files are copied  from a central
+server but the local BDC is acting as a PDC. This results in the application of
+Local Machine Trust Account password updates to the local SAM. Such updates 
+are not copied back to the central server. The newer machine account password is then
+overwritten when the SAM is recopied from the PDC. The result is that the domain member machine
+on startup will find that its passwords do not match the one now in the database, and
+since the startup security check will now fail, this machine will not allow logon attempts
+to proceed and the account expiry error will be reported.
+</para>
+
+<para>
+The solution is to use a more robust passdb backend, such as the ldapsam backend, setting up
+a slave LDAP server for each BDC and a master LDAP server for the PDC.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Can Samba Be a Backup Domain Controller to an NT4 PDC?</title>
+
+<para>
+<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+No. The native NT4 SAM replication protocols have not yet been fully implemented.
+</para>
+
+<para>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>logon requests</primary></indexterm>
+Can I get the benefits of a BDC with Samba?  Yes, but only to a Samba PDC.The
+main reason for implementing a BDC is availability. If the PDC is a Samba
+machine, a second Samba machine can be set up to service logon requests whenever
+the PDC is down.
+</para>
+
+</sect2>
+
+<sect2>
+<title>How Do I Replicate the smbpasswd File?</title>
+
+<para>
+<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+Replication of the smbpasswd file is sensitive. It has to be done whenever changes
+to the SAM are made. Every user's password change is done in the smbpasswd file and
+has to be replicated to the BDC. So replicating the smbpasswd file very often is necessary.
+</para>
+
+<para>
+<indexterm><primary>plaintext password</primary></indexterm>
+<indexterm><primary>ssh</primary></indexterm>
+<indexterm><primary>rsync</primary></indexterm>
+As the smbpasswd file contains plaintext password equivalents, it must not be
+sent unencrypted over the wire. The best way to set up smbpasswd replication from
+the PDC to the BDC is to use the utility rsync. rsync can use ssh as a transport.
+<command>ssh</command> itself can be set up to accept <emphasis>only</emphasis>
+<command>rsync</command> transfer without requiring the user to type a password.
+</para>
+
+<para>
+<indexterm><primary>machine trust accounts</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+As said a few times before, use of this method is broken and flawed. Machine trust 
+accounts will go out of sync, resulting in a broken domain. This method is
+<emphasis>not</emphasis> recommended. Try using LDAP instead.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Can I Do This All with LDAP?</title>
+
+<para>
+<indexterm><primary>pdb_ldap</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+The simple answer is yes. Samba's pdb_ldap code supports binding to a replica
+LDAP server and will also follow referrals and rebind to the master if it ever
+needs to make a modification to the database. (Normally BDCs are read-only, so
+this will not occur often).
+</para>
+
+</sect2>
+</sect1>
+</chapter>