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.

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 as long as the nsss/pwd.h header is accessible in your header search path.
• 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.