diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 132 | ||||
| -rw-r--r-- | doc/libutmps/index.html | 171 | ||||
| -rw-r--r-- | doc/overview.html | 109 | ||||
| -rw-r--r-- | doc/upgrade.html | 28 | ||||
| -rw-r--r-- | doc/utmps-utmpd.html | 77 | ||||
| -rw-r--r-- | doc/utmps-wtmpd.html | 78 |
6 files changed, 595 insertions, 0 deletions
diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..8d080da --- /dev/null +++ b/doc/index.html @@ -0,0 +1,132 @@ +<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 - a secure utmp implementation</title> + <meta name="Description" content="utmps - a secure utmp implementation" /> + <meta name="Keywords" content="utmps utmp utmpx unix login accounting wtmp laurent bercot skarnet" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> utmps </h1> + +<h2> What is it ? </h2> + +<p> + utmps is an implementation of the <tt>utmp.h</tt> and <tt>utmpx.h</tt> +family of functions performing user accounting on Unix systems. +</p> + +<p> + Traditionally, <tt>utmp</tt> functionality is provided by the system's +libc. However, not all libcs implement utmp: for instance the +<a href="https://musl-libc.org/">musl</a> libc, on Linux, does not. The +main reason for it is that <tt>utmp</tt> functionality is difficult to +implement in a secure way; in particular, it is impossible to implement +without either running a daemon or allowing arbitrary programs to tamper +with user accounting. +</p> + +<p> + <tt>utmps</tt> is a secure implementation of user accounting, using +a daemon as the only authority to manage the utmp and wtmp data; programs +running utmp functions are just clients to this daemon. +</p> + +<hr /> + +<ul> + <li> <a href="overview.html">An overview of utmps</a> </li> +</ul> + +<hr /> + +<h2> Installation </h2> + +<h3> Requirements </h3> + +<ul> + <li> A POSIX-compliant system with a standard C development environment </li> + <li> GNU make, version 3.81 or later </li> + <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version +2.6.1.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> +</ul> + +<h3> Licensing </h3> + +<p> + s6 is free software. It is available under the +<a href="http://opensource.org/licenses/ISC">ISC license</a>. +</p> + +<h3> Download </h3> + +<ul> + <li> The current released version of utmps is <a href="utmps-0.0.1.0.tar.gz">0.0.1.0</a>. </li> + <li> Alternatively, you can checkout a copy of the +<a href="//git.skarnet.org/cgi-bin/cgit.cgi/utmps/">utmps +git repository</a>: +<pre> git clone git://git.skarnet.org/utmps </pre> </li> + <li> There's also a +<a href="https://github.com/skarnet/utmps">GitHub mirror</a> +of the utmps git repository. </li> +</ul> + +<h3> Compilation </h3> + +<ul> + <li> See the enclosed INSTALL file for installation details. </li> +</ul> + +<h3> Upgrade notes </h3> + +<ul> + <li> <a href="upgrade.html">This page</a> lists the differences to be aware of between +the previous versions of utmps and the current one. </li> +</ul> + +<hr /> + +<h2> Reference </h2> + +<h3> Commands </h3> + +<ul> +<li><a href="utmps-utmpd.html">The <tt>utmps-utmpd</tt> program</a></li> +<li><a href="utmps-wtmpd.html">The <tt>utmps-wtmpd</tt> program</a></li> +</ul> + +<h3> Libraries </h3> + +<ul> +<li> <a href="libutmps/">The <tt>utmps</tt> library interface</a> </li> +<li> <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/utmpx.h.html">The +<tt>utmpx.h</tt> library interface</a> is implemented on top of the utmps library. </li> +<li> <a href="http://man7.org/linux/man-pages/man3/logwtmp.3.html">The <tt>logwtmp()</tt> +and <tt>updwtmpx()</tt> functions</a> are also implemented. </li> +</ul> + +<hr /> + +<a name="related"> +<h2> Related resources </h2> +</a> + +<h3> utmps discussion </h3> + +<ul> + <li> <tt>utmps</tt> is discussed on the +<a href="//skarnet.org/lists.html#skaware">skaware</a> mailing-list. </li> +</ul> + +</body> +</html> diff --git a/doc/libutmps/index.html b/doc/libutmps/index.html new file mode 100644 index 0000000..0372726 --- /dev/null +++ b/doc/libutmps/index.html @@ -0,0 +1,171 @@ +<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 library interface</title> + <meta name="Description" content="utmps: the utmps library interface" /> + <meta name="Keywords" content="utmps utmp wtmp library libutmps" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="../">utmps</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>utmps</tt> library interface </h1> + +<h2> General information </h2> + +<p> + <tt>libutmps</tt> is a client library meant to be used by client +programs needing utmp functionality. It interacts with the +<a href="../utmps-utmpd.html">utmps-utmpd</a> and +<a href="../utmps-wtmpd.html">utmps-wtmpd</a> daemons. +</p> + +<p> + Application programs can use it directly, but most existing programs +simply use the standard +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/utmpx.h.html">utmpx.h</a> +interface, which in utmps is implemented as a series of thin wrappers +around the utmps library. +</p> + +<h2> Compiling </h2> + +<ul> + <li> Make sure the utmps headers, as well as the skalibs headers, +are visible in your header search path. </li> + <li> Use <tt>#include <utmps/utmps.h></tt> </li> + <li> To use the standard <tt>utmpx.h</tt> interface, you can +just <tt>#include <utmpx.h></tt>, which will work as long +as the <tt>utmps/utmpx.h</tt> header is accessible in your header +search path. </li> +</ul> + +<h2> Linking </h2> + +<ul> + <li> Make sure the utmps library, as well as the skalibs library, +are visible in your library search path. </li> + <li> Link against <tt>-lutmps</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> + +<p> + Check the <tt>utmps/utmps.h</tt> header for the exact function list, +and the <tt>utmps/utmpx.h</tt> header for the definition of the standard +<tt>struct utmpx</tt> data type. +</p> + +<h3> Synchronous functions with a specified maximum execution time </h3> + +<p> + The standard utmpx.h functions are fully synchronous. They were not +initially meant to perform inter-processus communication; however, in +utmps, they do. Their synchronous nature is obviously not changed here, +but the underlying utmps functions use a safety mechanism to bound their +execution time in case daemons fail to respond. This mechanism is described, +for instance, +<a href="//skarnet.org/libs6/ftrigr.html#synctimed">here</a>. +</p> + +<h3> Starting and ending a session </h3> + +<p> +<code>int utmps_start (utmps *a, char const *path, tain_t const *deadline, tain_t *stamp)</code> <br /> +Connects to a <tt>utmps-utmpd</tt> service listening on a Unix domain socket at <em>path</em>. +<em>a</em> must point to a previously allocated <em>utmps</em> object, which is flat and can +be allocated in the stack. This object must have been initialized to UTMPS_ZERO before the call. +<em>a</em> will be a handle describing the session, and must be given to all utmps functions +called in that session. +<em>deadline</em> and <em>stamp</em> are used to bound the execution time as described in the +above link. The function returns 1 if it succeeds; it returns 0, and sets errno, if it fails. +</p> + +<p> +<code>void utmps_end (utmps *a)</code> <br /> +Ends the session described by <em>a</em>, and releases all used resources. +</p> + +<h3> Reading from the utmp database </h3> + +<p> + Any user authorized to connect to the utmpd service can call these functions. In other +words, if <tt>utmps_start()</tt> succeeded, then these functions should not fail due to +insufficient permissions. +</p> + +<p> +<code>int utmps_rewind (utmps *a, tain_t const *deadline, tain_t *stamp)</code> <br /> +Performs the <tt>setutxent()</tt> functionality on the utmp database addressed via <em>a</em>, +i.e. sets the internal pointer at the start of the database. +On success, stores the result into <em>*b</em> and returns 1. On failure, returns 0 and sets errno. +</p> + +<p> +<code>int utmps_getent (utmps *a, struct utmpx *b, tain_t const *deadline, tain_t *stamp)</code> <br /> +Performs the <tt>getutxent()</tt> functionality on the utmp database addressed via <em>a</em>. +On success, stores the result into <em>*b</em> and returns 1. On failure, returns 0 and sets errno. +</p> + +<p> +<code>int utmps_getid (utmps *a, unsigned short type, char const *id, struct utmpx *b, tain_t const *deadline, tain_t *stamp)</code> <br /> +Performs the <tt>getutxid()</tt> functionality on the utmp database addressed via <em>a</em>, +using ut_type <em>type</em> and ut_id <em>id</em>. <em>id</em> must be a null-terminated +string; only its first UTMPS_UT_IDSIZE-1 characters will be taken into account. +On success, the function stores the result into <em>*b</em> and returns 1. On failure, +it returns 0 and sets errno. +</p> + +<p> +<code>int utmps_getline (utmps *a, char const *line, struct utmpx *b, tain_t const *deadline, tain_t *stamp)</code> <br /> +Performs the <tt>getutxline()</tt> functionality on the utmp database addressed via <em>a</em>, +using ut_line <em>line</em>. <em>line</em> must be a null-terminated +string; only its first UTMPS_UT_LINESIZE-1 characters will be taken into account. +On success, the function stores the result into <em>*b</em> and returns 1. On failure, +it returns 0 and sets errno. +</p> + +<h3> Writing to the utmp database </h3> + +<p> + Currently, only the super-user is allowed to use this function. +</p> + +<p> +<code>int utmps_putline (utmps *a, struct utmpx const *b, tain_t const *deadline, tain_t *stamp)</code> <br /> +Performs the <tt>pututxline()</tt> functionality on the utmp database addressed via <em>a</em>, +i.e. writes the <em>*b</em> structure into the utmp database looking for an appropriate +record to replace, and appending to the database if no such record can be found. +On success, the function returns 1. On failure, it returns 0 and sets errno. +</p> + +<h3> Writing to the wtmp database </h3> + +<p> +<code>int utmps_updwtmpx (char const *path, struct utmpx const *b, tain_t const *deadline, tain_t *stamp)</code> <br /> +Unlike the previous functions, <tt>utmps_updwtmpx()</tt> does not use a utmps handle, because +it does not connect to an utmpd service. Instead, it connects to a wtmpd service listening +on Unix domain socket <em>path</em>, once for every call. It appends the <em>*b</em> structure +to the wtmp database, returning 1 on success and 0 (and setting errno) on failure. +</p> + +<p> + <tt>utmps_updwtmpx()</tt> will only succeed if the caller is root, or if +<em>b→ut_user</em> resolves (according to <tt>getpwnam()</tt>) to the +effective uid of the caller. In other words: users can append phony records +for themselves, but not for others, and only root can spoof the whole +wtmp database. +</p> + +</body> +</html> diff --git a/doc/overview.html b/doc/overview.html new file mode 100644 index 0000000..22e9210 --- /dev/null +++ b/doc/overview.html @@ -0,0 +1,109 @@ +<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: an overview</title> + <meta name="Description" content="s6: an overview" /> + <meta name="Keywords" content="utmps overview utmp wtmp utmpx login user accounting unix" /> + <!-- <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> An overview of utmps </h1> + +<p> + utmps is a secure implementation of the <em>utmp</em> functionality, i.e. +user accounting on Unix systems. It includes full POSIX +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/utmpx.h.html">utmpx.h</a> +functionality, a few extensions created by GNU, and an underlying +<a href="libutmps/">C client library</a> with better error reporting +than the POSIX interface specifies. +</p> + +<h2> The issues with traditional utmp </h2> + +<p> + Traditional <em>utmp</em> implementations, as performed by most Unix +libcs, are woefully insecure. The fundamental issue with <em>utmp</em> +is that it requires user programs to write to files (the utmp or wtmp +databases) owned by either root or a specific system user. That means +having the suid bit set on programs using it. +</p> + +<h2> The utmps solution </h2> + +<p> + utmps uses the age old Unix client-server model, following the +adage "one resource → one daemon". It provides two daemons, +<a href="utmps-utmpd.html">utmps-utmpd</a> and +<a href="utmps-wtmpd.html">utmps-wtmpd</a>, which should be the only +programs allowed to access the utmp and wtmp databases respectively. +It provides the +<a href="libutmps/">utmps client library</a> to communicate with +those daemons; and it implements the +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/utmpx.h.html">utmpx.h</a> +interfaces, and the extensions, as wrappers for this client library. +</p> + +<h2> Authentication, local services and superservers </h2> + +<p> +<a href="utmps-utmpd.html">utmps-utmpd</a> and +<a href="utmps-wtmpd.html">utmps-wtmpd</a> do not listen to the +network themselves. They are designed to serve only one client +connection, following the +<a href="http://cr.yp.to/proto/ucspi.txt">UCSPI model</a> - +also known as the inetd model. To implement the utmpd and wtmpd +<a href="//skarnet.org/software/s6/localservice.html">local services</a>, +a Unix domain superserver such as +<a href="//skarnet.org/software/s6/s6-ipcserver.html">s6-ipcserver</a> +is required. s6-ipcserver listens to a socket, and spawns a +<a href="utmps-utmpd.html">utmps-utmpd</a> process when a client +calls <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setutxent.html">setutxent()</a> +for instance. +</p> + +<p> + The utmpd and wtmpd services must be started at boot time in +order for utmp calls to succeed. The <tt>examples/</tt> subdirectory +of the utmps package has examples on how to start those services +when using the +<a href="//skarnet.org/software/s6/">s6</a> supervision suite, +the <a href="//skarnet.org/software/s6-rc/">s6-rc</a> service manager, or +the <a href="https://wiki.gentoo.org/wiki/OpenRC">OpenRC</a> service manager. +</p> + +<p> + This model has advantages and drawbacks. The main drawback is that it requires +a daemon to be running in order for the system to provide full POSIX +functionality. The main advantage, on the other hand, is that no program +needs to be suid or sgid, and permissions can actually be quite fine-grained. +</p> + +<ul> + <li> <a href="utmps-utmpd.html">utmps-utmpd</a> will allow any user to +read from the utmp database, but will only allow root to write to it. </li> + <li> <a href="utmps-wtmpd.html">utmps-wtmpd</a> will only allow a user +to add an entry to the wtmp database if the user is root, or if the +<tt>ut_user</tt> field of the added entry resolves to the user's effective +uid. </li> + <li> The <a href="//skarnet.org/software/s6/s6-ipcserver.html">s6-ipcserver</a> +superserver, which is recommended to implement the utmpd and wtmpd services, +allows fine-tuning the permissions: it is possible to deny users from +connecting to the service, or to only allow certain groups, etc. </li> +</ul> + +<p> + All in all, I believe the flexibility it offers overweighs the inconvenience +of having to run services before providing utmp/wtmp. +</p> + +</body> +</html> diff --git a/doc/upgrade.html b/doc/upgrade.html new file mode 100644 index 0000000..b5c9db9 --- /dev/null +++ b/doc/upgrade.html @@ -0,0 +1,28 @@ +<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>How to upgrade utmps</title> + <meta name="Description" content="How to upgrade utmps" /> + <meta name="Keywords" content="utmps installation upgrade" /> + <!-- <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> What has changed in utmps </h1> + +<h2> in 0.0.1.0 </h2> + +<p> + Initial release. +</p> + +</body> +</html> diff --git a/doc/utmps-utmpd.html b/doc/utmps-utmpd.html new file mode 100644 index 0000000..57fa6ac --- /dev/null +++ b/doc/utmps-utmpd.html @@ -0,0 +1,77 @@ +<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-utmpd program</title> + <meta name="Description" content="utmps: the utmps-utmpd program" /> + <meta name="Keywords" content="utmps utmp utmpd daemon service utmps-utmpd" /> + <!-- <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-utmpd program </h1> + +<p> +utmps-utmpd manages the utmp database. It expects to be able to create, read and +modify a file named <tt>utmp</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 "utmpd" +<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-utmpd</pre> +<p> + while being in the <tt>/run/utmps</tt> directory. +</p> + +<p> +<tt>/run/utmps/utmpd-socket</tt> is the default place where utmps's +implementation of the <tt>utmpx.h</tt> functions expects the utmpd +service to be. It can be changed at build time by giving the +<tt>--with-utmp-socket=PATH</tt> option to configure. +</p> + +<p> + utmps-utmpd 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-utmpd 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 - +for instance, it allows any user to read from the database but it only +allows root to write to it. +</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. +</p> + +<p> + utmps-utmpd 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-utmpd and +<a href="utmps-wtmpd.html">utmps-wtmpd</a> operation, and run the +superserver as this user and group. +</p> + +</body> +</html> 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> |