path: root/manual/nss.texi

@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 aliases
@cindex ethers
@cindex group
@cindex gshadow
@cindex hosts
@cindex initgroups
@cindex netgroup
@cindex networks
@cindex passwd
@cindex protocols
@cindex publickey
@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 gshadow
Group passphrase hashes and related information.
@item hosts
Host names and numbers, @pxref{Host Names}.
@item initgroups
Supplementary group access list.
@item netgroup
Network wide list of host and users, @pxref{Netgroup Database}.
@item networks
Network names and numbers, @pxref{Networks Database}.
@item passwd
User identities, @pxref{User Database}.
@item protocols
Network protocols, @pxref{Protocols Database}.
@item publickey
Public keys for Secure RPC.
@item rpc
Remote procedure call names and numbers.
@comment @pxref{RPC Database}.
@item services
Network services, @pxref{Services Database}.
@item shadow
User passphrase hashes and related information.
@comment @pxref{Shadow Passphrase Database}.
@end table

@noindent
@c We currently don't implement automount, netmasks, or bootparams.
More databases may be added later.

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

Lastly, some system software may make use of the NSS configuration file
to store their own configuration for similar purposes.  Examples of this
include the @code{automount} service which is used by @code{autofs}.

@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{files dns}.  I.e., local configuration will override the contents
of the domain name system (DNS).

The @code{passwd}, @code{group}, and @code{shadow} databases was
traditionally handled in a special way.  The appropriate files in the
@file{/etc} directory were read but if an entry with a name starting
with a @code{+} character was found NIS was used.  This kind of lookup
was removed and now the default value for the services is @code{files}.
libnss_compat no longer depends on libnsl and can be used without NIS.

For all other databases the default value is @code{files}.

@cindex optimizing NSS
A second point is that the user should try to optimize the lookup
process.