nsss
Software
skarnet.org

The nsssd library interface

General information

libnsssd is a library that can be used by external applications to implement extra nsss backends, in the style of nsssd-unix and nsssd-nslcd, without learning the details of the nsss protocol or having to perform IO themselves.

Compiling

• Make sure the nsss headers, as well as the skalibs headers, are visible in your header search path.
• Use #include <skalibs/strerr.h> and #include <nsss/nsssd.h>

Linking

• Make sure the nsssd library, as well as the skalibs library, are visible in your library search path.
• Link against -lnsssd, -lskarnet, `cat $SYSDEPS/socket.lib` and `cat $SYSDEPS/sysclock.lib`, $SYSDEPS being your skalibs sysdeps directory.

Programming

• In your main() function, start with assigning the name of your program to the PROG variable. Example: PROG = "nsssd-foobar";
• Your main() function can parse options and take command line arguments as it sees fit. But once it's done parsing options, give control to the nsssd_main() function, using your argv as an argument: return nsssd_main(argv);

The rest of your program should implement the functions needed by nsssd_main(). Here is what those functions are:

void *nsssd_handle_init (void)

This function must return a pointer to an uninitialized handle. The handle can be whatever you need to implement your backend; the pointer to your handle will be passed to every subsequent function. The function must not return NULL.

int nsssd_handle_start (void *handle, char const *const *argv)

This function must initialize the handle. The arguments it takes are a pointer to the handle and the argv that has been passed to nsssd_main(). This allows you to write daemons that can be somewhat configured via the command line: it is how nsssd-nslcd takes an argument telling it where the nslcd socket is, and uses that argument in its own nsssd_handle_start to actually connect to the nslcd daemon.
The function must return nonzero if it succeeds, and 0 if it fails, setting errno appropriately.

void nsssd_handle_end (void *handle)

This function must deinitialize the handle and free all related resources: close connections to external processes, etc.

int nsssd_pwd_start (void *handle)

This function will be called at the start of a passwd enumeration. It must return nonzero on success and 0 on error.

int nsssd_pwd_rewind (void *handle)

This function will be called on a setpwent() call. It must rewind the current enumeration to the start of the database. It must return nonzero on success and 0 on error.

int nsssd_pwd_get (void *handle, struct passwd *pw)

This function will be called on every getpwent() call, i.e. on every iteration of an enumeration. On error, it must return 0; on success, it must return nonzero and store the obtained passwd structure into *pw.

void nsssd_pwd_end (void *handle)

This function will be called at the end of a passwd enumeration.

int nsssd_pwd_getbyuid (void *handle, struct passwd *pw, uid_t uid)

This function must implement a getpwuid(uid) call. On error, it must return 0; on success, it must return nonzero and store the result into *pw.

int nsssd_pwd_getbyname (void *handle, struct passwd *pw, char const *name)

This function must implement a getpwnam(name) call. On error, it must return 0; on success, it must return nonzero and store the result into *pw.

Similar functions for the group and shadow databases must also be implemented. The full list can be found in the nsss/nsssd.h header.