1 files changed, 78 insertions, 0 deletions
diff --git a/doc/utmps-wtmpd.html b/doc/utmps-wtmpd.html
new file mode 100644
index 0000000..a1e090b
--- /dev/null
+++ b/doc/utmps-wtmpd.html
@@ -0,0 +1,78 @@
+<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>utmps: the utmps-wtmpd program</title>
+    <meta name="Description" content="utmps: the utmps-wtmpd program" />
+    <meta name="Keywords" content="utmps wtmp wtmpd daemon service utmps-wtmpd" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">utmps</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The utmps-wtmpd program </h1>
+
+<p>
+utmps-wtmpd manages the wtmp database. It expects to be able to create, read and
+modify a file named <tt>wtmp</tt> in the directory it is launched in.
+</p>
+
+<p>
+ It is not meant to be called directly; instead, it is expected to be run from
+a script as a part of a "wtmpd"
+<a href="//skarnet.org/software/s6/localservice.html">local service</a>.
+</p>
+
+<p>
+ The <tt>examples/</tt> subdirectory of the utmps 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 utmpd-socket utmps-wtmpd</pre>
+<p>
+ while being in the <tt>/run/utmps</tt> directory.
+</p>
+
+<p>
+<tt>/run/utmps/wtmpd-socket</tt> is the default place where utmps's
+implementation of the <tt>updwtmpx()</tt> function expects the wtmpd
+service to be. It can be changed at build time by giving the
+<tt>--with-wtmp-socket=PATH</tt> option to configure.
+</p>
+
+<p>
+ utmps-wtmpd 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 utmps-wtmpd is run
+for every client connection;
+every instance reads the effective uid of the client in an environment
+variable set by the superserver, which allows it to filter operations:
+only lines whose <tt>ut_user</tt> field resolves to the effective uid of
+the client will be appended to the database.
+</p>
+
+<p>
+ If more fine-grained authorizations are required (only allowing
+certain users and groups to connect to the service), the superserver
+can be configured to enforce them. For instance, it is possible to
+tell s6-ipcserver to only accept connections from root.
+</p>
+
+<p>
+ utmps-wtmpd does not need to run as root, provided it can write its file;
+it is recommended to create a <em>utmp</em> user and group, dedicated to
+utmps-wtmpd and
+<a href="utmps-utmpd.html">utmps-utmpd</a> operation, and run the
+superserver as this user and group.
+</p>
+
+</body>
+</html>