From 4c23a9556536561f79fa90bc431fc62fcc4e3c90 Mon Sep 17 00:00:00 2001 From: Andrew Tridgell Date: Fri, 19 Jun 2009 13:57:30 +1000 Subject: added some basic documentation for the idmap script option --- examples/scripts/idmap/README | 168 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 examples/scripts/idmap/README (limited to 'examples') diff --git a/examples/scripts/idmap/README b/examples/scripts/idmap/README new file mode 100644 index 0000000000..3032493cbc --- /dev/null +++ b/examples/scripts/idmap/README @@ -0,0 +1,168 @@ +idmap script option for flexible UID/GID handling +------------------------------------------------- + +If you are using "idmap backend = tdb2" with winbind in Samba3, then +you have the option of specifying an external script to perform +uid/gid allocation. This can be useful in situations where you are +using AD for authentication, but the AD server is not configured to +supply uid/gid mappings via the services for unix extensions and you +have a need to support a pre-existing system for uid/gid allocation. + +One common situation where this arises is where you have a mixture of +NFS and CIFS clients, and the NFS clients are configured to use NIS +for their id mapping. It is quite common to have an administrative +mechanism in place to ensure that all of the NIS users have a +corresponding AD user account, but there may be no direct mechanism to +ensure that any unix uid/gid attributes in AD match those in NIS. + +In this situation it would normally not be possible to share files +with correct ownership between the CIFS and NFS clients, as winbind +would normally allocate its own set of UIDs from a reserved pool, and +those uids won't match the existing ones in NIS. + +The idmap script option +----------------------- + +To resolve this problem the idmap tdb2 module has the ability to call +out to an external script whenever it meeds an unknown SID or UID/GID +for the first time. It is then the job of that script to provide a +mapping consistent with whatever external system is in place (such as +NIS), and return the mapped result to winbind. + +Winbind will then persistently store the result of the mapping, so +that the script is not invoked more than once per user/group. + +To setup the idmap script you need to set the following options: + + idmap backend = tdb2 + idmap script = /usr/local/bin/idmap.sh + +where the location and name of the script is arbitrary. It just needs +to be executable by winbind. + +You then need to stop Samba, delete the key idmap cache files, and +restart Samba. The idmap files that need to be deleted are: + + - gencache.tdb + - winbindd_cache.tdb + - idmap2.tdb + + +Script operation +---------------- + +The script will be called by winbind in one of three ways. + + 1) idmap.sh SIDTOID + 2) idmap.sh IDTOSID UID + 2) idmap.sh IDTOSID GID + +In the first form the script is being asked to map a windows SID (in +the string form "S-*") to a UID or GID. In the second form the script +is being asked to map a UID to a SID, and in the third form it is +being asked to map a GID to a SID. + +SIDTOID +------- + +In the first form the script is expected to output a UID or GID given +a SID. The output format is expected to be like this: + + UID:1234 +or + GID:1122 + +If the SID cannot be found, then the script should output an error +like this: + + ERR:Some error message + +Note that it is common for the external mechanism to not know about +windows SIDs, in which case the script may use the wbinfo command to +ask winbind to change the SID into a username or group name. The +"wbinfo -s" option is the one to use. + + +IDTOSID UID +----------- + +In this form the script is expected to turn a UID into a SID, +returning a result like this: + + SID:S-1-5-21-1110277820-2343689819-414998773-1124 + +or an error like this: + + ERR:Some error message + +If the external mechanism that the script wants to use cannot produce +a SID, but can produce a username, then the script can convert the +username to a SID using the "wbinfo -n" option. + +IDTOSID GID +----------- + +In this form the script is expected to turn a GID into a SID, +returning a result like this: + + SID:S-1-5-21-1110277820-2343689819-414998773-1120 + +or an error like this: + + ERR:Some error message + +If the external mechanism that the script wants to use cannot produce +a SID, but can produce a group name, then the script can convert the +groupname to a SID using the "wbinfo -n" option. + + +Testing the script +------------------ + +It is suggested that you test the script on the command line first, +before using it in winbind. To do that first get a list of users you +would like to test using the command "wbinfo -u". Let's assume one of +those users is "DC01\tridge". You would then test the script as +follows: + + [root ~]# wbinfo -n 'DC01\tridge' + S-1-5-21-1110277820-2343689819-414998773-1124 User (1) + + [root ~]# /usr/local/bin/idmap.sh SIDTOID S-1-5-21-1110277820-2343689819-414998773-1124 + UID:1003 + + [root ~]# /usr/local/bin/idmap.sh IDTOSID UID 1003 + SID:S-1-5-21-1110277820-2343689819-414998773-1124 + +Once those steps pass, you can enable the script in winbind +(remembering to clear the cache tdbs), and test using the id command: + + [root ~]# id 'DC01\tridge' + uid=1003(DC01\tridge) gid=10000009(DC01\domain users) + + +nsswitch.conf +------------- + +When using the idmap script option you setup nsswitch.conf as usual +for winbind, with one addition. If your external idmap mechanism +support nsswitch then you may optionally choose to add it to +nsswitch.conf, but you must add it after the winbind entry. So for +example, if using NIS, you could have a nsswitch.conf entry like this: + + passwd: files winbind nis + group: files winbind nis + +Adding this to nsswitch.conf is not essential, but may be useful for +some local administration tools. + +Sample script +------------- + +This directory contains a simple example script 'idmap_nis.sh' that +provides idmap script support for NIS. To use it you first need to +enable the NIS client on your Samba server, usually by configuring +/etc/yp.conf. See the manual page for yp.conf for details. + +You should test the ypcat and ypmatch commands and make sure they work +before enabling the idmap_nis.sh script. -- cgit