Update from main archive 961219
[kopensolaris-gnu/glibc.git] / manual / nss.texi
1 @c each section should have index entries corresponding to the section title
2
3 @node Name Service Switch
4 @chapter System Databases and Name Service Switch
5
6 @cindex Name Service Switch
7 @cindex NSS
8 @cindex databases
9 Various functions in the C Library need to be configured to work
10 correctly in the local environment.  Traditionally, this was done by
11 using files (e.g., @file{/etc/passwd}), but other nameservices (line the
12 Network Information Service (NIS) and the Domain Name Service (DNS))
13 became popular, and were hacked into the C library, usually with a fixed
14 search order (@pxref{frobnicate, , ,jargon, The Jargon File}).
15
16 The GNU C Library contains a cleaner solution of this problem.  It is
17 designed after a method used by Sun Microsystems in the C library of
18 @w{Solaris 2}.  GNU C Library follows their name and calls this
19 scheme @dfn{Name Service Switch} (NSS).
20
21 Though the interface might be similar to Sun's version there is no
22 common code.  We never saw any source code of Sun's implementation and
23 so the internal interface is incompatible.  This is also manifests in the
24 file names we use as we will see later.
25
26
27 @menu
28 * NSS Basics::                  What is this NSS good for.
29 * NSS Configuration File::      Configuring NSS.
30 * NSS Module Internals::        How does it work internally.
31 * Extending NSS::               What to do to add services or databases.
32 @end menu
33
34 @node NSS Basics, NSS Configuration File, Name Service Switch, Name Service Switch
35 @section NSS Basics
36
37 The basic idea is to put the implementation of the different services
38 offered to access the databases in separate modules.  This has some
39 advantages:
40
41 @enumerate
42 @item
43 Contributors can add new services without adding them to GNU C Library.
44 @item
45 The modules can be updated separately.
46 @item
47 The C library image is smaller.
48 @end enumerate
49
50 To fulfill the first goal above the ABI of the modules will be described
51 below.  For getting the implementation of a new service right it is
52 important to understand how the functions in the modules get called.
53 They are in no way designed to be used by the programmer directly.
54 Instead the programmer should only use the documented and standardized
55 functions to access the databases.
56
57 @noindent
58 The databases available in the NSS are
59
60 @cindex ethers
61 @cindex group
62 @cindex hosts
63 @cindex netgroup
64 @cindex network
65 @cindex protocols
66 @cindex passwd
67 @cindex rpc
68 @cindex services
69 @cindex shadow
70 @vtable @code
71 @item ethers
72 Ethernet numbers,
73 @comment @pxref{Ethernet Numbers}.
74 @item group
75 Groups of users, @pxref{Group Database}.
76 @item hosts
77 Host names and numbers, @pxref{Host Names}.
78 @item netgroup
79 Network wide list of host and users, @pxref{Netgroup Database}.
80 @item network
81 Network names and numbers, @pxref{Networks Database}.
82 @item protocols
83 Network protocols, @pxref{Protocols Database}.
84 @item passwd
85 User passwords, @pxref{User Database}.
86 @item rpc
87 Remote procedure call names and numbers,
88 @comment @pxref{RPC Database}.
89 @item services
90 Network services, @pxref{Services Database}.
91 @item shadow
92 Shadow user passwords,
93 @comment @pxref{Shadow Password Database}.
94 @end vtable
95
96 @noindent
97 There will be some more added later (@code{aliases}, @code{automount},
98 @code{bootparams}, @code{netmasks}, and @code{publickey}).
99
100 @node NSS Configuration File, NSS Module Internals, NSS Basics, Name Service Switch
101 @section The NSS Configuration File
102
103 @cindex @file{/etc/nsswitch.conf}
104 @cindex @file{nsswitch.conf}
105 Somehow the NSS code must be told about the wishes of the user.  For
106 this reason there is the file @file{/etc/nsswitch.conf}.  For each
107 database this file contain a specification how the lookup process should
108 work.  The file could look like this:
109
110 @example
111 @include nsswitch.texi
112 @end example
113
114 The first column is the database as you can guess from the table above.
115 The rest of the line specifies how the lookup process works.  Please
116 note that you specify the way it works for each database individually.
117 This cannot be done with the old way of a monolithic implementation.
118
119 The configuration specification for each database can contain two
120 different items:
121
122 @itemize @bullet
123 @item
124 the service specification like @code{files}, @code{db}, or @code{nis}.
125 @item
126 the reaction on lookup result line @code{[NOTFOUND=return]}.
127 @end itemize
128
129 @menu
130 * Services in the NSS configuration::  Service names in the NSS configuration.
131 * Actions in the NSS configuration::  React appropriately to the lookup result.
132 * Notes on NSS Configuration File::  Things to take care about while
133                                      configuring NSS.
134 @end menu
135
136 @node Services in the NSS configuration, Actions in the NSS configuration, NSS Configuration File, NSS Configuration File
137 @subsection Services in the NSS configuration File
138
139 The above example file mentions four different services: @code{files},
140 @code{db}, @code{nis}, and @code{nisplus}.  This does not mean these
141 services are available on all sites and it does also not mean these are
142 all the services which will ever be available.
143
144 In fact, these names are simply strings which the NSS code uses to find
145 the implicitly addressed functions.  The internal interface will be
146 described later.  Visible to the user are the modules which implement an
147 individual service.
148
149 Assume the service @var{name} shall be used for a lookup.  The code for
150 this service is implemented in a module called @file{libnss_@var{name}}.
151 On a system supporting shared libraries this is in fact a shared library
152 with the name (for example) @file{libnss_@var{name}.so.1}.  The number
153 at the end is the currently used version of the interface which will not
154 change frequently.  Normally the user should not have to be cognizant of
155 these files since they should be placed in a directory where they are
156 found automatically.  Only the names of all available services are
157 important.
158
159 @node Actions in the NSS configuration, Notes on NSS Configuration File, Services in the NSS configuration, NSS Configuration File
160 @subsection Actions in the NSS configuration
161
162 The second item in the specification gives the user much finer control
163 on the lookup process.  Action items are placed between two service
164 names and are written within brackets.  The general form is
165
166 @display
167 @code{[} ( @code{!}? @var{status} @code{=} @var{action} )+ @code{]}
168 @end display
169
170 @noindent
171 where
172
173 @smallexample
174 @var{status} @result{} success | notfound | unavail | tryagain
175 @var{action} @result{} return | continue
176 @end smallexample
177
178 The case of the keywords is insignificant.  The @var{status}
179 values are the results of a call to a lookup function of a specific
180 service.  They mean
181
182 @ftable @samp
183 @item success
184 No error occurred and the wanted entry is returned.  The default action
185 for this is @code{return}.
186
187 @item notfound
188 The lookup process works ok but the needed value was not found.  The
189 default action is @code{continue}.
190
191 @item unavail
192 @cindex DNS server unavailable
193 The service is permanently unavailable.  This can either mean the needed
194 file is not available, or, for DNS, the server is not available or does
195 not allow queries.  The default action is @code{continue}.
196
197 @item tryagain
198 The service is temporarily unavailable.  This could mean a file is
199 locked or a server currently cannot accept more connections.  The
200 default action is @code{continue}.
201 @end ftable
202
203 @noindent
204 If we have a line like
205
206 @smallexample
207 ethers: nisplus [NOTFOUND=return] db files
208 @end smallexample
209
210 @noindent
211 this is equivalent to
212
213 @smallexample
214 ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
215                  TRYAGAIN=continue]
216         db      [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
217                  TRYAGAIN=continue]
218         files
219 @end smallexample
220
221 @noindent
222 (except that it would have to be written on one line).  The default
223 value for the actions are normally what you want, and only need to be
224 changed in exceptional cases.
225
226 If the optional @code{!} is placed before the @var{status} this means
227 the following action is used for all statii but @var{status} itself.
228 I.e., @code{!} is negation as in the C language (and others).
229
230 Before we explain the exception which makes this action item necessary
231 one more remark: obviously it makes no sense to add another action
232 item after the @code{files} service.  Since there is no other service
233 following the action @emph{always} is @code{return}.
234
235 @cindex nisplus, and completeness
236 Now, why is this @code{[NOTFOUND=return]} action useful?  To understand
237 this we should know that the @code{nisplus} service is often
238 complete; i.e., if an entry is not available in the NIS+ tables it is
239 not available anywhere else.  This is what is expressed by this action
240 item: it is useless to examine further services since they will not give
241 us a result.
242
243 @cindex nisplus, and booting
244 @cindex bootstrapping, and services
245 The situation would be different if the NIS+ service is not available
246 because the machine is booting.  In this case the return value of the
247 lookup function is not @code{notfound} but instead @code{unavail}.  And
248 as you can see in the complete form above: in this situation the
249 @code{db} and @code{files} services are used.  Neat, isn't it?  The
250 system administrator need not pay special care for the time the system
251 is not completely ready to work (while booting or shutdown or
252 network problems).
253
254
255 @node Notes on NSS Configuration File,  , Actions in the NSS configuration, NSS Configuration File
256 @subsection Notes on the NSS Configuration File
257
258 Finally a few more hints.  The NSS implementation is not completely
259 helpless if @file{/etc/nsswitch.conf} does not exist.  For
260 all supported databases there is a default value so it should normally
261 be possible to get the system running even if the file is corrupted or
262 missing.
263
264 @cindex default value, and NSS
265 For the @code{hosts} and @code{network} databases the default value is
266 @code{dns [!UNAVAIL=return] files}.  I.e., the system is prepared for
267 the DNS service not to be available but if it is available the answer it
268 returns is ultimative.
269
270 The @code{passwd}, @code{group}, and @code{shadow} databases are
271 traditionally handled in a special way.  The appropriate files in the
272 @file{/etc} directory are read but if an entry with a name starting
273 with a @code{+} character is found NIS is used.  This kind of lookup
274 remains possible by using the special lookup service @code{compat}
275 and the default value for the three databases above is
276 @code{compat [NOTFOUND=return] files}.
277
278 For all other databases the default value is
279 @code{nis [NOTFOUND=return] files}.  This solution give the best
280 chance to be correct since NIS and file based lookup is used.
281
282 @cindex optimizing NSS
283 A second point is that the user should try to optimize the lookup
284 process.  The different service have different response times.
285 A simple file look up on a local file could be fast, but if the file
286 is long and the needed entry is near the end of the file this may take
287 quite some time.  In this case it might be better to use the @code{db}
288 service which allows fast local access to large data sets.
289
290 Often the situation is that some global information like NIS must be
291 used.  So it is unavoidable to use service entries like @code{nis} etc.
292 But one should avoid slow services like this if possible.
293
294
295 @node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch
296 @section NSS Module Internals
297
298 Now it is time to described how the modules look like.  The functions
299 contained in a module are identified by their names.  I.e., there is no
300 jump table or the like.  How this is done is of no interest here; those
301 interested in this topic should read about Dynamic Linking.
302 @comment @ref{Dynamic Linking}.
303
304
305 @menu
306 * NSS Module Names::            Construction of the interface function of
307                                 the NSS modules.
308 * NSS Modules Interface::       Programming interface in the NSS module
309                                 functions.
310 @end menu
311
312 @node NSS Module Names, NSS Modules Interface, NSS Module Internals, NSS Module Internals
313 @subsection The Naming Scheme of the NSS Modules
314
315 @noindent
316 The name of each function consist of various parts:
317
318 @quotation
319        _nss_@var{service}_@var{function}
320 @end quotation
321
322 @var{service} of course corresponds to the name of the module this
323 function is found in.@footnote{Now you might ask why to duplicate this
324 information.  The answer is that we want to keep the possibility to link
325 directly with these shared objects.}  The @var{function} part is derived
326 from the interface function in the C library itself.  If the user calls
327 the function @code{gethostbyname} and the service used is @code{files}
328 the function
329
330 @smallexample
331        _nss_files_gethostbyname_r
332 @end smallexample
333
334 @noindent
335 in the module
336
337 @smallexample
338        libnss_files.so.1
339 @end smallexample
340
341 @noindent
342 @cindex reentrant NSS functions
343 is used.  You see, what is explained above in not the whole truth.  In
344 fact the NSS modules only contain reentrant versions of the lookup
345 functions.  I.e., if the user would call the @code{gethostbyname_r}
346 function this also would end in the above function.  For all user
347 interface functions the C library maps this call to a call to the
348 reentrant function.  For reentrant functions this is trivial since the
349 interface is (nearly) the same.  For the non-reentrant version pointers
350 to static buffers are used to replace the user supplied buffers.
351
352 I.e., the reentrant functions @emph{can} have counterparts.  No service
353 module is forced to have functions for all databases and all kinds to
354 access them.  If a function is not available it is simply treated as if
355 the function would return @code{unavail}
356 (@pxref{Actions in the NSS configuration}).
357
358 The file name @file{libnss_files.so.1} would be on a @w{Solaris 2}
359 system @file{nss_files.so.1}.  This is the difference mentioned above.
360 Sun's NSS modules are usable as modules which get indirectly loaded
361 only.
362
363 The NSS modules in the GNU C Library are prepared to be used as normal
364 libraries itself.
365 @comment Fix me if necessary.
366 This is @emph{not} true in the moment, though.  But the different
367 organization of the name space in the modules does not make it
368 impossible like it is for Solaris.  Now you can see why the modules are
369 still libraries.@footnote{There is a second explanation: we were too
370 lazy to change the Makefiles to allow the generation of shared objects
371 not starting with @file{lib} but do not tell this anybody.}
372
373
374 @node NSS Modules Interface,  , NSS Module Names, NSS Module Internals
375 @subsection The Interface of the Function in NSS Modules
376
377 Now we know about the functions contained in the modules.  It is now
378 time to describe the types.  When we mentioned the reentrant versions of
379 the functions above, this means there are some additional arguments
380 (compared with the standard, non-reentrant version).  The prototypes for
381 the non-reentrant and reentrant versions of our function above are:
382
383 @smallexample
384 struct hostent *gethostbyname (const char *name)
385
386 int gethostbyname_r (const char *name, struct hostent *result_buf,
387                      char *buf, size_t buflen, struct hostent **result,
388                      int *h_errnop)
389 @end smallexample
390
391 @noindent
392 The actual prototype of the function in the NSS modules in this case is
393
394 @smallexample
395 enum nss_status _nss_files_gethostbyname_r (const char *name,
396                                             struct hostent *result_buf,
397                                             char *buf, size_t buflen,
398                                             int *h_errnop)
399 @end smallexample
400
401 I.e., the interface function is in fact the reentrant function with the
402 change of the return value.  While the user-level function returns a
403 pointer to the result the reentrant function return an @code{enum
404 nss_status} value:
405
406 @vindex NSS_STATUS_TRYAGAIN
407 @vindex NSS_STATUS_UNAVAIL
408 @vindex NSS_STATUS_NOTFOUND
409 @vindex NSS_STATUS_SUCCESS
410 @ftable @code
411 @item NSS_STATUS_TRYAGAIN
412 numeric value @code{-2}
413
414 @item NSS_STATUS_UNAVAIL
415 numeric value @code{-1}
416
417 @item NSS_STATUS_NOTFOUND
418 numeric value @code{0}
419
420 @item NSS_STATUS_SUCCESS
421 numeric value @code{1}
422 @end ftable
423
424 @noindent
425 Now you see where the action items of the @file{/etc/nsswitch.conf} file
426 are used.
427
428 If you study the source code you will find there is a fifth value:
429 @code{NSS_STATUS_RETURN}.  This is an internal use only value, used by a
430 few functions in places where none of the above value can be used.  If
431 necessary the source code should be examined to learn about the details.
432
433 The above function has something special which is missing for almost all
434 the other module functions.  There is an argument @var{h_errnop}.  This
435 points to a variable which will be filled with the error code in case
436 the execution of the function fails for some reason.  The reentrant
437 function cannot use the global variable @var{h_errno};
438 @code{gethostbyname} calls @code{gethostbyname_r} with the
439 last argument set to @code{&h_errno}.
440
441 The @code{get@var{XXX}by@var{YYY}} functions are the most important
442 functions in the NSS modules.  But there are others which implement
443 the other ways to access system databases (say for the
444 password database, there are @code{setpwent}, @code{getpwent}, and
445 @code{endpwent}).  These will be described in more detail later.
446 Here we give a general way to determine the
447 signature of the module function:
448
449 @itemize @bullet
450 @item
451 the return value is @code{int};
452 @item
453 the name is as explain in @pxref{NSS Module Names};
454 @item
455 the first arguments are identical to the arguments of the non-reentrant
456 function;
457 @item
458 the next three arguments are:
459
460 @table @code
461 @item STRUCT_TYPE result_buf
462 pointer to buffer where the result is stored.  @code{STRUCT_TYPE} is
463 normally a struct which corresponds to the database.
464 @item char *buffer
465 pointer to a buffer where the function can store additional adata for
466 the result etc.
467 @item int buflen
468 length of the buffer pointed to by @var{buffer}.
469 @end table
470
471 @item
472 possibly a last argument @var{h_errnop}, for the host name and network
473 name lookup functions.
474 @end itemize
475
476 @noindent
477 This table is correct for all functions but the @code{set@dots{}ent}
478 and @code{end@dots{}ent} functions.
479
480
481 @node Extending NSS,  , NSS Module Internals, Name Service Switch
482 @section Extending NSS
483
484 One of the advantages of NSS mentioned above is that it can be extended
485 quite easily.  There are two ways in which the extension can happen:
486 adding another database or adding another service.  The former is
487 normally done only by the C library developers.  It is
488 here only important to remember that adding another database is
489 independent from adding another service because a service need not
490 support all databases or lookup functions.
491
492 A designer/implementor of a new service is therefore free to choose the
493 databases s/he is interested in and leave the rest for later (or
494 completely aside).
495
496 @menu
497 * Adding another Service to NSS::  What is to do to add a new service.
498 * NSS Module Function Internals::  Guidelines for writing new NSS
499                                         service functions.
500 @end menu
501
502 @node Adding another Service to NSS, NSS Module Function Internals, Extending NSS, Extending NSS
503 @subsection Adding another Service to NSS
504
505 The sources for a new service need not (and should not) be part of the
506 GNU C Library itself.  The developer retains complete control over the
507 sources and its development.  The links between the C library and the
508 new service module consists solely of the interface functions.
509
510 Each module is designed following a specific interface specification.
511 For now the version is 1 and this manifests in the version number of the
512 shared library object of the NSS modules: they have the extension
513 @code{.1}.  If the interface ever changes in an incompatible way,
514 this number will be increased---hopefully this will never be necessary.
515 Modules using the old interface will still be usable.
516
517 Developers of a new service will have to make sure that their module is
518 created using the correct interface number.  This means the file itself
519 must have the correct name and on ElF systems the @dfn{soname} (Shared
520 Object Name) must also have this number.  Building a module from a bunch
521 of object files on an ELF system using GNU CC could be done like this:
522
523 @smallexample
524 gcc -shared -o libnss_NAME.so.1 -Wl,-soname,libnss_NAME.so.1 OBJECTS
525 @end smallexample
526
527 @noindent
528 @ref{Link Options, Options for Linking, , gcc, GNU CC}, to learn
529 more about this command line.
530
531 To use the new module the library must be able to find it.  This can be
532 achieved by using options for the dynamic linker so that it will search
533 directory where the binary is placed.  For an ELF system this could be
534 done by adding the wanted directory to the value of
535 @code{LD_LIBRARY_PATH}.
536
537 But this is not always possible since some program (those which run
538 under IDs which do not belong to the user) ignore this variable.
539 Therefore the stable version of the module should be placed into a
540 directory which is searched by the dynamic linker.  Normally this should
541 be the directory @file{$prefix/lib}, where @file{$prefix} corresponds to
542 the value given to configure using the @code{--prefix} option.  But be
543 careful: this should only be done if it is clear the module does not
544 cause any harm.  System administrators should be careful.
545
546
547 @node NSS Module Function Internals,  , Adding another Service to NSS, Extending NSS
548 @subsection Internals of the NSS Module Functions
549
550 Until now we only provided the syntactic interface for the functions in
551 the NSS module.  In fact there is not more much we can tell since the
552 implementation obviously is different for each function.  But a few
553 general rules must be followed by all functions.
554
555 In fact there are four kinds of different functions which may appear in
556 the interface.  All derive from the traditional ones for system databases.
557 @var{db} in the following table is normally an abbreviation for the
558 database (e.g., it is @code{pw} for the password database).
559
560 @table @code
561 @item enum nss_status _nss_@var{database}_set@var{db}ent (void)
562 This function prepares the service for following operations.  For a
563 simple file based lookup this means files could be opened, for other
564 services this function simply is a noop.
565
566 One special case for this function is that it takes an additional
567 argument for some @var{database}s (i.e., the interface is
568 @code{int set@var{db}ent (int)}).  @ref{Host Names}, which describes the
569 @code{sethostent} function.
570
571 The return value should be @var{NSS_STATUS_SUCCESS} or according to the
572 table above in case of an error (@pxref{NSS Modules Interface}).
573
574 @item enum nss_status _nss_@var{database}_end@var{db}ent (void)
575 This function simply closes all files which are still open or removes
576 buffer caches.  If there are no files or buffers to remove this is again
577 a simple noop.
578
579 There normally is no return value different to @var{NSS_STATUS_SUCCESS}.
580
581 @item enum nss_status _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, size_t buflen)
582 Since this function will be called several times in a row to retrieve
583 one entry after the other it must keep some kind of state.  But this
584 also means the functions are not really reentrant.  They are reentrant
585 only in that simultaneous calls to this function will not try to
586 write the retrieved data in the same place (as it would be the case for
587 the non-reentrant functions); instead, it writes to the structure
588 pointed to by the @var{result} parameter.  But the calls share a common
589 state and in the case of a file access this means they return neighboring
590 entries in the file.
591
592 The buffer of length @var{buflen} pointed to by @var{buffer} can be used
593 for storing some additional data for the result.  It is @emph{not}
594 guaranteed that the same buffer will be passed for the next call of this
595 function.  Therefore one must not misuse this buffer to save some state
596 information from one call to another.
597
598 As explained above this function could also have an additional last
599 argument.  This depends on the database used; it happens only for
600 @code{host} and @code{network}.
601
602 The function shall return @code{NSS_STATUS_SUCCESS} as long as their are
603 more entries.  When the last entry was read it should return
604 @code{NSS_STATUS_NOTFOUND}.  When the buffer given as an argument is too
605 small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be
606 returned.  When the service was not formerly initialized by a call to
607 @code{_nss_@var{DATABASE}_set@var{db}ent} all return value allowed for
608 this function can also be returned here.
609
610 @item enum nss_status _nss_@var{DATABASE}_get@var{db}by@var{XX}_r (@var{PARAMS}, @var{STRUCTURE} *result, char *buffer, size_t buflen)
611 This function shall return the entry from the database which is
612 addressed by the @var{PARAMS}.  The type and number of these arguments
613 vary.  It must be individually determined by looking to the user-level
614 interface functions.  All arguments given to the non-reentrant version
615 are here described by @var{PARAMS}.
616
617 The result must be stored in the structure pointed to by @var{result}.
618 If there is additional data to return (say strings, where the
619 @var{result} structure only contains pointers) the function must use the
620 @var{buffer} or length @var{buflen}.  There must not be any references
621 to non-constant global data.
622
623 The implementation of this function should honour the @var{stayopen}
624 flag set by the @code{set@var{DB}ent} function whenever this makes sense.
625
626 Again, this function takes an additional last argument for the
627 @code{host} and @code{network} database.
628
629 The return value should as always follow the rules given above
630 (@pxref{NSS Modules Interface}).
631
632 @end table