Add some documentation

8 files changed, 579 insertions, 48 deletions

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
 <a href="https://musl-libc.org/">musl</a> libc, on Linux, only supports
 the standard <tt>/etc/passwd</tt> mechanism; it also supports the
-<tt>nscd</tt> protocol but this is not quite enough to implement the
-full set of database access functions with certain backends (such as a
-LDAP server).
+<tt>nscd</tt> protocol but this is not quite enough:
+<p>
+
+<ul>
+ <li> musl only connects to nscd when it cannot find an answer in
+its files backend </li>
+ <li> The nscd protocol does not support enumeration, so primitives
+such as <tt>getpwent()</tt> cannot be implemented over nscd. </li>
+</ul>
+
+<p>
+ The mechanism used by glibc, called <tt>Name Service Switch</tt>
+(abbreviated to <tt>nsswitch</tt> or <tt>NSS</tt>), has its own
+<a href="nsswitch.html">set of issues</a> that makes it unsuitable
+in certain situations.
 </p>
 
 <p>
- <tt>nsss</tt> is a secure implementation of configurable user/group/shadow
-database access, providing <tt>getpwnam()</tt> et al. functionality
-by communicating over a Unix domain socket with a daemon; the daemon
-can perform lookups in any database it chooses.
+ <tt>nsss</tt> is a secure implementation of a "name service switch":
+configurable user/group/shadow database access, providing <tt>getpwnam()</tt>
+et al. functionality by communicating over a Unix domain socket with a daemon;
+the daemon can perform lookups in any database it chooses.
 </p>
 
 <p>
- Unlike NSS, <tt>nsss</tt> does not perform dynamic module
+ <tt>nsss</tt> 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 <tt>nsss</tt>
@@ -55,7 +67,8 @@ functions.
 <hr />
 
 <ul>
- <li> <a href="overview.html">An overview of nsss</a> </li>
+ <li> <a href="nsswitch.html">The problem with <tt>nsswitch</tt></a> </li>
+ <li> <a href="overview.html">An overview of <tt>nsss</tt></a> </li>
 </ul>
 
 <hr />
@@ -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. </li>
+ <li> <a href="//skarnet.org/software/s6/">s6</a> version
+2.7.1.1 or later. It's a <em>run-time</em> requirement only, to run
+the nsssd service (and can be done without if you have a suitable replacement
+for <a href="//skarnet.org/software/s6/s6-ipcserver">s6-ipcserver</a>). </li>
 </ul>
 
 <h3> Licensing </h3>
@@ -112,14 +129,32 @@ the previous versions of nsss and the current one. </li>
 
 <h3> Commands </h3>
 
+<p>
+ 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
+<a href="https://skarnet.org/software/s6/s6-ipcserver.html">s6-ipcserver</a>
+in order to provide a
+<a href="https://skarnet.org/software/s6/localservice.html">local service</a>.
+Depending on the chosen command, the service will provide a different
+backend to the name service.
+</p>
+
 <ul>
+ <li> The <a href="nsssd-unix"><tt>nsssd-unix</tt></a> program </li>
+ <li> The <a href="nsssd-nslcd"><tt>nsssd-nslcd</tt></a> program </li>
 </ul>
 
+<p>
+ Future versions of nsss will come with more backends.
+</p>
+
 <h3> Libraries </h3>
 
 <ul>
- <li> <a href="libnsss/">The <tt>nsss</tt> library interface</a> </li>
- <li> The following primitives are also implemented:
+ <li> <a href="libnsss/">The <tt>nsss</tt> library interface</a>,
+which applications use. A client application using one of the
+following primitives will automatically perform libnsss calls:
   <ul>
    <li> endpwent() </li>
    <li> setpwent() </li>
@@ -144,6 +179,8 @@ the previous versions of nsss and the current one. </li>
    <li> getspnam() </li>
    <li> getspnam_r() </li>
   </ul> </li>
+ <li> <a href="libnsssd/">The <tt>nsssd</tt> library interface</a>,
+which can be used to write additional backends. </li>
 </ul>
 
 <hr />
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 @@
 <h2> General information </h2>
 
 <p>
- <tt>libnsss</tt> is a client library meant to be used by client
-programs needing utmp functionality. It interacts with various
-server-side daemons such as
-<a href="../nsssd-unix.html">nsssd-unix</a>.
+ <tt>libnsss</tt> is the generic name for the nsss client library.
+This library is made of several parts:
+</p>
+
+<ul>
+ <li> <a href="nsss-unix.html">nsss-unix</a>: this is a set of
+functions to access the <tt>/etc/passwd</tt>, <tt>/etc/group</tt>
+and <tt>/etc/shadow</tt> files. </li>
+ <li> <a href="nsss-switch.html">nsss-switch</a>: this is a set of
+functions to connect to a <em>nsssd-service</em> and interact with
+various server-side daemons such as
+<a href="../nsssd-unix.html">nsssd-unix</a> or
+<a href="../nsssd-nslcd.html">nsssd-nslcd</a>. </li>
+ <li> nsss-all: this is a set of
+functions that try connecting to a nsssd service first, and fall
+back to the <a href="nsss-unix.html">nsss-unix</a> implementation
+if the connection fails (no nsssd service is running). </li>
 </p>
 
 <p>
- Application programs can use it directly, but most existing programs
-simply use the standard
+ Both <a href="nsss-unix.html">nsss-unix</a> and
+<a href="nsss-switch.html">nsss-switch</a> are made of two parts:
+</p>
+
+<ul>
+ <li> An internal, clean API, that applications can use directly
+if they include the <tt>nsss/nsss.h</tt> header, or the relevant
+<tt>nsss/nsss-unix.h</tt> or <tt>nsss/nsss-switch.h</tt> header. </li>
+ <li> As a series of thin wrappers around the internal API, an
+implementation of the standard following functions:
+  <ul>
+   <li> endpwent() </li>
+   <li> setpwent() </li>
+   <li> getpwent() </li>
+   <li> getpwent_r() </li>
+   <li> getpwuid() </li>
+   <li> getpwuid_r() </li>
+   <li> getpwnam() </li>
+   <li> getpwnam_r() </li>
+   <li> endgrent() </li>
+   <li> setgrent() </li>
+   <li> getgrent() </li>
+   <li> getgrent_r() </li>
+   <li> getgrgid() </li>
+   <li> getgrgid_r() </li>
+   <li> getgrnam() </li>
+   <li> getgrnam_r() </li>
+   <li> endspent() </li>
+   <li> setspent() </li>
+   <li> getspent() </li>
+   <li> getspent_r() </li>
+   <li> getspnam() </li>
+   <li> getspnam_r() </li>
+  </ul> </li>
+ The functions are prefixed with <tt>nsss_unix_</tt> or
+<tt>nsss_switch_</tt>. For instance, <tt>nsss_unix_getpwnam()</tt>
+is the implementation of <tt>getpwnam()</tt> that uses the
+<tt>/etc/passwd</tt> backend. </li>
+</ul>
+
+<p>
+ nsss-all does not have an internal API. It only contains the
+implementation of the above standard functions, as
+<tt>nsss_all_getpwnam()</tt> and similar.
+</p>
+
+<h2> Compiling </h2>
+
+<p>
+ Application programs can use the internal API directly, or
+the prefixed <tt>nsss_</tt> functions directly. Most programs,
+however, will simply use the standard
 <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pwd.h.html">pwd.h</a>,
 <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/grp.h.html">grp.h</a> or
 <a href="http://man7.org/linux/man-pages/man3/getspnam.3.html">shadow.h</a>
-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 <tt>getpwnam()</tt>
+will automatically be aliased to <tt>nsss_all_getpwnam()</tt>, and
+the other functions will be aliased similarly.
 </p>
 
-<h2> Compiling </h2>
+<p>
+ If the NSSS_DISABLE_SWITCH macro is defined before inclusion of the
+nsss headers, then <tt>getpwnam()</tt> will be aliased to
+<tt>nsss_unix_getpwnam()</tt> 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 <tt>getpwnam()</tt>
+will be aliased to <tt>nsss_switch_getpwnam()</tt>, and the other
+functions will follow the same pattern.
+</p>
+
+<p>
+ So, the proper steps to compile an application with libnsss are:
+</p>
 
 <ul>
  <li> Make sure the nsss headers, as well as the skalibs headers,
@@ -48,6 +125,10 @@ just <tt>#include &lt;pwd.h&gt;</tt>, which will work as long
 as the <tt>nsss/pwd.h</tt> header is accessible in your header
 search path. </li>
  <li> Same thing for <tt>grp.h</tt> and <tt>shadow.h</tt>. </li>
+ <li> 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. </li>
 </ul>
 
 <h2> Linking </h2>
@@ -63,35 +144,16 @@ sysdeps directory. </li>
 
 <h2> Programming </h2>
 
-<p>
- The <tt>nsss/nsss.h</tt> header is actually a collection of headers:
-</p>
-
 <ul>
- <li> <tt>nsss/nsss-unix.h</tt> implements basic access to the
-<tt>/etc/passwd</tt>, <tt>/etc/group</tt> and <tt>/etc/shadow</tt>
-database. </li>
- <li> <tt>nsss/nsss-switch.h</tt> implements connection via a Unix
-domain socket to a listening <tt>nsssd</tt> daemon, implementing an
-authentication backend based on what implementation of
-the daemon is listening. </li>
- <li> <tt>nsss/nsss-all.h</tt> implements a safe policy: first a
-connection via <tt>nsss-switch</tt> is attempted, and if no daemon
-is listening, the safe <tt>nsss-unix</tt> backend is used. </li>
+ <li> nsss-all, nsss-switch and nsss-unix implement the
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpwnam.html">POSIX
+layer</a> of user database access, plus a few
+<a href="http://man7.org/linux/man-pages/man3/getpwent_r.3.html">GNU extensions</a>. </li>
+ <li> The <a href="nsss-unix.html">nsss/nsss-unix.h</a> header
+can be used to access the internal nsss-unix API. </li>
+ <li> The <a href="nsss-switch.html">nsss/nsss-switch.h</a> header
+can be used to access the internal nsss-switch API. </li>
 </ul>
 
-<p>
- By default, the <tt>getpwnam()</tt> et al. functions are aliased
-to their <tt>nsss-all</tt> implementations. You can disable the
-<tt>nsss-unix</tt> 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).
-</p>
-
-<p>
- (To be completed.)
-</p>
-
 </body>
 </html>
diff --git a/doc/libnsss/nsss-switch.html b/doc/libnsss/nsss-switch.html
new file mode 100644
index 0000000..224cea6
--- /dev/null
+++ b/doc/libnsss/nsss-switch.html
@@ -0,0 +1,29 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss: the nsss-switch library interface</title>
+    <meta name="Description" content="nsss: the nsss-switch library interface" />
+    <meta name="Keywords" content="NSS pwd group shadow library libnsss switch nsss-switch client server nsssd backend connection socket skarnet" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">libnsss</a><br />
+<a href="../">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>nsss-switch</tt> library interface </h1>
+
+<h2> General information </h2>
+
+<h2> Programming </h2>
+
+<p> TODO: to be completed. </p>
+
+</body>
+</html>
diff --git a/doc/libnsss/nsss-unix.html b/doc/libnsss/nsss-unix.html
new file mode 100644
index 0000000..b51985b
--- /dev/null
+++ b/doc/libnsss/nsss-unix.html
@@ -0,0 +1,29 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss: the nsss-unix library interface</title>
+    <meta name="Description" content="nsss: the nsss-unix library interface" />
+    <meta name="Keywords" content="NSS pwd group shadow library libnsss unix nsss-unix files /etc/passwd /etc/group /etc/shadow skarnet" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">libnsss</a><br />
+<a href="../">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>nsss-unix</tt> library interface </h1>
+
+<h2> General information </h2>
+
+<h2> Programming </h2>
+
+<p> TODO: to be completed. </p>
+
+</body>
+</html>
diff --git a/doc/libnsssd/index.html b/doc/libnsssd/index.html
new file mode 100644
index 0000000..ec2c5d4
--- /dev/null
+++ b/doc/libnsssd/index.html
@@ -0,0 +1,102 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss: the nsssd library interface</title>
+    <meta name="Description" content="nsss: the nsssd library interface" />
+    <meta name="Keywords" content="NSS pwd group shadow library backend nsssd daemon libnsssd skarnet" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="../">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>nsssd</tt> library interface </h1>
+
+<h2> General information </h2>
+
+<p>
+ <tt>libnsssd</tt> is a library that can be used by external applications
+to implement extra nsss backends, in the style of
+<a href="../nsssd-unix.html">nsssd-unix</a> and
+<a href="../nsssd-nslcd.html">nsssd-nslcd</a>, without learning the
+details of the nsss protocol or having to perform IO themselves.
+</p>
+
+<h2> Compiling </h2>
+
+<ul>
+ <li> Make sure the nsss headers, as well as the skalibs headers,
+are visible in your header search path. </li>
+ <li> Use <tt>#include &lt;skalibs/strerr2.h&gt;</tt> and
+<tt>#include &lt;nsss/nsssd.h&gt;</tt> </li>
+</ul>
+
+<h2> Linking </h2>
+
+<ul>
+ <li> Make sure the nsssd library, as well as the skalibs library,
+are visible in your library search path. </li>
+ <li> Link against <tt>-lnsssd</tt>, <tt>-lskarnet</tt>, </li>
+<tt>`cat $SYSDEPS/socket.lib`</tt> and
+<tt>`cat $SYSDEPS/tainnow.lib`</tt>, $SYSDEPS being your skalibs
+sysdeps directory. </li>
+</ul>
+
+<h2> Programming </h2>
+
+<ul>
+ <li> In your <tt>main()</tt> function, start with assigning
+the name of your program to the PROG variable. Example:
+<tt>PROG = "nsssd-foobar";</tt> </li>
+ <li> Your <tt>main()</tt> function can parse options and
+take command line arguments as it sees fit. But once it's done
+parsing options, give control to the <tt>nsssd_main()</tt>
+function, using your <em>argv</em> and <em>envp</em> as
+arguments: <tt>return nsssd_main(argv, envp);</tt> </li>
+</ul>
+
+<p>
+ The rest of your program should implement the functions needed by
+<tt>nsssd_main()</tt>. Here is what those functions are:
+</p>
+
+<h4><code>void *nsssd_handle_init (void)</code></h4>
+<p>
+This function must return a pointer to an <em>uninitialized</em>
+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.
+</p>
+
+<h4><code>int nsssd_handle_start (void *handle, char const *const *argv, char const *const *envp)</code></h4>
+<p>
+This function must <em>initialize the handle</em>. The arguments
+it receives are the <em>argv</em> and <em>envp</em> that have been
+passed to <tt>nsssd_main()</tt>. This allows you to write daemons
+that can be somewhat configured via the command line: it is how
+<a href="../nsssd-nslcd.html">nsssd-nslcd</a> takes an argument
+telling it where the nslcd socket is, and uses that argument in
+its own <tt>nsssd_handle_start</tt> to actually connect to the
+nslcd daemon. <br />
+The function must return nonzero if it succeeds, and 0 if it
+fails, setting errno appropriately.
+</p>
+
+<h4><code>void nsssd_handle_end (void *handle)</code></h4>
+<p>
+This function must deinitialize the handle and free all
+related resources: close connections to external processes, etc.
+</p>
+
+<p>
+ TODO: to be completed.
+</p>
+
+</body>
+</html>
diff --git a/doc/nsssd-nslcd.html b/doc/nsssd-nslcd.html
new file mode 100644
index 0000000..ce6fea8
--- /dev/null
+++ b/doc/nsssd-nslcd.html
@@ -0,0 +1,85 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss: the nsssd-nslcd program</title>
+    <meta name="Description" content="nsss: the nsssd-nslcd program" />
+    <meta name="Keywords" content="nsss name service switch nsssd nslcd ldap daemon authentication service nsssd-nslcd" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The nsssd-nslcd program </h1>
+
+<p>
+nsssd-nslcd is a daemon providing a backend for clients using the
+<a href="libnsss/">nsss library</a> - more precisely, clients using
+the <a href="libnsss/nsss-all.html">nsss-all</a> or
+the <a href="libnsss/nsss-switch.html">nsss-switch</a> functions.
+</p>
+
+<p>
+ The nsssd-nslcd backend is meant to be used when the user/group/shadow
+information is held in a LDAP server, and the
+<a href="https://github.com/arthurdejong/nss-pam-ldapd/tree/master/nslcd">nslcd</a>
+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.
+</p>
+
+<p>
+ 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"
+<a href="//skarnet.org/software/s6/localservice.html">local service</a>.
+</p>
+
+<p>
+ The <tt>examples/</tt> 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:
+</p>
+<pre>s6-ipcserver -l0 /run/service/nsss/s nsssd-nslcd /var/run/nslcd/socket</pre>
+
+<p>
+<tt>/run/service/nsss/s</tt> is the default place where nsss's
+implementation of the <tt>pwd.h</tt>, <tt>grp.h</tt> and <tt>shadow.h</tt>
+functions expects the nsssd
+service to be. It can be changed at nsss build time by giving the
+<tt>--with-nsssd-socket=PATH</tt> option to configure.
+nsssd-nslcd takes one argument: the path to connect to the nslcd daemon.
+By default, this is <tt>/var/run/nslcd/socket</tt>. The default can be
+changed at nslcd build time.
+</p>
+
+<p>
+ 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
+<a href="//skarnet.org/software/s6/s6-ipcserver.html">s6-ipcserver</a>
+to manage connections to the socket. An instance of nsssd-nslcd is run
+for every client connection.
+</p>
+
+<p>
+ 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.
+</p>
+
+<p>
+ nsssd-nslcd does not need to run as root, provided it can connect
+to the nslcd daemon.
+It is recommended to create a <em>nsss</em> user and group, dedicated to
+the nsssd service, and run the superserver as this user and group.
+</p>
+
+</body>
+</html>
diff --git a/doc/nsssd-unix.html b/doc/nsssd-unix.html
new file mode 100644
index 0000000..bcb5634
--- /dev/null
+++ b/doc/nsssd-unix.html
@@ -0,0 +1,88 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss: the nsssd-unix program</title>
+    <meta name="Description" content="nsss: the nsssd-unix program" />
+    <meta name="Keywords" content="nsss name service switch nsssd unix daemon service nsssd-unix" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The nsssd-unix program </h1>
+
+<p>
+nsssd-unix is a daemon providing a backend for clients using the
+<a href="libnsss/">nsss library</a> - more precisely, clients using
+the <a href="libnsss/nsss-all.html">nsss-all</a> or
+the <a href="libnsss/nsss-switch.html">nsss-switch</a> functions.
+</p>
+
+<p>
+ The nsssd-unix backend is a simple one. It simply fetches user/group/shadow
+information from the <tt>/etc/passwd</tt>, <tt>/etc/group</tt> and
+<tt>/etc/shadow</tt> files. The same information can be directly obtained
+by a client if it uses the <a href="libnsss/nsss-unix.html">nsss-unix</a>
+functions, without the overhead of going through an independent process.
+However, setting up a nsssd-unix service can still be useful:
+</p>
+
+<ul>
+ <li> For testing purposes </li>
+ <li> As a placeholder service that will be replaced later with a more
+complex backend </li>
+ <li> ... </li>
+</ul>
+
+<p>
+ 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"
+<a href="//skarnet.org/software/s6/localservice.html">local service</a>.
+</p>
+
+<p>
+ The <tt>examples/</tt> 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:
+</p>
+<pre>s6-ipcserver -l0 /run/service/nsss/s nsssd-unix</pre>
+
+<p>
+<tt>/run/service/nsss/s</tt> is the default place where nsss's
+implementation of the <tt>pwd.h</tt>, <tt>grp.h</tt> and <tt>shadow.h</tt>
+functions expects the nsssd
+service to be. It can be changed at nsss build time by giving the
+<tt>--with-nsssd-socket=PATH</tt> option to configure.
+</p>
+
+<p>
+ 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
+<a href="//skarnet.org/software/s6/s6-ipcserver.html">s6-ipcserver</a>
+to manage connections to the socket. An instance of nsssd-unix is run
+for every client connection.
+</p>
+
+<p>
+ 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.
+</p>
+
+<p>
+ nsssd-unix does not need to run as root, provided it can read the files
+database.
+It is recommended to create a <em>nsss</em> user and group, dedicated to
+the nsssd service, and run the superserver as this user and group.
+</p>
+
+</body>
+</html>
diff --git a/doc/overview.html b/doc/overview.html
index 222e296..047bea6 100644
--- a/doc/overview.html
+++ b/doc/overview.html
@@ -28,7 +28,106 @@ than the POSIX interface specifies.
 </p>
 
 <p>
- To be completed.
+ nsss has two parts: the client library and the nsssd service.
+</p>
+
+<h2> The nsss client library </h2>
+
+<p>
+ The <a href="libnsss/">client library</a> provides:
+</p>
+
+<ul>
+ <li> <a href="libnsss/nsss-unix.html">nsss-unix</a>: a set of
+functions providing access to the standard <tt>/etc/passwd</tt>,
+<tt>/etc/group</tt> and <tt>/etc/shadow</tt> files. </li>
+ <li> <a href="libnsss/nsss-switch.html">nsss-switch: a set of
+functions implementing the same functionality as <tt>nsss-unix</tt>,
+but instead of looking for information in the standard files, they
+connect to a <em>nsssd service</em> (see below) that performs the
+requests for them. <li>
+ <li> three implementations of the the standard <tt>getpwnam()</tt>
+et al. functions: one using the <tt>nsss-unix</tt> functions, one
+using the <tt>nsss-switch</tt> functions, and the default one, called
+<tt>nsss-all</tt>, which attempts to connect to the nsssd service
+and retrieve information from it, but falls back to the <tt>nsss-unix</tt>
+implementation if it fails (for instance, if no nsssd service is
+listening). </li>
+<ul>
+
+<p>
+ Applications wishing to use nsss should be built against this client
+library. The <tt>getpwnam()</tt> et al. definitions will override those
+of the libc, and use the <tt>nsss-all</tt>, <tt>nsss-switch</tt> or
+<tt>nsss-unix</tt> depending on compilation options.
+</p>
+
+<p>
+ Unlike glibc's <tt>nsswitch</tt>, 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.
+</p>
+
+<h2> The nsssd service </h2>
+
+<p>
+ For applications that need to use the <tt>nsss-all</tt> or
+<tt>nsss-switch</tt> implementations of <tt>getpwnam()</tt> et al.
+(and that is the point, otherwise the libc's implementation could
+generally be used over <tt>nsss-unix</tt> instead!) there needs to
+be a daemon running on the system, and serving requests from
+<tt>nsss-switch</tt> clients.
+</p>
+
+<p>
+ That daemon should be set up by the system administrator. It should
+listen to the <tt>/run/service/nsssd/s</tt> Unix domain socket; that
+default location can be changed at nsss build time via the
+<tt>--with-nsssd-socket</tt> option to the configure script.
+</p>
+
+<p>
+ As of 0.0.1.0, two suitable implementations of a nsssd daemon are
+provided by the nsss package:
+</p>
+
+<ul>
+ <li> The <a href="nsssd-unix.html">nsssd-unix</a> program, which is
+sort of a dummy implementation since it simply accesses the standard
+files (it simply uses the <tt>nsss-unix</tt> library). It is still
+useful for testing purposes, and to have a placeholder service that
+can easily be replaced later. </li>
+ <li> The <a href="nsssd-nslcd.html">nsssd-nslcd</a> program, which
+performs requests to a
+<a href="https://arthurdejong.org/nss-pam-ldapd/nslcd.8">nslcd</a>
+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. </li>
+</ul>
+
+<p>
+ More implementations, with a wider variety of backends, will come
+in future versions of nsss.
+</p>
+
+<p>
+ 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
+<a href="//skarnet.org/software/s6/s6-ipcserver.html">s6-ipcserver</a>
+program, from the <a href="//skarnet.org/software/s6/">s6</a> 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:
+</p>
+
+<pre> s6-ipcserver -- /run/service/nsssd/s nsssd-unix </pre>
+
+<p>
+ 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
+<tt>examples/</tt> subdirectory of the nsss package, for OpenRC,
+s6 or s6-rc based systems.
 </p>
 
 </body>