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