@Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.
Œ

ˆ‰SEC435Št�”›System Databases and Name Service Switch

‰IDX1954Š‰IDX1955Š‰IDX1956Š@�”˜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., H`/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 (see section `frobnicate' in BThe Jargon File@).
The GNU C Library contains a cleaner solution of this problem. It is designed after a method used by Sun Microsystems in the C library of Solaris 2. GNU C Library follows their name and calls this scheme BName 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.
ˆ‰SEC436Št�”›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: þÂ
1. Contributors can add new services without adding them to GNU C Library.
2. The modules can be updated separately.
3. The C library image is smaller.Àð
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.
The databases available in the NSS are
‰IDX1957Š‰IDX1958Š‰IDX1959Š‰IDX1960Š‰IDX1961Š‰IDX1962Š‰IDX1963Š‰IDX1964Š‰IDX1965Š‰IDX1966Š
H�”˜aliases
Â‰IDX1967Š@�”˜Mail aliases
ÀHethers
Â‰IDX1968Š@�”˜Ethernet numbers,
ÀHgroup
Â‰IDX1969Š@�”˜Groups of users, see section ‰ŠP�”›Group Database@�”˜.
ÀHhosts
Â‰IDX1970Š@�”˜Host names and numbers, see section ‰ŠP�”›Host Names@�”˜.
ÀHnetgroup
Â‰IDX1971Š@�”˜Network wide list of host and users, see section ‰ŠP�”›Netgroup Database@�”˜.
ÀHnetwork
Â‰IDX1972Š@�”˜Network names and numbers, see section ‰ŠP�”›Networks Database@�”˜.
ÀHprotocols
Â‰IDX1973Š@�”˜Network protocols, see section ‰ŠP�”›Protocols Database@�”˜.
ÀHpasswd
Â‰IDX1974Š@�”˜User passwords, see section ‰ŠP�”›User Database@�”˜.
ÀHrpc
Â‰IDX1975Š@�”˜Remote procedure call names and numbers,
ÀHservices
Â‰IDX1976Š@�”˜Network services, see section ‰ŠP�”›The Services Database@�”˜.
ÀHshadow
Â‰IDX1977Š@�”˜Shadow user passwords,À

There will be some more added later (Hautomount@, Hbootparams@, Hnetmasks@, and Hpublickey@).
ˆ‰SEC437Št�”›The NSS Configuration File

‰IDX1978Š‰IDX1979Š@�”˜Somehow the NSS code must be told about the wishes of the user. For this reason there is the file H`/etc/nsswitch.conf'@. For each database this file contain a specification how the lookup process should work. The file could look like this: # /etc/nsswitch.conf
#
# Name Service Switch configuration file.
#

passwd: db files nis
shadow: files
group: db files nis

hosts: files nisplus nis dns
networks: nisplus [NOTFOUND=return] files

ethers: nisplus [NOTFOUND=return] db files
protocols: nisplus [NOTFOUND=return] db files
rpc: nisplus [NOTFOUND=return] db files
services: nisplus [NOTFOUND=return] db files
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: þÂ
• the service specification like Hfiles@, Hdb@, or Hnis@.
• the reaction on lookup result like H[NOTFOUND=return]@.Àð
ˆ‰SEC438ŠT�”›Services in the NSS configuration File

@�”˜The above example file mentions four different services: Hfiles@, Hdb@, Hnis@, and Hnisplus@. This does not mean these services are available on all sites and it does also not 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 Bname@ shall be used for a lookup. The code for this service is implemented in a module called H`libnss_JnameH'@. On a system supporting shared libraries this is in fact a shared library with the name (for example) H`libnss_JnameH.so.1'@. 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.
ˆ‰SEC439ŠT�”›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 H[@ ( H!@? Bstatus@ H=@ Baction@ )+ H]@
where Bstatus@ => success | notfound | unavail | tryagain
Baction@ => return | continue
The case of the keywords is insignificant. The Bstatus@ values are the results of a call to a lookup function of a specific service. They mean
H`success'
Â‰IDX1980Š@�”˜No error occurred and the wanted entry is returned. The default action for this is Hreturn@.
ÀH`notfound'
Â‰IDX1981Š@�”˜The lookup process works ok but the needed value was not found. The default action is Hcontinue@.
ÀH`unavail'
Â‰IDX1982Š‰IDX1983Š@�”˜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 Hcontinue@.
ÀH`tryagain'
Â‰IDX1984Š@�”˜The service is temporarily unavailable. This could mean a file is locked or a server currently cannot accept more connections. The default action is Hcontinue@.À

If we have a line like ethers: nisplus [NOTFOUND=return] db files
this is equivalent to ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
TRYAGAIN=continue]
db [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
TRYAGAIN=continue]
files
(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 H!@ is placed before the Bstatus@ this means the following action is used for all statii but Bstatus@ itself. I.e., H!@ 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 Hfiles@ service. Since there is no other service following the action Balways@ is Hreturn@.
‰IDX1985Š@�”˜Now, why is this H[NOTFOUND=return]@ action useful? To understand this we should know that the Hnisplus@ 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.
‰IDX1986Š‰IDX1987Š@�”˜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 Hnotfound@ but instead Hunavail@. And as you can see in the complete form above: in this situation the Hdb@ and Hfiles@ 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).
ˆ‰SEC440ŠT�”›Notes on the NSS Configuration File

@�”˜Finally a few more hints. The NSS implementation is not completely helpless if H`/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.
‰IDX1988Š@�”˜For the Hhosts@ and Hnetwork@ databases the default value is Hdns [!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 ultimative.
The Hpasswd@, Hgroup@, and Hshadow@ databases are traditionally handled in a special way. The appropriate files in the H`/etc'@ directory are read but if an entry with a name starting with a H+@ character is found NIS is used. This kind of lookup remains possible by using the special lookup service Hcompat@ and the default value for the three databases above is Hcompat [NOTFOUND=return] files@.
For all other databases the default value is Hnis [NOTFOUND=return] files@. This solution give the best chance to be correct since NIS and file based lookup is used.
‰IDX1989Š@�”˜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 Hdb@ 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 Hnis@ etc. But one should avoid slow services like this if possible.
ˆ‰SEC441Št�”›NSS Module Internals

@�”˜Now it is time to described how 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.
ˆ‰SEC442ŠT�”›The Naming Scheme of the NSS Modules

@�”˜The name of each function consist of various parts:
Â
_nss_Bservice@_BfunctionÀ

Bservice@ of course corresponds to the name of the module this function is found in.‰DOCF1ŠP�”›(1)@�”˜ The Bfunction@ part is derived from the interface function in the C library itself. If the user calls the function Hgethostbyname@ and the service used is Hfiles@ the function _nss_files_gethostbyname_r
in the module libnss_files.so.1
‰IDX1990Š@�”˜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 Hgethostbyname_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 Bcan@ 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 Hunavail@ (see section ‰ŠP�”›Actions in the NSS configuration@�”˜).
The file name H`libnss_files.so.1'@ would be on a Solaris 2 system H`nss_files.so.1'@. This is the difference mentioned above. Sun's NSS modules are usable as modules which get indirectly loaded only.
The NSS modules in the GNU C Library are prepared to be used as normal libraries itself. This is Bnot@ true in the moment, though. But the different 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.‰DOCF2ŠP�”›(2)@�”˜
ˆ‰SEC443ŠT�”›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 version). The prototypes for the non-reentrant and reentrant versions of our function above are: 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)
The actual prototype of the function in the NSS modules in this case is enum nss_status _nss_files_gethostbyname_r (const char *name,
struct hostent *result_buf,
char *buf, size_t buflen,
int *h_errnop)
I.e., the interface function is in fact the reentrant function with the change of the return value and the omission of the Bresult@ parameter. While the user-level function returns a pointer to the result the reentrant function return an Henum nss_status@ value:
‰IDX1991Š‰IDX1992Š‰IDX1993Š‰IDX1994Š
H�”˜NSS_STATUS_TRYAGAIN
Â‰IDX1995Š@�”˜numeric value H-2@
ÀHNSS_STATUS_UNAVAIL
Â‰IDX1996Š@�”˜numeric value H-1@
ÀHNSS_STATUS_NOTFOUND
Â‰IDX1997Š@�”˜numeric value H0@
ÀHNSS_STATUS_SUCCESS
Â‰IDX1998Š@�”˜numeric value H1À

@Now you see where the action items of the H`/etc/nsswitch.conf'@ file are used.
If you study the source code you will find there is a fifth value: HNSS_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.
The above function has something special which is missing for almost all the other module functions. There is an argument Bh_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. The reentrant function cannot use the global variable Bh_errno@; Hgethostbyname@ calls Hgethostbyname_r@ with the last argument set to H&h_errno@.
The HgetJXXXHbyJYYY@ 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 Hsetpwent@, Hgetpwent@, and Hendpwent@). These will be described in more detail later. Here we give a general way to determine the signature of the module function: þÂ
• the return value is Hint@;
• the name is as explain in see section ‰ŠP�”›The Naming Scheme of the NSS Modules@�”˜;
• the first arguments are identical to the arguments of the non-reentrant function;
• the next three arguments are:
ðHSTRUCT_TYPE *result_buf
þðÄ@pointer to buffer where the result is stored. HSTRUCT_TYPE@ is normally a struct which corresponds to the database.
ÂþðHchar *buffer
þðÄ@pointer to a buffer where the function can store additional adata for the result etc.
ÂþðHsize_t buflen
þðÄ@length of the buffer pointed to by Bbuffer@.Âþ

• possibly a last argument Bh_errnop@, for the host name and network name lookup functions.Àð
This table is correct for all functions but the Hset...ent@ and Hend...ent@ functions.
ˆ‰SEC444Št�”›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/implementor 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).
ˆ‰SEC445ŠT�”›Adding another Service to NSS

@�”˜The sources for a new service need not (and should not) be part of the GNU C Library 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 1 and this manifests in the version number of the shared library object of the NSS modules: they have the extension H.1@. If the interface ever changes in an incompatible way, this number will be increased--hopefully this will never be necessary. 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 Bsoname@ (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: gcc -shared -o libnss_NAME.so.1 -Wl,-soname,libnss_NAME.so.1 OBJECTS
section `Link Options' in BGNU 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 directory where the binary is placed. For an ELF system this could be done by adding the wanted directory to the value of HLD_LIBRARY_PATH@.
But this is not always possible since some program (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 H`$prefix/lib'@, where H`$prefix'@ corresponds to the value given to configure using the H--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.
ˆ‰SEC446ŠT�”›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 more much we can tell 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. Bdb@ in the following table is normally an abbreviation for the database (e.g., it is Hpw@ for the password database).
Henum nss_status _nss_JdatabaseH_setJdbHent (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 Bdatabase@s (i.e., the interface is Hint setJdbHent (int)@). section ‰ŠP�”›Host Names@�”˜, which describes the Hsethostent@ function. The return value should be BNSS_STATUS_SUCCESS@ or according to the table above in case of an error (see section ‰ŠP�”›The Interface of the Function in NSS Modules@�”˜).
ÀHenum nss_status _nss_JdatabaseH_endJdbHent (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 different to BNSS_STATUS_SUCCESS@.
ÀHenum nss_status _nss_JdatabaseH_getJdbHent_r (JSTRUCTUREH *result, char *buffer, size_t buflen)
Â@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 Bresult@ 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 Bbuflen@ pointed to by Bbuffer@ can be used for storing some additional data for the result. It is Bnot@ 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. As explained above this function could also have an additional last argument. This depends on the database used; it happens only for Hhost@ and Hnetwork@. The function shall return HNSS_STATUS_SUCCESS@ as long as their are more entries. When the last entry was read it should return HNSS_STATUS_NOTFOUND@. When the buffer given as an argument is too small for the data to be returned HNSS_STATUS_TRYAGAIN@ should be returned. When the service was not formerly initialized by a call to H_nss_JDATABASEH_setJdbHent@ all return value allowed for this function can also be returned here.
ÀHenum nss_status _nss_JDATABASEH_getJdbHbyJXXH_r (JPARAMSH, JSTRUCTUREH *result, char *buffer, size_t buflen)
Â@This function shall return the entry from the database which is addressed by the BPARAMS@. 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 BPARAMS@. The result must be stored in the structure pointed to by Bresult@. If there is additional data to return (say strings, where the Bresult@ structure only contains pointers) the function must use the Bbuffer@ or length Bbuflen@. There must not be any references to non-constant global data. The implementation of this function should honour the Bstayopen@ flag set by the HsetJDBHent@ function whenever this makes sense. Again, this function takes an additional last argument for the Hhost@ and Hnetwork@ database. The return value should as always follow the rules given above (see section ‰ŠP�”›The Interface of the Function in NSS Modules@�”˜). À

Œ
Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.