merge from 2.2
[samba.git] / docs / docbook / projdoc / winbind.sgml
1 <chapter>
2
3
4 <chapterinfo>
5         <author>
6                 <firstname>Tim</firstname><surname>Potter</surname>
7                 <affiliation>
8                         <orgname>Samba Team</orgname>
9                         <address><email>tpot@linuxcare.com.au</email></address>
10                 </affiliation>
11         </author>
12         <author>
13                 <firstname>Andrew</firstname><surname>Trigdell</surname>
14                 <affiliation>
15                         <orgname>Samba Team</orgname>
16                         <address><email>tridge@linuxcare.com.au</email></address>
17                 </affiliation>
18         </author>
19         
20                 
21         <pubdate>16 Oct 2000</pubdate>
22 </chapterinfo>
23
24 <title>Unifed Logons between Windows NT and UNIX using Winbind</title>
25
26 <sect1>
27         <title>Abstract</title>
28
29         <para>Integration of UNIX and Microsoft Windows NT through 
30         a unified logon has been considered a "holy grail" in heterogeneous 
31         computing environments for a long time. We present <emphasis>winbind
32         </emphasis>, a component of the Samba suite of programs as a 
33         solution to the unied logon problem. Winbind uses a UNIX implementation 
34         of Microsoft RPC calls, Pluggable Authentication Modules, and the Name 
35         Service Switch to allow Windows NT domain users to appear and operate 
36         as UNIX users on a UNIX machine. This paper describes the winbind 
37         system, explaining the functionality it provides, how it is configured, 
38         and how it works internally.</para>
39 </sect1>
40
41
42 <sect1>
43         <title>Introduction</title>
44         
45         <para>It is well known that UNIX and Microsoft Windows NT have 
46         different models for representing user and group information and 
47         use different technologies for implementing them. This fact has 
48         made it difficult to integrate the two systems in a satisfactory 
49         manner.</para>
50         
51         <para>One common solution in use today has been to create 
52         identically named user accounts on both the UNIX and Windows systems 
53         and use the Samba suite of programs to provide file and print services 
54         between the two. This solution is far from perfect however, as 
55         adding and deleting users on both sets of machines becomes a chore 
56         and two sets of passwords are required both of which which
57         can lead to synchronization problems between the UNIX and Windows 
58         systems and confusion for users.</para>
59         
60         <para>We divide the unifed logon problem for UNIX machines into 
61         three smaller problems:</para>
62         
63         <itemizedlist>
64                 <listitem><para>Obtaining Windows NT user and group information
65                 </para></listitem>
66                 
67                 <listitem><para>Authenticating Windows NT users
68                 </para></listitem>
69                 
70                 <listitem><para>Password changing for Windows NT users
71                 </para></listitem>
72         </itemizedlist>
73
74
75         <para>Ideally, a prospective solution to the unified logon problem 
76         would satisfy all the above components without duplication of 
77         information on the UNIX machines and without creating additional 
78         tasks for the system administrator when maintaining users and 
79         groups on either system. The winbind system provides a simple 
80         and elegant solution to all three components of the unifed logon 
81         problem.</para>
82 </sect1>
83
84
85 <sect1>
86         <title>What Winbind Provides</title>
87
88         <para>Winbind unifies UNIX and Windows NT account management by 
89         allowing a UNIX box to become a full member of a NT domain. Once 
90         this is done the UNIX box will see NT users and groups as if 
91         they were native UNIX users and groups, allowing the NT domain 
92         to be used in much the same manner that NIS+ is used within 
93         UNIX-only environments.</para>
94         
95         <para>The end result is that whenever any 
96         program on the UNIX machine asks the operating system to lookup 
97         a user or group name, the query will be resolved by asking the 
98         NT domain controller for the specied domain to do the lookup.
99         Because Winbind hooks into the operating system at a low level 
100         (via the NSS name resolution modules in the C library) this 
101         redirection to the NT domain controller is completely 
102         transparent.</para>
103         
104         <para>Users on the UNIX machine can then use NT user and group 
105         names as they would use "native" UNIX names. They can chown files 
106         so that they are owned by NT domain users or even login to the 
107         UNIX machine and run a UNIX X-Window session as a domain user.</para>
108         
109         <para>The only obvious indication that Winbind is being used is 
110         that user and group names take the form DOMAIN\user and 
111         DOMAIN\group. This is necessary as it allows Winbind to determine 
112         that redirection to a domain controller is wanted for a particular 
113         lookup and which trusted domain is being referenced.</para>
114         
115         <para>Additionally, Winbind provides a authentication service 
116         that hooks into the Pluggable Authentication Modules (PAM) system 
117         to provide authentication via a NT domain to any PAM enabled 
118         applications. This capability solves the problem of synchronizing 
119         passwords between systems as all passwords are stored in a single 
120         location (on the domain controller).</para>
121         
122         <sect2>
123                 <title>Target Uses</title>
124                 
125                 <para>Winbind is targeted at organizations that have an 
126                 existing NT based domain infrastructure into which they wish 
127                 to put UNIX workstations or servers. Winbind will allow these 
128                 organizations to deploy UNIX workstations without having to 
129                 maintain a separate account infrastructure. This greatly simplies 
130                 the administrative overhead of deploying UNIX workstations into 
131                 a NT based organization.</para>
132                 
133                 <para>Another interesting way in which we expect Winbind to 
134                 be used is as a central part of UNIX based appliances. Appliances 
135                 that provide file and print services to Microsoft based networks 
136                 will be able to use Winbind to provide seamless integration of 
137                 the appliance into the domain.</para>
138         </sect2>
139 </sect1>
140
141
142
143 <sect1>
144         <title>How Winbind Works</title>
145         
146         <para>The winbind system is designed around a client/server 
147         architecture. A long running <command>winbindd</command> daemon 
148         listens on a UNIX domain socket waiting for requests
149         to arrive. These requests are generated by the NSS and PAM 
150         clients and processed sequentially.</para>
151         
152         <para>The technologies used to implement winbind are described 
153         in detail below.</para>
154         
155         <sect2>
156                 <title>Microsoft Remote Procedure Calls</title>
157                 
158                 <para>Over the last two years, efforts have been underway 
159                 by various Samba Team members to decode various aspects of 
160                 the Microsoft Remote Procedure Call (MSRPC) system. This 
161                 system is used for most network related operations between 
162                 Windows NT machines including remote management, user authentication
163                 and print spooling. Although initially this work was done 
164                 to aid the implementation of Primary Domain Controller (PDC) 
165                 functionality in Samba, it has also yielded a body of code which 
166                 can be used for other purposes.</para>
167                 
168                 <para>Winbind uses various MSRPC calls to enumerate domain users 
169                 and groups and to obtain detailed information about individual 
170                 users or groups. Other MSRPC calls can be used to authenticate 
171                 NT domain users and to change user passwords. By directly querying 
172                 a Windows PDC for user and group information, winbind maps the 
173                 NT account information onto UNIX user and group names.</para>
174         </sect2>
175         
176         <sect2>
177                 <title>Name Service Switch</title>
178                 
179                 <para>The Name Service Switch, or NSS, is a feature that is 
180                 present in many UNIX operating systems. It allows system 
181                 information such as hostnames, mail aliases and user information 
182                 to be resolved from dierent sources. For example, a standalone 
183                 UNIX workstation may resolve system information from a series of 
184                 flat files stored on the local lesystem. A networked workstation 
185                 may first attempt to resolve system information from local files, 
186                 then consult a NIS database for user information or a DNS server 
187                 for hostname information.</para>
188                 
189                 <para>The NSS application programming interface allows winbind 
190                 to present itself as a source of system information when 
191                 resolving UNIX usernames and groups.  Winbind uses this interface, 
192                 and information obtained from a Windows NT server using MSRPC 
193                 calls to provide a new source of account enumeration.  Using standard 
194                 UNIX library calls, one can enumerate the users and groups on
195                 a UNIX machine running winbind and see all users and groups in 
196                 a NT domain plus any trusted domain as though they were local 
197                 users and groups.</para>
198                 
199                 <para>The primary control le for NSS is <filename>/etc/nsswitch.conf
200                 </filename>. When a UNIX application makes a request to do a lookup 
201                 the C library looks in <filename>/etc/nsswitch.conf</filename> 
202                 for a line which matches the service type being requested, for 
203                 example the "passwd" service type is used when user or group names 
204                 are looked up. This     config line species which implementations 
205                 of that service should be tried andin what order. If the passwd 
206                 config line is:</para>
207
208                 <para><command>passwd: files example</command></para>
209
210                 <para>then the C library will first load a module called 
211                 <filename>/lib/libnss_files.so</filename> followed by
212                 the module <filename>/lib/libnss_example.so</filename>. The 
213                 C library will dynamically load each of these modules in turn 
214                 and call resolver functions within the modules to try to resolve 
215                 the request. Once the request is resolved the C library returns the
216                 result to the application.</para>
217                 
218                 <para>This NSS interface provides a very easy way for Winbind 
219                 to hook into the operating system. All that needs to be done 
220                 is to put <filename>libnss_winbind.so</filename> in <filename>/lib/</filename> 
221                 then add "winbind" into <filename>/etc/nsswitch.conf</filename> at 
222                 the appropriate place. The C library will then call Winbind to 
223                 resolve user and group names.</para>
224         </sect2>
225         
226         <sect2>
227                 <title>Pluggable Authentication Modules</title>
228                 
229                 <para>Pluggable Authentication Modules, also known as PAM, 
230                 is a system for abstracting authentication and authorization 
231                 technologies. With a PAM module it is possible to specify different 
232                 authentication methods for dierent system applications without 
233                 having to recompile these applications. PAM is also useful
234                 for implementing a particular policy for authorization. For example, 
235                 a system administrator may only allow console logins from users 
236                 stored in the local password file but only allow users resolved from 
237                 a NIS database to log in over the network.</para>
238                 
239                 <para>Winbind uses the authentication management and password 
240                 management PAM interface to integrate Windows NT users into a 
241                 UNIX system. This allows Windows NT users to log in to a UNIX 
242                 machine and be authenticated against a suitable Primary Domain 
243                 Controller. These users can also change their passwords and have 
244                 this change take eect directly on the Primary Domain Controller.
245                 </para>
246                 
247                 <para>PAM is congured by providing control files in the directory 
248                 <filename>/etc/pam.d/</filename> for each of the services that 
249                 require authentication. When an authentication request is made 
250                 by an application the PAM code in the C library looks up this
251                 control file to determine what modules to load to do the 
252                 authentication check and in what order. This interface makes adding 
253                 a new authentication service for Winbind very easy, all that needs 
254                 to be done is that the <filename>pam_winbind.so</filename> module 
255                 is copied to <filename>/lib/security/</filename> and the pam 
256                 control files for relevant services are updated to allow 
257                 authentication via winbind. See the PAM documentation
258                 for more details.</para>
259         </sect2>
260         
261         
262         <sect2>
263                 <title>User and Group ID Allocation</title>
264                 
265                 <para>When a user or group is created under Windows NT 
266                 is it allocated a numerical relative identier (RID). This is 
267                 slightly dierent to UNIX which has a range of numbers which are 
268                 used to identify users, and the same range in which to identify 
269                 groups. It is winbind's job to convert RIDs to UNIX id numbers and
270                 vice versa.  When winbind is congured it is given part of the UNIX 
271                 user id space and a part of the UNIX group id space in which to 
272                 store Windows NT users and groups. If a Windows NT user is 
273                 resolved for the first time, it is allocated the next UNIX id from 
274                 the range. The same process applies for Windows NT groups. Over 
275                 time, winbind will have mapped all Windows NT users and groups
276                 to UNIX user ids and group ids.</para>
277
278                 <para>The results of this mapping are stored persistently in 
279                 a ID mapping database held in a tdb database). This ensures that 
280                 RIDs are mapped to UNIX IDs in a consistent way.</para>
281         </sect2>
282         
283         
284         <sect2>
285                 <title>Result Caching</title>
286
287                 <para>An active system can generate a lot of user and group 
288                 name lookups. To reduce the network cost of these lookups winbind 
289                 uses a caching scheme based on the SAM sequence number supplied 
290                 by NT domain controllers.  User or group information returned 
291                 by a PDC is cached by winbind along with a sequence number also 
292                 returned by the PDC. This sequence number is incremented by 
293                 Windows NT whenever any user or group information is modied. If 
294                 a cached entry has expired, the sequence number is requested from 
295                 the PDC and compared against the sequence number of the cached entry. 
296                 If the sequence numbers do not match, then the cached information 
297                 is discarded and up to date information is requested directly 
298                 from the PDC.</para>
299         </sect2>
300 </sect1>
301
302
303 <sect1>
304         <title>Installation and Configuration</title>
305
306         <para>The easiest way to install winbind is by using the packages 
307         provided in the <filename>pub/samba/appliance/</filename> 
308         directory on your nearest 
309         Samba mirror. These packages provide snapshots of the Samba source 
310         code and binaries already setup to provide the full functionality 
311         of winbind. This setup is a little more complex than a normal Samba 
312         build as winbind needs a small amount of functionality from a 
313         development code branch called SAMBA_TNG.</para>
314         
315         <para>Once you have installed the packages you should read 
316         the <command>winbindd(8)</command> man page which will provide you 
317         with conguration information and give you sample conguration files. 
318         You may also wish to update the main Samba daemons smbd and nmbd) 
319         with a more recent development release, such as the recently
320         announced Samba 2.2 alpha release.</para>
321 </sect1>
322
323 <sect1>
324         <title>Limitations</title>
325         
326         <para>Winbind has a number of limitations in its current 
327         released version which we hope to overcome in future 
328         releases:</para>
329
330         <itemizedlist>
331                 <listitem><para>Winbind is currently only available for 
332                 the Linux operating system, although ports to other operating 
333                 systems are certainly possible. For such ports to be feasible, 
334                 we require the C library of the target operating system to 
335                 support the Name Service Switch and Pluggable Authentication
336                 Modules systems. This is becoming more common as NSS and 
337                 PAM gain        support among UNIX vendors.</para></listitem>
338                 
339                 <listitem><para>The mappings of Windows NT RIDs to UNIX ids 
340                 is not made algorithmically and depends on the order in which 
341                 unmapped users or groups are seen by winbind. It may be difficult 
342                 to recover the mappings of rid to UNIX id mapping if the file 
343                 containing this information is corrupted or destroyed.</para>
344                 </listitem>
345                 
346                 <listitem><para>Currently the winbind PAM module does not take 
347                 into account possible workstation and logon time restrictions 
348                 that may be been set for Windows NT users.</para></listitem>
349                 
350                 <listitem><para>Building winbind from source is currently 
351                 quite tedious as it requires combining source code from two Samba 
352                 branches. Work is underway to solve this by providing all 
353                 the necessary functionality in the main Samba code branch.</para>
354                 </listitem>
355         </itemizedlist>
356 </sect1>
357
358
359 <sect1>
360         <title>Conclusion</title>
361
362         <para>The winbind system, through the use of the Name Service 
363         Switch, Pluggable Authentication Modules, and appropriate 
364         Microsoft RPC calls have allowed us to provide seamless 
365         integration of Microsoft Windows NT domain users on a
366         UNIX system. The result is a great reduction in the administrative 
367         cost of running a mixed UNIX and NT network.</para>
368         
369 </sect1>
370
371 </chapter>
372