Technical Manual

1.1 · What RootSpeak is

RootSpeak — Advanced Messaging System for Linux is the tool with which the administrators of a Linux machine send text messages to users and know who has confirmed reading them. It answers a question that the system's own tools leave open: “who has not read it yet?”

wall and write write to the terminals of logged-in users without keeping track of anything; notify-send shows a notification that may disappear; the motd and login banners are fixed texts. None of them keeps a state per message and per user. RootSpeak puts the pieces together (logind, the terminals, desktop autostart, zenity, the journal) and adds exactly this state.

Version 0.2.0 is written in C (the 0.1.0 prototype was in bash): two programs, no daemon, no database. The rspeak command always runs as root and writes to the message store; on the user's side the helper rootspeak-user reads the mailbox and records the confirmation, in two ways: in the shell prompt (rootspeak-user prompt) and in the graphical session (rootspeak-user agent).

1.2 · Basic concepts

A few concepts are enough to read the rest of the manual. They are the same in the code, in the tests and in the manuals.

Message

a text (at most 65536 bytes) with an optional title and an optional expiry, identified by a sequential number, the ID. The sender is the administrator who ran rspeak.

Recipient

a human user of the machine to whom the message is addressed: by name, by group (@group), everyone (all) or the logged-in users (online).

Reference copy

the message in /var/lib/rootspeak/sent/ID/, readable only by root: what was sent, to whom, when, with which expiry. It is the authoritative source.

Mailbox

a user's /var/lib/rootspeak/users/U/ folder: a working copy that the user controls, with the subfolders inbox, read, acks and state.

Channel

where the user sees the message and confirms it: a terminal (terminal pts/N, terminal tty3) or the desktop (desktop).

Confirmation

the user's statement of having read the message, written into their mailbox in acks/ID with date and channel. The first one counts.

Postponement

the answer “no” in the terminal or “Later” on the desktop: the question comes back after RSPEAK_REMIND_MINUTES minutes, or at the next login.

State

for each recipient exactly one of three: sent, delivered, confirmed. Revoked and expired are properties of the message, not states.

1.3 · Subsystems at a glance

The code lives in src/ and is organised in small modules with clear-cut responsibilities. This is the map that the manual explores chapter by chapter.

rspeak.c

the administrators' command: relaunch through sudo, send, list, status, revoke, remind, log, purge, recovery of interrupted sends (chapter 4, chapter 8, chapter 9, chapter 10).

rootspeak-user.c

the helper that runs as the user: the question at the prompt, the desktop agent, the recording of the confirmation (chapter 11, chapter 12, chapter 13).

store.c

the operations on the mailboxes, always with the user's identity; writing to the terminals; waking up the agent (chapter 7, chapter 8).

user.c

as_user: a child process with a user's identity and a time limit (chapter 7).

sessions.c

human users, groups, sessions and terminals, from passwd and from logind (chapter 6).

text.c

text cleaning, message format, configuration (chapter 5, chapter 4).

event.c

the structured events in the journal and their text (chapter 17).

tui.c

the TUI for administrators (chapter 14).

help.c

the built-in help of rspeak --help (chapter 15).

common.c

environment, errors, memory, growable strings, safe reading and writing of files (chapter 5.5, chapter 18).

1.4 · How to read this manual

2.1 · Architectural principles

RootSpeak is small on purpose: two programs, files in a single folder, the systemd libraries already present on the system. The design favours verifiability: every state can be reconstructed by looking at the files, and every step that can be interrupted leaves a mark that the next command knows how to repair.

2.2 · The three privilege domains

A message crosses three domains with different privileges. The rule is simple: everything that passes between root and a user crosses a controlled boundary, in both directions.

2.3 · The two programs

The Makefile produces two executables. The common parts (common text event user sessions) go into both; rspeak adds rspeak.o, help.o, store.o and tui.o.

Both depend only on glibc and libsystemd (sd-login for sessions, sd-journal for the log). At run time they also need sudo, zenity, systemd-run and date; notify-send if available.

2.4 · The path of a message

The complete path touches every subsystem. Here it is in brief; each step has its own chapter.

2.5 · Sessions and channels

RootSpeak does not use utmp, which does not record many modern terminals, but logind and the terminal devices. The useful question is not “how is the user logged in” but “on which channels can I reach them right now”.

• The mailbox acts as a queue: a message that reaches no channel when it is sent appears at the next login (question in the terminal) or at the agent's first round (dialog).
• Writing the text to a terminal does not count as a confirmation: the question arrives at the next prompt.

3.1 · File map

The repository contains the C code, the files to install on the system, the manuals with their sources, the tests and the consistency checks. The following table is the file map: the lines are counted every time the manual is generated, and tools/check-docs.py fails if a code file is missing or if one that does not exist is listed.

RootSpeak/
├── src/                  # the C code: two programs, common parts
├── etc/                  # shell hooks, autostart, configuration
├── install.sh            # installation, upgrade, removal
├── Makefile              # build, tests, analysis, sanitizer
├── docs/                 # the two generated manuals, decisions, reviews
│   └── sources/          # generator, style, one file per chapter
├── tests/                # engine, TUI, help, units, fuzzing, container, VM
│   └── */results/        # results recorded with commit and fingerprint
├── tools/                # manual consistency, fingerprint, screenshots, release
└── site/                 # the website: landing page, publication

The chapters of the manuals are in docs/sources/user/ and docs/sources/technical/, one file per chapter; docs/decisions-and-history.md and CLAUDE.md collect the decisions and the working agreements, docs/adversarial-review.md the two external reviews. The bash prototype (version 0.1.0) is in the repository history.

3.2 · Building: the Makefile

The build is a Makefile with no external tools besides gcc and pkg-config (for libsystemd). Everything ends up in build/ (or in a folder chosen with B=); the installation folder of the helper is compiled into the program with -DLIBDIR.

WARNINGS   = -Wall -Wextra -Wpedantic -Wformat=2 -Wformat-security -Wshadow -Wpointer-arith \
           -Wcast-qual -Wwrite-strings -Wstrict-prototypes -Wmissing-prototypes -Wvla \
           -Wnull-dereference -Wimplicit-fallthrough -Wundef -Werror
HARDENING   = -D_FORTIFY_SOURCE=3 -fstack-protector-strong -fstack-clash-protection -fcf-protection -fPIE
LDFLAGS += -pie -Wl,-z,relro,-z,now -Wl,-z,noexecstack

Warnings are errors (-Werror): the code does not build if gcc finds anything to object to. The meaning of each hardening flag is in chapter 16.3.

3.3 · install.sh step by step

1. It relaunches itself with sudo if it is not root, and picks the administrators' group: the first one that exists among sudo, wheel, admin (otherwise root). It warns if zenity, loginctl or systemd-run are missing.
2. If the programs are missing from build/, or were built for other folders (the LIBDIR path does not appear inside build/rspeak), it builds them with make PREFIX=… (gcc, make, pkg-config and libsystemd-dev are needed). From the downloadable archive, which has no Makefile, it never builds: the programs are already in build/, built for /usr/local; with another PREFIX it stops with “The programs of this archive install only in /usr/local (PREFIX=…)”.
3. It installs $PREFIX/lib/rootspeak/rootspeak-user (755) and $PREFIX/bin/rspeak with owner root:group (the administrators' group) and permissions 750. PREFIX is /usr/local. It removes the language catalogs left by the first 0.2.0 builds: RootSpeak speaks English only.
4. It installs the manuals in $PREFIX/share/doc/rootspeak/, the configuration (only if missing), the shell hooks and the autostart entry, replacing @LIBDIR@ and @VARDIR@.
5. It adds to /etc/bash.bashrc the line marked # RootSpeak hook (on Debian, interactive non-login shells do not read /etc/profile.d); if the system zshrc exists, it adds the line that sources rootspeak.zsh; for fish it writes /etc/fish/conf.d/rootspeak.fish.
6. It creates /var/lib/rootspeak and users/ (755) and sent/ (700).
7. It closes the agents of the previous version: they restart, updated, at the first send or at login.

3.4 · What it installs, and where

3.5 · Before committing a change

1. make (all warnings are errors) and make unit.
2. python3 docs/sources/build.py, then tools/check-docs.py: generated manuals up to date, reference aligned with the help, file map complete, internal links valid, tests run on the current code (chapter 20.5).
3. tests/engine.sh always; tests/help-tui.py if the help has changed; tests/tui.py and tools/tui-screenshots.sh if the TUI has changed; make sanitizer with RSPEAK_BUILD=build-san tests/engine.sh, make analyze and tests/fuzz/run.sh if the code that reads data has changed; tests/container/run.sh if sending, delivery, confirmations or permissions have changed; tests/vm/run.sh if the desktop has changed.
4. A test of the affected flow in test mode (chapter 4.4); for the desktop, sudo and other users, a live test after ./install.sh, done by whoever has the root password.

3.6 · The downloadable archive and the website

RootSpeak is freeware and is distributed as built programs, not as source: one archive, rootspeak-VERSION-linux-x86_64.tar.gz, the same for every supported distribution.

1. tools/release.sh copies the files under version control to the test server and builds them in the image of RHEL 9 of the compatibility tests: RHEL 9 and its rebuilds have the oldest C library among the supported distributions (glibc 2.34; Ubuntu 22.04 has 2.35, SLES 15 2.38), and a program built against an older glibc runs on the newer ones. The programs are stripped of their symbols.
2. It checks that no symbol needs a glibc newer than 2.34 and that the programs were built for /usr/local, then makes the archive with install.sh, etc/, build/rspeak, build/rootspeak-user, the two manuals, LICENSE, NOTICE.md and a README.txt, and its SHA256SUMS.
3. RSPEAK_ARCHIVE=build/release/….tar.gz tests/distros/run.sh runs all the scenarios on the 22 distributions with the archive installed as a customer would (no build on the test machines); the summary records how RootSpeak was installed.
4. site/publish.sh builds the website in site/public/ (landing page, manuals, licence.html, download/, og.jpg, robots.txt, sitemap.xml) and copies it to /srv/www/rootspeak.nicfio.it on the VPS; --build only builds.

4.1 · Starting rspeak

The main of src/rspeak.c is short and its order is a rule: nothing runs without root, not even the help. Before looking at the arguments it reads the environment; then, if it is not root and not in test mode, it relaunches itself with sudo.

int main(int argc, char **argv)
{
	const char *cmd = argc > 1 ? argv[1] : "";

	rspeak_init("rspeak");
	/* As a non-root administrator, rspeak re-runs itself with sudo, even for
	 * the help and the version. */
	if (geteuid() != 0 && !rspeak_test)
		rerun_with_sudo(argv);
	umask(022);

	/* rspeak alone in a terminal opens the TUI; in a pipe, or with a
	 * terminal too small, the help */
	if (!*cmd && isatty(0) && isatty(1)) {
		recover();
		if (rspeak_tui())
			return 0;
	}
	if (!*cmd || !strcmp(cmd, "help") || !strcmp(cmd, "-h") || !strcmp(cmd, "--help")) {
		rspeak_help();
		return 0;
	}
	if (!strcmp(cmd, "version") || !strcmp(cmd, "--version")) {
		printf("RootSpeak - Advanced Messaging System for Linux %s\n", RSPEAK_VERSION);
		return 0;
	}
	if (strcmp(cmd, "send") && strcmp(cmd, "list") && strcmp(cmd, "status") && strcmp(cmd, "revoke") &&
	    strcmp(cmd, "remind") && strcmp(cmd, "log") && strcmp(cmd, "purge"))
		die("unknown command: %s (rspeak --help for the guide)", cmd);
	…
}

• rerun_with_sudo reads its own path from /proc/self/exe and calls execvp("sudo", ["sudo", "--", path, arguments…]): the arguments arrive unchanged, and -- prevents them from being taken as sudo options.
• Under sudo the environment is what sudo preserves: RSPEAK_TEST is not kept. SUDO_USER tells who launched the command: it becomes the sender (from) and the author of the events.
• Recovery of interrupted sends (chapter 8.6) runs before send, list, status, revoke, remind, log and the TUI; not before purge, which skips incomplete sends by itself.
• An unknown command ends with die: rspeak: unknown command: X (rspeak --help for the guide), exit status 1.

4.2 · Starting rootspeak-user

rootspeak-user never relaunches itself: it runs with the identity of whoever launches it, that is the user. Its main has a different order, dictated by the desktop agent.

4.3 · The environment and test mode

rspeak_init in src/common.c sets the working folders. The defaults are compiled into the program; the environment variables count only in test mode: a root program does not take folders from the environment of whoever launches it.

RSPEAK_TEST=1

rspeak does not relaunch itself with sudo, does not wake or start agents, does not change identity in child processes and writes only to the “terminal” RSPEAK_TEST_TTY. An ordinary user who sets it keeps their own permissions (scenario G4: “Permission denied” as soon as rspeak is executed), and sudo removes it from the environment.

RSPEAK_TEST_TTY=file

the “terminal” that rspeak send writes to in test mode; empty: none.

RSPEAK_BUILD=folder

for the tests: the folder of the programs to test (for example build-san).

4.4 · Testing without root

The code is tested from the repository folder as an ordinary user, on a test message store, after make. This is how tests/engine.sh, tests/tui.py and tests/help-tui.py run.

nicfio@server:~/ROOTSPEAK$ make
nicfio@server:~/ROOTSPEAK$ export RSPEAK_TEST=1 RSPEAK_LIB=$PWD/build
nicfio@server:~/ROOTSPEAK$ export RSPEAK_VAR=/tmp/test-store RSPEAK_CONF=/dev/null RSPEAK_TEST_TTY=/tmp/tty
nicfio@server:~/ROOTSPEAK$ build/rspeak send --to nicfio "Test"
Message 1 sent to 1 user.
nicfio@server:~/ROOTSPEAK$ script -qec 'build/rootspeak-user prompt' /dev/null

4.5 · The configuration: rootspeak.conf

The configuration is a data file, not a script: in the bash prototype it was read with source, by root and by the users, and could execute code. Now conf_read in src/text.c reads at most 65536 bytes of it and conf_from_text accepts only two keys, with positive integers.

# RootSpeak - Advanced Messaging System for Linux: configuration
# A data file, not a script: KEY=value lines with positive whole numbers.
# Unknown keys and invalid values are ignored.

# After how many minutes a message postponed by the user is shown again
RSPEAK_REMIND_MINUTES=30

# Every how many seconds the desktop agent checks the messages again
# (new messages wake it at once anyway)
RSPEAK_AGENT_POLL=60

• Each line loses its comment (from # onwards) and all spaces; a line that is still longer than 255 characters is not valid.
• The value must consist of digits only, at most 6, and be greater than zero: 0, -3, abc and $(…) are ignored and the default stays (tests/engine.sh, group 5).
• Unknown keys are ignored; a missing file, or one that is not a regular file, counts as empty.
• rspeak itself does not read the configuration: the two keys concern only what rootspeak-user does.

5.1 · Structure

The message store is made of files and folders under /var/lib/rootspeak. One part belongs to root, one part to each user: the boundary between the two is the heart of RootSpeak security. There is no database and no index: every piece of information is in a file that can be read with cat.

/var/lib/rootspeak/                   # root 755
├── sent/                       # root 700 · root only
│   ├── .seq  .seq.lock         # last ID assigned; lock for flock
│   ├── 12/
│   │   ├── msg                 # the message (reference copy)
│   │   ├── recipients          # one recipient per line
│   │   ├── delivery            # “user date terminals” for each delivered copy
│   │   ├── lock                # held by rspeak send while delivering (flock)
│   │   ├── incomplete          # marker: send in progress or to be completed
│   │   ├── revoked             # date of revocation, if revoked
│   │   ├── revoking            # marker: revoked copies still to be removed
│   │   └── failed              # marker: send interrupted before it was saved
│   └── .deleting-9/            # a message that rspeak purge is deleting
└── users/                      # root 755
    └── mario/                  # mario 700 · the mailbox: only Mario and root
        ├── inbox/12            # to be shown
        ├── read/11             # confirmed or expired
        ├── acks/11             # “date channel” of the confirmation
        └── state/12.term       # postponement: the file's modification time counts

5.2 · Format of a message

A message is a UTF-8 text file: a key: value header, an empty line, the text. The same file, byte for byte, is the reference copy in sent/ID/msg and the copy in the mailbox of each recipient.

format: 1
id: 12
from: admin
date: 1790714288
title: Maintenance
expires: 1790800688

On Saturday from 8 am to 12 noon the server will be off for disk maintenance.

5.3 · Message numbers

Every message has a sequential number. next_id in src/rspeak.c takes it under an exclusive flock on sent/.seq.lock: two simultaneous rspeak send runs never get the same number.

• It reads the last number from sent/.seq (0 if missing or not a number), increments it and creates the folder with mkdir(…, 0700).
• If the folder already exists, it moves on to the next number: this happens if .seq went backwards, for example after a power failure that lost the last write. No message is ever overwritten.
• It writes the new value with write_atomic and releases the lock by closing the descriptor.
• A number taken and never used (an interruption right afterwards) remains a gap in the numbering: harmless.

5.4 · Owners and permissions

A user can delete or modify the files in their own mailbox: they only spoil their own copy. The reference copy stays in sent/, and a message deleted from the mailbox simply shows up as not confirmed. A confirmation written by hand remains a statement by the user (chapter 19.1).

5.5 · Reading and writing files safely

All file I/O goes through a few functions in src/common.c with fixed rules. These are the functions that make it safe to read what users write and that guarantee durability after an interruption.

Every descriptor is opened with O_CLOEXEC: no open file is passed on to the programs launched by RootSpeak (zenity, sudo, systemd-run, the editor). Memory is requested with xmalloc and texts grow in a buf_t (chapter 23.5): no fixed-length buffer receives data that comes from outside.

5.6 · Preserving the message store

RootSpeak has no backup or restore command: the message store is made of files, and the only tools provided are the purge of old messages (rspeak purge, chapter 9.3) and complete removal (install.sh --purge).

• A reset message store reuses message numbers, the journal does not: this is why rspeak log ID reads only the events after the message's sending date (chapter 17.4).
• A copy taken while a send is in progress contains the incomplete marker: given how recovery works (chapter 8.6), after a restore that send would be completed by the first rspeak command.

6.1 · From --to to the list

resolve_recipients in src/rspeak.c turns the value of --to into the list of recipients. It does so before taking a number and before writing anything: an error here leaves no trace in the message store.

• The value is split on commas; each part is one of the four forms in the figure. Empty parts (two commas in a row) are skipped; a space, on the other hand, becomes part of the name, which therefore does not exist: this is why the help asks for names separated by commas without spaces.
• An unknown user or group ends with die (“no such user: nobodyhere”, “no such group: x”): the unknown user is scenario B6 on the test machine.
• Duplicates are removed along the way (scenario B2) and the final list is in alphabetical order: this is the order of the deliveries and of sent/ID/recipients.
• An empty list (for example a group with no members) ends with “no recipients” (scenario B7).
• An explicit name may also be a system account or root: the filter on human users applies only to all and online.

6.2 · Human users, logged-in users, groups

Everything goes through the system interfaces (getpwent, getgrnam, libsystemd's sd-login library): LDAP users or users from other name services work if the system exposes them this way. all excludes root and system accounts because they have a UID below UID_MIN or a non-login shell (scenario B4).

6.3 · A user's terminals

user_terminals collects the terminals to which rspeak send writes the text when sending. There are two sources, because neither is enough on its own.

• Here the owner of /dev/pts/N serves only to find the candidates: at the moment of writing, write_terminal reopens the terminal and checks the owner of the opened terminal (chapter 8.4). The name /dev/pts/N does not identify a session: between the search and the write it might pass to another user.
• In test mode there is a single «terminal»: the file RSPEAK_TEST_TTY, if set.
• An ssh session without a terminal (scp, remote commands) and services have no terminals: they are not touched (scenario C3).

6.4 · The graphical session

graphical_session tells whether a user has an X11 or Wayland session open. It is needed in two places, with the same code.

A user with several graphical sessions (for example a local desktop and a remote one that creates a new session) still has a single agent: the lock rootspeak-agent.lock lives in $XDG_RUNTIME_DIR, which is unique per user (chapter 12.1). The behaviour with several simultaneous desktops of the same user has not been tested.

7.1 · The danger of symbolic links

The mailbox users/U belongs to the user, who can replace its subfolders with symbolic links, pipes or odd files. If root wrote into it directly, it would follow the link and could write anywhere; if it read from it, it could show files the user is not allowed to read. This is why every access by root to the contents of a mailbox happens in a child process with the user's identity: as_user in src/user.c, in place of the runuser used by the prototype.

In the child the user's permissions apply: a link to /etc leads to «permission denied», and the worst the user can achieve is to spoil their own copy. Scenario G1 on the test machine checks this: with the mailbox turned into a link to /etc, rspeak send writes nothing in /etc and the recipient stays “sent, not delivered”.

7.2 · How the child process starts

as_user(u, fn, arg, in, out, max, seconds) runs fn(arg) in a child process with the identity of u. The parent passes it data on stdin, collects its output on a pipe and waits for it to finish, always with a time limit.

static void child(const user_t *u, as_user_fn fn, void *arg, int in, int out)
{
	int nul = open("/dev/null", O_RDWR | O_CLOEXEC);

	if (nul < 0 || dup2(in >= 0 ? in : nul, 0) < 0 || dup2(out >= 0 ? out : nul, 1) < 0 || dup2(nul, 2) < 0)
		_exit(126);
	if (geteuid() == 0 && !rspeak_test) {
		/* the user's full identity: supplementary groups, then group, then user */
		if (initgroups(u->name, u->gid) < 0 || setresgid(u->gid, u->gid, u->gid) < 0 ||
		    setresuid(u->uid, u->uid, u->uid) < 0)
			_exit(126);
		if (getuid() != u->uid || geteuid() != u->uid || getegid() != u->gid || setuid(0) == 0)
			_exit(126);
	}
	if (chdir("/") < 0)
		_exit(126);
	umask(022);
	signal(SIGPIPE, SIG_DFL);
	{
		int r = fn(arg);

		fflush(stdout);
		_exit(r & 0xff);
	}
}

• The order matters: first the supplementary groups (initgroups), then the group, then the user; after setresuid the group can no longer be changed.
• The child checks that it can not become root again: if setuid(0) succeeded, the identity would not really have been assumed. Any anomaly ends with exit code 126, which the parent turns into an error.
• After the identity change the kernel makes the process non-inspectable by the user (not «dumpable»): U cannot read its memory while it works.
• In test mode, without root, the child keeps the identity of whoever runs the test.

7.3 · Time limits and results

The child runs with the user's identity, so the user can stop it (SIGSTOP) or slow it down. rspeak must not hang: the time limit applies both while the child is writing and afterwards, until it exits.

The pipes are created with O_CLOEXEC; the child's stdin is written in non-blocking mode, alternating with reading the output via poll (at most one second per round), so a child that does not read does not block the parent. gcc's static analysis found pipes left open in an error path of as_user: fixed (chapter 20.7).

7.4 · Operations on the mailboxes

All operations on the mailboxes are functions in src/store.c that run inside the child. They are small on purpose: each does one thing, with paths built from the message number.

8.1 · Options and text

cmd_send in src/rspeak.c checks everything it can check before writing to the message store: options, text, expiry, recipients. An error at this stage ends with die and leaves nothing behind.

• Options end at the first argument that is not an option: from there on the arguments, joined by a space, are the text. Without text and without --file the text is read from stdin (at most 64 MiB).
• An unknown option (“unknown option: --level”) or one without a value (“missing value for --to”) ends at once. --level belonged to version 0.1.0 and is rejected (tests/engine.sh, group 3).
• A duration is a number followed by m, h or d; everything else is interpreted by date -d … +%s in a child process (for example "2026-10-04 12:00"). Dates in words are those understood by date, in English.
• Trailing newlines are removed from the text, which is then cleaned (chapter 8.7). A text made only of spaces is an “empty message”; beyond 65536 bytes, after cleaning, it is a “message too long”: the desktop dialog receives the text as an argument to zenity, and Linux does not accept an argument larger than 128 KiB.

8.2 · The sending sequence

After the checks, sending is a fixed sequence. The order is chosen so that every interruption leaves a state that the next command can recognise and repair.

admin@server:~$ sudo rspeak send --to @developers --title Maintenance --expires 1d \
    "On Saturday from 8 am to 12 noon the server will be off for disk maintenance."
Message 12 sent to 2 users.

8.3 · Verified delivery

“Delivered” means that the copy was in the mailbox, verified, at the time of delivery. deliver_copy in src/store.c writes and checks in the same child process; only if it succeeds does rspeak send record the line in delivery.

• Root prepares only users/U (chapter 7.1); the subfolders and the copy are written by the child with U's identity.
• If the message is already in read/ or acks/ the copy is not rewritten: recovery does not present again to a user a message already read or confirmed (tests/engine.sh, group 2).
• The copy is born as inbox/ID.tmp and becomes inbox/ID through a rename: rootspeak-user, which lists only names made of digits, never sees a half-written file.
• A failure for one recipient (mailbox not writable, link to /etc, timeout) does not stop the others: the event NOT_DELIVERED goes to the log and sending continues (scenario F1).

8.4 · Writing to the terminals

For each terminal from user_terminals (chapter 6.3), rspeak send writes the formatted text, in English whatever the language of the session. Writing to the terminal does not count as confirmation: the question comes at the next prompt.

── RootSpeak · Message from the administrator · Maintenance · 30/09 16:55 ──
On Saturday from 8 am to 12 noon the server will be off for disk maintenance.
────────────────────────────────────────

8.5 · Waking or starting the agent

After the copy, wake_agent makes the dialog appear on the desktop at once, without waiting for the agent's periodic check. If the user has no graphical session (or in test mode) it does nothing.

• The signal goes only to a ready agent: the PID written in /run/user/UID/rootspeak-agent.ready (at most 64 bytes, without following links), which the agent writes after it has prepared to receive the signal (chapter 12.2).
• The signal is sent from a child with U's identity, and only if /proc/PID/cmdline is exactly LIBDIR/rootspeak-user followed by agent: it cannot reach other users' processes, nor a process of U that had inherited an old PID.
• If there is no ready agent, systemd-run --user --machine=U@.host --collect --quiet starts one in the systemd user manager, which already knows the graphical environment of the session. If an agent was starting, the new one finds the lock and exits; the one that was starting reads the mailbox anyway on its first round (scenario I8: dialog in about half a second).

8.6 · Recovery

recover runs at the start of almost every command (chapter 4.1) and repairs what an interrupted command left half done: sends, revocations, deletions. It is idempotent: repeating it changes nothing.

• The lock tells a send in progress from an interrupted one: rspeak send holds it for the whole delivery and the kernel releases it when the process dies, even with SIGKILL. Without this rule recovery, started during a long send, delivered in parallel and recorded duplicates (found by the real-world suite; scenarios F3 and F5).
• Copies already recorded are checked again because, after a power failure, a delivery line might be on disk while the copy is not (tests/engine.sh, group 9).
• In the last recorded run on the test machine (scenario F3), an rspeak send killed with SIGKILL after 4 deliveries out of 68 was completed by the next command in less than a second.

8.7 · Cleaning the text

A message's text and title come from an administrator but end up in the users' terminals: they must not be able to move the cursor, change the window title or write to the clipboard. clean_text in src/text.c removes, in three passes, everything a terminal could interpret as a command.

• An OSC sequence without a final BEL is not removed as a sequence: its ESC disappears in pass 2 and the rest remains as harmless text (tests/unit-tests.c).
• Normal UTF-8 text stays intact, including non-breaking spaces (C2 A0).
• clean_text is applied to text and title before they are saved, to what rspeak reads from the mailboxes (chapter 10.2), to the lines of rspeak log and to what the TUI shows of the commands it ran.
• It gives the same result as the bash prototype (sed and tr): the two were compared on 2000 random texts full of sequences and control characters before the prototype was removed. Scenario G2 checks that no ESC reaches the terminal.

9.1 · Revoking: rspeak revoke

rspeak revoke ID revokes a message: whoever has not seen it yet will not see it, open questions and dialogs close by themselves. The revocation takes place at the instant sent/ID/revoked appears: from then on no new delivery, and no confirmation with a later date counts.

• Serialising revocation with sending comes from the second review: before, a copy could arrive after the revocation. tests/engine.sh (group 9) checks that rspeak revoke waits for a lock held for 2 seconds; scenario F7 revokes a send to many users while it is in progress, and no copy is left behind.
• If the revocation arrives during the send, rspeak send ends with “Message N revoked while sending: delivery stopped.”: the recipients not yet reached stay sent.
• The question in the terminal and the dialog check inbox/ID every second and close (scenarios E3 and I6); a confirmation that arrives between their last check and the revocation does not count, because its date is later than revoked (chapter 13.1).

9.2 · Reminding: rspeak remind

rspeak remind ID brings the question back at once to those who have not confirmed yet, even if they had postponed it. It rewrites nothing: it removes the postponements and wakes the agent.

• A revoked or expired message cannot be reminded: “message N has been revoked: nobody to remind” (tests/engine.sh, group 10).
• The recipients' state comes from recipients, the same function used by rspeak status: the reminder goes to those who are delivered. Those who are sent do not have the copy (recovery will complete it), those who have confirmed must not be disturbed. If everyone has already confirmed, the command says so (“Message N: everyone has already confirmed, nobody to remind.”) instead of “0 recipients reminded”, which looked like a fault in the first live test (tests/engine.sh, group 10).
• For each of them, as the user, state/ID.term and state/ID.gui are removed; then wake_agent. The question comes back at the next prompt (scenario D5); the dialog reappears at once (scenario I11: 0.37 s in the last recorded run).
• The reminder takes no lock: if a confirmation arrives in the meantime, removing the postponements of someone who has confirmed has no effect (chapter 19.4).

admin@server:~$ sudo rspeak remind 12
Message 12: 3 recipients reminded.

9.3 · Deleting: rspeak purge

rspeak purge DURATION deletes the messages sent more than DURATION ago, together with the copies, confirmations and postponements in the mailboxes. The events stay in the journal.

• The rename is the point at which the message stops existing for all commands: list_numbers sees only names made of digits. rspeak list reads what it needs from each message before using it and skips a message that has disappeared in the meantime (summarise returns false).
• A deletion interrupted after the rename is completed by the recovery of the next command (tests/engine.sh, group 9).
• rspeak purge does not run recovery before itself: it skips incomplete sends anyway.

admin@server:~$ sudo rspeak purge 90d
Deleted 4 messages older than 90d.

10.1 · The state deduced from the files

A recipient's state is not written anywhere: recipient_state in src/rspeak.c deduces it every time from sent/ID/delivery, from the confirmation in the mailbox and from the reference copy. The expiry and revocation that count are root's, not those of the copy, which the user might have altered.

• The date of the confirmation is the number before the space in acks/ID (0 if it is not a number); the rest of the line is the channel, stored as it is shown (“terminal pts/2”, “desktop”; channel_text).
• A confirmation with the same date as the revocation counts; one from the second after does not (tests/engine.sh, group 9).
• A recipient is in exactly one of the three states: the function returns a value of state_e (SENT, DELIVERED, CONFIRMED) plus, separately, if the confirmation was late, its date and channel.

10.2 · Reading the mailboxes

rspeak status and rspeak list read the confirmations from the mailboxes, which the users control. read_mailbox in src/store.c treats them as untrusted data and reads them once per user, in a single child process.

• The child receives on stdin the numbers of the messages that exist in sent/ and looks only for those: thousands of fake files in acks/ do not matter (5000 files: rspeak list under a second, tests/engine.sh group 9; before the fix, 3.9 s).
• Of acks/ID it reads at most 200 bytes, and only if it is a regular file opened without blocking: a pipe in place of the confirmation does not block rspeak status (group 9).
• Of state/ID.* it reads the most recent modification date: that is the time of the postponement.
• The child's output (at most 4 MiB) goes through clean_text before it is interpreted: a confirmation forged with escape sequences does not reach the administrator's terminal (scenario G3).
• The mailboxes read stay in memory for the whole command; the TUI forgets them at every refresh (mailboxes_empty). Deliveries are read once per message (read_deliveries).

10.3 · A message's summary

In the list of messages, in rspeak list and in the TUI, a message is summarised by its recipients: how many are in each of the three states, in words and with a bar, plus the properties revoked and expired. No other word describes the state of a message (chapter 19.3).

/* A message summarised with its recipients. */
typedef struct {
	long long id;
	msg_t m;
	int confirmed, delivered, sent;
	bool revoked, expired;
} summary_t;

10.4 · rspeak list and rspeak status

The two query commands show the same state at two levels: the list of messages and the detail of one. Both run recovery first; after that, only reads, without locks.

admin@server:~$ sudo rspeak list
ID    DATE         TEXT                                      RECIPIENTS
1     01/10 10:49  Tonight at 11 pm the mail server is upda  all confirmed (3)
2     01/10 10:49  On Saturday from 8 am to 12 noon the ser  4 confirmed · 3 delivered · 1 sent
3     01/10 10:49  Your account expires on Friday: please d  1 delivered
4     01/10 10:49  [revoked] Reboot at 1 pm.                 2 delivered

• Columns: ID, sending date (“01/10 10:49”), the first 40 columns of the first line of the text (preceded by [revoked] and [expired]), the summary phrase.
• A cancelled send appears as “[send cancelled: interrupted before it was saved]”: it reports an internal marker, not a state.

admin@server:~$ sudo rspeak status 2
Message 2 · Maintenance · 01/10 10:49 · from root
  │ On Saturday from 8 am to 12 noon the server will be off for disk maintenance.
  │ Please save your work by Friday evening.

USER             STATE
admin            confirmed on 01/10 10:49 (terminal pts/0)
anna             confirmed on 01/10 10:49 (desktop)
dario            sent, not delivered: the copy could not be written (see the log; the next rspeak command will retry)
fabio            confirmed on 01/10 10:49 (desktop)
kora             delivered, postponed on 01/10 10:49
luca             delivered
mario            delivered, postponed on 01/10 10:49
zeno             confirmed on 01/10 10:49 (terminal pts/2)

• Header: number, title and date, sender; then “REVOKED on …” and “EXPIRED” if they apply; then the text, indented.
• One line per recipient, in the order of recipients (alphabetical), with the state line from the previous table; the same lines appear in the TUI's detail view.
• A non-existent or cancelled message ends with an error: “no such message: 99”, “message N was cancelled: sending was interrupted before it was saved”.

Times measured in the last recorded run (scenarios H2 and H3, 10 messages to 58 recipients on the test machine): rspeak list 0.24 s, rspeak status 0.28 s. In the prototype, before reading per user, rspeak list took about 6 s.

11.1 · The shell hooks

Each shell has its own hook, installed where that shell reads it. They all do the same thing: if the mailbox contains messages, they run rootspeak-user prompt, right at login and then before every prompt.

The message text reaches the terminal at send time whatever the shell: root writes it, not the shell (chapter 8.4). dash, ksh and similar shells have no place to hook into before the prompt: the question arrives at the next login, or through the desktop dialog (scenarios K of the test machine). profile.d/rootspeak.sh is written in plain sh because every shell reads it: it hands bash over to rootspeak.bash, leaves zsh to its own hook and asks the others at login.

11.2 · From the hook to the question

__rspeak_prompt() {
	local s=$?
	# A check without external processes: with an empty mailbox it costs nothing.
	if compgen -G "$__RSPEAK_INBOX/[0-9]*" >/dev/null; then
		@LIBDIR@/rootspeak-user prompt
	fi
	return $s
}

• The hook acts only in an interactive shell, if rootspeak-user exists, and once per shell (variable __RSPEAK_HOOK, in fish __rspeak_hook).
• It adds __rspeak_prompt to PROMPT_COMMAND: as an element if it is an array (bash 5.1 and later), at the front if it is a string. It preserves $?: the user's prompt sees the result of their last command.
• The mailbox check uses compgen -G, a bash builtin that starts no processes: with an empty mailbox the prompt costs nothing. zsh does the same with the (N) glob, fish with string match on the names (fish globs have no [0-9]).
• In a login shell it calls rootspeak-user prompt --login straight away: the message appears before the first prompt (scenario C1b: about 0.3 s after login).
• On Debian, interactive non-login shells (the desktop terminals) do not read /etc/profile.d: the hook is also called from /etc/bash.bashrc (chapter 3.3).

11.3 · rootspeak-user prompt

rootspeak-user prompt in src/rootspeak-user.c takes the messages in the mailbox in numeric order. If stdin is not a terminal it does nothing; the confirmation channel is the terminal name (terminal pts/3).

• pending_n lists inbox/ (only names made of digits, and regular files). A message whose confirmation is already present, because of an interruption between the confirmation and the move, goes to read/ without asking; an expired one goes to read/ without a confirmation.
• A message postponed less than RSPEAK_REMIND_MINUTES minutes ago (modification time of state/ID.term) is not asked about: it is counted, and at the end the one-line reminder appears. With --login the postponement does not apply.

mario@server:~$ 
── RootSpeak · Message from the administrator · Maintenance · 01/10 10:49 ──
On Saturday from 8 am to 12 noon the server will be off for disk maintenance.
────────────────────────────────────────
[RootSpeak] Do you confirm you have read the message? [y/N] y
[RootSpeak] Confirmed.
mario@server:~$ 

11.4 · The question and the wait

ask waits for the answer on /dev/tty with poll, one second at a time, then reads it with read. At every second without an answer it checks the mailbox: if the confirmation has appeared, the user confirmed elsewhere; if the message has disappeared, it was revoked; if it has expired, the question stops.

• The terminal stays in canonical mode: whatever the user is typing stays in the terminal's buffer and is not lost from one second to the next.
• The question closes within about a second: confirmation from another session (scenario C4b, 0.95 s), revocation (scenario E3, 1.0 s), expiry (tests/engine.sh, group 4).
• Without /dev/tty (no controlling terminal) the answer counts as “no”: the message stays and comes back later.
• Only the first character of the answer is checked: only y and Y mean yes. RootSpeak speaks English, whatever the language of the session.

12.1 · The agent's loop

The agent, rootspeak-user agent, starts with the desktop's autostart (/etc/xdg/autostart/rootspeak-agent.desktop) or from systemd-run when rspeak send does not find one, and lives as long as the graphical session.

• Only one agent per user: flock(LOCK_EX | LOCK_NB) on $XDG_RUNTIME_DIR/rootspeak-agent.lock; if the lock is taken the agent exits at once, without an error. The descriptor is opened with O_CLOEXEC and is not passed on to zenity: otherwise, if the agent died, one of its orphaned dialogs would hold the lock and the agent started in its place would exit at once (a defect found by the test VM).
• Ready: after taking the lock the agent writes its PID to $XDG_RUNTIME_DIR/rootspeak-agent.ready and deletes it on exit (atexit). rspeak send wakes only that PID (chapter 8.5).
• Lives as long as the session: the loop goes on as long as graphical_session(getuid()) finds an X11 or Wayland session of the user, or until a termination signal arrives.
• Configuration always current: conf_read at every round; a change to RSPEAK_REMIND_MINUTES or RSPEAK_AGENT_POLL applies from the next round.
• One dialog at a time: the messages not postponed on the desktop channel (state/ID.gui), oldest first (scenario I7).

12.2 · Signals and waits without losses

The agent must react to three things: a new message (SIGUSR1 from rspeak send), the end of the session (SIGTERM from logind) and the closing of the dialog (SIGCHLD). It handles them without losing signals and without interrupting a confirmation halfway.

• The five signals stay blocked with sigprocmask all the time, except during the waits, done with ppoll, which unblocks and re-blocks them atomically: a signal that arrives while the agent is working stays pending and interrupts the next wait.
• Each wait lasts at most one second; the one between two rounds lasts RSPEAK_AGENT_POLL seconds (60) in total, and ends earlier if a wake-up or termination arrives. The periodic check stays as a safety net: a lost signal delays the dialog, it does not lose it.
• The wake-up clears its flag at the start of the round: a wake-up that arrives while a dialog is open makes the next round start at once.

12.3 · The confirmation dialog

show_dialog starts zenity --question --no-markup --width=460 with title, text and buttons in English, whatever the language of the session, and waits for it to finish, checking the mailbox every second as well.

• --no-markup: the message text is not interpreted as zenity markup. The text has already been cleaned at send time (chapter 8.7).
• The child that becomes zenity restores the signal mask and handlers before exec: zenity does not inherit the agent's blocked signals.
• The end of zenity interrupts the wait at once (SIGCHLD): the answer is recorded within a few milliseconds, so an rspeak remind arriving right after a “Later” finds the postponement already written and removes it (scenario I11; with a check once a second, the VM had found the reminder lost).
• The wake-up signal does not close the dialog: the agent keeps waiting for it. In the bash prototype the signal interrupted wait and the agent took the dialog as closed, recording a postponement never chosen (test VM, scenario I7).
• When the session ends the agent waits for the dialog at most 2 seconds, then closes it: a confirmation already given is not lost (scenario I10: logout as soon as zenity has exited with the answer, confirmation recorded).
• After an exit 1 the agent tells “Later” from a lost display: the session must still be there for logind (not closing) and the display socket ($WAYLAND_DISPLAY or /tmp/.X11-unix/XN) must accept a connection. Otherwise nothing is recorded and the dialog comes back at the next login (scenario I13). Until 1 October 2026 the end of the session was recorded as a postponement, and the dialog came back only after RSPEAK_REMIND_MINUTES: the tests on Ubuntu, Fedora with KDE Plasma and Cinnamon found it.
• Timings of the last run recorded in the VM: dialog after sending 0.58 s (I1), closing after a confirmation from the terminal 0.65 s (I5), after a revocation 0.67 s (I6), at graphical login 2.64 s after the login manager restart (I9).

12.4 · The error notification

The agent uses notify-send, if it is installed, for one case only: telling the user that their confirmation has not been recorded (disk full, permissions). The text is fixed: no message content goes through notifications, which may disappear by themselves or be ignored.

13.1 · The first one counts

confirm(ID, CHANNEL) in src/rootspeak-user.c is the only place where a confirmation is born. It writes it to a temporary file, flushes it to disk and publishes it with link, which fails if acks/ID already exists: the confirmation is born whole or not at all, and “already confirmed” stays distinct from “write failed”.

static int confirm(long long id, const char *channel)
{
	if (exists(ack)) { mark_read(id); return 0; }          /* the first one counts */
	if (!has_entry("inbox", id, "")) return 3;             /* revoked: no confirmation */
	if (expired(id)) { mark_read(id); return 2; }
	fd = open(tmp, O_WRONLY | O_CREAT | O_EXCL | O_CLOEXEC | O_NOFOLLOW, 0644);
	if (fd < 0 || n <= 0 || write_all(fd, line, (size_t)n) < 0 || fsync(fd) < 0 || close(fd) < 0 ||
	    link(tmp, ack) < 0) {                              /* link fails if acks/ID exists */
		unlink(tmp);
		if (exists(ack)) { mark_read(id); return 0; }  /* another confirmation came first */
		event("CONFIRMATION_FAILED", id, U, channel, err, "");
		return 1;                                      /* the message stays in the mailbox */
	}
	unlink(tmp);
	sync_path(dir);                                        /* on disk before “Confirmed” */
	mark_read(id);
	event("CONFIRMED", id, U, channel, "", "");
	return 0;
}

• The line is date channel: seconds since the Unix epoch, a space, the channel as it is shown (desktop, terminal pts/3, terminal tty3).
• The temporary file acks/.ID.PID starts with a dot: it is never mistaken for a confirmation. If an interruption leaves it behind, it is ignored.
• If the revocation arrives between the check of inbox/ID and link, the confirmation is born, but rspeak status does not count it: its date is later than sent/ID/revoked (chapter 10.1).
• mark_read renames inbox/ID to read/ID and removes the postponements. If it is interrupted between the confirmation and the move, whoever reads the mailbox next completes the move without asking again (tests/engine.sh, group 1).

13.2 · Two simultaneous confirmations

A user may have the dialog open on the desktop and the question in two terminals. The confirmation must be one: the first to arrive.

• Two almost simultaneous confirmations produce a single record: link succeeds only once; the other finds acks/ID and only moves the message.
• The questions and dialogs still open notice it at their next check (within a second) and close: “[RootSpeak] Message already confirmed elsewhere (for example on the desktop).” in the terminal, while the dialog closes by itself (scenarios C4b and I5).
• This rule came from a live test of the prototype: the user had to confirm twice, from the dialog and from the terminal.

13.3 · The confirmations read by root

rspeak status reads the confirmations from the mailbox, which the user controls. That is why it treats them as untrusted data, and their meaning is deliberately limited.

14.1 · Architecture: same data, same commands

rspeak without arguments, with stdin and stdout on a terminal of at least 80 × 20, opens the TUI of src/tui.c after recovery; in a pipe, or on a smaller terminal, it shows the help. The TUI has no way of its own of doing things and no states of its own: it reads the store with the functions of rspeak list and rspeak status, and every action is the command itself.

• Same functions for reading: the list uses summarise (the recipients counted in the three states, revoked and expired), the detail uses recipients (the same line as rspeak status).
• The actions are the commands: sending, revoking, reminding and purging run in a child process that calls cmd_send, cmd_revoke, cmd_remind, cmd_purge with stdout and stderr collected on a pipe and shown in a window. An error of the command (die) ends only the child; the child's exit status gives the result. The recipients preview and the history (cmd_log) also come from a child.
• The decision of the user who wanted the TUI is also a design constraint: while discussing the previews, invented states had appeared (“pending”, “complete”, “incomplete”, “cancelled”) and were removed; tests/tui.py checks that none of these words appears on the screen.

14.2 · The list

The list shows the messages from the most recent, one per row, with the recipients summary: a three-colour bar and a phrase. It refreshes by itself every 3 seconds.

┌─ RootSpeak · sent messages ──────────────────────────────────────────────────────────────── updated at 11:20:20 ─┐
│                                                                                                                  │
│   ID  DATE         MESSAGE                              RECIPIENTS                                               │
│    4  01/10 11:20  [revoked] Reboot · Reboot at 1 pm.   ▒▒▒▒▒▒▒▒▒▒▒▒  2 delivered                                │
│    3  01/10 11:20  Your account expires on Friday: ple  ▒▒▒▒▒▒▒▒▒▒▒▒  1 delivered                                │
│ >  2  01/10 11:20  Maintenance · On Saturday from 8 am  ██████▒▒▒▒▒░  4 confirmed · 3 delivered · 1 sent         │
│    1  01/10 11:20  Server update · Tonight at 11 pm th  ████████████  all confirmed (3)                          │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│ █ confirmed   ▒ delivered   ░ sent                                                                               │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Enter open   n new   r revoke   m remind   p purge   / search   ? keys   q quit                                  │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

14.3 · The detail and the history

The detail of a message has two tabs: the recipients, with the status line of rspeak status coloured according to the state, and the history, that is the output of rspeak log. It is re-read every 3 seconds and after every action; Esc leaves it.

┌─ Message 2 · Maintenance ────────────────────────────────────────────────────────────────── updated at 11:20:20 ─┐
│  Maintenance · 01/10 11:20 · from root                                                                           │
│  │ On Saturday from 8 am to 12 noon the server will be off for disk maintenance.                                 │
│  │ Please save your work by Friday evening.                                                                      │
│                                                                                                                  │
│   Recipients (8)   History     ██████▒▒▒▒▒░  4 confirmed · 3 delivered · 1 sent                                  │
│                                                                                                                  │
│  USER          STATE                                                                                             │
│  admin         confirmed on 01/10 11:20 (terminal pts/0)                                                         │
│  anna          confirmed on 01/10 11:20 (desktop)                                                                │
│  dario         sent, not delivered: the copy could not be written (see the log; the next rspeak command will ret │
│  fabio         confirmed on 01/10 11:20 (desktop)                                                                │
│  kora          delivered, postponed on 01/10 11:20                                                               │
│  luca          delivered                                                                                         │
│  mario         delivered, postponed on 01/10 11:20                                                               │
│  zeno          confirmed on 01/10 11:20 (terminal pts/2)                                                         │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Tab recipients/history   ↑/↓ scroll   m remind   r revoke   Esc back                                             │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

┌─ Message 2 · Maintenance ────────────────────────────────────────────────────────────────── updated at 11:20:26 ─┐
│  Maintenance · 01/10 11:20 · from root                                                                           │
│  │ On Saturday from 8 am to 12 noon the server will be off for disk maintenance.                                 │
│  │ Please save your work by Friday evening.                                                                      │
│                                                                                                                  │
│   Recipients (8)   History     ██████▒▒▒▒▒░  4 confirmed · 3 delivered · 1 sent                                  │
│                                                                                                                  │
│  2026-10-01 11:20:19  message 2 delivered to admin (terminals written: 0)                                        │
│  2026-10-01 11:20:19  message 2 delivered to anna (terminals written: 0)                                         │
│  2026-10-01 11:20:19  message 2: ERROR, copy for dario not written                                               │
│  2026-10-01 11:20:19  message 2 delivered to fabio (terminals written: 0)                                        │
│  2026-10-01 11:20:19  message 2 delivered to kora (terminals written: 0)                                         │
│  2026-10-01 11:20:19  message 2 delivered to luca (terminals written: 0)                                         │
│  2026-10-01 11:20:19  message 2 delivered to mario (terminals written: 0)                                        │
│  2026-10-01 11:20:19  message 2 delivered to zeno (terminals written: 0)                                         │
│  2026-10-01 11:20:19  message 2 sent by root to: admin anna dario fabio kora luca mario zeno                     │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                            

• The header shows title, date, sender, expiry (“expires on …” or “expired on …”) and revocation (“revoked on …”, in red); then at most six lines of the text, indented.
• The tab row repeats bar and phrase: the summary stays visible while scrolling through the list.
• Colours of the STATE column: green confirmed, yellow delivered, red sent. They are the three states, and only those.
• Keys: Tab switches tab, ↑ ↓ scroll, m and r remind and revoke with the same rules as the list.

14.4 · Writing and sending

The new-message form has four fields: recipients, title, expiry and text. When the recipients field is left, a child performs the same resolution as rspeak send and shows the number of recipients, or the error in red.

┌─ New message ────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                                                  │
│  To         [ @developers                                                              ]  2 recipients           │
│  Title      [ Maintenance                                                              ]  optional, one line     │
│  Expires    [ 2d                                                                       ]  optional: 30m, 2h, 3d  │
│  Text       ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│             │ On Saturday from 8 am to 12 noon the server will be off.                                         │ │
│             │ Please save your work by Friday evening.                                                         │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             └──────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│             97 of 65536 bytes                                                                                    │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Tab next field   Ctrl+E open in the editor   Ctrl+S send   Esc cancel                                            │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

┌─ New message ────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                                                  │
│  To         [ @developers                                                              ]  2 recipients           │
│  Title      [ Maintenance                                                              ]  optional, one line     │
│  Expires    [ 2d                                                                       ]  optional: 30m, 2h, 3d  │
│  Text       ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│             │ On Saturday from 8 am to 12 noon the server will be off.                                         │ │
│             │ Please save your work by Friday evening.                                                         │ │
│             │                                                                                                  │ │
│                           ┌─ Send the message? ──────────────────────────────────────┐                           │
│                           │                                                          │                           │
│                           │  To: @developers (2 recipients)                          │                           │
│                           │  Title: Maintenance                                      │                           │
│                           │  Expires: 2d                                             │                           │
│                           │  Text: 97 bytes                                          │                           │
│                           │                                                          │                           │
│                           │   y  Confirm       n  Cancel                             │                           │
│                           └──────────────────────────────────────────────────────────┘                           │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             │                                                                                                  │ │
│             └──────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│             97 of 65536 bytes                                                                                    │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ y confirm   n or Esc cancel                                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

• One-line fields accept at most 1000 bytes; the text shows the count “97 of 65536 bytes”. The real checks are those of rspeak send: an error arrives in the result window, “Sending result”.
• Editor: Ctrl+E writes the text to a temporary file in /tmp (mkstemp), hands it over to the administrator in SUDO_USER and opens VISUAL, EDITOR, nano or vi with their identity, not as root; then it re-reads the file (at most twice the maximum length, without following links) and deletes it.
• After sending, the list reloads and the new message appears at the top (tests/tui.py).

14.5 · The actions with confirmation

Revoking, reminding and purging always ask for a confirmation that describes the action with the real numbers; the result of the command then appears in a window.

┌─ RootSpeak · sent messages ──────────────────────────────────────────────────────────────── updated at 11:20:26 ─┐
│                                                                                                                  │
│   ID  DATE         MESSAGE                              RECIPIENTS                                               │
│    4  01/10 11:20  [revoked] Reboot · Reboot at 1 pm.   ▒▒▒▒▒▒▒▒▒▒▒▒  2 delivered                                │
│    3  01/10 11:20  Your account expires on Friday: ple  ▒▒▒▒▒▒▒▒▒▒▒▒  1 delivered                                │
│ >  2  01/10 11:20  Maintenance · On Saturday from 8 am  ██████▒▒▒▒▒░  4 confirmed · 3 delivered · 1 sent         │
│    1  01/10 11:20  Server update · Tonight at 11 pm th  ████████████  all confirmed (3)                          │
│                                                                                                                  │
│                                                                                                                  │
│                           ┌─ Remind message 2? ──────────────────────────────────────┐                           │
│                           │                                                          │                           │
│                           │  3 recipients have not confirmed yet.                    │                           │
│                           │                                                          │                           │
│                           │  They are asked again now: at the next prompt            │                           │
│                           │  and with the dialog on the desktop.                     │                           │
│                           │                                                          │                           │
│                           │   y  Confirm       n  Cancel                             │                           │
│                           └──────────────────────────────────────────────────────────┘                           │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│                                                                                                                  │
│ █ confirmed   ▒ delivered   ░ sent                                                                               │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ y confirm   n or Esc cancel                                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Windows and confirmations are drawn on a copy of the base screen: a later window does not stay on top of the previous one. y confirms, n or Esc cancels.

14.6 · Terminal, keys and refresh

15.1 · A single source

The built-in help of rspeak --help is modelled on that of MTERM: no system manual pages, but a tabbed help in the terminal. Its texts live in src/help.c, in English, as "label¦description" items, one array per group, and are shown as they are.

The manual generator reads the items straight from the arrays of src/help.c (help_items in docs/sources/build.py), in code order, and builds from them the user manual's reference, with the data-help attribute on every entry; tools/check-docs.py reads src/help.c again at check time and verifies that commands and options match the manual, word for word (chapter 20.5).

15.2 · The three forms

rspeak_help chooses the form according to where the output goes. All three have the same content.

• Colours are turned off with NO_COLOR; PAGER and NO_COLOR reach rspeak only if sudo preserves them (env_keep in sudoers): the help says so in the ENVIRONMENT section.
• The help too requires root: rspeak --help re-runs itself with sudo like every other command (chapter 4.1). It is the user's decision, at the cost of asking for the password even for the help.
• rspeak on its own in a pipe shows the help as plain text (tests/tui.py).

admin@server:~$ sudo rspeak --help | head -5
RSPEAK(1)                        rspeak manual                         RSPEAK(1)

NAME
       rspeak — sends messages to the users of the machine and tracks their read
       confirmation

15.3 · The tabbed help

tests/help-tui.py opens the help on a 100 × 30 pseudo-terminal, presses keys like a person and checks every screen: opening and frame, tab switching with arrow and digit, end and start of a tab, resizing to 70 × 20, clean exit, and the page with the pager on a 40 × 8 terminal (chapter 20.4).

16.1 · The trust model

Administrators are trusted: they can already do anything on the machine, and RootSpeak does not protect them from themselves. Users are not trusted: they control their own mailbox and their own terminals, and they can write to the journal. Everything that goes from root to a user, or comes back from a user to root, crosses a controlled boundary.

16.2 · Risks and countermeasures

16.3 · Compiler hardening

A root program in C that reads user data must not have memory errors. Besides the coding rules (buf_t for every text that comes from outside, no variable-length arrays, O_CLOEXEC everywhere), the code is compiled with the hardening that gcc and the linker offer.

• Fuzzing with libFuzzer (tests/fuzz/) exercises, with AddressSanitizer and UBSan, everything that reads untrusted data, with 4 targets: text cleaning, message format, the output of mailbox reading, configuration.
• The choice of C, rather than a language that avoids memory errors by construction, is the owner's: the hardening in this table is the condition under which it was made (chapter 21.3).

17.1 · Structured events in the journal

Every relevant fact in the life of a message becomes a structured event in the system journal. The log answers a different question from rspeak status: not “where does it stand” but “what happened, when, and by whose hand”.

• event(EV, ID, USER, CHANNEL, DETAILS, AUTHOR) in src/event.c writes with sd_journal_send a readable text (MESSAGE) and the structured fields. If the journal does not respond, it writes at least the text with syslog.
• The readable text is in English, whatever the language of the system; rspeak log rewrites it from the fields with the same function, event_text.
• The details fit on a single line: line breaks become spaces.
• The log is the history, not the state: states are always derived from the message store, never from the journal (chapter 19.1). Retention of the events follows the journal's rules, not those of RootSpeak: rspeak purge does not touch them.

17.2 · The fields of an event

For an audit, journalctl RSPEAK_MESSAGE=12 -o verbose shows all the fields, _UID included; journalctl -t rspeak shows the text of all RootSpeak events.

17.3 · The events

17.4 · rspeak log and trustworthiness

rspeak log ID reconstructs the history of a message from the events; the History tab of the TUI shows the same output.

• Events are searched with two conditions together: SYSLOG_IDENTIFIER=rspeak and RSPEAK_MESSAGE=ID, and only from the sending date of the message (minus one second): a message store that has been reset reuses the numbers, the journal does not.
• Anyone can write an event with the RSPEAK_* fields to the journal: _UID says who wrote it, not that it is true. rspeak log expects root (in test mode, whoever runs it) for the administrator's events and the recipient themselves for POSTPONED, CONFIRMED and CONFIRMATION_FAILED; if _UID differs, the line begins with “[not trustworthy: written by UID N]” (scenario J3).
• An event with an unknown name is shown with its MESSAGE; every line goes through clean_text before it reaches the terminal.

admin@server:~$ sudo rspeak log 1
Message 1 · Maintenance · 30/09 20:42
2026-09-30 20:42:25  message 1 delivered to mario (terminals written: 1)
2026-09-30 20:42:25  message 1 delivered to anna (terminals written: 0)
2026-09-30 20:42:25  message 1 sent by admin to: anna mario
2026-09-30 20:43:02  user mario: confirmed reading message 1 (terminal pts/2)

18.1 · Three families of errors

RootSpeak distinguishes three families of errors. Those that can be detected before writing stop the command without leaving traces; those that happen during the work do not stop the other recipients and leave a mark; interruptions leave a state that the next command knows how to repair.

• rootspeak-user does not use die in normal work: it runs inside the prompt or in the graphical session, and every problem it meets becomes “do nothing” or a notice to the user (chapter 11.3).
• In the TUI a die of the command closes only the child process: its message appears in the result dialog (chapter 14.1).

18.2 · The errors of rspeak

admin@server:~$ sudo rspeak send --to nobodyhere "Test"
rspeak: no such user: nobodyhere
admin@server:~$ sudo rspeak purge 7x
rspeak: invalid duration: 7x (for example 90d, 12h, 30m)

18.3 · Internal results

Inside RootSpeak the functions talk to each other through numeric results. They are the contract between the parts, and the chapters that describe them use them with these values.

18.4 · Recovery warnings and exit status

The warnings appear at the start of any command that runs recovery, even one that has nothing to do with that message: rspeak list can therefore say “rspeak: completed delivery of message 2 to 64 recipients” (scenario F3). The command then carries on normally.

19.1 · Authoritative sources

This chapter is the contract of RootSpeak: what any implementation must respect, regardless of how it is written. The rest of the manual describes how the C version implements it; the bash prototype (0.1.0) worked on the same message store, and the same tests apply to both. Every change to the code respects this chapter or updates it explicitly.

• A confirmation is a fact declared by the user in their own mailbox; it is valid only if it does not contradict root's message store: its date must not be later than the expiry written in sent/ID/msg nor than the revocation (sent/ID/revoked).
• “Confirmed” means: the mailbox contains a valid read statement from the user. It is not an action observed by RootSpeak, nor proof of reading: the user controls their own mailbox and could write it themselves. Anyone using rspeak status for an audit must read it this way.
• If the user deletes their own copy, the message simply shows as not confirmed; if they alter it (text, expiry), only what they see changes.

19.2 · States and transitions

Each recipient of a message is in one of three states; the state is derived from the files, according to fixed rules (chapter 10.1). There are only these three states (the owner's decision): revocation and expiry are properties of the message, not states; incomplete, failed, revoking and .deleting-ID are internal marks with which recovery completes or cancels an interrupted operation, and they are not shown as states. An interrupted sending shows for itself: some recipients stay sent.

19.3 · How a message is summarised

In the message list (TUI and rspeak list) a message is summarised by its recipients: how many are in each of the three states, in words and with a bar (confirmed, delivered, sent), plus the properties revoked and expired. No other word describes the state of a message.

• The phrase leaves out zero counts; if everyone has confirmed it says “all confirmed (N)”.
• Words such as “pending”, “complete”, “incomplete sending”, “cancelled” are not states and do not appear: tests/engine.sh (group 3) and tests/tui.py check this.
• A sending cancelled before it was saved has no recipients to count: rspeak list reports it with a warning line, the TUI does not show it (chapter 10.4).

19.4 · Concurrent operations

For each command that changes the message store: which lock it holds, at which instant the operation is considered to have happened (the linearisation point: before that instant it has not happened, after it has, for any observer) and what happens with other commands at the same time.

19.5 · Invariants

19.6 · Interruptions and recovery

For each point at which a process can be interrupted, the state that remains and who repairs it.

19.7 · Time, revocation and expiry

19.8 · Message store format

Message store format 1. Readers ignore header keys they do not know.

19.9 · Supported and verified scope

Supported means that the requirements are met and RootSpeak is designed to work; verified that it has been tested, and how. The two are distinct.

20.1 · The tests and their results

Every statement about how RootSpeak behaves comes from a run. The tests are organised in levels: at the bottom the internal parts and the engine, fast and without root; at the top the test machine and the VM, where RootSpeak runs as root with real users, sessions and dialogs.

Test figures are never written by hand: each suite records its result together with the commit and the fingerprint of the code under test (tools/fingerprint.sh: SHA-256 of src/, Makefile, etc/ and install.sh), and this table reads them every time the manual is generated. “Valid for the current code” says whether the recorded fingerprint is that of the code this manual describes.

20.2 · The engine: tests/engine.sh

tests/engine.sh tests the engine in test mode, without root, on a fresh temporary message store for each case, with the programs in build/ (or in RSPEAK_BUILD, for example the sanitizer build). Every defect that gets fixed adds checks that fail without the fix.

At the end tests/engine.sh writes tests/results/engine.json with date, commit, fingerprint and counts; tools/check-docs.py fails if that fingerprint is not the one of the current code. tests/unit-tests.c (make unit) tests the internal parts one by one: text cleaning, messages, configuration, event texts.

20.3 · For real: the test machine and the VM

tests/container/run.sh tests RootSpeak for real in an isolated test machine: a Debian 13 container with systemd running (logind, sshd), without root on the host system. RootSpeak is built there and installed with install.sh; the users are admin (group sudo), mario and anna (group developers), luca, service (without a shell) and four users with other shells: zeno (zsh), fabio (fish), kora (ksh), dario (dash). scenarios.py runs as root, opens real ssh sessions with a terminal, answers the questions as a person would, measures the timings and records every result.

tests/vm/run.sh runs the same scenarios in a virtual machine with a desktop, on the test server (QEMU with KVM, without root or libvirt), plus the dialog scenarios. Each desktop is a profile in tests/vm/desktops/: the cloud image of its distribution, the packages of the desktop, the automatic login of sara (GDM, SDDM or LightDM) and the accessibility settings. prepare.sh builds the base disk of a profile once with cloud-init (users.sh adds the users), and again when the profile changes; each run starts from a clean copy of it, builds RootSpeak in the VM and puts the system and the desktop in Italian. The dialog buttons are pressed through the desktop's accessibility (desktop.py, AT-SPI), as a person would, and the screenshots come from the QEMU monitor (capture.py).

Cinnamon is tested on Ubuntu 24.04, the base of Linux Mint 22, because Mint publishes no cloud image; Rocky Linux 9 runs with SELinux enforcing, as RHEL ships it. The measurements of each run are in tests/vm/results/report.md (Debian) and in tests/vm/desktops/results/.

• RSPEAK_TEST_ONLY=i_desktop runs only the desktop scenarios.
• Each run writes results.json and report.md to tests/container/results/ and tests/vm/results/, with the measurements of every scenario.

20.4 · On other distributions: tests/distros

tests/distros/run.sh runs the same real-world scenarios on every distribution listed in tests/distros/list: the families of Debian and Ubuntu, Fedora, RHEL and its rebuilds (CentOS Stream, Rocky, Alma, Oracle; RHEL itself through its free UBI images), SUSE (openSUSE and SLES) and Arch. Only distributions with systemd: RootSpeak relies on logind and systemd-run.

Each distribution gets its own image, built from the official image of the distribution by the same tests/container/Containerfile with tests/container/setup.sh: the package manager tells the family, and the script installs the compiler, sshd, the shells and the test users. The administrators' group is the one of the distribution (sudo or wheel). RootSpeak is then built inside the machine, with the compiler and the libraries of that distribution, and installed with install.sh, as a customer would. The images carry the fingerprint of the preparation: a change to setup.sh builds them again.

A shell that a distribution does not package (ksh on Arch, or the shells missing from the limited repositories of RHEL's UBI images) is “not tested”, not failed; so is a login shell that already stops on the distribution's own files before reaching RootSpeak (dash on Fedora and RHEL: /etc/profile.d/lang.sh is not POSIX).

• The runs go on the test server (192.168.0.2), four distributions at a time (RSPEAK_PARALLEL); the images live in /media/ROOTSPEAK/distros/storage, on the SSD, because the server's / is in RAM.
• tests/distros/run.sh fedora-44 arch runs only some of them; the results are in tests/distros/results/ (summary.md, and the report.md of each one).
• The desktop of other distributions is tested in a VM (tests/vm), not here.

20.5 · The interfaces: tests/tui.py and tests/help-tui.py

The two full-screen interfaces are tested on a pseudo-terminal, pressing keys as a person would and checking the last screen drawn after each one.

tools/tui-screenshots.sh uses the test machine to capture the real TUI screens shown in chapter 14: the colours are the ones the administrator sees.

20.6 · The documentation: tools/check-docs.py