Untitled Document

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., `/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 The 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 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.

The basic idea is to put the implementation of the different services
offered to access the databases in separate modules. This has some
advantages:

Contributors can add new services without adding them to GNU C Library.

The modules can be updated separately.

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

aliases

Mail aliases

ethers

Ethernet numbers,

group

Groups of users, @xref{Group Database}.

hosts

Host names and numbers, @xref{Host Names}.

netgroup

Network wide list of host and users, @xref{Netgroup Database}.

network

Network names and numbers, @xref{Networks Database}.

protocols

Network protocols, @xref{Protocols Database}.

passwd

User passwords, @xref{User Database}.

rpc

Remote procedure call names and numbers,

services

Network services, @xref{Services Database}.

shadow

Shadow user passwords,

There will be some more added later (automount, bootparams,
netmasks, and publickey).

Somehow the NSS code must be told about the wishes of the user. For
this reason there is the file `/etc/nsswitch.conf'. For each
database this file contain a specification how the lookup process should
work. The file could look like this:

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 above example file mentions four different services: files,
db, nis, and nisplus. 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 name shall be used for a lookup. The code for
this service is implemented in a module called `libnss_name'.
On a system supporting shared libraries this is in fact a shared library
with the name (for example) `libnss_name.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.

(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 ! is placed before the status this means
the following action is used for all statii but status itself.
I.e., ! 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 files service. Since there is no other service
following the action always is return.

Now, why is this [NOTFOUND=return] action useful? To understand
this we should know that the 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.

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 notfound but instead unavail. And
as you can see in the complete form above: in this situation the
db and 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).

Finally a few more hints. The NSS implementation is not completely
helpless if `/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.

For the hosts and network databases the default value is
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 ultimative.

The passwd, group, and shadow databases are
traditionally handled in a special way. The appropriate files in the
`/etc' directory are read but if an entry with a name starting
with a + character is found NIS is used. This kind of lookup
remains possible by using the special lookup service compat
and the default value for the three databases above is
compat [NOTFOUND=return] files.

For all other databases the default value is
nis [NOTFOUND=return] files. This solution give the best
chance to be correct since NIS and file based lookup is used.

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 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 nis etc.
But one should avoid slow services like this if possible.

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.

service of course corresponds to the name of the module this
function is found in.(1) The function part is derived
from the interface function in the C library itself. If the user calls
the function gethostbyname and the service used is files
the function

_nss_files_gethostbyname_r

in the module

libnss_files.so.1

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 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 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 unavail
(see section Actions in the NSS configuration).

The file name `libnss_files.so.1' would be on a Solaris 2
system `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 not 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.(2)

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:

I.e., the interface function is in fact the reentrant function with the
change of the return value and the omission of the result
parameter. While the user-level function returns a pointer to the
result the reentrant function return an enum nss_status value:

NSS_STATUS_TRYAGAIN

numeric value -2

NSS_STATUS_UNAVAIL

numeric value -1

NSS_STATUS_NOTFOUND

numeric value 0

NSS_STATUS_SUCCESS

numeric value 1

Now you see where the action items of the `/etc/nsswitch.conf' file
are used.

If you study the source code you will find there is a fifth value:
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.

The above function has something special which is missing for almost all
the other module functions. There is an argument 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. The reentrant
function cannot use the global variable h_errno;
gethostbyname calls gethostbyname_r with the
last argument set to &h_errno.

The getXXXbyYYY 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 setpwent, getpwent, and
endpwent). These will be described in more detail later.
Here we give a general way to determine the
signature of the module function:

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).

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
.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 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:

gcc -shared -o libnss_NAME.so.1 -Wl,-soname,libnss_NAME.so.1 OBJECTS

section `Link Options' in 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
directory where the binary is placed. For an ELF system this could be
done by adding the wanted directory to the value of
LD_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 `$prefix/lib', where `$prefix' corresponds to
the value given to configure using the --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.

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.
db in the following table is normally an abbreviation for the
database (e.g., it is pw for the password database).

enum nss_status _nss_database_setdbent (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 databases (i.e., the interface is
int setdbent (int)). @xref{Host Names}, which describes the
sethostent function.
The return value should be NSS_STATUS_SUCCESS or according to the
table above in case of an error (see section The Interface of the Function in NSS Modules).

enum nss_status _nss_database_enddbent (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 NSS_STATUS_SUCCESS.

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 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 buflen pointed to by buffer can be used
for storing some additional data for the result. It is 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.
As explained above this function could also have an additional last
argument. This depends on the database used; it happens only for
host and network.
The function shall return NSS_STATUS_SUCCESS as long as their are
more entries. When the last entry was read it should return
NSS_STATUS_NOTFOUND. When the buffer given as an argument is too
small for the data to be returned NSS_STATUS_TRYAGAIN should be
returned. When the service was not formerly initialized by a call to
_nss_DATABASE_setdbent all return value allowed for
this function can also be returned here.

This function shall return the entry from the database which is
addressed by the 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 PARAMS.
The result must be stored in the structure pointed to by result.
If there is additional data to return (say strings, where the
result structure only contains pointers) the function must use the
buffer or length buflen. There must not be any references
to non-constant global data.
The implementation of this function should honour the stayopen
flag set by the setDBent function whenever this makes sense.
Again, this function takes an additional last argument for the
host and network database.
The return value should as always follow the rules given above
(see section The Interface of the Function in NSS Modules).

This document was generated on 27 May 1998 using the
texi2html
translator version 1.51.