added some basic documentation for the idmap script option
[ira/wip.git] / 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.