examples/scripts/idmap/README

   1 idmap script option for flexible UID/GID handling
   2 -------------------------------------------------
   3
   4 If you are using "idmap backend = tdb2" with winbind in Samba3, then
   5 you have the option of specifying an external script to perform
   6 uid/gid allocation. This can be useful in situations where you are
   7 using AD for authentication, but the AD server is not configured to
   8 supply uid/gid mappings via the services for unix extensions and you
   9 have a need to support a pre-existing system for uid/gid allocation.
  10
  11 One common situation where this arises is where you have a mixture of
  12 NFS and CIFS clients, and the NFS clients are configured to use NIS
  13 for their id mapping. It is quite common to have an administrative
  14 mechanism in place to ensure that all of the NIS users have a
  15 corresponding AD user account, but there may be no direct mechanism to
  16 ensure that any unix uid/gid attributes in AD match those in NIS.
  17
  18 In this situation it would normally not be possible to share files
  19 with correct ownership between the CIFS and NFS clients, as winbind
  20 would normally allocate its own set of UIDs from a reserved pool, and
  21 those uids won't match the existing ones in NIS.
  22
  23 The idmap script option
  24 -----------------------
  25
  26 To resolve this problem the idmap tdb2 module has the ability to call
  27 out to an external script whenever it meeds an unknown SID or UID/GID
  28 for the first time. It is then the job of that script to provide a
  29 mapping consistent with whatever external system is in place (such as
  30 NIS), and return the mapped result to winbind.
  31
  32 Winbind will then persistently store the result of the mapping, so
  33 that the script is not invoked more than once per user/group.
  34
  35 To setup the idmap script you need to set the following options:
  36
  37   idmap backend = tdb2
  38   idmap script = /usr/local/bin/idmap.sh
  39
  40 where the location and name of the script is arbitrary. It just needs
  41 to be executable by winbind.
  42
  43 You then need to stop Samba, delete the key idmap cache files, and
  44 restart Samba. The idmap files that need to be deleted are:
  45
  46  - gencache.tdb
  47  - winbindd_cache.tdb
  48  - idmap2.tdb
  49
  50
  51 Script operation
  52 ----------------
  53
  54 The script will be called by winbind in one of three ways.
  55
  56  1) idmap.sh SIDTOID <SID>
  57  2) idmap.sh IDTOSID UID <UID>
  58  2) idmap.sh IDTOSID GID <GID>
  59
  60 In the first form the script is being asked to map a windows SID (in
  61 the string form "S-*") to a UID or GID. In the second form the script
  62 is being asked to map a UID to a SID, and in the third form it is
  63 being asked to map a GID to a SID.
  64
  65 SIDTOID
  66 -------
  67
  68 In the first form the script is expected to output a UID or GID given
  69 a SID. The output format is expected to be like this:
  70
  71  UID:1234
  72 or
  73  GID:1122
  74
  75 If the SID cannot be found, then the script should output an error
  76 like this:
  77
  78  ERR:Some error message
  79
  80 Note that it is common for the external mechanism to not know about
  81 windows SIDs, in which case the script may use the wbinfo command to
  82 ask winbind to change the SID into a username or group name. The
  83 "wbinfo -s" option is the one to use.
  84
  85
  86 IDTOSID UID
  87 -----------
  88
  89 In this form the script is expected to turn a UID into a SID,
  90 returning a result like this:
  91
  92  SID:S-1-5-21-1110277820-2343689819-414998773-1124
  93
  94 or an error like this:
  95
  96  ERR:Some error message
  97
  98 If the external mechanism that the script wants to use cannot produce
  99 a SID, but can produce a username, then the script can convert the
 100 username to a SID using the "wbinfo -n" option.
 101
 102 IDTOSID GID
 103 -----------
 104
 105 In this form the script is expected to turn a GID into a SID,
 106 returning a result like this:
 107
 108  SID:S-1-5-21-1110277820-2343689819-414998773-1120
 109
 110 or an error like this:
 111
 112  ERR:Some error message
 113
 114 If the external mechanism that the script wants to use cannot produce
 115 a SID, but can produce a group name, then the script can convert the
 116 groupname to a SID using the "wbinfo -n" option.
 117
 118
 119 Testing the script
 120 ------------------
 121
 122 It is suggested that you test the script on the command line first,
 123 before using it in winbind. To do that first get a list of users you
 124 would like to test using the command "wbinfo -u". Let's assume one of
 125 those users is "DC01\tridge". You would then test the script as
 126 follows:
 127
 128   [root ~]# wbinfo -n 'DC01\tridge'
 129   S-1-5-21-1110277820-2343689819-414998773-1124 User (1)
 130
 131   [root ~]# /usr/local/bin/idmap.sh SIDTOID S-1-5-21-1110277820-2343689819-414998773-1124
 132   UID:1003
 133
 134   [root ~]# /usr/local/bin/idmap.sh IDTOSID UID 1003
 135   SID:S-1-5-21-1110277820-2343689819-414998773-1124
 136
 137 Once those steps pass, you can enable the script in winbind
 138 (remembering to clear the cache tdbs), and test using the id command:
 139
 140   [root ~]# id 'DC01\tridge'
 141   uid=1003(DC01\tridge) gid=10000009(DC01\domain users)
 142
 143
 144 nsswitch.conf
 145 -------------
 146
 147 When using the idmap script option you setup nsswitch.conf as usual
 148 for winbind, with one addition. If your external idmap mechanism
 149 support nsswitch then you may optionally choose to add it to
 150 nsswitch.conf, but you must add it after the winbind entry. So for
 151 example, if using NIS, you could have a nsswitch.conf entry like this:
 152
 153   passwd:     files winbind nis
 154   group:      files winbind nis
 155
 156 Adding this to nsswitch.conf is not essential, but may be useful for
 157 some local administration tools.
 158
 159 Sample script
 160 -------------
 161
 162 This directory contains a simple example script 'idmap_nis.sh' that
 163 provides idmap script support for NIS. To use it you first need to
 164 enable the NIS client on your Samba server, usually by configuring
 165 /etc/yp.conf. See the manual page for yp.conf for details.
 166
 167 You should test the ypcat and ypmatch commands and make sure they work
 168 before enabling the idmap_nis.sh script.