More work in progress - further commits to follow.

[Samba.git] / docs / Samba-HOWTO-Collection / IDMAP.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

  <!-- entities files to use -->
  <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
  %global_entities;

]>

<chapter id="idmapper">
<chapterinfo>
        &author.jht;
</chapterinfo>

<title>Identity Mapping (IDMAP)</title>

<note><para>
THIS IS A WORK IN PROGRESS - it is a preparation for the release of Samba-3.0.8.
</para></note>

<para>
The Microsoft Windows operating system has a number of features that impose specific challenges
to interoperability with operating system 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 Identify Mapping (IDMAP) of Windows Security Identifers (SIDs)
to UNIX UIDs and GIDs.
</para>

<para>
To ensure good sufficient coverage each possible Samba deployment type will be discussed.
This is followed by an overview of how the IDMAP facility may be implemented.
</para>

<para>
The IDMAP facility is usually of concern where more than one Samba server (or Samba network client)
is installed in the one Domain. Where there is a single Samba server do not be too concerned regarding
the IDMAP infrastructure - the default behavior of Samba is nearly always sufficient.
</para>

<para>
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>
The use of the IDMAP facility requires that the <command>winbindd</command> be executed on Samba start-up.
</para>

<sect1>
<title>Samba Server Deployment Types</title>

<para>
There are four (4) basic server deployment types, as documented in <link linkend="ServerType">the chapter
on Server Types and Security Modes</link>.
</para>

        <sect2>
        <title>Stand-Alone Samba Server</title>

        <para>
        A stand-alone Samba server is an implementation that is not a member of a Windows NT4 Domain,
        a Windows 200X Active Directory Domain, or of a Samba Domain.
        </para>

        <para>
        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>
        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 version of Microsoft Windows products. Windows NT4, as with Microsoft Active Directory, i
        extensively makes use of Windows security identifiers (SIDs).
        </para>

        <para>
        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>
        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 is will use 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: &smbmdash; </term>
                        <listitem>
                                <para>
                                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 will be 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 <quote>users and groups are local</quote>
                                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>
                                For example, if an incoming SessionSetupAndX request is owned by the user
                                <constant>BERYLIUM\WambatW</constant>, a system call will be made to look up
                                the user <constant>WambatW</constant> in the <filename>/etc/passwd</filename>
                                file.
                                </para>

                                <para>
                                This configuration may be used with stand-alone Samba servers, Domain Member
                                servers (NT4 or ADS), and may be used 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: &smbmdash; </term>
                        <listitem>
                                <para>
                                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 a NIS type database or else in LDAP.
                                </para>

                                <para>
                                This configuration may be used with stand-alone Samba servers, Domain Member
                                servers (NT4 or ADS), and may be used 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: &smbmdash; </term>
                        <listitem>
                                <para>
                                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>
                                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>
                                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 may become corrupted or lost, the repaired or rebuilt IDMAP file may allocate
                                UIDs and GIDs to differing 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
                                to rightful owner.
                                </para>
                        </listitem>
                </varlistentry>

                <varlistentry><term>Winbind with an NSS/LDAP backend based IDMAP facility: &smbmdash; </term>
                        <listitem>
                                <para>
                                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>
                                It is important that all LDAP IDMAP clients use only the master LDAP server as 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: &smbmdash; </term>
                        <listitem>
                                <para>
                                When Samba is being used as the PDC and BDC the of an LDAP passdb backend is a smart
                                solution, certainly for the domain controllers, but also for Domain Member servers.
                                It is a neat method for assuring that UIDs, GIDs and the matching SIDs will be consistent
                                across all servers.
                                </para>

                                <para>
                                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; ie: SIDs from
                                stand-alone 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>
                                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 else use the Microsoft Services for UNIX
                                version 3.5 of 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 in 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>

                <varlistentry><term>Winbind/NSS uses RID based IDMAP: &smbmdash; </term>
                        <listitem>
                                <para>
                                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, who do not want to apply
                                an ADS schema extension, and who do not wish to install 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>
                                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 sub-set 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>

        </variablelist>

        </sect2>

        <sect2>
        <title>Primary Domain Controller</title>

        <para>
        Microsoft Windows domain security systems generate the user and group security identifier (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 a relative identifier (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.
        </para>

        <para>
        For example, a user has a UID of 4321, and the algorithmic RID base has a value of 1000, the RID will
        be <constant>1000 + (2 x 4321) = 9642</constant>. Thus, if the domain SID is
        <constant>S-1-5-21-89238497-92787123-12341112</constant>, the resulting SID is
        <constant>S-1-5-21-89238497-92787123-12341112-9642</constant>.
        </para>

        <para>
        The foregoing type SID is produced by Samba as an automatic function and is either produced on-the-fly
        (as in 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>
        MS Active Directory Server (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>
        Security identifiers used within a domain must be managed to avoid conflict and to preserve itegrity.
        In an NT4 domain context that PDC manages the distribution of all security credentials to the backup
        domain controllers. 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>
        Backup Domain Controllers (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 however 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>IDMAP Backend Usage</title>

<para>
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>
        The following is a simple example of an NT4 DMS &smb.conf; file that shows only the global section.
<screen>
#Global parameters
[global]
        workgroup = MEGANET2
        security = DOMAIN
        idmap uid = 10000-20000
        idmap gid = 10000-20000
        template primary group = "Domain Users"
        template shell = /bin/bash
        winbind separator = +
</screen>
        </para>

        <para>
        The creation of the DMS requires the following steps:
        </para>

        <procedure>
                <step><para>
                Create or install and &smb.conf; file with the above configuration.
                </para></step>

                <step><para>
                Execute:
<screen>
&rootprompt; net rpc join -UAdministrator%password
Joined domain MEGANET2.
</screen>
        The success or failure 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 the following:
<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>
                Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown.
                </para></step>
        </procedure>

        <para>
        The procedure for joining and ADS domain is similar to the NT4 domain join, except the &smb.conf; file
        will have the following contents:
<screen>
# Global parameters
[global]
        workgroup = BUTTERNET
        netbios name = GARGOYLE
        realm = BUTTERNET.BIZ
        security = ADS
        template shell = /bin/bash
        idmap uid = 500-10000000
        idmap gid = 500-10000000
        winbind use default domain = Yes
        winbind nested groups = Yes
        printer admin = "BUTTERNET\Domain Admins"
</screen>
        </para>

        <para>
        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 and &smb.conf; file with the above configuration.
                </para></step>

                <step><para>
                Execute:
<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
Join to 'BUTTERNET' is OK
</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>
                </para></step>

                <step><para>
                Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown.
                </para></step>

        </procedure>

        </sect2>

        <sect2>
        <title>IDMAP Storage in LDAP using Winbind</title>

        <para>
<screen>
# Global parameters
[global]
        workgroup = SNOWSHOW
        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>

        </sect2>

        <sect2>
        <title>IDMAP and NSS IDMAP Resolution</title>

        <para>
<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>

                <sect3>
                <title>IDMAP, Active Directory and MS Services for UNIX 3.5</title>

                <para>
                </para>

                </sect3>

                <sect3>
                <title>IDMAP, Active Directory and AD4UNIX</title>

                <para>
                </para>

                </sect3>

        </sect2>

        <sect2>
        <title>IDMAP_RID with Winbind</title>

        <para>
<screen>
# Global parameters
[global]
        workgroup = KPAK
        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>

        </sect2>

</sect1>

</chapter>