From 4057413c79ffb467210f27de71006d4237b8d8e9 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 20 Dec 2021 11:33:37 +0000 Subject: Add utmps-write doc Signed-off-by: Laurent Bercot --- doc/index.html | 1 + doc/utmps-utmpd.html | 2 +- doc/utmps-write.html | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/utmps-wtmpd.html | 2 +- 4 files changed, 103 insertions(+), 2 deletions(-) create mode 100644 doc/utmps-write.html diff --git a/doc/index.html b/doc/index.html index 75aac4f..f22082d 100644 --- a/doc/index.html +++ b/doc/index.html @@ -108,6 +108,7 @@ the previous versions of utmps and the current one.

Libraries

diff --git a/doc/utmps-utmpd.html b/doc/utmps-utmpd.html index 2bee9ad..ea7fb3b 100644 --- a/doc/utmps-utmpd.html +++ b/doc/utmps-utmpd.html @@ -34,7 +34,7 @@ a script as a part of a "utmpd" 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 utmpd-socket utmps-utmpd

s6-ipcserver .utmpd-socket utmps-utmpd

while being in the /run/utmps directory.

diff --git a/doc/utmps-write.html b/doc/utmps-write.html new file mode 100644 index 0000000..d456a00 --- /dev/null +++ b/doc/utmps-write.html @@ -0,0 +1,100 @@ + + + + + + utmps: the utmps-write program + + + + + + +

+utmps
+Software
+skarnet.org +

+ +

The utmps-write program

+ +

+utmps-write is a command-line generic utmp client for utmps. +It sends an arbitrary utmp entry to the utmpd and/or wtmpd daemon. It can +be used to test utmps installations. +

+ +

Interface

+ +

+     utmps-write [ -u ] [ -w ] [ -U utmpd-socket ] [ -W wtmpd-socket ] [ -t timeout ] [ -T timestamp ] [ -h host ] [ -i ip ] [ -l user ] [ -p pid ] id type line
+

+ +

utmps-write constructs an utmp entry of type type, with identifier id, containing the line line.
Other fields can also be manually filled via options; by default, utmps-write will put in reasonable values.
utmps-write connects to a utmpd and/or a +wtmpd instance, and sends them that utmp entry for writing.
It exits 0 on success, or prints an error message on stderr.

+ +

+ The type argument must be symbolic: EMPTY, BOOT_TIME etc. The valid types +are the symbolic constants for the ut_type field of the utmpx structure, +as documented here +or in the utmps/utmpx.h header provided with the utmps package. +

+ +

Options

+ +

-u : add the entry to the utmp database.
-w : add the entry to the wtmp database. At least one of the -u or -w +option must be given.
-U utmpd-socket : if the -u option has been given, +connect to a utmpd instance listening on utmpd-socket. The default is the compile-time +default, /run/utmps/.utmpd-socket or the value given to the --with-utmp-socket +configure option.
-W wtmpd-socket : if the -w option has been given, +connect to a wtmpd instance listening on wtmpd-socket. The default is the compile-time +default, /run/utmps/.wtmpd-socket or the value given to the --with-wtmp-socket +configure option.
-t timeout : if the operations have not been completed +under timeout milliseconds, exit with an error message. By default, utmps-write +will wait forever for an answer from the utmpd or wtmpd daemons.
-T timestamp : spoof the ut_tv field of the utmp +entry. timestamp must be given as an absolute +TAI64N label in external TAI64N format, +prepended with a @ character. By default, ut_tv will contain the time when +utmps-write was invoked.
-h host : spoof the ut_host field of the utmp entry. +By default, it is empty (all null characters).
-i ip : spoof the ut_addr_v6 field of the utmp entry. +ip can be given as an ipv4 or an ipv6 address. By default, it's :: (all null +characters).
-l user : spoof the ut_user field of the utmp entry. +This can only be done by root, otherwise the utmp or wtmp daemon will refuse to add the entry. +By default, the field contains the user's name as obtained by +getpwuid().
-p pid : spoof the ut_pid field of the utmp entry. +By default, the field contains the pid of the utmps-write process.

+ +

Notes

+ +

There is an official API to write a complete utmp entry to the +utmp or the wtmp database, and this is what utmps-write uses. However, +there is no official API to read, and format, a complete utmp entry from +the databases; you can read them from instance via util-linux's +utmpdump +utility, but you need to give it the direct path to the utmp and wtmp files.
The wtmp database can only grow; a user calling utmps-write -w +repeatedly can easily make it grow fast and indefinitely, using up all the available +disk space. This is a fundamental problem with the design of utmp, and is already +achievable without the use of utmps-write. The only solution is for +administrators to detect fast-growing wtmp files, and clean them up or archive them.

+ + + diff --git a/doc/utmps-wtmpd.html b/doc/utmps-wtmpd.html index f2f77db..d8a3b7c 100644 --- a/doc/utmps-wtmpd.html +++ b/doc/utmps-wtmpd.html @@ -34,7 +34,7 @@ a script as a part of a "wtmpd" 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 wtmpd-socket utmps-wtmpd

s6-ipcserver .wtmpd-socket utmps-wtmpd

while being in the /run/utmps directory.

-- cgit 1.4.1