diff options
Diffstat (limited to 'manual/nss.texi')
| -rw-r--r-- | manual/nss.texi | 734 |
1 files changed, 0 insertions, 734 deletions
diff --git a/manual/nss.texi b/manual/nss.texi deleted file mode 100644 index ee70ad309d..0000000000 --- a/manual/nss.texi +++ /dev/null @@ -1,734 +0,0 @@ -@node Name Service Switch, Users and Groups, Job Control, Top -@chapter System Databases and Name Service Switch -@c %MENU% Accessing system databases -@cindex Name Service Switch -@cindex NSS -@cindex databases - -Various functions in the C Library need to be configured to work -correctly in the local environment. Traditionally, this was done by -using files (e.g., @file{/etc/passwd}), but other nameservices (like the -Network Information Service (NIS) and the Domain Name Service (DNS)) -became popular, and were hacked into the C library, usually with a fixed -search order. - -@Theglibc{} contains a cleaner solution to this problem. It is -designed after a method used by Sun Microsystems in the C library of -@w{Solaris 2}. @Theglibc{} follows their name and calls this -scheme @dfn{Name Service Switch} (NSS). - -Though the interface might be similar to Sun's version there is no -common code. We never saw any source code of Sun's implementation and -so the internal interface is incompatible. This also manifests in the -file names we use as we will see later. - - -@menu -* NSS Basics:: What is this NSS good for. -* NSS Configuration File:: Configuring NSS. -* NSS Module Internals:: How does it work internally. -* Extending NSS:: What to do to add services or databases. -@end menu - -@node NSS Basics, NSS Configuration File, Name Service Switch, Name Service Switch -@section NSS Basics - -The basic idea is to put the implementation of the different services -offered to access the databases in separate modules. This has some -advantages: - -@enumerate -@item -Contributors can add new services without adding them to @theglibc{}. -@item -The modules can be updated separately. -@item -The C library image is smaller. -@end enumerate - -To fulfill the first goal above, the ABI of the modules will be described -below. For getting the implementation of a new service right it is -important to understand how the functions in the modules get called. -They are in no way designed to be used by the programmer directly. -Instead the programmer should only use the documented and standardized -functions to access the databases. - -@noindent -The databases available in the NSS are - -@cindex ethers -@cindex group -@cindex hosts -@cindex netgroup -@cindex networks -@cindex protocols -@cindex passwd -@cindex rpc -@cindex services -@cindex shadow -@table @code -@item aliases -Mail aliases -@comment @pxref{Mail Aliases}. -@item ethers -Ethernet numbers, -@comment @pxref{Ethernet Numbers}. -@item group -Groups of users, @pxref{Group Database}. -@item hosts -Host names and numbers, @pxref{Host Names}. -@item netgroup -Network wide list of host and users, @pxref{Netgroup Database}. -@item networks -Network names and numbers, @pxref{Networks Database}. -@item protocols -Network protocols, @pxref{Protocols Database}. -@item passwd -User passwords, @pxref{User Database}. -@item rpc -Remote procedure call names and numbers, -@comment @pxref{RPC Database}. -@item services -Network services, @pxref{Services Database}. -@item shadow -Shadow user passwords, -@comment @pxref{Shadow Password Database}. -@end table - -@noindent -There will be some more added later (@code{automount}, @code{bootparams}, -@code{netmasks}, and @code{publickey}). - -@node NSS Configuration File, NSS Module Internals, NSS Basics, Name Service Switch -@section The NSS Configuration File - -@cindex @file{/etc/nsswitch.conf} -@cindex @file{nsswitch.conf} -Somehow the NSS code must be told about the wishes of the user. For -this reason there is the file @file{/etc/nsswitch.conf}. For each -database, this file contains a specification of how the lookup process should -work. The file could look like this: - -@example -@include nsswitch.texi -@end example - -The first column is the database as you can guess from the table above. -The rest of the line specifies how the lookup process works. Please -note that you specify the way it works for each database individually. -This cannot be done with the old way of a monolithic implementation. - -The configuration specification for each database can contain two -different items: - -@itemize @bullet -@item -the service specification like @code{files}, @code{db}, or @code{nis}. -@item -the reaction on lookup result like @code{[NOTFOUND=return]}. -@end itemize - -@menu -* Services in the NSS configuration:: Service names in the NSS configuration. -* Actions in the NSS configuration:: React appropriately to the lookup result. -* Notes on NSS Configuration File:: Things to take care about while - configuring NSS. -@end menu - -@node Services in the NSS configuration, Actions in the NSS configuration, NSS Configuration File, NSS Configuration File -@subsection Services in the NSS configuration File - -The above example file mentions five different services: @code{files}, -@code{db}, @code{dns}, @code{nis}, and @code{nisplus}. This does not -mean these -services are available on all sites and neither does it mean these are -all the services which will ever be available. - -In fact, these names are simply strings which the NSS code uses to find -the implicitly addressed functions. The internal interface will be -described later. Visible to the user are the modules which implement an -individual service. - -Assume the service @var{name} shall be used for a lookup. The code for -this service is implemented in a module called @file{libnss_@var{name}}. -On a system supporting shared libraries this is in fact a shared library -with the name (for example) @file{libnss_@var{name}.so.2}. The number -at the end is the currently used version of the interface which will not -change frequently. Normally the user should not have to be cognizant of -these files since they should be placed in a directory where they are -found automatically. Only the names of all available services are -important. - -@node Actions in the NSS configuration, Notes on NSS Configuration File, Services in the NSS configuration, NSS Configuration File -@subsection Actions in the NSS configuration - -The second item in the specification gives the user much finer control -on the lookup process. Action items are placed between two service -names and are written within brackets. The general form is - -@display -@code{[} ( @code{!}? @var{status} @code{=} @var{action} )+ @code{]} -@end display - -@noindent -where - -@smallexample -@var{status} @result{} success | notfound | unavail | tryagain -@var{action} @result{} return | continue -@end smallexample - -The case of the keywords is insignificant. The @var{status} -values are the results of a call to a lookup function of a specific -service. They mean: - -@ftable @samp -@item success -No error occurred and the wanted entry is returned. The default action -for this is @code{return}. - -@item notfound -The lookup process works ok but the needed value was not found. The -default action is @code{continue}. - -@item unavail -@cindex DNS server unavailable -The service is permanently unavailable. This can either mean the needed -file is not available, or, for DNS, the server is not available or does -not allow queries. The default action is @code{continue}. - -@item tryagain -The service is temporarily unavailable. This could mean a file is -locked or a server currently cannot accept more connections. The -default action is @code{continue}. -@end ftable - -@noindent -The @var{action} values mean: - -@ftable @samp -@item return - -If the status matches, stop the lookup process at this service -specification. If an entry is available, provide it to the application. -If an error occurred, report it to the application. In case of a prior -@samp{merge} action, the data is combined with previous lookup results, -as explained below. - -@item continue - -If the status matches, proceed with the lookup process at the next -entry, discarding the result of the current lookup (and any merged -data). An exception is the @samp{initgroups} database and the -@samp{success} status, where @samp{continue} acts like @code{merge} -below. - -@item merge - -Proceed with the lookup process, retaining the current lookup result. -This action is useful only with the @samp{success} status. If a -subsequent service lookup succeeds and has a matching @samp{return} -specification, the results are merged, the lookup process ends, and the -merged results are returned to the application. If the following service -has a matching @samp{merge} action, the lookup process continues, -retaining the combined data from this and any previous lookups. - -After a @code{merge} action, errors from subsequent lookups are ignored, -and the data gathered so far will be returned. - -The @samp{merge} only applies to the @samp{success} status. It is -currently implemented for the @samp{group} database and its group -members field, @samp{gr_mem}. If specified for other databases, it -causes the lookup to fail (if the @var{status} matches). - -When processing @samp{merge} for @samp{group} membership, the group GID -and name must be identical for both entries. If only one or the other is -a match, the behavior is undefined. - -@end ftable - -@noindent -If we have a line like - -@smallexample -ethers: nisplus [NOTFOUND=return] db files -@end smallexample - -@noindent -this is equivalent to - -@smallexample -ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue - TRYAGAIN=continue] - db [SUCCESS=return NOTFOUND=continue UNAVAIL=continue - TRYAGAIN=continue] - files -@end smallexample - -@noindent -(except that it would have to be written on one line). The default -value for the actions are normally what you want, and only need to be -changed in exceptional cases. - -If the optional @code{!} is placed before the @var{status} this means -the following action is used for all statuses but @var{status} itself. -I.e., @code{!} is negation as in the C language (and others). - -Before we explain the exception which makes this action item necessary -one more remark: obviously it makes no sense to add another action -item after the @code{files} service. Since there is no other service -following the action @emph{always} is @code{return}. - -@cindex nisplus, and completeness -Now, why is this @code{[NOTFOUND=return]} action useful? To understand -this we should know that the @code{nisplus} service is often -complete; i.e., if an entry is not available in the NIS+ tables it is -not available anywhere else. This is what is expressed by this action -item: it is useless to examine further services since they will not give -us a result. - -@cindex nisplus, and booting -@cindex bootstrapping, and services -The situation would be different if the NIS+ service is not available -because the machine is booting. In this case the return value of the -lookup function is not @code{notfound} but instead @code{unavail}. And -as you can see in the complete form above: in this situation the -@code{db} and @code{files} services are used. Neat, isn't it? The -system administrator need not pay special care for the time the system -is not completely ready to work (while booting or shutdown or -network problems). - - -@node Notes on NSS Configuration File, , Actions in the NSS configuration, NSS Configuration File -@subsection Notes on the NSS Configuration File - -Finally a few more hints. The NSS implementation is not completely -helpless if @file{/etc/nsswitch.conf} does not exist. For -all supported databases there is a default value so it should normally -be possible to get the system running even if the file is corrupted or -missing. - -@cindex default value, and NSS -For the @code{hosts} and @code{networks} databases the default value is -@code{dns [!UNAVAIL=return] files}. I.e., the system is prepared for -the DNS service not to be available but if it is available the answer it -returns is definitive. - -The @code{passwd}, @code{group}, and @code{shadow} databases are -traditionally handled in a special way. The appropriate files in the -@file{/etc} directory are read but if an entry with a name starting -with a @code{+} character is found NIS is used. This kind of lookup -remains possible by using the special lookup service @code{compat} -and the default value for the three databases above is -@code{compat [NOTFOUND=return] files}. - -For all other databases the default value is -@code{nis [NOTFOUND=return] files}. This solution gives the best -chance to be correct since NIS and file based lookups are used. - -@cindex optimizing NSS -A second point is that the user should try to optimize the lookup -process. The different service have different response times. -A simple file look up on a local file could be fast, but if the file -is long and the needed entry is near the end of the file this may take -quite some time. In this case it might be better to use the @code{db} -service which allows fast local access to large data sets. - -Often the situation is that some global information like NIS must be -used. So it is unavoidable to use service entries like @code{nis} etc. -But one should avoid slow services like this if possible. - - -@node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch -@section NSS Module Internals - -Now it is time to describe what the modules look like. The functions -contained in a module are identified by their names. I.e., there is no -jump table or the like. How this is done is of no interest here; those -interested in this topic should read about Dynamic Linking. -@comment @ref{Dynamic Linking}. - - -@menu -* NSS Module Names:: Construction of the interface function of - the NSS modules. -* NSS Modules Interface:: Programming interface in the NSS module - functions. -@end menu - -@node NSS Module Names, NSS Modules Interface, NSS Module Internals, NSS Module Internals -@subsection The Naming Scheme of the NSS Modules - -@noindent -The name of each function consists of various parts: - -@quotation - _nss_@var{service}_@var{function} -@end quotation - -@var{service} of course corresponds to the name of the module this -function is found in.@footnote{Now you might ask why this information is -duplicated. The answer is that we want to make it possible to link -directly with these shared objects.} The @var{function} part is derived -from the interface function in the C library itself. If the user calls -the function @code{gethostbyname} and the service used is @code{files} -the function - -@smallexample - _nss_files_gethostbyname_r -@end smallexample - -@noindent -in the module - -@smallexample - libnss_files.so.2 -@end smallexample - -@noindent -@cindex reentrant NSS functions -is used. You see, what is explained above in not the whole truth. In -fact the NSS modules only contain reentrant versions of the lookup -functions. I.e., if the user would call the @code{gethostbyname_r} -function this also would end in the above function. For all user -interface functions the C library maps this call to a call to the -reentrant function. For reentrant functions this is trivial since the -interface is (nearly) the same. For the non-reentrant version the -library keeps internal buffers which are used to replace the user -supplied buffer. - -I.e., the reentrant functions @emph{can} have counterparts. No service -module is forced to have functions for all databases and all kinds to -access them. If a function is not available it is simply treated as if -the function would return @code{unavail} -(@pxref{Actions in the NSS configuration}). - -The file name @file{libnss_files.so.2} would be on a @w{Solaris 2} -system @file{nss_files.so.2}. This is the difference mentioned above. -Sun's NSS modules are usable as modules which get indirectly loaded -only. - -The NSS modules in @theglibc{} are prepared to be used as normal -libraries themselves. This is @emph{not} true at the moment, though. -However, the organization of the name space in the modules does not make it -impossible like it is for Solaris. Now you can see why the modules are -still libraries.@footnote{There is a second explanation: we were too -lazy to change the Makefiles to allow the generation of shared objects -not starting with @file{lib} but don't tell this to anybody.} - - -@node NSS Modules Interface, , NSS Module Names, NSS Module Internals -@subsection The Interface of the Function in NSS Modules - -Now we know about the functions contained in the modules. It is now -time to describe the types. When we mentioned the reentrant versions of -the functions above, this means there are some additional arguments -(compared with the standard, non-reentrant versions). The prototypes for -the non-reentrant and reentrant versions of our function above are: - -@smallexample -struct hostent *gethostbyname (const char *name) - -int gethostbyname_r (const char *name, struct hostent *result_buf, - char *buf, size_t buflen, struct hostent **result, - int *h_errnop) -@end smallexample - -@noindent -The actual prototype of the function in the NSS modules in this case is - -@smallexample -enum nss_status _nss_files_gethostbyname_r (const char *name, - struct hostent *result_buf, - char *buf, size_t buflen, - int *errnop, int *h_errnop) -@end smallexample - -I.e., the interface function is in fact the reentrant function with the -change of the return value, the omission of the @var{result} parameter, -and the addition of the @var{errnop} parameter. While the user-level -function returns a pointer to the result the reentrant function return -an @code{enum nss_status} value: - -@vtable @code -@item NSS_STATUS_TRYAGAIN -numeric value @code{-2} - -@item NSS_STATUS_UNAVAIL -numeric value @code{-1} - -@item NSS_STATUS_NOTFOUND -numeric value @code{0} - -@item NSS_STATUS_SUCCESS -numeric value @code{1} -@end vtable - -@noindent -Now you see where the action items of the @file{/etc/nsswitch.conf} file -are used. - -If you study the source code you will find there is a fifth value: -@code{NSS_STATUS_RETURN}. This is an internal use only value, used by a -few functions in places where none of the above value can be used. If -necessary the source code should be examined to learn about the details. - -In case the interface function has to return an error it is important -that the correct error code is stored in @code{*@var{errnop}}. Some -return status values have only one associated error code, others have -more. - -@multitable @columnfractions .3 .2 .50 -@item -@code{NSS_STATUS_TRYAGAIN} @tab - @code{EAGAIN} @tab One of the functions used ran temporarily out of -resources or a service is currently not available. -@item -@tab - @code{ERANGE} @tab The provided buffer is not large enough. -The function should be called again with a larger buffer. -@item -@code{NSS_STATUS_UNAVAIL} @tab - @code{ENOENT} @tab A necessary input file cannot be found. -@item -@code{NSS_STATUS_NOTFOUND} @tab - @code{ENOENT} @tab The requested entry is not available. - -@item -@code{NSS_STATUS_NOTFOUND} @tab - @code{SUCCESS} @tab There are no entries. -Use this to avoid returning errors for inactive services which may -be enabled at a later time. This is not the same as the service -being temporarily unavailable. -@end multitable - -These are proposed values. There can be other error codes and the -described error codes can have different meaning. @strong{With one -exception:} when returning @code{NSS_STATUS_TRYAGAIN} the error code -@code{ERANGE} @emph{must} mean that the user provided buffer is too -small. Everything else is non-critical. - -In statically linked programs, the main application and NSS modules do -not share the same thread-local variable @code{errno}, which is the -reason why there is an explicit @var{errnop} function argument. - -The above function has something special which is missing for almost all -the other module functions. There is an argument @var{h_errnop}. This -points to a variable which will be filled with the error code in case -the execution of the function fails for some reason. (In statically -linked programs, the thread-local variable @code{h_errno} is not shared -with the main application.) - -The @code{get@var{XXX}by@var{YYY}} functions are the most important -functions in the NSS modules. But there are others which implement -the other ways to access system databases (say for the -password database, there are @code{setpwent}, @code{getpwent}, and -@code{endpwent}). These will be described in more detail later. -Here we give a general way to determine the -signature of the module function: - -@itemize @bullet -@item -the return value is @code{enum nss_status}; -@item -the name (@pxref{NSS Module Names}); -@item -the first arguments are identical to the arguments of the non-reentrant -function; -@item -the next four arguments are: - -@table @code -@item STRUCT_TYPE *result_buf -pointer to buffer where the result is stored. @code{STRUCT_TYPE} is -normally a struct which corresponds to the database. -@item char *buffer -pointer to a buffer where the function can store additional data for -the result etc. -@item size_t buflen -length of the buffer pointed to by @var{buffer}. -@item int *errnop -the low-level error code to return to the application. If the return -value is not @code{NSS_STATUS_SUCCESS}, @code{*@var{errnop}} needs to be -set to a non-zero value. An NSS module should never set -@code{*@var{errnop}} to zero. The value @code{ERANGE} is special, as -described above. -@end table - -@item -possibly a last argument @var{h_errnop}, for the host name and network -name lookup functions. If the return value is not -@code{NSS_STATUS_SUCCESS}, @code{*@var{h_errnop}} needs to be set to a -non-zero value. A generic error code is @code{NETDB_INTERNAL}, which -instructs the caller to examine @code{*@var{errnop}} for further -details. (This includes the @code{ERANGE} special case.) -@end itemize - -@noindent -This table is correct for all functions but the @code{set@dots{}ent} -and @code{end@dots{}ent} functions. - - -@node Extending NSS, , NSS Module Internals, Name Service Switch -@section Extending NSS - -One of the advantages of NSS mentioned above is that it can be extended -quite easily. There are two ways in which the extension can happen: -adding another database or adding another service. The former is -normally done only by the C library developers. It is -here only important to remember that adding another database is -independent from adding another service because a service need not -support all databases or lookup functions. - -A designer/implementer of a new service is therefore free to choose the -databases s/he is interested in and leave the rest for later (or -completely aside). - -@menu -* Adding another Service to NSS:: What is to do to add a new service. -* NSS Module Function Internals:: Guidelines for writing new NSS - service functions. -@end menu - -@node Adding another Service to NSS, NSS Module Function Internals, Extending NSS, Extending NSS -@subsection Adding another Service to NSS - -The sources for a new service need not (and should not) be part of @theglibc{} -itself. The developer retains complete control over the -sources and its development. The links between the C library and the -new service module consists solely of the interface functions. - -Each module is designed following a specific interface specification. -For now the version is 2 (the interface in version 1 was not adequate) -and this manifests in the version number of the shared library object of -the NSS modules: they have the extension @code{.2}. If the interface -changes again in an incompatible way, this number will be increased. -Modules using the old interface will still be usable. - -Developers of a new service will have to make sure that their module is -created using the correct interface number. This means the file itself -must have the correct name and on ELF systems the @dfn{soname} (Shared -Object Name) must also have this number. Building a module from a bunch -of object files on an ELF system using GNU CC could be done like this: - -@smallexample -gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS -@end smallexample - -@noindent -@ref{Link Options, Options for Linking, , gcc, GNU CC}, to learn -more about this command line. - -To use the new module the library must be able to find it. This can be -achieved by using options for the dynamic linker so that it will search -the directory where the binary is placed. For an ELF system this could be -done by adding the wanted directory to the value of -@code{LD_LIBRARY_PATH}. - -But this is not always possible since some programs (those which run -under IDs which do not belong to the user) ignore this variable. -Therefore the stable version of the module should be placed into a -directory which is searched by the dynamic linker. Normally this should -be the directory @file{$prefix/lib}, where @file{$prefix} corresponds to -the value given to configure using the @code{--prefix} option. But be -careful: this should only be done if it is clear the module does not -cause any harm. System administrators should be careful. - - -@node NSS Module Function Internals, , Adding another Service to NSS, Extending NSS -@subsection Internals of the NSS Module Functions - -Until now we only provided the syntactic interface for the functions in -the NSS module. In fact there is not much more we can say since the -implementation obviously is different for each function. But a few -general rules must be followed by all functions. - -In fact there are four kinds of different functions which may appear in -the interface. All derive from the traditional ones for system databases. -@var{db} in the following table is normally an abbreviation for the -database (e.g., it is @code{pw} for the password database). - -@table @code -@item enum nss_status _nss_@var{database}_set@var{db}ent (void) -This function prepares the service for following operations. For a -simple file based lookup this means files could be opened, for other -services this function simply is a noop. - -One special case for this function is that it takes an additional -argument for some @var{database}s (i.e., the interface is -@code{int set@var{db}ent (int)}). @ref{Host Names}, which describes the -@code{sethostent} function. - -The return value should be @var{NSS_STATUS_SUCCESS} or according to the -table above in case of an error (@pxref{NSS Modules Interface}). - -@item enum nss_status _nss_@var{database}_end@var{db}ent (void) -This function simply closes all files which are still open or removes -buffer caches. If there are no files or buffers to remove this is again -a simple noop. - -There normally is no return value other than @var{NSS_STATUS_SUCCESS}. - -@item enum nss_status _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, size_t buflen, int *errnop) -Since this function will be called several times in a row to retrieve -one entry after the other it must keep some kind of state. But this -also means the functions are not really reentrant. They are reentrant -only in that simultaneous calls to this function will not try to -write the retrieved data in the same place (as it would be the case for -the non-reentrant functions); instead, it writes to the structure -pointed to by the @var{result} parameter. But the calls share a common -state and in the case of a file access this means they return neighboring -entries in the file. - -The buffer of length @var{buflen} pointed to by @var{buffer} can be used -for storing some additional data for the result. It is @emph{not} -guaranteed that the same buffer will be passed for the next call of this -function. Therefore one must not misuse this buffer to save some state -information from one call to another. - -Before the function returns with a failure code, the implementation -should store the value of the local @var{errno} variable in the variable -pointed to be @var{errnop}. This is important to guarantee the module -working in statically linked programs. The stored value must not be -zero. - -As explained above this function could also have an additional last -argument. This depends on the database used; it happens only for -@code{host} and @code{networks}. - -The function shall return @code{NSS_STATUS_SUCCESS} as long as there are -more entries. When the last entry was read it should return -@code{NSS_STATUS_NOTFOUND}. When the buffer given as an argument is too -small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be -returned. When the service was not formerly initialized by a call to -@code{_nss_@var{DATABASE}_set@var{db}ent} all return values allowed for -this function can also be returned here. - -@item enum nss_status _nss_@var{DATABASE}_get@var{db}by@var{XX}_r (@var{PARAMS}, @var{STRUCTURE} *result, char *buffer, size_t buflen, int *errnop) -This function shall return the entry from the database which is -addressed by the @var{PARAMS}. The type and number of these arguments -vary. It must be individually determined by looking to the user-level -interface functions. All arguments given to the non-reentrant version -are here described by @var{PARAMS}. - -The result must be stored in the structure pointed to by @var{result}. -If there are additional data to return (say strings, where the -@var{result} structure only contains pointers) the function must use the -@var{buffer} of length @var{buflen}. There must not be any references -to non-constant global data. - -The implementation of this function should honor the @var{stayopen} -flag set by the @code{set@var{DB}ent} function whenever this makes sense. - -Before the function returns, the implementation should store the value of -the local @var{errno} variable in the variable pointed to by -@var{errnop}. This is important to guarantee the module works in -statically linked programs. - -Again, this function takes an additional last argument for the -@code{host} and @code{networks} database. - -The return value should as always follow the rules given above -(@pxref{NSS Modules Interface}). - -@end table |