General Information, Including Pros & Cons, And Examples, Of Various Identity Mapping (idmap) Options

idmap_ad

• Allows the administrator to coordinate across multiple systems, including UNIX
• This option can be utilized to ensure matching ids on both the NFS client and NFS server
• UID/GID mappings match the Active Directory (AD) side exactly

• Services For UNIX (SFU) or Identity Management for Unix (depending on the version of Windows Server installed) must be installed on the AD server

• An NIS Domain must be installed

• POSIX UID and GID must be added by the AD administrator to the user object(s) in AD (either manually or through a script, if possible), and to the group objects. User/Group objects must belong to the NIS domain

• Tighter Samba security now requires that the User must belong to a Primary Group, and the Group, in turn, must see the User as a Member (Unix and Windows tabs)

Samba.org doc

Description

Examples

• Useful if AD is not in the environment and if coordination between servers is desired
• Mapping are stored in ldap, instead of a local trivial database (*.tdb file)
• SLE 11 versions can be configured with a different, writable alloc backend (tdb, etc)

• Users are allocated on a first come, first serve basis
• Need to have ldap setup

Samba.org doc

Description

Examples

• Allows utilization of other existing systems, such as NIS or the standard /etc/passwd to allocate names

• Should only be used for one domain at a time

Samba.org doc

Description

Examples

• Easy to setup
• Because idmap_rid is deterministic, UIDs and GIDs across multiple machines will be the same as long as the deterministic values utilized by rid are the same; namely, the rid, rid_offset parameter, and the range

• Only works for one domain at a time. Be sure that each domain gets configured with a range that doesn't overlap with another

Samba.org doc

Description

Examples

• Easy to setup, and there wont be any conflicts
• Can work for all domains, even trusted ones

• Mapping is guaranteed to be local to the server. This is not the option needed if mappings need to be identical across multiple servers
• No algorithm is used, and UIDs and GIDs are assigned on a first come, first serve basis. If the local /var/lib/samba/*.tdb files are lost, so are the mappings. Backup these files regularly

Samba.org doc

Description

Examples

• Allows mappings across multiple servers because it is deterministic
• Allows multiple domains

• idmap_hash is deterministic, and utilizes the "range" for its algorithm. If the range changes, so does the algorithm
• It is possible, yet rare, for two AD SIDs to be mapped to a single UID. In this case, one of the SIDs would need to be changed. Also, if the highest rated RID in the domain is greater than 2^19th, the plugin will suffer from integer overflow
• Unique to SAMBA

Samba.org doc

Description

Examples

The idmap_ad plugin provides a way for Winbind to read id mappings from an AD server that uses RFC2307/SFU schema . This module implements only the "idmap" API, and is READONLY. Mappings must be provided in advance by the administrator by adding the uidNumber attributes for users and gidNumber attributes for groups in the AD. Winbind will only map users that have a uidNumber and whose primary group have a gidNumber attribute set. It is however recommended that all groups in use have gidNumber attributes assigned, otherwise they are not working.

Currently, the ad backend does not work as the the default idmap backend, but one has to configure it separately for each domain for which one wants to use it, using disjoint ranges. One usually needs to configure a writeable default idmap range, using for example the tdb or ldap backend, in order to be able to map the BUILTIN sids and possibly other trusted domains. The writeable default config is also needed in order to be able to create group mappings. This catch-all default idmap configuration should have a range that is disjoint from any explicitly configured domain with idmap backend ad. See the example below.

Top

The idmap_ldap plugin provides a means for Winbind to store and retrieve SID/uid/gid mapping tables in an LDAP directory service.

In contrast to read only backends like idmap_rid, it is an allocating backend: This means that it needs to allocate new user and group IDs in order to create new mappings. The allocator can be provided by the idmap_ldap backend itself or by any other allocating backend like idmap_tdb or idmap_tdb2. This is configured with the parameter idmap alloc backend.

Note that in order for this (or any other allocating) backend to function at all, the default backend needs to be writeable. The ranges used for uid and gid allocation are the default ranges configured by "idmap uid" and "idmap gid".

Furthermore, since there is only one global allocating backend responsible for all domains using writeable idmap backends, any explicitly configured domain with idmap backend ldap should have the same range as the default range, since it needs to use the global uid / gid allocator.

The following example shows how an ldap directory is used as the default idmap backend. It also configures the idmap range and base directory suffix. The secret for the ldap_user_dn has to be set with "net idmap secret '*' password".

This example shows how ldap can be used as a readonly backend while tdb is the default backend used to store the mappings. It adds an explicit configuration for some domain DOM1, that uses the ldap idmap backend. Note that a range disjoint from the default range is used.

Top

The idmap_nss plugin provides a means to map Unix users and groups to Windows accounts and obseletes the "winbind trusted domains only" smb.conf option. This provides a simple means of ensuring that the SID for a Unix user named jsmith is reported as the one assigned to DOMAIN\jsmith which is necessary for reporting ACLs on files and printers stored on a Samba member server.

  [global]
        idmap config * : backend = tdb
        idmap config * : range = 1000000-1999999
       
        idmap config SAMBA : backend = nss
        idmap config SAMBA : range = 1000-999999       

Top

The idmap_rid backend provides a way to use an algorithmic mapping scheme to map UIDs/GIDs and SIDs. No database is required in this case as the mapping is deterministic.

Note that the idmap_rid module has changed considerably since Samba versions 3.0. and 3.2. Currently, there should to be an explicit idmap configuration for each domain that should use the idmap_rid backend, using disjoint ranges. One usually needs to define a writeable default idmap range, using a backend like tdb or ldap that can create unix ids, in order to be able to map the BUILTIN sids and other domains, and also in order to be able to create group mappings. 

See the example below.

Note that the old syntax idmap backend = rid:"DOM1=range DOM2=range2 ..." is not supported any more since Samba version 3.0.25.

                  [global]     

security = domain      workgroup = MAIN       
                  idmap config * : backend        = tdb     
                  idmap config * : range          = 1000000-1999999       
                 
                  idmap config MAIN : backend     = rid
                  idmap config MAIN : range       = 10000 - 49999       
                 
                  idmap config TRUSTED : backend  = rid
                  idmap config TRUSTED : range    = 50000 - 99999     
                  idmap config TRUSTED : base_rid = 1000

 See TID 7016070: How To Set Up A Basic idmap_rid Backend on SLES 11 SP 2  for a walkthrough. TID 7016070 is maintained more frequently than this TID (7007006).  It will have more up-to-date examples.

The original, and most simple of all of the configurations. Local database files are stored under /var/lib/samba/*tdb. If these files are lost, so are your mappings. It wouldn't be a bad idea to back these up regularly.

The idmap_tdb plugin is the default backend used by winbindd for storing SID/uid/gid mapping tables.

In contrast to read only backends like idmap_rid, it is an allocating backend: This means that it needs to allocate new user and group IDs in order to create new mappings. The allocator can be provided by the idmap_tdb backend itself or by any other allocating backend like idmap_ldap or idmap_tdb2. This is configured with the parameter idmap alloc backend.

[global]
# "idmap backend = tdb" is redundant here since it is the default
idmap config *: backend = tdb
idmap config *: range = 1000000 - 2000000

Top

The idmap_hash plugin implements a hashing algorithm used to map SIDs for domain users and groups to 31-bit uids and gids, respectively. This plugin also implements the nss_info API and can be used to support a local name mapping files if enabled via the "winbind normalize names" and "winbind nss info" parameters in smb.conf.

[global]     
            idmap config * : backend = hash     
          idmap config * : range = 1000-4000000000       

winbind nss info = hash     
          winbind normalize names = yes
idmap_hash:name_map = /etc/samba/name_map.cfg

Top

CONSIDERATIONS AND NOTES:

• Depending on the version of winbind (samba-winbind) that is installed, some of the options listed above may or may not be available. Review the man pages on your system (idmap_<option>) to see what is available for use based on your installed version.  Many of the options listed, particularly with idmap uid/gid, have been deprecated.

• This document does not cover idmap_adex (soon to be deprecated) nor idmap_tdb2 (used for clustered environments)

• By default, idmap_tdb is the default idmap backend unless one is specified.

• It is important to understand that "idmap uid" and "idmap gid" are only utilized by the default tdb backend. The newer method utilized (as shown in the examples) for some of the idmap_<option> settings is "range". As seen under an example under idmap_ad, both may be utilized.

• If Active Directory (AD) is in the environment, run "yast2 samba-client" (or the "Windows Domain Membership" plugin found under yast) to join the domain. Keep in mind that time needs to be in sync (configure ntpd--this can't be stressed enough) and an entry should be added to the /etc/resolv.conf that points the joining server's DNS to the AD server (IE nameserver your.ad.srvr.ip). Check the box next to "Also Use SMB Information for Linux Authentication". This plugin will install and setup winbind and kerberos for you. Be sure that the Microsoft firewall, if being utilized, is opened up to allow the join.

• Some of the examples contain more than "bare bones" configuration for the given idmap_<option> settings.

• idmap uid/gid ranges should not overlap the 'idmap config <domain> : range' ranges.  'idmap config <domain> : range' acts essentially as a filter for the domain specified.  If the SIDs on the AD server do not fall within the range specified, winbind will not query for the user's information.  This range must encompass any user SIDs the administrator desires to retrieve from the AD server. 
•    
  idmap uid/gid ranges are configured for allocating IDs for builtin or trusted domain users and groups.  For example, if the SLES server trusts two domains, CORP and REMOTE, and CORP is setup with 'idmap config CORP : range = 10000-20000', and if idmap uid = 5000-9999, then users from the REMOTE domain will be mapped to the 5000-9999 range (as will local users), and users in the CORP domain will be mapped to the 10000-20000 range. Depending on the version of Samba installed (3.6 for instance), this option is deprecated in favor of the 'idmap config *: range = ####-####'