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
- nsss-all, nsss-switch and nsss-unix implement the POSIX layer of user database access, plus a few GNU extensions.
- The nsss/nsss-unix.h header can be used to access the internal nsss-unix API.
- The nsss/nsss-switch.h header can be used to access the internal nsss-switch API.