1idmap(1M) System Administration Commands idmap(1M)
2
6 idmap - configure and manage the Native Identity Mapping service
7
9 idmap
10 idmap -f command-file
13 idmap add [-d] name1 name2
16 idmap dump [-n] [-v]
19 idmap export [-f file] format
22 idmap get-namemap name
25 idmap help
28 idmap import [-F] [-f file] format
31 idmap list
34 idmap remove [-t|-f] name
37 idmap remove -a
40 idmap remove [-d] name1 name2
43 idmap set-namemap [-a authenticationMethod] [-D bindDN]
46 [-j passwdfile] name1 name2
47 idmap show [-c] [-v] identity [target-type]
50 idmap unset-namemap [-a authenticationMethod] [-D bindDN]
53 [-j passwdfile] name [target-type]
54
57 The idmap utility is used to configure and manage the Native Identity
58 Mapping service.
59 The Native Identity Mapping service supports the following types of
62 mappings between Windows security identities (SIDs) and POSIX user IDs
63 and group IDs (UIDs and GIDs):
64 o Name-based mapping. An administrator maps Windows and UNIX
66 users and groups by name.
67 o Ephemeral ID mapping. A UID or GID is dynamically allocated
69 for every SID that is not already mapped by name.
70 o Local-SID mapping. A non-ephemeral UID or GID is mapped to
72 an algorithmically generated local SID.
73 The idmap utility can be used to create and manage the name-based map‐
76 pings and to monitor the mappings in effect.
77 If the idmap utility is invoked without a subcommand or option, it
80 reads the subcommands from standard input. When standard input is a
81 TTY, the idmap command prints the usage message and exits.
82 Mapping Mechanisms
84 The idmapd(1M) daemon maps Windows user and group SIDs to UNIX UIDs and
85 GIDs as follows:
86 1. SIDs are mapped by name.
88 This mapping uses the name-based mappings that are manually
90 set up by the system administrator.
91 2. If no name-based mapping is found, the SID is mapped to a
93 dynamically allocated ephemeral ID.
94 This allocation uses the next available UID or GID from 2^31
96 to 2^32 - 2.
97 Local SID mappings are used to map from UNIX to Windows.
100 To prevent aliasing problems, all file systems, archive and backup for‐
103 mats, and protocols must store SIDs or map all UIDs and GIDs in the
104 2^31 to 2^32 - 2 range to the nobody user and group.
105 It is possible to create also diagonal mappings. They are the mappings
108 between Windows groups and Solaris users and between Solaris groups and
109 Windows users. They are needed when Windows uses a group identity as a
110 file owner or vice versa.
111 Name-based Mappings
113 Name-based mappings establish name equivalence between Windows users
114 and groups and their counterparts in the UNIX name service. These map‐
115 pings persist across reboots. For example, the following command maps
116 Windows users to UNIX users with the same name:
117 # idmap add "winuser:*@mywindomain.com" "unixuser:*"
119 If configured to use a directory service, idmapd(1M) will first try to
124 use the mapping information that is stored in user or group objects in
125 the Active Directory (AD) and/or the native LDAP directory service. For
126 example, an AD object for a given Windows user or group can be aug‐
127 mented to include the corresponding Solaris user or group name or
128 numeric id. Similarly, the native LDAP object for a given Solaris user
129 or group can be augmented to include the corresponding Windows user or
130 group name.
131 idmapd(1M) can be configured to use AD and/or native LDAP directory-
134 based name mappings by setting the appropriate service management
135 facility (SMF) properties of the idmap service. See "Service Proper‐
136 ties," below, for more details.
137 If directory-based name mapping is not configured or if configured but
140 not found, then idmapd(1M) will process locally stored name-based map‐
141 ping rules.
142 idmap supports the mapping of Windows well-known names. A few of these
145 are listed below:
146 Administrator
148 Guest
149 KRBTGT
150 Domain Admins
151 Domain Users
152 Domain Guest
153 Domain Computers
154 Domain Controllers
155 When idmap rules are added, these well-known names will be expanded to
160 canonical form. That is, either the default domain name will be added
161 (for names that are not well-known) or an appropriate built-in domain
162 name will be added. Depending on the particular well-known name, this
163 domain name might be null, BUILTIN, or the local host name.
164 The following sequence of idmap commands illustrate the treatment of
167 the non-well-known name fred and the well-known names administrator and
168 guest.
169 # idmap add winname:fred unixuser:fredf
171 add winname:fred unixuser:fredf
172 # idmap add winname:administrator unixuser:root
174 add winname:administrator unixuser:root
175 # idmap add winname:guest unixuser:nobody
177 add winname:guest unixuser:nobody
178 # idmap add wingroup:administrators sysadmin
180 add wingroup:administrators unixgroup:sysadmin
181 # idmap list
183 add winname:Administrator@examplehost unixuser:root
184 add winname:Guest@examplehost unixuser:nobody
185 add wingroup:Administrators@BUILTIN unixgroup:sysadmin
186 add winname:fred@example.com unixuser:fredf
187 Ephemeral Mappings
191 The idmapd daemon attempts to preserve ephemeral ID mappings across
192 daemon restarts. However, when IDs cannot be preserved, the daemon maps
193 each previously mapped SID to a new ephemeral UID or GID value. The
194 daemon will never re-use ephemeral UIDs or GIDs. If the idmapd daemon
195 runs out of ephemeral UIDs and GIDs, it returns an error as well as a
196 default UID or GID for SIDs that cannot be mapped by name.
197 The dynamic ID mappings are not retained across reboots. So, any SIDs
200 that are dynamically mapped to UNIX UIDs or GIDs are most likely mapped
201 to different IDs after rebooting the system.
202 Local SID Mappings
204 If no name-based mapping is found, a non-ephemeral UID or GID is mapped
205 to an algorithmically generated local SID. The mapping is generated as
206 follows:
207 local SID for UID = <machine SID> - <1000 + UID>
209 local SID for GID = <machine SID> - <2^31 + GID>
210 <machine SID> is a unique SID generated by the idmap service for the
215 host on which it runs.
216 Rule Lookup Order
218 When mapping a Windows name to a UNIX name, lookup for name-based map‐
219 ping rules is performed in the following order:
220 1. windows-name@domain to ""
222 2. windows-name@domain to unix-name
224 3. windows-name@* to ""
226 4. windows-name@* to unix-name
228 5. *@domain to *
230 6. *@domain to ""
232 7. *@domain to unix-name
234 8. *@* to *
236 9. *@* to ""
238 10. *@* to unix-name
240 When mapping a UNIX name to a Windows name, lookup for name-based map‐
243 ping rules is performed in the following order:
244 1. unix-name to ""
246 2. unix-name to windows-name@domain
248 3. * to *@domain
250 4. * to ""
252 5. * to windows-name@domain
254 Service Properties
256 The service properties determine the behavior of the idmapd(1M) daemon.
257 These properties are stored in the SMF repository (see smf(5)) under
258 property group config. They can be accessed and modified using svc‐
259 cfg(1M), which requires solaris.smf.value.idmap authorization. The ser‐
260 vice properties for the idmap service are:
261 config/ad_unixuser_attr
263 Specify the name of the AD attribute that contains the UNIX user
265 name. There is no default.
266 config/ad_unixgroup_attr
269 Specify the name of the AD attribute that contains the UNIX group
271 name. There is no default.
272 config/nldap_winname_attr
275 Specify the name of the Native LDAP attribute that contains the
277 Windows user/group name. There is no default.
278 config/directory_based_mapping
281 Controls support for identity mapping using data stored in a direc‐
283 tory service.
284 none disables directory-based mapping.
286 name enables name-based mapping using the properties described
288 above.
289 idmu enables mapping using Microsoft's Identity Management for UNIX
291 (IDMU). This Windows component allows the administrator to specify
292 a UNIX user ID for each Windows user, mapping the Windows identity
293 to the corresponding UNIX identity. Only IDMU data from the domain
294 the Solaris system is a member of is used.
295 Changes to service properties do not affect a running idmap service.
299 The service must be refreshed (with svcadm(1M)) for the changes to take
300 effect.
301
303 The idmap command uses the following operands:
304 format
306 Specifies the format in which user name mappings are described for
308 the export and import subcommands. The Netapp usermap.cfg and Samba
309 smbusers external formats are supported. These external formats are
310 only for users, not groups.
311 o The usermap.cfg rule-mapping format is as follows:
313 windows-username [direction] unix-username
315 windows-username is a Windows user name in either the
318 domain\username or username@domain format.
319 unix-username is a UNIX user name.
321 direction is one of the following:
324 o == means a bidirectional mapping, which is the
326 default.
327 o => or <= means a unidirectional mapping.
329 The IP qualifier is not supported.
330 o The smbusers rule-mapping format is as follows:
332 unixname = winname1 winname2 ...
334 If winname includes whitespace, escape the whitespace by
337 enclosing the value in double quotes. For example, the
338 following file shows how to specify whitespace in a
339 valid format for the idmap command:
340 $ cat myusermap
342 terry="Terry Maddox"
343 pat="Pat Flynn"
344 cal=cbrown
345 The mappings are imported as unidirectional mappings
348 from Windows names to UNIX names.
349 The format is based on the "username map" entry of the
351 smb.conf man page, which is available on the samba.org
352 web site. The use of an asterisk (*) for windows-name is
353 supported. However, the @group directive and the chain‐
354 ing of mappings are not supported.
355 By default, if no mapping entries are in the smbusers
357 file, Samba maps a windows-name to the equivalent unix-
358 name, if any. If you want to set up the same mapping as
359 Samba does, use the following idmap command:
360 idmap add -d "winuser:*@*" "unixuser:*"
362 identity
367 Specifies a user name, user ID, group name, or group ID. identity
369 is specified as type:value. type is one of the following:
370 usid Windows user SID in text format
372 gsid Windows group SID in text format
375 sid Windows group SID in text format that can belong
378 either to a user or to a group
379 uid Numeric POSIX UID
382 gid Numeric POSIX GID
385 unixuser UNIX user name
388 unixgroup UNIX group name
391 winuser Windows user name
394 wingroup Windows group name
397 winname Windows user or group name
400 value is a number or string that is appropriate to the specified
402 type. For instance, unixgroup:staff specifies the UNIX group name,
403 staff. The identity gid:10 represents GID 10, which corresponds to
404 the UNIX group staff.
405 name
408 Specifies a UNIX name (unixuser, unixgroup) or a Windows name
410 (winuser, wingroup) that can be used for name-based mapping rules.
411 A Windows security entity name can be specified in one of these
414 ways:
415 o domain\name
417 o name@domain
419 o name, which uses the default mapping domain
421 If name is the empty string (""), mapping is inhibited. Note that a
422 name of "" should not be used to preclude logins by unmapped Win‐
423 dows users.
424 If name uses the wildcard (*), it matches all names that are not
426 matched by other mappings. Similarly, if name is the wildcard Win‐
427 dows name (*@*), it matches all names in all domains that are not
428 matched by other mappings.
429 If name uses the wildcard on both sides of the mapping rule, the
431 name is the same for both Windows and Solaris users. For example,
432 if the rule is "*@domain" == "*", the jp@domain Windows user name
433 matches this rule and maps to the jp Solaris user name.
434 Specifying the type of name is optional if the type can be deduced
436 from other arguments or types specified on the command line.
437 target-type
440 Used with the show and unset-namemap subcommands. For show, speci‐
442 fies the mapping type that should be shown. For example, if target-
443 type is sid, idmap show returns the SID mapped to the identity
444 specified on the command line. For unset-namemap, identifies an
445 attribute within the object specified by the name operand.
446
449 The idmap command supports one option and a set of subcommands. The
450 subcommands also have options.
451 Command-Line Option
453 -f command-file
454 Reads and executes idmap subcommands from command-file. The idmap
456 -f - command reads from standard input. This option is not used by
457 any subcommands.
458 Subcommands
461 The following subcommands are supported:
462 add [-d] name1 name2
464 Adds a name-based mapping rule. By default, the name mapping is
466 bidirectional. If the -d option is used, a unidirectional mapping
467 is created from name1 to name2.
468 Either name1 or name2 must be a Windows name, and the other must be
470 a UNIX name. For the Windows name, the winname identity type must
471 not be used. Instead, specify one of the winuser or wingroup types.
472 See "Operands" for information about the name operand.
473 Note that two unidirectional mappings between the same two names in
475 two opposite directions are equivalent to one bidirectional map‐
476 ping.
477 This subcommand requires the solaris.admin.idmap.rules authoriza‐
479 tion.
480 dump [-n] [-v]
483 Dumps all the mappings cached since the last system boot. The -n
485 option shows the names, as well. By default, only sids, uids, and
486 gids are shown. The -v option shows how the mappings were gener‐
487 ated.
488 export [-f file] format
491 Exports name-based mapping rules to standard output in the speci‐
493 fied format. The -f file option writes the rules to the specified
494 output file.
495 get-namemap name
498 Get the directory-based name mapping information from the AD or
500 native LDAP user or group object represented by the specified name.
501 help
504 Displays the usage message.
506 import [-F] [-f file] format
509 Imports name-based mapping rules from standard input by using the
511 specified format. The -f file option reads the rules from the spec‐
512 ified file. The -F option flushes existing name-based mapping rules
513 before adding new ones.
514 Regardless of the external format used, the imported rules are pro‐
516 cessed by using the semantics and order described in the section
517 "Rule Lookup Order," above.
518 This subcommand requires the solaris.admin.idmap.rules authoriza‐
520 tion.
521 list
524 Lists all name-based mapping rules. Each rule appears in its idmap
526 add form.
527 remove [-t|-f] name
530 Removes any name-based mapping rule that involves the specified
532 name. name can be either a UNIX or Windows user name or group name.
533 The -f option removes rules that use name as the source. The -t
535 option removes rules that use name as the destination. These
536 options are mutually exclusive.
537 This subcommand requires the solaris.admin.idmap.rules authoriza‐
539 tion.
540 remove -a
543 Removes all name-based mapping rules.
545 This subcommand requires the solaris.admin.idmap.rules authoriza‐
547 tion.
548 remove [-d] name1 name2
551 Removes name-based mapping rules between name1 and name2. If the -d
553 option is specified, rules from name1 to name2 are removed.
554 Either name1 or name2 must be a Windows name, and the other must be
556 a UNIX name.
557 This subcommand requires the solaris.admin.idmap.rules authoriza‐
559 tion.
560 set-namemap [-a authenticationMethod] [-D bindDN] [-j passwdfile] name1
563 name2
564 Sets name mapping information in the AD or native LDAP user or
566 group object. Either name1 or name2 must be a Windows name, and the
567 other must be a UNIX name.
568 If name1 is a Windows name, then the UNIX name name2 is added to
570 the AD object represented by name1. Similarly, if name1 is a UNIX
571 name then the Windows name name2 is added to the native LDAP entry
572 represented by name1.
573 The following options are supported:
575 -a authenticationMethod
577 Specify authentication method when modifying native LDAP entry.
579 See ldapaddent(1M) for details. Default value is sasl/GSSAPI.
580 -D bindDN
583 Uses the distinguished name bindDN to bind to the directory.
585 -j passwdfile
588 Specify a file containing the password for authentication to
590 the directory.
591 show [-c] [-v] name [target-type]
595 Shows the identity of type, target-type, that the specified name
597 maps to. If the optional target-type is omitted, the non-diagonal
598 mapping is shown.
599 By default, this subcommand shows only mappings that have been
601 established already. The -c option forces the evaluation of name-
602 based mapping configurations or the dynamic allocation of IDs.
603 The -v option shows how the mapping was generated and also whether
605 the mapping was just generated or was retrieved from the cache.
606 unset-namemap [-a authenticationMethod] [-D bindDN] [-j passwdfile]
609 name [target-type]
610 Unsets directory-based name mapping information from the AD or
612 native LDAP user or group object represented by the specified name
613 and optional target type.
614 See the set-namemap subcommand for options.
616
619 Example 1 Using a Wildcard on Both Sides of a Name-Based Mapping Rule
620 The following command maps all Windows user names in the xyz.com domain
623 to the UNIX users with the same names provided that one exists and is
624 not otherwise mapped. If such a rule is matched but the UNIX user name
625 does not exist, an ephemeral ID mapping is used.
626 # idmap add "winuser:*@xyz.com" "unixuser:*"
629 Example 2 Using a Wildcard on One Side of a Name-Based Mapping Rule
633 The following command maps all unmapped Windows users in the xyz.com
636 domain to the guest UNIX user. The -d option specifies a unidirectional
637 mapping from *@xyz.com users to the guest user.
638 # idmap add -d "winuser:*@xyz.com" unixuser:guest
641 Example 3 Adding a Bidirectional Name-Based Mapping Rule
645 The following command maps Windows user, foobar@example.com, to UNIX
648 user, foo, and conversely:
649 # idmap add winuser:foobar@example.com unixuser:foo
652 This command shows how to remove the mapping added by the previous com‐
657 mand:
658 # idmap remove winuser:foobar@example.com unixuser:foo
661 Example 4 Showing a UID-to-SID Mapping
665 o The following command shows the SID that the specified UID,
667 uid:50000, maps to:
668 # idmap show uid:50000 sid
670 uid:50000 -> usid:S-1-5-21-3223191800-2000
671 o The following command shows the UNIX user name that the
675 specified Windows user name, joe@example.com, maps to:
676 # idmap show joe@example.com unixuser
678 winuser:joe@example.com -> unixuser:joes
679 Example 5 Listing the Cached SID-to-UID Mappings
683 The following command shows all of the SID-to-UID mappings that are in
686 the cache:
687 # idmap dump | grep "uid:"
690 usid:S-1-5-21-3223191800-2000 == uid:50000
691 usid:S-1-5-21-3223191800-2001 == uid:50001
692 usid:S-1-5-21-3223191800-2006 == uid:50010
693 usid:S-1-5-21-3223191900-3000 == uid:2147491840
694 usid:S-1-5-21-3223191700-4000 => uid:60001
695 Example 6 Batching idmap Requests
699 The following commands show how to batch idmap requests. This particu‐
702 lar command sequence does the following:
703 o Removes any previous rules for foobar@example.com.
706 o Maps Windows user foobar@example.com to UNIX user bar and
708 vice-versa.
709 o Maps Windows group members to UNIX group staff and vice-
711 versa.
712 # idmap <<EOF
714 remove winuser:foobar@example.com
715 add winuser:foobar@example.com unixuser:bar
716 add wingroup:members unixgroup:staff
717 EOF
718 Example 7 Listing Name-Based Mapping Rules
722 The following command shows how to list the name-based mapping rules:
725 # idmap list
728 add winuser:foobar@example.com unixuser:bar
729 add wingroup:members unixgroup:staff
730 Example 8 Importing Name-Based Mapping Rules From the usermap.cfg File
734 The usermap.cfg file can be used to configure name-based mapping rules.
737 The following usermap.cfg file shows mapping rules that map Windows
738 user foo@example.com to UNIX user foo, and that map foobar@example.com
739 to the UNIX user foo.
740 # cat usermap.cfg
743 foo@example.com == foo
744 foobar@example.com => foo
745 The following idmap command imports usermap.cfg information to the
750 idmapd database:
751 # cat usermap.cfg | idmap import usermap.cfg
754 This command does the same as the previous command:
759 # idmap import -f usermap.cfg usermap.cfg
762 The following commands are equivalent to the previous idmap import com‐
767 mands:
768 # idmap <<EOF
771 add winuser:foo@example.com unixuser:foo
772 add -d winuser:foobar@example.com unixuser:foo
773 EOF
774 Example 9 Using Name-Based and Ephemeral ID Mapping With Identity Func‐
778 tion Mapping and Exceptions
779 The following commands map all users in the example.com Windows domain
782 to UNIX user accounts of the same name. The command also specifies map‐
783 pings for the following Windows users: joe@example.com, jane.doe@exam‐
784 ple.com, administrator@example.com. The administrator from all domains
785 is mapped to nobody. Any Windows users without corresponding UNIX
786 accounts are mapped dynamically to available ephemeral UIDs.
787 # idmap import usermap.cfg <<EOF
790 joe@example.com == joes
791 jane.doe@example.com == janed
792 administrator@* => nobody
793 *@example.com == *
794 *@example.com => nobody
795 EOF
796 Example 10 Adding Directory-based Name Mapping to AD User Object
800 The following command maps Windows user joe@example.com to UNIX user
803 joe by adding the UNIX name to AD object for joe@example.com.
804 # idmap set-namemap winuser:joe@example.com joes
807 Example 11 Adding Directory-based Name Mapping to Native LDAP User
811 Object
812 The following command maps UNIX user foo to Windows user foobar@exam‐
815 ple.com by adding the Windows name to native LDAP object for foo.
816 # idmap set-namemap unixuser:foo foobar@example.com
819 Example 12 Removing Directory-based Name Mapping from AD User Object
823 The following command removes the UNIX username unixuser from the AD
826 object representing joe@example.com.
827 # idmap unset-namemap winuser:joe@example.com unixuser
830
834 0 Successful completion.
835 >0 An error occurred. A diagnostic message is written to standard
838 error.
839
842 See attributes(5) for descriptions of the following attributes:
843 ┌─────────────────────────────┬─────────────────────────────┐
848 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
849 ├─────────────────────────────┼─────────────────────────────┤
850 │Availability │SUNWcsu │
851 ├─────────────────────────────┼─────────────────────────────┤
852 │Interface Stability │Uncommitted │
853 └─────────────────────────────┴─────────────────────────────┘
854
856 svcs(1), idmapd(1M), ldapaddent(1M), svcadm(1M), svccfg(1M),
857 attributes(5), smf(5)
858
860 The idmapd service is managed by the service management facility,
861 smf(5). The service identifier for the idmapd service is svc:/sys‐
862 tem/idmap.
863 Use the svcadm command to perform administrative actions on this ser‐
866 vice, such as enabling, disabling, or restarting the service. These
867 actions require the solaris.smf.manage.idmap authorization. Use the
868 svcs command to query the service's status.
869 Windows user names are case-insensitive, while UNIX user names are
872 case-sensitive. The case of Windows names as they appear in idmap name-
873 rules and idmap show command lines is irrelevant.
874 Because common practice in UNIX environments is to use all-lowercase
877 user names, wildcard name-rules map Windows names to UNIX user/group
878 names as follows: first, the canonical Windows name (that is, in the
879 case as it appears in the directory) is used as a UNIX user or group
880 name. If there is no such UNIX entity, then the Windows name's case is
881 folded to lowercase and the result is used as the UNIX user or group
882 name.
883 As a result of this differing treatment of case, user names that appear
886 to be alike might not be recognized as matches. You must create rules
887 to handle such pairings of strings that differ only in case. For exam‐
888 ple, to map the Windows user sam@example to the Solaris user Sam, you
889 must create the following rules:
890 # idmap add "winuser:*@example" "unixuser:*"
892 # idmap add winuser:sam@example unixuser:Sam
893 For guidance on modifying an Active Directory schema, consult the Mi‐
898 crosoft document, Step-by-Step Guide to Using Active Directory Schema
899 and Display Specifiers, which you can find at their technet web site,
900 http://technet.microsoft.com/.
901SunOS 5.11 3 Aug 2009 idmap(1M)