1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
5 <!-- entities files to use -->
6 <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
11 <chapter id="idmapper">
16 <title>Identity Mapping (IDMAP)</title>
19 THIS IS A WORK IN PROGRESS - it is a preparation for the release of Samba-3.0.8.
23 The Microsoft Windows operating system has a number of features that impose specific challenges
24 to interoperability with operating system on which Samba is implemented. This chapter deals
25 explicitly with the mechanisms Samba-3 (version 3.0.8 and later) uses to overcome one of the
26 key challenges in the integration of Samba servers into an MS Windows networking environment.
27 This chapter deals with IDentity MAPping (IDMAP) of Windows Security IDentifiers (SIDs)
28 to UNIX UIDs and GIDs.
32 To ensure good sufficient coverage each possible Samba deployment type will be discussed.
33 This is followed by an overview of how the IDMAP facility may be implemented.
37 The IDMAP facility is usually of concern where more than one Samba server (or Samba network client)
38 is installed in the one Domain. Where there is a single Samba server do not be too concerned regarding
39 the IDMAP infrastructure - the default behavior of Samba is nearly always sufficient.
43 The use of IDMAP is important where the Samba server will be accessed by workstations or servers from
44 more than one domain, in which case it is important to run winbind so it can handle the resolution (ID mapping)
45 of foreign SIDs to local UNIX UIDs and GIDs.
49 The use of the IDMAP facility requires that the <command>winbindd</command> be executed on Samba start-up.
53 <title>Samba Server Deployment Types</title>
56 There are four (4) basic server deployment types, as documented in <link linkend="ServerType">the chapter
57 on Server Types and Security Modes</link>.
61 <title>Stand-Alone Samba Server</title>
64 A stand-alone Samba server is an implementation that is not a member of a Windows NT4 Domain,
65 a Windows 200X Active Directory Domain, or of a Samba Domain.
69 By definition, this means that users and groups will be created and controlled locally and
70 the identity of a network user must match a local UNIX/Linux user login. The IDMAP facility
71 is therefore of little to no interest, winbind will not be necessary, and the IDMAP facility
72 will not be relevant or of interest.
78 <title>Domain Member Server or Domain Member Client</title>
81 Samba-3 can act as a Windows NT4 PDC or BDC thereby providing domain control protocols that
82 are compatible with Windows NT4. Samba-3 file and print sharing protocols are compatible with
83 all version of Microsoft Windows products. Windows NT4, as with Microsoft Active Directory, i
84 extensively makes use of Windows security identifiers (SIDs).
88 Samba-3 Domain Member servers and clients must interact correctly with MS Windows SIDs. Incoming
89 Windows SIDs must be translated to local UNIX UIDs and GIDs. Outgoing information from the Samba
90 server must provide to MS Windows clients and servers appropriate SIDs.
94 A Samba member of a Windows networking domain (NT4-style or ADS) can be configured to handle
95 identity mapping in a variety of ways. The mechanism is will use depends on whether or not
96 the <command>winbindd</command> daemon is used, and how the winbind functionality is configured.
97 The configuration options are briefly described here:
101 <varlistentry><term>Winbind is not used, users and groups are local: &smbmdash; </term>
104 Where <command>winbindd</command> is not used Samba (<command>smbd</command>)
105 uses the underlying UNIX/Linux mechanisms to resolve the identity of incoming
106 network traffic. This will be done using the LoginID (account name) in the
107 session setup request and passing it to the getpwnam() system function call.
108 This call is implemented using the name service switch (NSS) mechanism on
109 modern UNIX/Linux systems. By saying <quote>users and groups are local</quote>
110 we are implying that they are stored only on the local system, in the
111 <filename>/etc/passwd</filename> and <filename>/etc/group</filename> respectively.
115 For example, if an incoming SessionSetupAndX request is owned by the user
116 <constant>BERYLIUM\WambatW</constant>, a system call will be made to look up
117 the user <constant>WambatW</constant> in the <filename>/etc/paswwd</filename>
122 This configuration may be used with stand-alone Samba servers, Domain Member
123 servers (NT4 or ADS), and may be used for a PDC that uses either an smbpasswd
124 or a tdbsam based Samba passdb backend.
129 <varlistentry><term>Winbind is not used, users and groups resolved via NSS: &smbmdash; </term>
132 In this situation user and group accounts are treated as if they are local
133 accounts, the only way in which this differs from having local accounts is
134 that the accounts are stored in a repository that can be shared. In practice
135 this means that they will reside in either a NIS type database or else in LDAP.
139 This configuration may be used with stand-alone Samba servers, Domain Member
140 servers (NT4 or ADS), and may be used for a PDC that uses either an smbpasswd
141 or a tdbsam based Samba passdb backend.
146 <varlistentry><term>Winbind/NSS with the default local IDMAP table: &smbmdash; </term>
149 There are many sites that require only a simple Samba server, or a single Samba
150 server that is a member of a Windows NT4 Domain or an ADS Domain. A typical example
151 is an appliance like file server on which no local accounts are configured and
152 winbind is used to obtain account credentials from the domain controllers for the
153 domain. The domain control can be provided by Samba-3, MS Windows NT4 or MS Windows
158 Winbind is a great convenience in this situation. All that is needed is a range of
159 UID numbers and GID numbers that can be defined in the &smb.conf; file, the
160 <filename>/etc/nsswitch.conf</filename> file is configued to use <command>winbind</command>
161 which does all the difficult work of mapping incoming SIDs to appropriate UIDs and GIDs.
162 The SIDs are allocated a UID/GID in the order in which winbind receives them.
166 This configuration is not convenient or practical in sites that have more than one
167 Samba server and that require the same UID or GID for the same user or group across
168 all servers. One of the hazards of this method is that in the event that the winbind
169 IDMAP file may become corrupted or lost, the repaired or rebuilt IDMAP file may allocate
170 UIDs and GIDs to differing users and groups from what was there previously with the
171 result that MS Windows files that are stored on the Samba server may now not belong to
177 <varlistentry><term>Winbind with an NSS/LDAP backend based IDMAP facility: &smbmdash; </term>
180 In this configuration <command>winbind</command> resolved SIDs to UIDs and GIDs from
181 the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter> ranges specified
182 in the &smb.conf; file, but instead of using a local winbind IDMAP table it is stored
183 in an LDAP directory so that all Domain Member machines (clients and servers) can share
184 a common IDMAP table.
188 It is important that all LDAP IDMAP clients use only the master LDAP server as the
189 <parameter>idmap backend</parameter> facility in the &smb.conf; file does not correctly
190 handle LDAP redirects.
195 <varlistentry><term>Winbind with NSS to resolve UNIX/Linux user and group IDs: &smbmdash; </term>
198 When Samba is being used as the PDC and BDC the of an LDAP passdb backend is a smart
199 solution, certainly for the domain controllers, but also for Domain Member servers.
200 It is a neat method for assuring that UIDs, GIDs and the matching SIDs will be consistent
205 The use of the LDAP based passdb backend requires use of the PADL nss_ldap utility, or
206 an equivalent. In this situation winbind is used to handle foreign SIDs; ie: SIDs from
207 stand-alone Windows clients (i.e.: not a member of our domain) as well as SIDs from
208 another domain. The foreign UID/GID is mapped from allocated ranges (idmap uid and idmap gid)
209 in precisely the same manner as when using winbind with a local IDMAP table.
213 The nss_ldap tool set can be used to access UIDs and GIDs via LDAP as well as via Active
214 Directory. In order to use Active Directory it is necessary to modify the ADS schema by
215 installing either the AD4UNIX schema extension or else use the Microsoft Services for UNIX
216 version 3.5 of later to extend the ADS schema so it maintains UNIX account credentials.
217 Where the ADS schema is extended a Microsoft Management Console (MMC) snap-in in also
218 installed to permit the UNIX credentials to be set and managed from the ADS User and Computer
219 managment tool. Each account must be separately UNIX enabled before the UID and GID data can
225 <varlistentry><term>Winbind/NSS uses RID based IDMAP: &smbmdash; </term>
228 The IDMAP_RID facility is new to Samba version 3.0.8. It was added to make life easier
229 for a number of sites that are committed to use of MS ADS, who do not want to apply
230 an ADS schema extension, and who do not wish to install an LDAP directory server just for
231 the purpose of maintaining an IDMAP table. If you have a single ADS domain (not a forest of
232 domains, and not mutiple domain trees) and you want a simple cookie-cutter solution to the
233 IDMAP table problem, then IDMAP_RID is an obvious choice.
237 This facility requires the allocation of the <parameter>idmap uid</parameter> and the
238 <parameter>idmap gid</parameter> ranges, and within the <parameter>idmap uid</parameter>
239 it is possible to allocate a sub-set of this range for automatic mapping of the relative
240 identifier (RID) portion of the SID directly to the base of the UID plus the RID value.
241 For example, if the <parameter>idmap uid</parameter> range is <constant>1000-100000000</constant>
242 and the <parameter>idmap backend = idmap_rid:DOMAIN_NAME=1000-50000000</parameter>, and
243 a SID is encountered that has the value <constant>S-1-5-21-34567898-12529001-32973135-1234</constant>,
244 the resulting UID will be <constant>1000 + 1234 = 2234</constant>.
254 <title>Primary Domain Controller</title>
257 Microsoft Windows domain security systems generate the user and group security identifier (SID) as part
258 of the process of creation of an account. Windows does not have a concept of a UID or a GID.
262 MS Active Directory Server (ADS) uses a directory schema that can be extended to accommodate additional
263 account attributes such as UIDs and GIDs.
269 <title>Backup Domain Controller</title>
279 <title>IDMAP Backend Usage</title>
285 <title>Default Winbind TDB</title>
293 <title>IDMAP Storage in LDAP using Winbind</title>
301 <title>IDMAP and NSS IDMAP Resolution</title>
307 <title>IDMAP, Active Directory and MS Services for UNIX 3.5</title>
315 <title>IDMAP, Active Directory and AD4UNIX</title>
325 <title>IDMAP_RID with Winbind</title>