1 files changed, 85 insertions, 0 deletions
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>