nsss
Software
skarnet.org
The nsss library interface
General information
libnsss is the generic name for the nsss client library.
This library is made of several parts:
- nsss-unix: this is a set of
functions to access the /etc/passwd, /etc/group
and /etc/shadow files.
- nsss-switch: this is a set of
functions to connect to a nsssd-service and interact with
various server-side daemons such as
nsssd-unix or
nsssd-nslcd.
- nsss-all: this is a set of
functions that try connecting to a nsssd service first, and fall
back to the nsss-unix implementation
if the connection fails (no nsssd service is running).
Both nsss-unix and
nsss-switch are made of two parts:
- An internal, clean API, that applications can use directly
if they include the nsss/nsss.h header, or the relevant
nsss/nsss-unix.h or nsss/nsss-switch.h header.
- As a series of thin wrappers around the internal API, an
implementation of the standard following functions:
- endpwent()
- setpwent()
- getpwent()
- getpwent_r()
- getpwuid()
- getpwuid_r()
- getpwnam()
- getpwnam_r()
- endgrent()
- setgrent()
- getgrent()
- getgrent_r()
- getgrgid()
- getgrgid_r()
- getgrnam()
- getgrnam_r()
- endspent()
- setspent()
- getspent()
- getspent_r()
- getspnam()
- getspnam_r()
- The functions are prefixed with nsss_unix_ or
nsss_switch_. For instance, nsss_unix_getpwnam()
is the implementation of getpwnam() that uses the
/etc/passwd backend.
nsss-all does not have an internal API. It only contains the
implementation of the above standard functions, as
nsss_all_getpwnam() and similar.
Compiling
Application programs can use the internal API directly, or
the prefixed nsss_ functions directly. Most programs,
however, will simply use the standard
pwd.h,
grp.h or
shadow.h
interfaces. nsss provides a version of these standard headers: if an
application is built with these headers, then getpwnam()
will automatically be aliased to nsss_all_getpwnam(), and
the other functions will be aliased similarly.
pwd.h can be found in the nsss/ subdirectory of
the header installation directory; if the --enable-libc-includes
option has been given to configure, it can also be found directly
in that directory. (Example: /usr/include/nsss/pwd.h is
always installed, but if the option has been given at nsss build time,
/usr/include/pwd.h is also installed and replaces the
version provided by the libc.) This also applies to the grp.h
and shadow.h files.
If the NSSS_DISABLE_SWITCH macro is defined before inclusion of the
nsss headers, then getpwnam() will be aliased to
nsss_unix_getpwnam() instead, and the other functions will
follow the same pattern. If, instead, the NSSS_DISABLE_UNIX macro
is defined before inclusion of the nsss headers, then getpwnam()
will be aliased to nsss_switch_getpwnam(), and the other
functions will follow the same pattern.
So, the proper steps to compile an application with libnsss are:
- Make sure the nsss headers, as well as the skalibs headers,
are visible in your header search path.
- Use #include <nsss/nsss.h>
- To use the standard pwd.h interface, you can
just #include <pwd.h>, which will work:
- either if the --enable-libc-includes option
has been given at nsss build time
- or if you give the -I/usr/include/nsss option
to your compiler. (Depending on your standard header location,
specify that the header search path should include the
nsss subdirectory of that location.) This is useful when
the administrator did not want to overwrite the libc-provided
pwd.h file when they installed nsss.
- Same thing for grp.h and shadow.h.
- If don't want to use the nsss-all implementation of
"try nsss-switch and fall back to nsss-unix if it fails", then
compile with -DNSSS_DISABLE_SWITCH or -DNSSS_DISABLE_UNIX as
desired.
Linking
- Make sure the nsss library, as well as the skalibs library,
are visible in your library search path.
- Link against -lnsss, -lskarnet, -lpthread,
`cat $SYSDEPS/socket.lib` and
`cat $SYSDEPS/sysclock.lib`, $SYSDEPS being your skalibs
sysdeps directory.
Programming