Update to add IDMAP_RID info etc.

(This used to be commit fe76e2461397e72b7a91aa8ed606bf0dd28bc558)

1 files changed, 440 insertions, 1 deletions

diff --git a/docs/Samba-Guide/SBE-AddingUNIXClients.xml b/docs/Samba-Guide/SBE-AddingUNIXClients.xml
index 3baa02e28e..c7656f8b58 100644
--- a/docs/Samba-Guide/SBE-AddingUNIXClients.xml
+++ b/docs/Samba-Guide/SBE-AddingUNIXClients.xml
@@ -1681,7 +1681,446 @@ data = "\00\00\00\00bp\00\00\06krbtgt\06krbtgt-
 <smbconfoption name="write list">root</smbconfoption>
 </smbconfexample>
 
-	</sect2>
+        <sect3>
+        <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 down-side 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 uses 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> must 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 as well as with Active Directory.
+        To use this with an NT4 Domain the <parameter>realm</parameter> is not used, 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 here:
+<screen>
+# Global parameters
+[global]
+        workgroup = KPAK
+        netbios name = BIGJOE
+        realm = CORP.KPAK.COM
+        server string = Office Server
+        security = ADS
+        allow trusted domains = No
+        idmap backend = idmap_rid:KPAK=500-100000000
+        idmap uid = 500-100000000
+        idmap gid = 500-100000000
+        template shell = /bin/bash
+        winbind use default domain = Yes
+        winbind enum users = No
+        winbind enum groups = No
+        winbind nested groups = Yes
+        printer admin = "Domain Admins"
+</screen>
+        </para>
+
+        <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 examplem, 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 start-up of
+        <command>winbind</command>. Disabling of such 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 procedure
+        below.
+        </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 be used to utilize the idmap_rid facility:
+        </para>
+
+        <procedure>
+                <step><para>
+                Create or install and &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 as it depends on the type of failure that
+                may have occured. Increase the <parameter>log level</parameter> to 10, repeat the above test
+                and then examine the log files produced to identify the nature of the failure.
+                </para></step>
+
+                <step><para>
+                Start the <command>nmbd, 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>
+
+        </sect3>
+
+        <sect3>
+        <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 as well as
+        with 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>
+        The following example is for an ADS style domain:
+        </para>
+
+        <para>
+<screen>
+# Global parameters
+[global]
+        workgroup = SNOWSHOW
+        netbios name = GOODELF
+        realm = SNOWSHOW.COM
+        server string = Samba Server
+        security = ADS
+        log level = 1 ads:10 auth:10 sam:10 rpc:10
+        ldap admin dn = cn=Manager,dc=SNOWSHOW,dc=COM
+        ldap idmap suffix = ou=Idmap
+        ldap suffix = dc=SNOWSHOW,dc=COM
+        idmap backend = ldap:ldap://ldap.snowshow.com
+        idmap uid = 150000-550000
+        idmap gid = 150000-550000
+        template shell = /bin/bash
+        winbind use default domain = Yes
+</screen>
+        </para>
+        <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">the chapter called
+        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 can not 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 as 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 affect 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 following the indications 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, initialize the directory with the top level entries needed by IDMAP
+                as 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 Domain Member Server 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, 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>
+
+        </sect3>
+
+        <sect3>
+        <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>
+        The following is an example &smb.conf; file:
+<screen>
+# Global parameters
+[global]
+        workgroup = BOBBY
+        realm = BOBBY.COM
+        security = ADS
+        idmap uid = 150000-550000
+        idmap gid = 150000-550000
+        template shell = /bin/bash
+        winbind cache time = 5
+        winbind use default domain = Yes
+        winbind trusted domains only = Yes
+        winbind nested groups = Yes
+</screen>
+        </para>
+
+        <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 on the ADS schema. This is briefly discussed in the remaining
+        part of this chapter.
+        </para>
+
+                <sect4>
+                <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>
+
+                </sect4>
+
+                <sect4>
+                <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>
+
+                </sect4>
+
+        </sect3>
+
+        </sect2>
+
 
 	<sect2>
 	<title>UNIX/Linux Client Domain Member</title>