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

This document (7007006) is provided subject to the disclaimer at the end of this document.


SUSE Linux Enterprise Server 10 
SUSE Linux Enterprise Server 11
SUSE Linux Enterprise Server 12


General information, including pros, cons, and examples, of various identity mapping (idmap) options utilizing winbind.






  • 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
    • 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) doc



    • 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 doc



    • 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 doc



    • 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 doc



    • 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 doc



    • 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 doc



      * docs will contain the most up-to-date and relevant information. These options have undergone many changes over the years. Be sure to refer to the docs, or current man pages for the most up-to-date and accurate information.

    Considerations and notes




    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.



    idmap_ad Examples:

              workgroup = CORP       
              idmap config * : backend = tdb     
              idmap config * : range = 1000000-1999999       
              idmap config CORP : backend  = ad     
              idmap config CORP : range = 1000-999999

    See TID 7007419: How To Setup A Basic idmap_ad On SLES 11 SP 1 for a walkthrough. TID 7007419 is maintained more frequently than this TID (7007006). It contains examples for older and newere systems.





    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.


     idmap_ldap Examples:

    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".

    idmap config * : backend      = ldap
    idmap config * : range        = 1000000-1999999
    idmap config * : ldap_url     = ldap://localhost/
    idmap config * : ldap_base_dn = ou=idmap,dc=example,dc=com
    idmap config * : ldap_user_dn = cn=idmap_admin,dc=example,dc=com

    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.

    # "backend = tdb" is redundant here since it is the default     
    idmap config * : backend = tdb
    idmap config * : range = 1000000-1999999
    idmap config DOM1 : backend = ldap
    idmap config DOM1 : range = 2000000-2999999
    idmap config DOM1 : read only = yes
    idmap config DOM1 : ldap_url = ldap://server/
    idmap config DOM1 : ldap_base_dn = ou=idmap,dc=dom1,dc=example,dc=com
    idmap config DOM1 : ldap_user_dn = cn=idmap_admin,dc=dom1,dc=example,dc=com       







    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.


     idmap_nss Examples:

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






    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.



     idmap_rid Examples:



    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.



     idmap_tdb Example(s):

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






    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.


     idmap_hash Examples:

                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






    • 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 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 = ####-####'




    This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.

    • Document ID:7007006
    • Creation Date: 05-Oct-2010
    • Modified Date:07-May-2020
      • SUSE Linux Enterprise Server

    < Back to Support Search

    For questions or concerns with the SUSE Knowledgebase please contact:

    SUSE Support Forums

    Get your questions answered by experienced Sys Ops or interact with other SUSE community experts.

    Join Our Community

    Support Resources

    Learn how to get the most from the technical support you receive with your SUSE Subscription, Premium Support, Academic Program, or Partner Program.

    SUSE Customer Support Quick Reference Guide SUSE Technical Support Handbook Update Advisories
    Support FAQ

    Open an Incident

    Open an incident with SUSE Technical Support, manage your subscriptions, download patches, or manage user access.

    Go to Customer Center