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.