From 32935ef03767814ef54c4c1905e00e320261c67c Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 3 Jul 2018 21:38:08 +0000 Subject: Add some documentation --- doc/index.html | 59 +++++++++++++++---- doc/libnsss/index.html | 134 +++++++++++++++++++++++++++++++------------ doc/libnsss/nsss-switch.html | 29 ++++++++++ doc/libnsss/nsss-unix.html | 29 ++++++++++ doc/libnsssd/index.html | 102 ++++++++++++++++++++++++++++++++ doc/nsssd-nslcd.html | 85 +++++++++++++++++++++++++++ doc/nsssd-unix.html | 88 ++++++++++++++++++++++++++++ doc/overview.html | 101 +++++++++++++++++++++++++++++++- 8 files changed, 579 insertions(+), 48 deletions(-) create mode 100644 doc/libnsss/nsss-switch.html create mode 100644 doc/libnsss/nsss-unix.html create mode 100644 doc/libnsssd/index.html create mode 100644 doc/nsssd-nslcd.html create mode 100644 doc/nsssd-unix.html diff --git a/doc/index.html b/doc/index.html index 49cf697..d4b7861 100644 --- a/doc/index.html +++ b/doc/index.html @@ -31,20 +31,32 @@ function is provided by the system's libc. However, not all libcs implement a configurable backend for the user/group database. For instance the musl libc, on Linux, only supports the standard /etc/passwd mechanism; it also supports the -nscd protocol but this is not quite enough to implement the -full set of database access functions with certain backends (such as a -LDAP server). +nscd protocol but this is not quite enough: +

+ +

musl only connects to nscd when it cannot find an answer in +its files backend
The nscd protocol does not support enumeration, so primitives +such as getpwent() cannot be implemented over nscd.

+ +

+ The mechanism used by glibc, called Name Service Switch +(abbreviated to nsswitch or NSS), has its own +set of issues that makes it unsuitable +in certain situations.

- nsss is a secure implementation of configurable user/group/shadow -database access, providing getpwnam() et al. functionality -by communicating over a Unix domain socket with a daemon; the daemon -can perform lookups in any database it chooses. + nsss is a secure implementation of a "name service switch": +configurable user/group/shadow database access, providing getpwnam() +et al. functionality by communicating over a Unix domain socket with a daemon; +the daemon can perform lookups in any database it chooses.

- Unlike NSS, nsss does not perform dynamic module + nsss does not perform dynamic module loading, only adds a small footprint to the application's binary, and does not add any complex decision engine into the client's address space. Applications can be statically linked against the nsss @@ -55,7 +67,8 @@ functions.

@@ -71,6 +84,10 @@ functions. 2.6.5.0 or later. It's a build-time requirement. It's also a run-time requirement if you link against the shared version of the skalibs library. +

s6 version +2.7.1.1 or later. It's a run-time requirement only, to run +the nsssd service (and can be done without if you have a suitable replacement +for s6-ipcserver).

Licensing

@@ -112,14 +129,32 @@ the previous versions of nsss and the current one.

Commands

+ The following commands are not meant to be directly invoked on the +command-line. They are meant to be used behind a Unix domain socket +super-server such as +s6-ipcserver +in order to provide a +local service. +Depending on the chosen command, the service will provide a different +backend to the name service. +

The nsssd-unix program
The nsssd-nslcd program

+ Future versions of nsss will come with more backends. +

Libraries

The nsss library interface
The following primitives are also implemented: +
The nsss library interface, +which applications use. A client application using one of the +following primitives will automatically perform libnsss calls:
- endpwent()
- setpwent()
- getspnam()
- getspnam_r()
The nsssd library interface, +which can be used to write additional backends.

diff --git a/doc/libnsss/index.html b/doc/libnsss/index.html index 0307725..ac99e54 100644 --- a/doc/libnsss/index.html +++ b/doc/libnsss/index.html @@ -21,23 +21,100 @@

General information

- libnsss is a client library meant to be used by client -programs needing utmp functionality. It interacts with various -server-side daemons such as -nsssd-unix. + 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).

- Application programs can use it directly, but most existing programs -simply use the standard + 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()

nsss_unix_

nsss_switch_

nsss_unix_getpwnam()

getpwnam()

/etc/passwd

+ 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, which in nsss are implemented as a series of thin wrappers -around the nsss library. +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.

Compiling

+ 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, @@ -48,6 +125,10 @@ 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

Programming

- The nsss/nsss.h header is actually a collection of headers: -

nsss/nsss-unix.h implements basic access to the -/etc/passwd, /etc/group and /etc/shadow -database.
nsss/nsss-switch.h implements connection via a Unix -domain socket to a listening nsssd daemon, implementing an -authentication backend based on what implementation of -the daemon is listening.
nsss/nsss-all.h implements a safe policy: first a -connection via nsss-switch is attempted, and if no daemon -is listening, the safe nsss-unix backend is used.
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.

- By default, the getpwnam() et al. functions are aliased -to their nsss-all implementations. You can disable the -nsss-unix fallback by compiling with the NSSS_DISABLE_UNIX -macro defined (-DNSSS_DISABLE_UNIX). Or you can disable any -attempt to connect to a daemon by compiling with the -NSSS_DISABLE_SWITCH macro defined (-DNSSS_DISABLE_SWITCH). -

- (To be completed.) -

nsss: the nsss-switch library interface

+libnsss
+nsss
+Software
+skarnet.org +

The `nsss-switch` library interface

General information

Programming

TODO: to be completed.

nsss: the nsss-unix library interface

+libnsss
+nsss
+Software
+skarnet.org +

The `nsss-unix` library interface

General information

Programming

TODO: to be completed.

nsss: the nsssd library interface

+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/strerr2.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`

`cat $SYSDEPS/tainnow.lib`

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 and envp as +arguments: return nsssd_main(argv, envp);

+ 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, char const const *envp)`

+This function must initialize the handle. The arguments +it receives are the argv and envp that have 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. +

+ TODO: to be completed. +

nsss: the nsssd-nslcd program

+nsss
+Software
+skarnet.org +

The nsssd-nslcd program

+nsssd-nslcd is a daemon providing a backend for clients using the +nsss library - more precisely, clients using +the nsss-all or +the nsss-switch functions. +

+ The nsssd-nslcd backend is meant to be used when the user/group/shadow +information is held in a LDAP server, and the +nslcd +daemon is running on the system as an interface to the LDAP architecture. +nsssd-nslcd acts a server for its libnsss-using client, and as a +client to nslcd. It forwards the application's requests to nslcd, and +forwards the answers back. +

+ nsssd-nslcd is not meant to be called directly; instead, it is expected to be run from +a script as a part of a "nsssd" +local service. +

+ The examples/ subdirectory of the nsss package provides examples +on how to run such a service. + The simplest way to do so, for testing purposes, is a command line such as: +

s6-ipcserver -l0 /run/service/nsss/s nsssd-nslcd /var/run/nslcd/socket

+/run/service/nsss/s is the default place where nsss's +implementation of the pwd.h, grp.h and shadow.h +functions expects the nsssd +service to be. It can be changed at nsss build time by giving the +--with-nsssd-socket=PATH option to configure. +nsssd-nslcd takes one argument: the path to connect to the nslcd daemon. +By default, this is /var/run/nslcd/socket. The default can be +changed at nslcd build time. +

+ nsssd-nslcd does not listen to the socket itself: it reads from its +standard input and writes to its standard output. It relies +on a superserver such as +s6-ipcserver +to manage connections to the socket. An instance of nsssd-nslcd is run +for every client connection. +

+ If fine-grained authorizations are required (only allowing +certain users and groups to connect to the service), the superserver +can be configured to enforce them. +

+ nsssd-nslcd does not need to run as root, provided it can connect +to the nslcd daemon. +It is recommended to create a nsss user and group, dedicated to +the nsssd service, and run the superserver as this user and group. +

nsss: the nsssd-unix program

+nsss
+Software
+skarnet.org +

The nsssd-unix program

+nsssd-unix is a daemon providing a backend for clients using the +nsss library - more precisely, clients using +the nsss-all or +the nsss-switch functions. +

+ The nsssd-unix backend is a simple one. It simply fetches user/group/shadow +information from the /etc/passwd, /etc/group and +/etc/shadow files. The same information can be directly obtained +by a client if it uses the nsss-unix +functions, without the overhead of going through an independent process. +However, setting up a nsssd-unix service can still be useful: +

For testing purposes
As a placeholder service that will be replaced later with a more +complex backend
...

+ nsssd-unix is not meant to be called directly; instead, it is expected to be run from +a script as a part of a "nsssd" +local service. +

+ The examples/ subdirectory of the nsss package provides examples +on how to run such a service. + The simplest way to do so, for testing purposes, is a command line such as: +

s6-ipcserver -l0 /run/service/nsss/s nsssd-unix

+ nsssd-unix does not listen to the socket itself: it reads from its +standard input and writes to its standard output. It relies +on a superserver such as +s6-ipcserver +to manage connections to the socket. An instance of nsssd-unix is run +for every client connection. +

+ If fine-grained authorizations are required (only allowing +certain users and groups to connect to the service), the superserver +can be configured to enforce them. +

+ nsssd-unix does not need to run as root, provided it can read the files +database. +It is recommended to create a nsss user and group, dedicated to +the nsssd service, and run the superserver as this user and group. +

- To be completed. + nsss has two parts: the client library and the nsssd service. +

The nsss client library

+ The client library provides: +

nsss-unix: a set of +functions providing access to the standard /etc/passwd, +/etc/group and /etc/shadow files.
nsss-switch: a set of +functions implementing the same functionality as nsss-unix, +but instead of looking for information in the standard files, they +connect to a nsssd service (see below) that performs the +requests for them.
+
three implementations of the the standard getpwnam() +et al. functions: one using the nsss-unix functions, one +using the nsss-switch functions, and the default one, called +nsss-all, which attempts to connect to the nsssd service +and retrieve information from it, but falls back to the nsss-unix +implementation if it fails (for instance, if no nsssd service is +listening).

+ +

+ Applications wishing to use nsss should be built against this client +library. The getpwnam() et al. definitions will override those +of the libc, and use the nsss-all, nsss-switch or +nsss-unix depending on compilation options. +

+ +

+ Unlike glibc's nsswitch, the nsss client library does not +use dynamically loadable modules. nsss can be statically linked, and +used in static programs. It's also quite light. +

+ +

The nsssd service

+ +

+ For applications that need to use the nsss-all or +nsss-switch implementations of getpwnam() et al. +(and that is the point, otherwise the libc's implementation could +generally be used over nsss-unix instead!) there needs to +be a daemon running on the system, and serving requests from +nsss-switch clients. +

+ +

+ That daemon should be set up by the system administrator. It should +listen to the /run/service/nsssd/s Unix domain socket; that +default location can be changed at nsss build time via the +--with-nsssd-socket option to the configure script. +

+ +

+ As of 0.0.1.0, two suitable implementations of a nsssd daemon are +provided by the nsss package: +

+ +

The nsssd-unix program, which is +sort of a dummy implementation since it simply accesses the standard +files (it simply uses the nsss-unix library). It is still +useful for testing purposes, and to have a placeholder service that +can easily be replaced later.
The nsssd-nslcd program, which +performs requests to a +nslcd +daemon running on the same system and returns the answers fetched +by nslcd. This allows nsss to get its users/groups information from +a LDAP database.

+ More implementations, with a wider variety of backends, will come +in future versions of nsss. +

+ The provided programs are not meant to be run directly; instead, they +use the UCSPI protocol and must be spawned by a Unix domain super-server +(the equivalent of inetd, for Unix domain sockets). The +s6-ipcserver +program, from the s6 package, +is such a super-server. What this means is that for instance, running the +following command-line as root will set up a correct nsss service: +

 s6-ipcserver -- /run/service/nsssd/s nsssd-unix

+ Refinements can be added to this command-line, such as options to +drop root privileges after binding to the socket, etc. Examples of how +to add a nsssd service to your init scripts are provided in the +examples/ subdirectory of the nsss package, for OpenRC, +s6 or s6-rc based systems.

Licensing

Commands

Libraries

General information

Compiling

Compiling

Linking

Programming

The nsss-switch library interface

General information

Programming

The nsss-unix library interface

General information

Programming

The nsssd library interface

General information

Compiling

Linking

Programming

void *nsssd_handle_init (void)

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

void nsssd_handle_end (void *handle)

The nsssd-nslcd program

The nsssd-unix program

The nsss client library

The nsssd service

The `nsss-switch` library interface

The `nsss-unix` library interface

The `nsssd` library interface

`void *nsssd_handle_init (void)`

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

`void nsssd_handle_end (void *handle)`