1 @c each section should have index entries corresponding to the section title
3 @node Name Service Switch
4 @chapter System Databases and Name Service Switch
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}.
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).
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 is incompatible. This is also manifests in the
21 file names we use as we will see later.
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.
31 @node NSS Basics, NSS Configuration File, Name Service Switch, Name Service Switch
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
40 Contributors can add new services without adding them to GNU C Library.
42 The modules can be updated separately.
44 The C library image is smaller.
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.
55 The databases available in the NSS are
69 @comment @pxref{Ethernet Numbers}.
71 Groups of users, @pxref{Group Database}.
73 Host names and numbers, @pxref{Host Names}.
75 Network names and numbers, @pxref{Networks Database}.
77 Network protocols, @pxref{Protocols Database}.
79 User passwords, @pxref{User Database}.
81 Remote procedure call names and numbers,
82 @comment @pxref{RPC Database}.
84 Network services, @pxref{Services Database}.
86 Shadow user passwords,
87 @comment @pxref{Shadow Password Database}.
91 There will be some more added later (@code{aliases}, @code{automount},
92 @code{bootparams}, @code{netgroup}, @code{netmasks}, and
95 @node NSS Configuration File, NSS Module Internals, NSS Basics, Name Service Switch
96 @section The NSS Configuration File
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:
106 @include nsswitch.texi
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.
114 The configuration specification for each database can contain two
119 the service specification like @code{files}, @code{db}, or @code{nis}.
121 the reaction on lookup result line @code{[NOTFOUND=return]}.
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
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
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.
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
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
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
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
162 @t{[} ( @t{!}? @var{status} @t{=} @var{action} )+ @t{]}
169 @var{status} @result{} success | notfound | unavail | tryagain
170 @var{action} @result{} return | continue
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
179 No error occured an the wanted entry is returned. The default action
180 for this is @code{return}.
183 The lookup process works ok but the needed value was not found. The
184 default action is @code{continue}.
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}.
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}.
199 If we have a line like
202 ethers: nisplus [NOTFOUND=return] db files
206 this is equivalent to
209 ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
211 db [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
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.
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).
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}.
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
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
250 @node Notes on NSS Configuration File, , Actions in the NSS configuration, NSS Configuration File
251 @subsection Notes on the NSS Configuration File
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
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.
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.
271 @node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch
272 @section NSS Module Internals
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}.
282 * NSS Module Names:: Construction of the interface function of
284 * NSS Modules Interface:: Programming interface in the NSS module
288 @node NSS Module Names, NSS Modules Interface, NSS Module Internals, NSS Module Internals
289 @subsection The Naming Scheme of the NSS Modules
292 The name of each function consist of various parts:
295 _nss_@var{service}_@var{function}
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}
307 _nss_files_gethostbyname_r
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.
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}).
334 The file name @file{libnss_files.so.1} would be on a @w{Solaris 2}
335 system @file{nss_files.so.1}. This is the difference mentioned above.
336 Sun's NSS modules are usable as modules which get indirectly loaded
339 The NSS modules in the GNU C Library are prepared to be used as normal
341 @comment Fix me if necessary.
342 This is @emph{not} true in the moment, though. But the different
343 organization of the name space in the modules does not make it
344 impossible like it is for Solaris. Now you can see why the modules are
345 still libraries.@footnote{There is a second explanation: we were too
346 lazy to change the Makefiles to allow the generation of shared objects
347 not starting with @file{lib} but do not tell this anybody.}
350 @node NSS Modules Interface, , NSS Module Names, NSS Module Internals
351 @subsection The Interface of the Function in NSS Modules
353 Now we know about the functions contained in the modules. It is now
354 time to describe the types. When we mentioned the reentrant versions of
355 the functions above, this means there are some additional arguments
356 (compared with the standard, non-reentrant version). The prototypes for
357 the non-reentrant and reentrant versions of our function above are:
360 struct hostent *gethostbyname (const char *name)
362 struct hostent *gethostbyname_r (const char *name,
363 struct hostent *result_buf, char *buf,
364 int buflen, int *h_errnop)
368 The actual prototype of the function is the NSS modules in this case is
371 int _nss_files_gethostbyname_r (const char *name,
372 struct hostent *result_buf, char *buf,
373 int buflen, int *h_errnop)
376 I.e., the interface function is in fact the reentrant function with
377 the change of the return value. While the user-level function returns a
378 pointer to the result the reentrant function return an @code{int} value:
380 @cindex NSS_STATUS_TRYAGAIN
381 @cindex NSS_STATUS_UNAVAIL
382 @cindex NSS_STATUS_NOTFOUND
383 @cindex NSS_STATUS_SUCCESS
385 @item NSS_STATUS_TRYAGAIN
386 numeric value @code{-2}
388 @item NSS_STATUS_UNAVAIL
389 numeric value @code{-1}
391 @item NSS_STATUS_NOTFOUND
392 numeric value @code{0}
394 @item NSS_STATUS_SUCCESS
395 numeric value @code{1}
399 Now you see where the action items of the @file{/etc/nsswitch.conf} file
402 The above function has somthing special which is missing for almost all
403 the other module functions. There is an argument @var{h_errnop}. This
404 points to a variable which will be filled with the error code in case
405 the execution of the function fails for some reason. The reentrant
406 function cannot use the global variable @var{h_errno};
407 @code{gethostbyname} calls @code{gethostbyname_r} with the
408 last argument set to @code{&h_errno}.
410 The @code{get@var{XXX}by@var{YYY}} functions are the most important
411 functions in the NSS modules. But there are others which implement
412 the other ways to access system databases (say for the
413 password database, there are @code{setpwent}, @code{getpwent}, and
414 @code{endpwent}). These will be described in more detail later.
415 Here we give a general way to determine the
416 signature of the module function:
420 the return value is @code{int};
422 the name is as explain in @pxref{NSS Module Names};
424 the first arguments are identical to the arguments of the non-reentrant
427 the next three arguments are:
430 @item STRUCT_TYPE result_buf
431 pointer to buffer where the result is stored. @code{STRUCT_TYPE} is
432 normally a struct which corresponds to the database.
434 pointer to a buffer where the function can store additional adata for
437 length of the buffer pointed to by @var{buffer}.
441 possibly a last argument @var{h_errnop}, for the host name and network
442 name lookup functions.
446 This table is correct for all functions but the @code{set@dots{}ent}
447 and @code{end@dots{}ent} functions.
450 @node Extending NSS, , NSS Module Internals, Name Service Switch
451 @section Extending NSS
453 One of the advantages of NSS mentioned above is that it can be extended
454 quite easily. There are two ways in which the extension can happen:
455 adding another database or adding another service. The former is
456 normally done only by the C library developers. It is
457 here only important to remember that adding another database is
458 independent from adding another service because a service need not
459 support all databases or lookup functions.
461 A designer/implementor of a new service is therefore free to choose the
462 databases s/he is interested in and leave the rest for later (or
466 * Adding another Service to NSS:: What is to do to add a new service.
467 * NSS Module Function Internals:: Guidelines for writing new NSS
471 @node Adding another Service to NSS, NSS Module Function Internals, Extending NSS, Extending NSS
472 @subsection Adding another Service to NSS
474 The sources for a new service need not (and should not) be part of the
475 GNU C Library itself. The developer retains complete control over the
476 sources and its development. The links between the C library and the
477 new service module consists solely of the interface functions.
479 Each module is designed following a specific interface specification.
480 For now the version is 1 and this manifests in the version number of the
481 shared library object of the NSS modules: they have the extension
482 @code{.1}. If the interface ever changes in an incompatible way,
483 this number will be increased---hopefully this will never be necessary.
484 Modules using the old interface will still be usable.
486 Developers of a new service will have to make sure that their module is
487 created using the correct interface number. This means the file itself
488 must have the correct name and on ElF systems the @dfn{soname} (Shared
489 Object Name) must also have this number. Building a module from a bunch
490 of object files on an ELF system using GNU CC could be done like this:
493 gcc -shared -o libnss_NAME.so.1 -Wl,-soname,libnss_NAME.so.1 OBJECTS
497 @ref{Link Options, Options for Linking, , gcc, GNU CC}, to learn
498 more about this command line.
500 To use the new module the library must be able to find it. This can be
501 achieved by using options for the dynamic linker so that it will search
502 directory where the binary is placed. For an ELF system this could be
503 done by adding the wanted directory to the value of
504 @code{LD_LIBRARY_PATH}.
506 But this is not always possible since some program (those which run
507 under IDs which do not belong to the user) ignore this variable.
508 Therefore the stable version of the module should be placed into a
509 directory which is searched by the dynamic linker. Normally this should
510 be the directory @file{$prefix/lib}, where @file{$prefix} corresponds to
511 the value given to configure using the @code{--prefix} option. But be
512 careful: this should only be done if it is clear the module does not
513 cause any harm. System administrators should be careful.
516 @node NSS Module Function Internals, , Adding another Service to NSS, Extending NSS
517 @subsection Internals of the NSS Module Functions
519 Until now we only provided the syntactic interface for the functions in
520 the NSS module. In fact there is not more much we can tell since the
521 implementation obviously is different for each function. But a few
522 general rules must be followed by all functions.
524 In fact there are four kinds of different functions which may appear in
525 the interface. All derive from the traditional ones for system databases.
526 @var{db} in the following table is normally an abbreviation for the
527 database (e.g., it is @code{pw} for the password database).
530 @item int _nss_@var{database}_set@var{db}ent (void)
531 This function prepares the service for following operations. For a
532 simple file based lookup this means files could be opened, for other
533 services this function simply is a noop.
535 One special case for this function is that it takes an additional
536 argument for some @var{database}s (i.e., the interface is
537 @code{int set@var{db}ent (int)}). @ref{Host Names}, which describes the
538 @code{sethostent} function.
540 The return value should be @var{NSS_STATUS_SUCCESS} or according to the
541 table above in case of an error (@pxref{NSS Modules Interface}).
543 @item int _nss_@var{database}_end@var{db}ent (void)
544 This function simply closes all files which are still open or removes
545 buffer caches. If there are no files or buffers to remove this is again
548 There normally is no return value different to @var{NSS_STATUS_SUCCESS}.
550 @item int _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, int buflen)
551 Since this function will be called several times in a row to retrieve
552 one entry after the other it must keep some kind of state. But this
553 also means the functions are not really reentrant. They are reentrant
554 only in that simultaneous calls to this function will not try to
555 write the retrieved data in the same place (as it would be the case for
556 the non-reentrant functions); instead, it writes to the structure
557 pointed to by the @var{result} parameter. But the calls share a common
558 state and in the case of a file access this means they return neighboring
561 The buffer of length @var{buflen} pointed to by @var{buffer} can be used
562 for storing some additional data for the result. It is @emph{not}
563 guaranteed that the same buffer will be passed for the next call of this
564 function. Therefore one must not misuse this buffer to save some state
565 information from one call to another.
567 As explained above this function could also have an additional last
568 argument. This depends on the database used; it happens only for
569 @code{host} and @code{network}.
571 The function shall return @code{NSS_STATUS_SUCCESS} as long as their are
572 more entries. When the last entry was read it should return
573 @code{NSS_STATUS_NOTFOUND}. When the buffer given as an argument is too
574 small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be
575 returned. When the service was not formerly initialized by a call to
576 @code{_nss_@var{DATABASE}_set@var{db}ent} all return value allowed for
577 this function can also be returned here.
579 @item int _nss_@var{DATABASE}_get@var{db}by@var{XX}_r (@var{PARAMS}, @var{STRUCTURE} *result, char *buffer, int buflen)
580 This function shall return the entry from the database which is
581 addressed by the @var{PARAMS}. The type and number of these arguments
582 vary. It must be individually determined by looking to the user-level
583 interface functions. All arguments given to the non-reentrant version
584 are here described by @var{PARAMS}.
586 The result must be stored in the structure pointed to by @var{result}.
587 If there is additional data to return (say strings, where the
588 @var{result} structure only contains pointers) the function must use the
589 @var{buffer} or length @var{buflen}. There must not be any references
590 to non-constant global data.
592 The implementation of this function should honour the @var{stayopen}
593 flag set by the @code{set@var{DB}ent} function whenever this makes sense.
595 Again, this function takes an additional last argument for the
596 @code{host} and @code{network} database.
598 The return value should as always follow the rules given above
599 (@pxref{NSS Modules Interface}).