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/utmps-write.html | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 doc/utmps-write.html (limited to 'doc/utmps-write.html') 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.

+ + + -- cgit v1.3.1