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