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, 1124 insertions, 0 deletions

diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-IDMAP.xml b/docs-xml/Samba3-HOWTO/TOSHARG-IDMAP.xml
new file mode 100644
index 0000000000..2ff794939c
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-IDMAP.xml
@@ -0,0 +1,1124 @@
+<?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="idmapper">
+<chapterinfo>
+	&author.jht;
+</chapterinfo>
+
+<title>Identity Mapping (IDMAP)</title>
+
+<para>
+<indexterm><primary>Windows</primary></indexterm>
+<indexterm><primary>interoperability</primary></indexterm>
+<indexterm><primary>IDMAP</primary></indexterm>
+<indexterm><primary>Windows Security Identifiers</primary><see>SID</see></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+The Microsoft Windows operating system has a number of features that impose specific challenges
+to interoperability with the operating systems on which Samba is implemented. This chapter deals
+explicitly with the mechanisms Samba-3 (version 3.0.8 and later) uses to overcome one of the
+key challenges in the integration of Samba servers into an MS Windows networking environment.
+This chapter deals with identity mapping (IDMAP) of Windows security identifiers (SIDs)
+to UNIX UIDs and GIDs.
+</para>
+
+<para>
+To ensure sufficient coverage, each possible Samba deployment type is discussed.
+This is followed by an overview of how the IDMAP facility may be implemented.
+</para>
+
+<para>
+<indexterm><primary>network client</primary></indexterm>
+<indexterm><primary>IDMAP</primary></indexterm>
+<indexterm><primary>IDMAP infrastructure</primary></indexterm>
+<indexterm><primary>default behavior</primary></indexterm>
+The IDMAP facility is of concern where more than one Samba server (or Samba network client)
+is installed in a domain. Where there is a single Samba server, do not be too concerned regarding
+the IDMAP infrastructure &smbmdash; the default behavior of Samba is nearly always sufficient.
+Where mulitple Samba servers are used it is often necessary to move data off one server and onto
+another, and that is where the fun begins!
+</para>
+
+<para>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>nss_ldap</primary></indexterm>
+<indexterm><primary>NT4 domain members</primary></indexterm>
+<indexterm><primary>ADS domain members</primary></indexterm>
+<indexterm><primary>security name-space</primary></indexterm>
+Where user and group account information is stored in an LDAP directory every server can have the same
+consistent UID and GID for users and groups. This is achieved using NSS and the nss_ldap tool. Samba
+can be configured to use only local accounts, in which case the scope of the IDMAP problem is somewhat
+reduced. This works reasonably well if the servers belong to a single domain, and interdomain trusts
+are not needed. On the other hand, if the Samba servers are NT4 domain members, or ADS  domain members,
+or if there is a need to keep the security name-space separate (i.e., the user
+<literal>DOMINICUS\FJones</literal> must not be given access to the account resources of the user 
+<literal>FRANCISCUS\FJones</literal><footnote>Samba local account mode results in both
+<literal>DOMINICUS\FJones</literal> and <literal>FRANCISCUS\FJones</literal> mapping to the UNIX user
+<literal>FJones</literal>.</footnote> free from inadvertent cross-over, close attention should be given
+to the way that the IDMAP facility is configured.
+</para>
+
+<para>
+<indexterm><primary>IDMAP</primary></indexterm>
+<indexterm><primary>domain access</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>one domain</primary></indexterm>
+The use of IDMAP is important where the Samba server will be accessed by workstations or servers from
+more than one domain, in which case it is important to run winbind so it can handle the resolution (ID mapping)
+of foreign SIDs to local UNIX UIDs and GIDs.
+</para>
+
+<para>
+<indexterm><primary>winbindd</primary></indexterm>
+The use of the IDMAP facility requires the execution of the <command>winbindd</command> upon Samba startup.
+</para>
+
+<sect1>
+<title>Samba Server Deployment Types and IDMAP</title>
+
+<para>
+<indexterm><primary>Server Types</primary></indexterm>
+There are four basic server deployment types, as documented in <link linkend="ServerType">the chapter
+on Server Types and Security Modes</link>.
+</para>
+
+	<sect2>
+	<title>Standalone Samba Server</title>
+
+	<para>
+	<indexterm><primary>stand-alone server</primary></indexterm>
+	<indexterm><primary>Active Directory</primary></indexterm>
+	<indexterm><primary>NT4 Domain</primary></indexterm>
+	A standalone Samba server is an implementation that is not a member of a Windows NT4 domain,
+	a Windows 200X Active Directory domain, or a Samba domain.
+	</para>
+
+	<para>
+	<indexterm><primary>IDMAP</primary></indexterm>
+	<indexterm><primary>identity</primary></indexterm>
+	<indexterm><primary>local user</primary></indexterm>
+	By definition, this means that users and groups will be created and controlled locally, and
+	the identity of a network user must match a local UNIX/Linux user login. The IDMAP facility
+	is therefore of little to no interest, winbind will not be necessary, and the IDMAP facility
+	will not be relevant or of interest.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Domain Member Server or Domain Member Client</title>
+
+	<para>
+	<indexterm><primary>PDC</primary></indexterm>
+	<indexterm><primary>BDC</primary></indexterm>
+	<indexterm><primary>NT4</primary></indexterm>
+	<indexterm><primary>SID</primary></indexterm>
+	<indexterm><primary>Active Directory</primary></indexterm>
+	Samba-3 can act as a Windows NT4 PDC or BDC, thereby providing domain control protocols that
+	are compatible with Windows NT4. Samba-3 file and print sharing protocols are compatible with
+	all versions of MS Windows products. Windows NT4, as with MS Active Directory,
+	extensively makes use of Windows SIDs.
+	</para>
+
+	<para>
+	<indexterm><primary>MS Windows SID</primary></indexterm>
+	<indexterm><primary>UID</primary></indexterm>
+	<indexterm><primary>GID</primary></indexterm>
+	Samba-3 domain member servers and clients must interact correctly with MS Windows SIDs. Incoming
+	Windows SIDs must be translated to local UNIX UIDs and GIDs. Outgoing information from the Samba
+	server must provide to MS Windows clients and servers appropriate SIDs.
+	</para>
+
+	<para>
+	<indexterm><primary>ADS</primary></indexterm>
+	<indexterm><primary>winbind</primary></indexterm>
+	A Samba member of a Windows networking domain (NT4-style or ADS) can be configured to handle 
+	identity mapping in a variety of ways. The mechanism it uses depends on whether or not
+	the <command>winbindd</command> daemon is used and how the winbind functionality is configured.
+	The configuration options are briefly described here:
+	</para>
+
+	<variablelist>
+		<varlistentry><term>Winbind is not used; users and groups are local: </term>
+			<listitem>
+				<para>
+				<indexterm><primary>winbindd</primary></indexterm>
+				<indexterm><primary>smbd</primary></indexterm>
+				<indexterm><primary>network traffic</primary></indexterm>
+				<indexterm><primary>LoginID</primary></indexterm>
+				<indexterm><primary>account name</primary></indexterm>
+				<indexterm><primary>getpwnam</primary></indexterm>
+				<indexterm><primary>NSS</primary></indexterm>
+				<indexterm><primary>local users</primary></indexterm>
+				<indexterm><primary>local groups</primary></indexterm>
+				<indexterm><primary>/etc/passwd</primary></indexterm>
+				<indexterm><primary>/etc/group</primary></indexterm>
+				Where <command>winbindd</command> is not used Samba (<command>smbd</command>)
+				uses the underlying UNIX/Linux mechanisms to resolve the identity of incoming
+				network traffic. This is done using the LoginID (account name) in the
+				session setup request and passing it to the getpwnam() system function call.
+				This call is implemented using the name service switch (NSS) mechanism on
+				modern UNIX/Linux systems. By saying "users and groups are local,"
+				we are implying that they are stored only on the local system, in the
+				<filename>/etc/passwd</filename> and <filename>/etc/group</filename> respectively.
+				</para>
+
+				<para>
+				<indexterm><primary>SessionSetupAndX</primary></indexterm>
+				<indexterm><primary>/etc/passwd</primary></indexterm>
+				For example, when the user <literal>BERYLIUM\WambatW</literal> tries to open a
+				connection to a Samba server the incoming SessionSetupAndX request will make a 
+				system call to look up the user <literal>WambatW</literal> in the
+				<filename>/etc/passwd</filename> file.
+				</para>
+
+				<para>
+				<indexterm><primary>standalone</primary></indexterm>
+				<indexterm><primary>domain member server</primary></indexterm>
+				<indexterm><primary>NT4</primary></indexterm>
+				<indexterm><primary>ADS</primary></indexterm>
+				<indexterm><primary>PDC</primary></indexterm>
+				<indexterm><primary>smbpasswd</primary></indexterm>
+				<indexterm><primary>tdbsam</primary></indexterm>
+				<indexterm><primary>passdb backend</primary></indexterm>
+				This configuration may be used with standalone Samba servers, domain member
+				servers (NT4 or ADS), and for a PDC that uses either an smbpasswd
+				or a tdbsam-based Samba passdb backend.
+				</para>
+			</listitem>
+		</varlistentry>
+	
+		<varlistentry><term>Winbind is not used; users and groups resolved via NSS: </term>
+			<listitem>
+				<para>
+				<indexterm><primary>user accounts</primary></indexterm>
+				<indexterm><primary>group accounts</primary></indexterm>
+				<indexterm><primary>local accounts</primary></indexterm>
+				<indexterm><primary>repository</primary></indexterm>
+				<indexterm><primary>NIS</primary></indexterm>
+				<indexterm><primary>LDAP</primary></indexterm>
+				In this situation user and group accounts are treated as if they are local
+				accounts. The only way in which this differs from having local accounts is
+				that the accounts are stored in a repository that can be shared. In practice
+				this means that they will reside in either an NIS-type database or else in LDAP.
+				</para>
+
+				<para>
+				<indexterm><primary>standalone</primary></indexterm>
+				<indexterm><primary>domain member server</primary></indexterm>
+				<indexterm><primary>NT4</primary></indexterm>
+				<indexterm><primary>ADS</primary></indexterm>
+				<indexterm><primary>PDC</primary></indexterm>
+				<indexterm><primary>smbpasswd</primary></indexterm>
+				<indexterm><primary>tdbsam</primary></indexterm>
+				This configuration may be used with standalone Samba servers, domain member
+				servers (NT4 or ADS), and for a PDC that uses either an smbpasswd
+				or a tdbsam-based Samba passdb backend.
+				</para>
+			</listitem>
+		</varlistentry>
+
+		<varlistentry><term>Winbind/NSS with the default local IDMAP table: </term>
+			<listitem>
+				<para>
+				<indexterm><primary>NT4 domain</primary></indexterm>
+				<indexterm><primary>ADS domain</primary></indexterm>
+				<indexterm><primary>winbind</primary></indexterm>
+				<indexterm><primary>domain control</primary></indexterm>
+				There are many sites that require only a simple Samba server or a single Samba
+				server that is a member of a Windows NT4 domain or an ADS domain. A typical example
+				is an appliance like file server on which no local accounts are configured and
+				winbind is used to obtain account credentials from the domain controllers for the
+				domain. The domain control can be provided by Samba-3, MS Windows NT4, or MS Windows
+				Active Directory.
+				</para>
+
+				<para>
+				<indexterm><primary>UID numbers</primary></indexterm>
+				<indexterm><primary>GID numbers</primary></indexterm>
+				<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+				<indexterm><primary>winbind</primary></indexterm>
+				<indexterm><primary>SID</primary></indexterm>
+				Winbind is a great convenience in this situation. All that is needed is a range of
+				UID numbers and GID numbers that can be defined in the &smb.conf; file. The
+				<filename>/etc/nsswitch.conf</filename> file is configured to use <command>winbind</command>,
+				which does all the difficult work of mapping incoming SIDs to appropriate UIDs and GIDs.
+				The SIDs are allocated a UID/GID in the order in which winbind receives them.
+				</para>
+
+				<para>
+				<indexterm><primary>UID</primary></indexterm>
+				<indexterm><primary>GID</primary></indexterm>
+				<indexterm><primary>IDMAP</primary></indexterm>
+				<indexterm><primary>corrupted file</primary></indexterm>
+				This configuration is not convenient or practical in sites that have more than one
+				Samba server and that require the same UID or GID for the same user or group across
+				all servers. One of the hazards of this method is that in the event that the winbind
+				IDMAP file becomes corrupted or lost, the repaired or rebuilt IDMAP file may allocate
+				UIDs and GIDs to different users and groups from what was there previously with the
+				result that MS Windows files that are stored on the Samba server may now not belong to
+				the rightful owners.
+				</para>
+			</listitem>
+		</varlistentry>
+
+		<varlistentry><term>Winbind/NSS uses RID based IDMAP: </term>
+			<listitem>
+				<para>
+				<indexterm><primary>RID</primary></indexterm>
+				<indexterm><primary>idmap_rid</primary></indexterm>
+				<indexterm><primary>ADS</primary></indexterm>
+				<indexterm><primary>LDAP</primary></indexterm>
+				The IDMAP_RID facility is new to Samba version 3.0.8. It was added to make life easier
+				for a number of sites that are committed to use of MS ADS, that do not apply
+				an ADS schema extension, and that do not have an installed an LDAP directory server just for
+				the purpose of maintaining an IDMAP table. If you have a single ADS domain (not a forest of
+				domains, and not multiple domain trees) and you want a simple cookie-cutter solution to the
+				IDMAP table problem, then IDMAP_RID is an obvious choice.
+				</para>
+
+				<para>
+				<indexterm><primary>idmap_rid</primary></indexterm>
+				<indexterm><primary>idmap uid</primary></indexterm>
+				<indexterm><primary>idmap gid</primary></indexterm>
+				<indexterm><primary>RID</primary></indexterm>
+				<indexterm><primary>SID</primary></indexterm>
+				<indexterm><primary>UID</primary></indexterm>
+				<indexterm><primary>idmap backend</primary></indexterm>
+				<indexterm><primary>automatic mapping</primary></indexterm>
+				This facility requires the allocation of the <parameter>idmap uid</parameter> and the
+				<parameter>idmap gid</parameter> ranges, and within the <parameter>idmap uid</parameter>
+				it is possible to allocate a subset of this range for automatic mapping of the relative
+				identifier (RID) portion of the SID directly to the base of the UID plus the RID value.
+				For example, if the <parameter>idmap uid</parameter> range is <constant>1000-100000000</constant>
+				and the <parameter>idmap backend = idmap_rid:DOMAIN_NAME=1000-50000000</parameter>, and
+				a SID is encountered that has the value <constant>S-1-5-21-34567898-12529001-32973135-1234</constant>,
+				the resulting UID will be <constant>1000 + 1234 = 2234</constant>.
+				</para>
+			</listitem>
+		</varlistentry>
+
+		<varlistentry><term>Winbind with an NSS/LDAP backend-based IDMAP facility: </term>
+			<listitem>
+				<para>
+				<indexterm><primary>Domain Member</primary></indexterm>
+				<indexterm><primary>winbind</primary></indexterm>
+				<indexterm><primary>SID</primary></indexterm>
+				<indexterm><primary>UID</primary></indexterm>
+				<indexterm><primary>GID</primary></indexterm>
+				<indexterm><primary>idmap gid</primary></indexterm>
+				<indexterm><primary>idmap uid</primary></indexterm>
+				<indexterm><primary>LDAP</primary></indexterm>
+				In this configuration <command>winbind</command> resolved SIDs to UIDs and GIDs from
+				the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter> ranges specified
+				in the &smb.conf; file, but instead of using a local winbind IDMAP table, it is stored
+				in an LDAP directory so that all domain member machines (clients and servers) can share
+				a common IDMAP table.
+				</para>
+
+				<para>
+				<indexterm><primary>idmap backend</primary></indexterm>
+				<indexterm><primary>LDAP server</primary></indexterm>
+				<indexterm><primary>LDAP redirects</primary></indexterm>
+				It is important that all LDAP IDMAP clients use only the master LDAP server because the
+				<parameter>idmap backend</parameter> facility in the &smb.conf; file does not correctly
+				handle LDAP redirects.
+				</para>
+			</listitem>
+		</varlistentry>
+
+		<varlistentry><term>Winbind with NSS to resolve UNIX/Linux user and group IDs: </term>
+			<listitem>
+				<para>
+				The use of LDAP as the passdb backend is a smart solution for PDC, BDC, and
+				domain member servers. It is a neat method for assuring that UIDs, GIDs, and the matching
+				SIDs are consistent across all servers.
+				</para>
+
+				<para>
+				<indexterm><primary>LDAP</primary></indexterm>
+				<indexterm><primary>PADL</primary></indexterm>
+				The use of the LDAP-based passdb backend requires use of the PADL nss_ldap utility or
+				an equivalent. In this situation winbind is used to handle foreign SIDs, that is, SIDs from
+				standalone Windows clients (i.e., not a member of our domain) as well as SIDs from 
+				another domain. The foreign UID/GID is mapped from allocated ranges (idmap uid and idmap gid)
+				in precisely the same manner as when using winbind with a local IDMAP table.
+				</para>
+
+				<para>
+				<indexterm><primary>nss_ldap</primary></indexterm>
+				<indexterm><primary>AD4UNIX</primary></indexterm>
+				<indexterm><primary>MMC</primary></indexterm>
+				The nss_ldap tool set can be used to access UIDs and GIDs via LDAP as well as via Active
+				Directory. In order to use Active Directory, it is necessary to modify the ADS schema by
+				installing either the AD4UNIX schema extension or using the Microsoft Services for UNIX
+				version 3.5 or later to extend the ADS schema so it maintains UNIX account credentials.
+				Where the ADS schema is extended, a Microsoft Management Console (MMC) snap-in is also
+				installed to permit the UNIX credentials to be set and managed from the ADS User and Computer
+				Management tool. Each account must be separately UNIX-enabled before the UID and GID data can
+				be used by Samba.
+				</para>
+			</listitem>
+		</varlistentry>
+
+	</variablelist>
+
+	</sect2>
+
+	<sect2>
+	<title>Primary Domain Controller</title>
+
+	<para>
+	<indexterm><primary>domain security</primary></indexterm>
+	<indexterm><primary>SID</primary></indexterm>
+	<indexterm><primary>RID</primary></indexterm>
+	<indexterm><primary>algorithmic mapping</primary></indexterm>
+	Microsoft Windows domain security systems generate the user and group SID as part
+	of the process of creation of an account. Windows does not have a concept of the UNIX UID or a GID; rather,
+	it has its own type of security descriptor. When Samba is used as a domain controller, it provides a method
+	of producing a unique SID for each user and group. Samba generates a machine and a domain SID to which it
+	adds an RID that is calculated algorithmically from a base value that can be specified
+	in the &smb.conf; file, plus twice (2x) the UID or GID. This method is called <quote>algorithmic mapping</quote>.
+	</para>
+
+	<para>
+	<indexterm><primary>RID base</primary></indexterm>
+	For example, if a user has a UID of 4321, and the algorithmic RID base has a value of 1000, the RID will
+	be <literal>1000 + (2 x 4321) = 9642</literal>. Thus, if the domain SID is
+	<literal>S-1-5-21-89238497-92787123-12341112</literal>, the resulting SID is
+	<literal>S-1-5-21-89238497-92787123-12341112-9642</literal>.
+	</para>
+
+	<para>
+	<indexterm><primary>on-the-fly</primary></indexterm>
+	<indexterm><primary>SID</primary></indexterm>
+	<indexterm><primary>passdb backend</primary></indexterm>
+	<indexterm><primary>ldapsam</primary></indexterm>
+	The foregoing type of SID is produced by Samba as an automatic function and is either produced on the fly
+	(as is the case when using a <parameter>passdb backend = [tdbsam | smbpasswd]</parameter>), or may be stored
+	as a permanent part of an account in an LDAP-based ldapsam.
+	</para>
+
+	<para>
+	<indexterm><primary>SFU 3.5</primary></indexterm>
+	<indexterm><primary>ADS</primary></indexterm>
+	<indexterm><primary>directory schema</primary></indexterm>
+	<indexterm><primary>account attributes</primary></indexterm>
+	<indexterm><primary>UID</primary></indexterm>
+	<indexterm><primary>GID</primary></indexterm>
+	<indexterm><primary>ADS schema</primary></indexterm>
+	<indexterm><primary>account management</primary></indexterm>
+	<indexterm><primary>MMC</primary></indexterm>
+	ADS uses a directory schema that can be extended to accommodate additional
+	account attributes such as UIDs and GIDs. The installation of Microsoft Service for UNIX 3.5 will expand
+	the normal ADS schema to include UNIX account attributes. These must of course be managed separately
+	through a snap-in module to the normal ADS account management MMC interface.
+	</para>
+
+	<para>
+	<indexterm><primary>PDC</primary></indexterm>
+	<indexterm><primary>passdb backend</primary></indexterm>
+	<indexterm><primary>BDC</primary></indexterm>
+	<indexterm><primary>LDAP backend</primary></indexterm>
+	Security identifiers used within a domain must be managed to avoid conflict and to preserve itegrity.
+	In an NT4 domain context, the PDC manages the distribution of all security credentials to the backup
+	domain controllers (BDCs). At this time the only passdb backend for a Samba domain controller that is suitable
+	for such information is an LDAP backend.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Backup Domain Controller</title>
+
+	<para>
+	<indexterm><primary>BDC</primary></indexterm>
+	<indexterm><primary>read-only access</primary></indexterm>
+	<indexterm><primary>security credentials</primary></indexterm>
+	<indexterm><primary>LDAP</primary></indexterm>
+	<indexterm><primary>group account</primary></indexterm>
+	<indexterm><primary>write changes</primary></indexterm>
+	<indexterm><primary>directory</primary></indexterm>
+	BDCs have read-only access to security credentials that are stored in LDAP.
+	Changes in user or group account information are passed by the BDC to the PDC. Only the PDC can write
+	changes to the directory.
+	</para>
+
+	<para>
+	IDMAP information can be written directly to the LDAP server so long as all domain controllers
+	have access to the master (writable) LDAP server. Samba-3 at this time does not handle LDAP redirects
+	in the IDMAP backend. This means that it is is unsafe to use a slave (replicate) LDAP server with
+	the IDMAP facility.
+	</para>
+
+	</sect2>
+
+</sect1>
+
+<sect1>
+<title>Examples of IDMAP Backend Usage</title>
+
+<para>
+<indexterm><primary>Domain Member Server</primary><see>DMS</see></indexterm>
+<indexterm><primary>Domain Member Client</primary><see>DMC</see></indexterm>
+<indexterm><primary>DMS</primary></indexterm>
+<indexterm><primary>DMC</primary></indexterm>
+<indexterm><primary>winbind</primary></indexterm>
+Anyone who wishes to use <command>winbind</command> will find the following example configurations helpful.
+Remember that in the majority of cases <command>winbind</command> is of primary interest for use with
+domain member servers (DMSs) and domain member clients (DMCs).
+</para>
+
+	<sect2>
+	<title>Default Winbind TDB</title>
+
+	<para>
+	Two common configurations are used:
+	</para>
+
+	<itemizedlist>
+		<listitem><para>
+		Networks that have an NT4 PDC (with or without BDCs) or a Samba PDC (with or without BDCs).
+		</para></listitem>
+
+		<listitem><para>
+		Networks that use MS Windows 200x ADS.
+		</para></listitem>
+	</itemizedlist>
+
+	<sect3>
+	<title>NT4-Style Domains (Includes Samba Domains)</title>
+
+	<para>
+	<link linkend="idmapnt4dms">NT4 Domain Member Server smb.con</link> is a simple example of an NT4 DMS
+	&smb.conf; file that shows only the global section.
+	</para>
+
+<example id="idmapnt4dms">
+<title>NT4 Domain Member Server smb.conf</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">MEGANET2</smbconfoption>
+<smbconfoption name="security">DOMAIN</smbconfoption>
+<smbconfoption name="idmap uid">10000-20000</smbconfoption>
+<smbconfoption name="idmap gid">10000-20000</smbconfoption>
+<smbconfoption name="template primary group">"Domain Users"</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+</smbconfblock>
+</example>
+
+	<para>
+	<indexterm><primary>winbind</primary></indexterm>
+	<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+	The use of <command>winbind</command> requires configuration of NSS. Edit the <filename>/etc/nsswitch.conf</filename>
+	so it includes the following entries:
+<screen>
+...
+passwd: files winbind
+shadow: files winbind
+group:  files winbind
+...
+hosts:  files [dns] wins
+...
+</screen>
+	The use of DNS in the hosts entry should be made only if DNS is used on site.
+	</para>
+
+	<para>
+	The creation of the DMS requires the following steps:
+	</para>
+
+	<procedure>
+		<step><para>
+		Create or install an &smb.conf; file with the above configuration.
+		</para></step>
+
+		<step><para>
+		Execute:
+<screen>
+&rootprompt; net rpc join -UAdministrator%password
+Joined domain MEGANET2.
+</screen>
+	<indexterm><primary>join</primary></indexterm>
+	The success of the join can be confirmed with the following command:
+<screen>
+&rootprompt; net rpc testjoin
+Join to 'MIDEARTH' is OK
+</screen>
+		A failed join would report an error message like the following:
+		<indexterm><primary>failed join</primary></indexterm>
+<screen>
+&rootprompt; net rpc testjoin
+[2004/11/05 16:34:12, 0] utils/net_rpc_join.c:net_rpc_join_ok(66)
+Join to domain 'MEGANET2' is not valid
+</screen>
+		</para></step>
+
+		<step><para>
+		<indexterm><primary>nmbd</primary></indexterm>
+		<indexterm><primary>winbind</primary></indexterm>
+		<indexterm><primary>smbd</primary></indexterm>
+		Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown.
+		</para></step>
+	</procedure>
+
+	</sect3>
+
+	<sect3>
+	<title>ADS Domains</title>
+
+	<para>
+	<indexterm><primary>domain join</primary></indexterm>
+	<indexterm><primary>ADS domain</primary></indexterm>
+	The procedure for joining an ADS domain is similar to the NT4 domain join, except the &smb.conf; file
+	will have the contents shown in <link linkend="idmapadsdms">ADS Domain Member Server smb.conf</link>
+	</para>
+
+<example id="idmapadsdms">
+<title>ADS Domain Member Server smb.conf</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">BUTTERNET</smbconfoption>
+<smbconfoption name="netbios name">GARGOYLE</smbconfoption>
+<smbconfoption name="realm">BUTTERNET.BIZ</smbconfoption>
+<smbconfoption name="security">ADS</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+<smbconfoption name="idmap uid">500-10000000</smbconfoption>
+<smbconfoption name="idmap gid">500-10000000</smbconfoption>
+<smbconfoption name="winbind use default domain">Yes</smbconfoption>
+<smbconfoption name="winbind nested groups">Yes</smbconfoption>
+<smbconfoption name="printer admin">"BUTTERNET\Domain Admins"</smbconfoption>
+</smbconfblock>
+</example>
+
+	<para>
+	<indexterm><primary>KRB</primary></indexterm>
+	<indexterm><primary>kerberos</primary></indexterm>
+	<indexterm><primary>/etc/krb5.conf</primary></indexterm>
+	<indexterm><primary>MIT</primary></indexterm>
+	<indexterm><primary>MIT kerberos</primary></indexterm>
+	<indexterm><primary>Heimdal</primary></indexterm>
+	<indexterm><primary>Heimdal kerberos</primary></indexterm>
+	ADS DMS operation requires use of kerberos (KRB). For this to work, the <filename>krb5.conf</filename>
+	must be configured. The exact requirements depends on which version of MIT or Heimdal Kerberos is being
+	used. It is sound advice to use only the latest version, which at this time are MIT Kerberos version
+	1.3.5 and Heimdal 0.61.
+	</para>
+
+	<para>
+	The creation of the DMS requires the following steps:
+	</para>
+
+	<procedure>
+		<step><para>
+		Create or install an &smb.conf; file with the above configuration.
+		</para></step>
+
+		<step><para>
+		Edit the <filename>/etc/nsswitch.conf</filename> file as shown above.
+		</para></step>
+
+		<step><para>
+		Execute:
+		<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>join</tertiary></indexterm>
+<screen>
+&rootprompt; net ads join -UAdministrator%password
+Joined domain BUTTERNET.
+</screen>
+	The success or failure of the join can be confirmed with the following command:
+<screen>
+&rootprompt; net ads testjoin
+Using short domain name -- BUTTERNET
+Joined 'GARGOYLE' to realm 'BUTTERNET.BIZ'
+</screen>
+	</para>
+
+	<para>
+	An invalid or failed join can be detected by executing:
+<screen>
+&rootprompt; net ads testjoin
+GARGOYLE$@'s password:
+[2004/11/05 16:53:03, 0] utils/net_ads.c:ads_startup(186)
+  ads_connect: No results returned
+Join to domain is not valid
+</screen>
+		<indexterm><primary>error message</primary></indexterm>
+		<indexterm><primary>failure</primary></indexterm>
+		<indexterm><primary>log level</primary></indexterm>
+		<indexterm><primary>identify</primary></indexterm>
+		The specific error message may differ from the above because it depends on the type of failure that
+		may have occurred. Increase the <parameter>log level</parameter> to 10, repeat the test,
+		and then examine the log files produced to identify the nature of the failure.
+		</para></step>
+
+		<step><para>
+		Start the <command>nmbd</command>, <command>winbind</command>, and <command>smbd</command> daemons in the order shown.
+		</para></step>
+
+	</procedure>
+
+	</sect3>
+	</sect2>
+
+	<sect2>
+	<title>IDMAP_RID with Winbind</title>
+
+	<para>
+	<indexterm><primary>idmap_rid</primary></indexterm>
+	<indexterm><primary>SID</primary></indexterm>
+	<indexterm><primary>RID</primary></indexterm>
+	<indexterm><primary>IDMAP</primary></indexterm>
+	The <command>idmap_rid</command> facility is a new tool that, unlike native winbind, creates a
+	predictable mapping of MS Windows SIDs to UNIX UIDs and GIDs. The key benefit of this method
+	of implementing the Samba IDMAP facility is that it eliminates the need to store the IDMAP data
+	in a central place. The downside is that it can be used only within a single ADS domain and
+	is not compatible with trusted domain implementations.
+	</para>
+
+	<para>
+	<indexterm><primary>SID</primary></indexterm>
+	<indexterm><primary>allow trusted domains</primary></indexterm>
+	<indexterm><primary>idmap uid</primary></indexterm>
+	<indexterm><primary>idmap gid</primary></indexterm>
+	This alternate method of SID to UID/GID  mapping can be achieved using the idmap_rid
+        plug-in. This plug-in uses the RID of the user SID to derive the UID and GID by adding the
+        RID to a base value specified. This utility requires that the parameter
+        <quote>allow trusted domains = No</quote> be specified, as it is not compatible
+        with multiple domain environments. The <parameter>idmap uid</parameter> and 
+	<parameter>idmap gid</parameter> ranges must be specified.
+	</para>
+
+	<para>
+	<indexterm><primary>idmap_rid</primary></indexterm>
+	<indexterm><primary>realm</primary></indexterm>
+	The idmap_rid facility can be used both for NT4/Samba-style domains and Active Directory.
+	To use this with an NT4 domain, do not include the <parameter>realm</parameter> parameter; additionally, the
+	method used to join the domain uses the <constant>net rpc join</constant> process.
+	</para>
+
+	<para>
+	An example &smb.conf; file for and ADS domain environment is shown in <link linkend="idmapadsridDMS">ADS
+	Domain Member smb.conf using idmap_rid</link>.
+	</para>
+
+<example id="idmapadsridDMS">
+<title>ADS Domain Member smb.conf using idmap_rid</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">KPAK</smbconfoption>
+<smbconfoption name="netbios name">BIGJOE</smbconfoption>
+<smbconfoption name="realm">CORP.KPAK.COM</smbconfoption>
+<smbconfoption name="server string">Office Server</smbconfoption>
+<smbconfoption name="security">ADS</smbconfoption>
+<smbconfoption name="allow trusted domains">No</smbconfoption>
+<smbconfoption name="idmap backend">idmap_rid:KPAK=500-100000000</smbconfoption>
+<smbconfoption name="idmap uid">500-100000000</smbconfoption>
+<smbconfoption name="idmap gid">500-100000000</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+<smbconfoption name="winbind use default domain">Yes</smbconfoption>
+<smbconfoption name="winbind enum users">No</smbconfoption>
+<smbconfoption name="winbind enum groups">No</smbconfoption>
+<smbconfoption name="winbind nested groups">Yes</smbconfoption>
+<smbconfoption name="printer admin">"Domain Admins"</smbconfoption>
+</smbconfblock>
+</example>
+
+	<para>
+	<indexterm><primary>large domain</primary></indexterm>
+	<indexterm><primary>Active Directory</primary></indexterm>
+	<indexterm><primary>response</primary></indexterm>
+	<indexterm><primary>getent</primary></indexterm>
+	In a large domain with many users it is imperative to disable enumeration of users and groups.
+	For example, at a site that has 22,000 users in Active Directory the winbind-based user and
+	group resolution is unavailable for nearly 12 minutes following first startup of 
+	<command>winbind</command>. Disabling enumeration resulted in instantaneous response.
+	The disabling of user and group enumeration means that it will not be possible to list users
+	or groups using the <command>getent passwd</command> and <command>getent group</command>
+	commands. It will be possible to perform the lookup for individual users, as shown in the following procedure.
+	</para>
+
+	<para>
+	<indexterm><primary>NSS</primary></indexterm>
+	<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+	The use of this tool requires configuration of NSS as per the native use of winbind. Edit the
+	<filename>/etc/nsswitch.conf</filename> so it has the following parameters:
+<screen>
+...
+passwd: files winbind
+shadow: files winbind
+group:  files winbind
+...
+hosts:  files wins
+...
+</screen>
+	</para>
+
+	<para>
+	The following procedure can use the idmap_rid facility:
+	</para>
+
+	<procedure>
+		<step><para>
+		Create or install an &smb.conf; file with the above configuration.
+		</para></step>
+
+		<step><para>
+		Edit the <filename>/etc/nsswitch.conf</filename> file as shown above.
+		</para></step>
+
+		<step><para>
+		Execute:
+<screen>
+&rootprompt; net ads join -UAdministrator%password
+Using short domain name -- KPAK
+Joined 'BIGJOE' to realm 'CORP.KPAK.COM'
+</screen>
+		</para>
+
+		<para>
+		<indexterm><primary>failed join</primary></indexterm>
+		An invalid or failed join can be detected by executing:
+<screen>
+&rootprompt; net ads testjoin
+BIGJOE$@'s password:
+[2004/11/05 16:53:03, 0] utils/net_ads.c:ads_startup(186)
+  ads_connect: No results returned
+Join to domain is not valid
+</screen>
+		The specific error message may differ from the above because it depends on the type of failure that
+		may have occurred. Increase the <parameter>log level</parameter> to 10, repeat the test,
+		and then examine the log files produced to identify the nature of the failure.
+		</para></step>
+
+		<step><para>
+		Start the <command>nmbd</command>, <command>winbind</command>, and <command>smbd</command> daemons in the order shown.
+		</para></step>
+
+		<step><para>
+		Validate the operation of this configuration by executing:
+		<indexterm><primary></primary></indexterm>
+<screen>
+&rootprompt; getent passwd administrator
+administrator:x:1000:1013:Administrator:/home/BE/administrator:/bin/bash
+</screen>
+		</para></step>
+	</procedure>
+
+	</sect2>
+
+	<sect2>
+	<title>IDMAP Storage in LDAP Using Winbind</title>
+
+	<para>
+	<indexterm><primary>ADAM</primary></indexterm>
+	<indexterm><primary>ADS</primary></indexterm>
+	The storage of IDMAP information in LDAP can be used with both NT4/Samba-3-style domains and
+	ADS domains. OpenLDAP is a commonly used LDAP server for this purpose, although any
+	standards-complying LDAP server can be used. It is therefore possible to deploy this IDMAP
+	configuration using the Sun iPlanet LDAP server, Novell eDirectory, Microsoft ADS plus ADAM,
+	and so on.
+	</para>
+
+	<para>
+	An example is for an ADS domain is shown in <link linkend="idmapldapDMS">ADS Domain Member Server using
+	LDAP</link>.
+	</para>
+
+<example id="idmapldapDMS">
+<title>ADS Domain Member Server using LDAP</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">SNOWSHOW</smbconfoption>
+<smbconfoption name="netbios name">GOODELF</smbconfoption>
+<smbconfoption name="realm">SNOWSHOW.COM</smbconfoption>
+<smbconfoption name="server string">Samba Server</smbconfoption>
+<smbconfoption name="security">ADS</smbconfoption>
+<smbconfoption name="log level">1 ads:10 auth:10 sam:10 rpc:10</smbconfoption>
+<smbconfoption name="ldap admin dn">cn=Manager,dc=SNOWSHOW,dc=COM</smbconfoption>
+<smbconfoption name="ldap idmap suffix">ou=Idmap</smbconfoption>
+<smbconfoption name="ldap suffix">dc=SNOWSHOW,dc=COM</smbconfoption>
+<smbconfoption name="idmap backend">ldap:ldap://ldap.snowshow.com</smbconfoption>
+<smbconfoption name="idmap uid">150000-550000</smbconfoption>
+<smbconfoption name="idmap gid">150000-550000</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+<smbconfoption name="winbind use default domain">Yes</smbconfoption>
+</smbconfblock>
+</example>
+
+	<para>
+	<indexterm><primary>realm</primary></indexterm>
+	In the case of an NT4 or Samba-3-style domain the <parameter>realm</parameter> is not used, and the
+	command used to join the domain is <command>net rpc join</command>. The above example also demonstrates
+	advanced error-reporting techniques that are documented in <link linkend="dbglvl">Reporting Bugs</link>.
+	</para>
+
+	<para>
+	<indexterm><primary>MIT kerberos</primary></indexterm>
+	<indexterm><primary>Heimdal kerberos</primary></indexterm>
+	<indexterm><primary>/etc/krb5.conf</primary></indexterm>
+	Where MIT kerberos is installed (version 1.3.4 or later), edit the <filename>/etc/krb5.conf</filename> 
+	file so it has the following contents:
+<screen>
+[logging]
+ default = FILE:/var/log/krb5libs.log
+ kdc = FILE:/var/log/krb5kdc.log
+ admin_server = FILE:/var/log/kadmind.log
+
+[libdefaults]
+ default_realm = SNOWSHOW.COM
+ dns_lookup_realm = false
+ dns_lookup_kdc = true
+
+[appdefaults]
+ pam = {
+   debug = false
+   ticket_lifetime = 36000
+   renew_lifetime = 36000
+   forwardable = true
+   krb4_convert = false
+ }
+</screen>
+	</para>
+
+	<para>
+	Where Heimdal kerberos is installed, edit the <filename>/etc/krb5.conf</filename>
+        file so it is either empty (i.e., no contents) or it has the following contents:
+<screen>
+[libdefaults]
+        default_realm = SNOWSHOW.COM
+        clockskew = 300
+
+[realms]
+        SNOWSHOW.COM = {
+                kdc = ADSDC.SHOWSHOW.COM
+        }
+        
+[domain_realm]
+        .snowshow.com = SNOWSHOW.COM
+</screen>
+	</para>
+
+	<note><para>
+	Samba cannot use the Heimdal libraries if there is no <filename>/etc/krb5.conf</filename> file.
+	So long as there is an empty file, the Heimdal kerberos libraries will be usable. There is no
+	need to specify any settings because Samba, using the Heimdal libraries, can figure this out automatically.
+	</para></note>
+
+	<para>
+	Edit the NSS control file <filename>/etc/nsswitch.conf</filename> so it has the following entries:
+<screen>
+...
+passwd: files ldap
+shadow: files ldap
+group:  files ldap
+...
+hosts:  files wins
+...
+</screen>
+	</para>
+
+	<para>
+	<indexterm><primary>PADL</primary></indexterm>
+	<indexterm><primary>/etc/ldap.conf</primary></indexterm>
+	You will need the <ulink url="http://www.padl.com">PADL</ulink> <command>nss_ldap</command> 
+	tool set for this solution. Configure the <filename>/etc/ldap.conf</filename> file so it has 
+	the information needed. The following is an example of a working file:
+<screen>
+host    192.168.2.1
+base    dc=snowshow,dc=com
+binddn  cn=Manager,dc=snowshow,dc=com
+bindpw  not24get
+
+pam_password exop
+
+nss_base_passwd ou=People,dc=snowshow,dc=com?one
+nss_base_shadow ou=People,dc=snowshow,dc=com?one
+nss_base_group  ou=Groups,dc=snowshow,dc=com?one
+ssl     no
+</screen>
+	</para>
+
+	<para>
+	The following procedure may be followed to effect a working configuration:
+	</para>
+
+	<procedure>
+		<step><para>
+		Configure the &smb.conf; file as shown above.
+		</para></step>
+
+		<step><para>
+		Create the <filename>/etc/krb5.conf</filename> file as shown above.
+		</para></step>
+
+		<step><para>
+		Configure the <filename>/etc/nsswitch.conf</filename> file as shown above.
+		</para></step>
+
+		<step><para>
+		Download, build, and install the PADL nss_ldap tool set. Configure the 
+		<filename>/etc/ldap.conf</filename> file as shown above.
+		</para></step>
+
+		<step><para>
+		Configure an LDAP server and initialize the directory with the top-level entries needed by IDMAP,
+		shown in the following LDIF file:
+<screen>
+dn: dc=snowshow,dc=com
+objectClass: dcObject
+objectClass: organization
+dc: snowshow
+o: The Greatest Snow Show in Singapore.
+description: Posix and Samba LDAP Identity Database
+
+dn: cn=Manager,dc=snowshow,dc=com
+objectClass: organizationalRole
+cn: Manager
+description: Directory Manager
+
+dn: ou=Idmap,dc=snowshow,dc=com
+objectClass: organizationalUnit
+ou: idmap
+</screen>
+		</para></step>
+
+		<step><para>
+		Execute the command to join the Samba DMS to the ADS domain as shown here:
+<screen>
+&rootprompt; net ads testjoin
+Using short domain name -- SNOWSHOW
+Joined 'GOODELF' to realm 'SNOWSHOW.COM'
+</screen>
+		</para></step>
+
+		<step><para>
+		Store the LDAP server access password in the Samba <filename>secrets.tdb</filename> file as follows:
+<screen>
+&rootprompt; smbpasswd -w not24get
+</screen>
+		</para></step>
+
+		<step><para>
+		Start the <command>nmbd</command>, <command>winbind</command>, and <command>smbd</command> daemons in the order shown.
+		</para></step>
+	</procedure>
+
+	<para>
+	<indexterm><primary>diagnostic</primary></indexterm>
+	Follow the diagnositic procedures shown earlier in this chapter to identify success or failure of the join.
+	In many cases a failure is indicated by a silent return to the command prompt with no indication of the
+	reason for failure.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>IDMAP and NSS Using LDAP from ADS with RFC2307bis Schema Extension</title>
+
+	<para>
+	<indexterm><primary>rfc2307bis</primary></indexterm>
+	<indexterm><primary>schema</primary></indexterm>
+	The use of this method is messy. The information provided in the following is for guidance only
+	and is very definitely not complete. This method does work; it is used in a number of large sites
+	and has an acceptable level of performance.
+	</para>
+
+	<para>
+	An example &smb.conf; file is shown in <link linkend="idmaprfc2307">ADS Domain Member Server using
+RFC2307bis Schema Extension Date via NSS</link>.
+	</para>
+
+<example id="idmaprfc2307">
+<title>ADS Domain Member Server using RFC2307bis Schema Extension Date via NSS</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">BOBBY</smbconfoption>
+<smbconfoption name="realm">BOBBY.COM</smbconfoption>
+<smbconfoption name="security">ADS</smbconfoption>
+<smbconfoption name="idmap uid">150000-550000</smbconfoption>
+<smbconfoption name="idmap gid">150000-550000</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+<smbconfoption name="winbind cache time">5</smbconfoption>
+<smbconfoption name="winbind use default domain">Yes</smbconfoption>
+<smbconfoption name="winbind trusted domains only">Yes</smbconfoption>
+<smbconfoption name="winbind nested groups">Yes</smbconfoption>
+</smbconfblock>
+</example>
+
+	<para>
+	<indexterm><primary>nss_ldap</primary></indexterm>
+	The DMS must be joined to the domain using the usual procedure. Additionally, it is necessary
+	to build and install the PADL nss_ldap tool set. Be sure to build this tool set with the
+	following:
+<screen>
+./configure --enable-rfc2307bis --enable-schema-mapping
+make install
+</screen> 
+	</para>
+
+	<para>
+	<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+	The following <filename>/etc/nsswitch.conf</filename> file contents are required:
+<screen>
+...
+passwd: files ldap
+shadow: files ldap
+group:  files ldap
+...
+hosts:  files wins
+...
+</screen>
+	</para>
+
+	<para>
+	<indexterm><primary>/etc/ldap.conf</primary></indexterm>
+	<indexterm><primary>nss_ldap</primary></indexterm>
+	The <filename>/etc/ldap.conf</filename> file must be configured also. Refer to the PADL documentation
+	and source code for nss_ldap to specific instructions.
+	</para>
+
+	<para>
+	The next step involves preparation of the ADS schema. This is briefly discussed in the remaining
+	part of this chapter.
+	</para>
+
+		<sect3>
+		<title>IDMAP, Active Directory, and MS Services for UNIX 3.5</title>
+
+		<para>
+		<indexterm><primary>SFU</primary></indexterm>
+		The Microsoft Windows Service for UNIX (SFU) version 3.5 is available for free 
+		<ulink url="http://www.microsoft.com/windows/sfu/">download</ulink>
+		from the Microsoft Web site. You will need to download this tool and install it following
+		Microsoft instructions.
+		</para>
+
+		</sect3>
+
+		<sect3>
+		<title>IDMAP, Active Directory and AD4UNIX</title>
+
+		<para>
+		Instructions for obtaining and installing the AD4UNIX tool set can be found from the
+		<ulink url="http://www.geekcomix.com/cgi-bin/classnotes/wiki.pl?LDAP01/An_Alternative_Approach">
+		Geekcomix</ulink> Web site.
+		</para>
+
+		</sect3>
+
+	</sect2>
+
+</sect1>
+
+</chapter>