Chapter 1
Welcome
1.1 · What RootSpeak is
RootSpeak — Advanced Messaging System for Linux lets whoever administers a Linux machine send a message to the users and know, for each of them, whether they have confirmed reading it. It is meant for the notices that matter: maintenance, a reboot, a new rule, an account about to expire.
The administrator writes the message in the full-screen interface of rspeak or with a command. RootSpeak delivers it wherever the user is: in terminal windows (including ssh connections), on the desktop, or at the next login if the user is not logged in at that moment. The user confirms with a click or a single letter, and the administrator sees who has confirmed, when and from where.
For administrators, RootSpeak offers a single place in which to:
- write a message and send it to one user, to a group, to everyone or only to whoever is logged in;
- see how far each recipient has got: sent, delivered or confirmed;
- remind whoever has not confirmed yet, revoke a mistaken message, give it an expiry;
- find the history of every message in the system log;
- delete old messages when they are no longer needed.
i
What a confirmation says. a confirmation is a statement by the user (“I have read it”), recorded with date, time and channel. RootSpeak cannot know whether the message was really read, and neither can any other messaging system.
1.2 · What it does, and what it does not
wall / write | /etc/motd and banners | RootSpeak | |
|---|---|---|---|
| Writes to the terminals of logged-in users | yes | no | yes |
| Appears on the desktop (X11 and Wayland) | no | no | yes, in a dialog |
| Reaches users who are not logged in | no | yes, at every text login | yes, at the next login |
| Asks for a read confirmation | no | no | yes, for every message |
| Shows the message again to whoever has not confirmed | no | no | yes, every 30 minutes |
| Tells the administrator who has read it | no | no | yes, with date, time and channel |
RootSpeak, on the other hand, does not do these things, by design:
- It never blocks anyone. No locked screen, no denied login, no disconnection: the user can always postpone and carry on working. The message comes back later.
- It is not a chat. Users receive and confirm; they do not reply, do not write to others and have no commands to learn.
- It does not use the network. It reaches the users of this machine, including those connected remotely with ssh, but not other machines.
- It does not disturb automated programs. Backups, cron, copies with
scporrsyncnever see the RootSpeak question: it appears only in interactive shells.
1.3 · Who this manual is for
| Who | What they do with RootSpeak | Chapters |
|---|---|---|
| Administrator of the machine | Installs RootSpeak, sends messages, follows the confirmations, revokes and reminds, changes the settings. | 2 - 7, 9 - 13 |
| Whoever has to explain RootSpeak to the users | Knows what users see in the terminal and on the desktop, and how to answer their questions. | 8 |
| Whoever assesses security | Knows who can use RootSpeak, who sees what and what a confirmation is worth. | 11 |
Anyone using RootSpeak for the first time can follow the guided path in chapter 4, which leads from installation to the first confirmation in a few steps. The users who receive the messages do not need to read anything: the dialog and the question explain themselves, and there is no command for them.
+
Further reading. the inner workings (message store, delivery, security) are described in the Technical Manual, installed next to this one in
/usr/local/share/doc/rootspeak/.1.4 · Conventions
| Convention | Meaning |
|---|---|
| I have read it | Text that appears on the screen: buttons, window titles, fields, RootSpeak messages. RootSpeak speaks English, whatever the language of the user's session. |
rspeak send --to mario | Commands, file names and values to type exactly as shown. |
| Ctrl+S Enter | Keys to press; the + sign means “together”. |
| sent delivered confirmed | The three states of a recipient, always in these colours, the same as in the TUI. |
| revoked expired | Properties of the message, not states of the recipients: from that moment on the message is no longer shown. |
| Blue Note box | Information that helps understanding. |
| Green Tip box | A better or safer way to do something. |
| Yellow Warning box | A behaviour that may be surprising or cause data loss. |
In the examples admin is an administrator; mario, anna and luca are users of the machine server, and @developers is a group. In the dark boxes, lines starting with the prompt (admin@server:~$) are commands to type; orange lines are what RootSpeak shows to the users; red lines are errors. The TUI screenshots are real, taken from RootSpeak while running.
i
Version. this manual describes RootSpeak 0.2.0. The command
rspeak version shows the installed version.!
Always with sudo.
rspeak always works as administrator (root) and asks for the sudo password, even just to show the help: this is a deliberate choice, not a bug.1.5 · Licence
RootSpeak is freeware: it costs nothing, at home or at work, on any number of machines, also when you administer the machines of a company, a school or a customer. The terms are in the RootSpeak Freeware Licence, the file LICENSE published with the programs.
| You may, free of charge | You may not, without a written licence |
|---|---|
| use RootSpeak for anything, also as a tool in paid work | sell it, or charge a fee for it |
| install it on any number of machines, also with your own deployment tools, and change its settings | include it in a product or service that is sold |
| copy it and give it to anyone, unchanged, with the licence | modify it, or decompile it beyond what the law allows |
i
A written licence. to include RootSpeak in a product, or for anything else the licence does not allow, write to rootspeak@nicfio.it.
Chapter 2
Installation and first start
2.1 · Requirements
RootSpeak runs on a Linux distribution with systemd; without systemd it does not work. It is tested automatically, as root and with real users and sessions, on the current versions of Debian, Ubuntu, Fedora, RHEL and its rebuilds (CentOS Stream, Rocky Linux, AlmaLinux, Oracle Linux), openSUSE, SLES and Arch Linux: the list, with the result on each one, is in the technical manual, chapter “Tests and checks”. The desktop dialog has been tested with GNOME (Debian 13, Ubuntu 24.04, Rocky Linux 9 with SELinux), KDE Plasma (Fedora 44) and Cinnamon (the desktop of Linux Mint), on Wayland and on X11.
| Requirement | What it is for |
|---|---|
| systemd | knowing who is logged in and where, and opening the dialog on the desktop |
| sudo and an administrators group | deciding who may use rspeak: the group sudo on Debian and Ubuntu, wheel on the others |
| a shell: bash, zsh or fish | the confirmation question in terminals at every prompt; with sh, dash and ksh only at login |
| zenity | the “I have read it” / “Later” dialog on the desktop |
| notify-send (optional) | the desktop notice when a confirmation could not be recorded |
| a 64-bit PC processor (x86-64) | the programs of the archive are built for it |
| Distribution | Packages to install |
|---|---|
| Debian, Ubuntu | sudo apt install zenity libnotify-bin |
| Fedora, RHEL, CentOS Stream, Rocky, Alma, Oracle | sudo dnf install zenity libnotify |
| openSUSE, SLES | sudo zypper install zenity libnotify-tools |
| Arch Linux | sudo pacman -S zenity libnotify |
admin@server:~$ sudo apt install zenity libnotify-bini
Servers without a desktop. on machines without a desktop zenity and notify-send are not needed: RootSpeak uses only the terminals. The installation reports “Warning: zenity is missing” but carries on.
i
Two shells to know about. on Fedora and RHEL the login shell dash stops on a file of the distribution (
/etc/profile.d/lang.sh) before reaching RootSpeak; on openSUSE the login shell must be /usr/bin/ksh93, not /usr/bin/ksh, which cannot start a login. Both are limits of the distributions, with or without RootSpeak.2.2 · Downloading and installing
RootSpeak is free (chapter 1, “Licence”) and is downloaded from its website, rootspeak.nicfio.it: a single archive, the same for every supported distribution, with the programs already built, the installer, the settings file and the two manuals. Nothing needs to be compiled.
- Download
rootspeak-0.2.0-linux-x86_64.tar.gzandSHA256SUMSfrom the website into the same folder, and check that the archive arrived intact:admin@server:~$ sha256sum -c --ignore-missing SHA256SUMS rootspeak-0.2.0-linux-x86_64.tar.gz: OK - Extract the archive and enter its folder:
admin@server:~$ tar -xzf rootspeak-0.2.0-linux-x86_64.tar.gz admin@server:~$ cd rootspeak-0.2.0-linux-x86_64 - Run the installation: the script restarts itself with sudo and asks for your password. At the end it confirms “RootSpeak installed”, gives the paths of the command (usable by the sudo group) and of the manuals, and reminds you that sessions already open get the messages in the terminal at once, and the confirmation question from the next shell or the next login.
admin@server:~/rootspeak-0.2.0-linux-x86_64$ ./install.sh [sudo] password for admin: RootSpeak installed. Command: /usr/local/bin/rspeak (usable by the sudo group). Manuals: /usr/local/share/doc/rootspeak/User Manual.html and Technical Manual.html Sessions already open get messages in the terminal at once, and the confirmation question from the next shell or the next login. - Check that the command answers:
admin@server:~$ rspeak version RootSpeak - Advanced Messaging System for Linux 0.2.0
+
Keep the folder. keep the extracted folder:
./install.sh --uninstall is run from there (“Upgrading and removing”, below). The archive also contains a short README.txt.i
Users already logged in. users who are already logged in receive messages straight away, on the desktop too. The confirmation question in the terminal, instead, arrives from the next terminal window they open: the ones already open have not loaded RootSpeak yet.
2.3 · What gets installed
The installation puts everything in the usual Linux places. Besides these files it adds a line, marked # RootSpeak hook, at the end of /etc/bash.bashrc and, if zsh is installed, to the system zshrc: this is what makes the question appear in the desktop's terminals.
/usr/local/bin/rspeak # the administrators' command (root:sudo, 750) /usr/local/lib/rootspeak/ # the internal parts ├── rootspeak-user # shows the messages and records the confirmations, as the user ├── rootspeak.bash # bash hook └── rootspeak.zsh # zsh hook /usr/local/share/doc/rootspeak/ # this manual and the technical manual /etc/rootspeak/rootspeak.conf # the settings (not overwritten by an upgrade) /etc/profile.d/rootspeak.sh # shell hook at login /etc/fish/conf.d/rootspeak.fish # fish hook /etc/xdg/autostart/rootspeak-agent.desktop # autostart on the desktop /var/lib/rootspeak/ # messages and confirmations ├── sent/ # the reference copies (root only) └── users/ # one mailbox per user
| Where | What it is | Who uses it |
|---|---|---|
/usr/local/bin/rspeak | The command. Only the administrators group can run it. | administrators |
/usr/local/lib/rootspeak/rootspeak-user | The helper that shows the messages and records the confirmations. It is not a command: users never launch it, it starts on its own. | users' shells and desktops |
/etc/rootspeak/rootspeak.conf | The settings (chapter 10). | everyone, read-only |
/var/lib/rootspeak/ | The messages, the users' mailboxes, the confirmations. | RootSpeak |
/etc/xdg/autostart/rootspeak-agent.desktop | Starts the desktop agent at every graphical login. | the users' desktops |
2.4 · The administrators
The rspeak command belongs to root and to the administrators group the machine already has: sudo on Debian and Ubuntu, wheel on Fedora and similar (failing that, admin or root). RootSpeak has no list of administrators of its own.
admin@server:~$ stat -c '%U:%G %a %n' /usr/local/bin/rspeak
root:sudo 750 /usr/local/bin/rspeak| To | Command | When it takes effect |
|---|---|---|
| give access to RootSpeak | sudo usermod -aG sudo anna | from anna's next login |
| take it away | sudo gpasswd -d anna sudo | from anna's next login |
| find out who can use it | getent group sudo | immediately |
!
A single group. joining the
sudo group means being able to become root on the whole machine, not only to use RootSpeak. This is intended: sending messages to all users is an administrator's task.2.5 · First start
Right after installation it is worth doing three checks, none of which disturbs anyone.
- Open the built-in help:
rspeak --help(chapter 9). Leave it withq. - Check the list of messages: it is empty, because nothing has been sent yet.
admin@server:~$ rspeak list No messages sent. - Open the TUI by typing
rspeakon its own: it shows “No messages sent.” and the keys at the bottom. Leave it withq. - For a complete test, send a message to yourself, as in chapter 4.
+
Try it on yourself. a message sent to yourself shows in a few seconds everything the users will see: the text in the terminal, the question at the prompt, the dialog on the desktop.
2.6 · Upgrading and removing
| To | Command | What happens |
|---|---|---|
| Upgrade | download and extract the new archive, then ./install.sh from its folder | Installs the new version; messages and settings are kept. The desktop agents of the previous version are closed: a new one starts with the first message or at the next login. |
| Remove RootSpeak | ./install.sh --uninstall | Removes the command, the hooks and the manuals; messages (/var/lib/rootspeak) and settings (/etc/rootspeak) are kept, for a possible reinstallation. |
| Remove everything | ./install.sh --purge | As above, and in addition deletes the messages and the settings. |
admin@server:~/rootspeak-0.2.0-linux-x86_64$ ./install.sh --uninstall
RootSpeak removed. Messages (/var/lib/rootspeak) and configuration (/etc/rootspeak) kept.!
Before --purge.
--purge also deletes the record of who confirmed what. If it needs to be kept, copy /var/lib/rootspeak elsewhere first. The events remain in the system log in any case.Chapter 3
RootSpeak at a glance
3.1 · Two ways of working
RootSpeak can be used in two ways, which do exactly the same things. Typed on its own in a terminal, rspeak opens the TUI, a full-screen interface inside the terminal: the list of messages, the state of every recipient, the keys to act. Followed by a command (rspeak send, rspeak status…) it does one single thing and returns to the prompt.
| Situation | Better to use |
|---|---|
| following a message while the confirmations come in | the TUI: it updates itself every 3 seconds |
| writing a long message calmly | the TUI, with your own editor (Ctrl+E) |
| sending a notice from a script or from cron | rspeak send |
| copying the state into a report or an email | rspeak status or rspeak log |
| a small terminal (fewer than 80 columns or 20 lines) | the commands: rspeak on its own shows the help |
i
Same commands. every TUI action runs the corresponding command and shows its answer: what you learn in one way also applies to the other.
3.2 · How the TUI is laid out
The main screen of the TUI is the list of sent messages. All RootSpeak screens have the same frame: the title at the top left, the time of the last update at the top right, the content in the middle and, at the bottom, the line of keys that can be pressed at that moment.
| Part | What it shows | |
|---|---|---|
| 1 | Title | Where you are: RootSpeak · sent messages, Message 2 · Maintenance, New message. |
| 2 | Update | The time at which RootSpeak last reread the message store. It changes every 3 seconds: if it stops, the TUI is no longer receiving updates. |
| 3 | Header | The columns: message number, date and time of sending, title and first line of the text, recipients. |
| 4 | Selected line | In reverse video and preceded by >: the message that Enter, r and m act on. Move it with ↑ ↓. |
| 5 | Recipients | The three-colour bar and the phrase with the recipients in the three states (chapter 3.3). |
| 6 | Legend | The colours of the bar; during a search, also the text searched for. |
| 7 | Keys | What can be done now. It changes with the screen and with the confirmation windows. |
┌─ 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 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘- The messages are sorted newest first.
[revoked]and[expired]before the text mark those that are no longer shown to the users. - In a terminal narrower than 110 columns the phrase gives way to just the count of confirmations out of the total, for example
4/8; the bar stays. - If the terminal becomes smaller than 80 columns or 20 lines while the TUI is open, the TUI closes and the terminal returns to how it was.
- With the
NO_COLORvariable the TUI has no colours (chapter 10.3).
3.3 · The three states of a recipient
There is only one concept you need to know to use RootSpeak: every recipient of every message is in one of three states. There are no others.
| State | What it means | What RootSpeak does |
|---|---|---|
| sent | The message has left, but the copy is not yet in the user's mailbox: usually because it could not be written, for example with a full disk. | Retries by itself the next time rspeak is used: a command such as list or status, or opening the TUI. |
| delivered | The copy is in the user's mailbox: they see it at once if logged in, otherwise at the next login. They have not confirmed yet. | Shows the message to them again until they confirm; if they postpone, it waits 30 minutes. |
| confirmed | The user has stated that they have read it, with a click or by answering y. | No longer shows it to them, in any session. Records date, time and channel. |
revoked and expired, on the other hand, are properties of the message: from that moment on the message is no longer shown or shown again to anyone, and whoever had not confirmed stays delivered, with the indication “not confirmed (revoked)” or “not confirmed (expired)”.
The list summarises each message with its recipients in the three states, in two forms: the bar of 12 coloured marks and the phrase, for example “4 confirmed · 3 delivered · 1 sent”. When everyone has confirmed, the phrase becomes “all confirmed (8)” and the bar is entirely green.
+
What about those who postpone? whoever has postponed is not in a separate state: they stay delivered. The message details say when they last postponed (chapter 6.2).
3.4 · Map of commands and keys
| I want to… | In the TUI | With a command | Where |
|---|---|---|---|
| send a message | n, then Ctrl+S | rspeak send --to … "text" | chapter 5 |
| see all messages | the main screen | rspeak list | chapter 6.1 |
| see who has confirmed | Enter on the message | rspeak status ID | chapter 6.2 |
| see the history of a message | Enter, then Tab | rspeak log ID | chapter 6.4 |
| find a message | / | — | chapter 6.6 |
| revoke a message | r | rspeak revoke ID | chapter 7.1 |
| remind whoever has not confirmed | m | rspeak remind ID | chapter 7.2 |
| delete old messages | p | rspeak purge 90d | chapter 7.3 |
| the list of keys | ? | — | chapter 3.4 |
| the complete help | — | rspeak --help | chapter 9 |
| quit | q | — |
In the TUI the ? key opens the list of keys over the message list; any key closes it. The complete list of commands is in rspeak --help.
┌─ RootSpeak · sent messages ──────────────────────────────────────────────────────────────── updated at 12:49:09 ─┐
│ │
│ ID DATE MESSAGE RECIPIENTS │
│ > 3 01/10 12:49 Your account expires on Friday: ple ▒▒▒▒▒▒▒▒▒▒▒▒ 1 delivered │
│ 2 01/10 12:49 Maintenance · On Saturday from 8 am ██████▒▒▒▒▒▒ 1 confirmed · 1 delivered │
│ 1 01/10 12:49 Server update · Tonight at 11 pm th ████████████ all confirmed (2) │
│ ┌─ Keys ─────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ↑ ↓ PgUp PgDn move through the list │ │
│ │ Enter open the message: recipients and history │ │
│ │ n write and send a new message │ │
│ │ r revoke the selected message │ │
│ │ m remind whoever has not confirmed │ │
│ │ p delete old messages │ │
│ │ / search the messages by text or title │ │
│ │ q quit │ │
│ │ │ │
│ │ The list updates by itself every 3 seconds. │ │
│ │ The complete guide: rspeak --help. │ │
│ │ │ │
│ │ any key to continue │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ │
│ │
│ │
│ █ confirmed ▒ delivered ░ sent │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ any key to continue │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘Chapter 4
First steps
4.1 · The path
This path leads from a freshly installed RootSpeak to the first confirmation, in four stages. The recipient of the first message can be the administrator themselves: that way you see with your own eyes what the users receive. Each stage refers to the chapter that explains it in detail.
4.2 · Sending the first message
The simplest way is the TUI. Here the message goes to Mario; to try it on yourself, just type your own name.
- Open a terminal and type
rspeak. When prompted, enter your password:rspeakalways asks for it, because it works as administrator.admin@server:~$ rspeak [sudo] password for admin: - In the list of messages press n: the New message screen opens.
- In the To field type
marioand press Tab: on the right 1 recipient appears. - In the Title field type
Maintenance; leave Expires empty and move to Text with Tab. - Type the text:
On Saturday from 8 am to 12 noon the server will be off.Start a new line with Enter. - Press Ctrl+S. The summary Send the message? appears: press y to confirm.
- The Message sent window reports the answer of RootSpeak, for example “Message 1 sent to 1 user.” Any key takes you back to the list, where the message is at the top.
The same message, with a single command (same text, same reply):
admin@server:~$ rspeak send --to mario --title Maintenance "On Saturday from 8 am to 12 noon the server will be off."
Message 1 sent to 1 user.+
The number. the message number (here
1) is needed for the commands status, log, revoke and remind. In the TUI it is not needed: you pick the message from the list.4.3 · What the user sees
If Mario is logged in, the message reaches him at once, in all his sessions. On the desktop this dialog appears, above the other windows:
RootSpeak · Message from the administrator
?
Maintenance · 01/10 10:49
On Saturday from 8 am to 12 noon the server will be off.
LaterI have read it
In terminal windows the text appears at once, under the heading “RootSpeak · Message from the administrator”; at the next prompt RootSpeak asks for the confirmation, and after the answer y replies “[RootSpeak] Confirmed.”:
── RootSpeak · Message from the administrator · Maintenance · 01/10 10:49 ──
On Saturday from 8 am to 12 noon the server will be off.
────────────────────────────────────────
[RootSpeak] Do you confirm you have read the message? [y/N] y
[RootSpeak] Confirmed.
mario@server:~$i
One confirmation is enough. confirming once, anywhere, is enough: the dialog closes by itself if Mario answers in the terminal, and vice versa. If Mario is not logged in, he will find the message at his next login. chapter 8 describes everything the users see.
4.4 · Seeing who has read it
In the list the message shows its recipients in the three states: before Mario logs in “1 delivered”, after his confirmation “all confirmed (1)”. With Enter you open the message and see the state of every recipient, with date, time and channel of the confirmation.
The same, with a commandadmin@server:~$ rspeak status 1
Message 1 · Maintenance · 01/10 10:49 · from admin
│ On Saturday from 8 am to 12 noon the server will be off.
USER STATE
mario confirmed on 01/10 10:50 (desktop)| If the state is… | It means | What to do |
|---|---|---|
| delivered | Mario has the copy but has not confirmed yet | wait, or remind him (chapter 7.2) |
| confirmed (desktop) | he pressed I have read it in the dialog | nothing: it is done |
| confirmed (terminal pts/1) | he answered y in a terminal window | nothing: it is done |
+
And then? the TUI updates itself every 3 seconds: keeping it open on the message, you see the confirmations arrive one after another.
Chapter 5
Writing and sending messages
5.1 · Choosing the recipients
The To field of the TUI and the --to option of the commands say who receives the message. Several recipients can be given, separated by commas and without spaces: anyone who appears more than once, for example because they belong to two groups, receives the message only once.
| You write | Who receives it | Example |
|---|---|---|
| a name | that user, even if not logged in | mario |
| several names | each of them | mario,anna,luca |
@group | the members of a system group, including those who have it as their primary group | @developers |
all | every user of the machine, logged in or not: UID of 1000 or above (the limits in /etc/login.defs) and a real shell, that is, not nologin or false | all |
online | among the users of all, whoever is logged in right now, in any way (desktop, console, ssh) | online |
| a combination | the union of all of them | mario,@developers |
i
Good to know. a group given with
@ includes all its members, even the accounts that all leaves out. In the TUI, when you move from the To field to the next one, the number of recipients appears on the right, or an error if a name does not exist: this is checked before sending.!
online is a snapshot.
online is evaluated at the moment of sending: someone who logs in a minute later does not receive the message. For a notice that must reach everyone sooner or later, use all.5.2 · Title and text
The title is optional and fits on one line: it appears at the top of the message in the terminal, in the desktop dialog and in the TUI list. The text can have several lines.
| How | Where | Example |
|---|---|---|
| typed in the TUI | the Text field; Enter starts a new line | — |
| typed in your own editor | TUI, Ctrl+E (chapter 5.5) | — |
| in quotes, at the end of the command | rspeak send | rspeak send --to mario "Message text" |
| from a file | rspeak send --file | rspeak send --to @developers --file notice.txt |
| from another command | rspeak send, with no text and no --file | df -h | rspeak send --to anna |
| typed on the spot | rspeak send in a terminal: type the text, then Ctrl+D | rspeak send --to mario |
From Monday 19 October passwords expire every 90 days.
At the first login after the expiry the system will ask you to change it.
For problems: IT office, extension 214.admin@server:~$ rspeak send --to all --title "New rule for passwords" --file notice.txt
Message 3 sent to 24 users.| Rule | Why |
|---|---|
| at most 64 KB of text (65536 bytes: about 30 pages) | beyond that, the desktop dialog could not show it; RootSpeak refuses with “message too long”. The TUI shows the count below the text, in red when the limit is exceeded |
| the text cannot be empty or made only of spaces | RootSpeak refuses with “empty message” |
| blank lines at the end of the text are removed | the message ends with the last line written |
| the title fits on one line | line breaks and tabs in the title become spaces |
| invisible characters and colour codes are removed | a message cannot disrupt the users' terminals (chapter 11.4) |
i
Order matters. in commands, the options must be written before the text: everything after the first word that is not an option is part of the message.
5.3 · The expiry
Every message asks for confirmation. For notices that are only valid for a short time, such as “the service restarts in 5 minutes”, you add an expiry: once that moment has passed the message is no longer shown or asked again, and whoever has not seen it in time will never see it.
You write (the Expires field or --expires) | The message expires |
|---|---|
30m | in 30 minutes |
2h | in 2 hours |
3d | in 3 days |
2026-10-04 12:00 | Sunday 4 October 2026 at 12:00 (in the command, in quotes: --expires "2026-10-04 12:00") |
tomorrow 18:00 | tomorrow at 18:00 |
admin@server:~$ rspeak send --to online --expires 15m "The web service restarts at 13:00."
Message 2 sent to 3 users.- On expiry, a dialog that is still open closes by itself, and a question waiting in the terminal is interrupted with “[RootSpeak] The message has expired.”
- A confirmation given after the expiry does not count: the recipient stays delivered, “not confirmed (expired)”.
- In the list the message appears with
[expired]in front; the detail view says when it expired.
i
Dates. dates in words are read by the system's
date command, which understands them in English only ("saturday 12:00", "tomorrow 18:00"). The year-month-day hours:minutes format always works. A date already in the past is refused with “the expiry is already in the past”.5.4 · Writing in the TUI
In the TUI the n key opens the New message screen: three one-line fields and the text box below them.
┌─ 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 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘| Field | What to write | Required |
|---|---|---|
| To | the recipients, as in chapter 5.1; on the right, when you leave the field, how many there are | yes |
| Title | one line | no |
| Expires | 30m, 2h, 3d or a date, as in chapter 5.3 | no |
| Text | the message, on several lines; below it, the count, for example “97 of 65536 bytes” | yes |
| Keys | What they do |
|---|---|
| Tab / Shift+Tab | next / previous field, including the text |
| Enter or ↓ in a field | moves to the field below |
| Enter in the text | starts a new line |
| ← → ↑ ↓, Home End | move the cursor |
| ⌫ Del | delete a character |
| Ctrl+E | opens the text in your own editor (chapter 5.5) |
| Ctrl+S | sends, after the summary |
| Esc | discards; if something has already been written it asks for confirmation: Discard the message? |
Ctrl+S shows a summary with the recipients (and how many there are), title, expiry and length of the text. y sends, n or Esc returns to the message without losing anything.
┌─ 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 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘- If sending succeeds, Message sent appears with the reply from RootSpeak; any key returns to the list.
- If something goes wrong, Sending result appears with the reason: a wrong recipient (for example “rspeak: no such user: mrio”) stops the sending, and any key returns to the message so it can be corrected; a copy that could not be written is listed, and RootSpeak retries by itself at the next command.
5.5 · Your own editor
For long texts your own editor is more convenient. Ctrl+E closes the TUI for a moment and opens the text written so far in the editor; when you save and quit you return to the TUI with the updated text.
- In the new message, press Ctrl+E.
- Write or paste the text in the editor, save and quit (with nano: Ctrl+O, Enter, Ctrl+X).
- Check the text in the box and send with Ctrl+S.
| Editor used | When |
|---|---|
the one set in VISUAL or, if that is missing, in EDITOR | if sudo keeps these variables (chapter 10.3) |
nano | otherwise |
vi | if nano is not installed |
i
Security. the editor runs with the administrator's identity, not as root: it opens a temporary file that belongs to the administrator and that RootSpeak deletes on return.
5.6 · What happens when sending
When a message is sent, RootSpeak saves it, puts a copy in each recipient's mailbox and makes it appear at once wherever the user is logged in. It all happens in a few moments.
| Reply from RootSpeak | What it means |
|---|---|
Message 3 sent to 24 users. | All the copies are in the mailboxes: every recipient is delivered. |
Message 3 delivered to 23 of 24 recipients.rspeak: message 3 not delivered to: sara (see the log; the next rspeak command will retry) | A copy could not be written, usually because the disk is full: Sara is sent. RootSpeak retries by itself (chapter 12.4). |
Message 3 revoked while sending: delivery stopped. | Another administrator revoked it while it was being sent. |
rspeak: … | An error: the message was not sent (chapter 12.1). |
The text written to the terminals when the message is sent appears even if the user is working; the confirmation question, instead, only arrives when the user is back at the prompt, so as not to interrupt a command halfway.
5.7 · Ready-made commands
| I want to… | Command |
|---|---|
| notify a user and know whether they have read it | rspeak send --to anna "Your account expires on Friday." |
| warn whoever is logged in that I am about to reboot | rspeak send --to online --expires 15m "Reboot at 13:00: save your work." |
| tell everyone about a new rule | rspeak send --to all --title "Password" --file rule.txt |
| write to a work group | rspeak send --to @developers --expires 2d "Deadline: Thursday at 18:00." |
| write to two people and a group | rspeak send --to mario,anna,@interns "Meeting at 11." |
| send the output of a command | df -h /home | rspeak send --to anna --title "Disk space" |
| send a notice from cron, every Monday at 8:00 | 0 8 * * 1 /usr/local/bin/rspeak send --to all --file /etc/weekly-notice.txt |
+
Automatic sending. in cron (root's crontab,
sudo crontab -e) rspeak is already root and does not ask for the password. It is best to give the full path of the command.Chapter 6
Following the confirmations
6.1 · The list of messages
The main screen of the TUI (chapter 3.2) and the rspeak list command show all the messages sent, each summarised by its recipients in the three states. The TUI puts the most recent first and updates by itself; rspeak list lists them from the oldest, once.
admin@server:~$ 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| Column | In the TUI | In rspeak list |
|---|---|---|
| ID | the message number | the same: it is used for status, log, revoke and remind |
| DATE | day and time of sending (day/month hours:minutes) | the same |
| MESSAGE / TEXT | title in bold, then the first line of the text | the first line of the text, cut at 40 characters |
| RECIPIENTS | three-colour bar and phrase (below 110 columns, confirmations out of the total) | the phrase |
| Mark in front of the text | Meaning |
|---|---|
[revoked] | the message has been revoked (chapter 7.1): it is no longer shown |
[expired] | the expiry has passed: it is no longer shown |
[send cancelled: interrupted before it was saved] | only in rspeak list: a sending stopped before the message was even saved (chapter 12.4) |
i
Recipients. the phrase counts recipients, not the people who have seen the message: “3 delivered” means three people with the copy in their mailbox who have not confirmed yet, logged in or not.
6.2 · The state of each recipient
Pressing Enter on the list opens the selected message: at the top title, date, sender, expiry and any revocation, then the first lines of the text, then two tabs. The Recipients tab shows the state of each user, with the colours of the bar.
┌─ 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 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘The same list, for one message at a time, is obtained with rspeak status followed by the number:
admin@server:~$ 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)| Status line | State | What it means |
|---|---|---|
sent, not delivered | sent | the copy is not yet in the mailbox: RootSpeak retries |
sent, not delivered: the copy could not be written (see the log; the next rspeak command will retry) | sent | the sending ran into an error for this user, usually a full disk |
delivered | delivered | has the copy; has not confirmed yet |
delivered, written to 2 terminals | delivered | was logged in when the message was sent, and the text appeared in two terminal windows |
delivered, postponed on 01/10 10:49 | delivered | answered “Later” or n; the time is that of the last postponement |
delivered, not confirmed (revoked) | delivered | the message was revoked before this user confirmed |
delivered, not confirmed (expired) | delivered | the message expired before this user confirmed |
delivered, not confirmed (expired; confirmation arrived after the expiry) | delivered | confirmed, but too late: the confirmation does not count |
confirmed on 01/10 10:49 (desktop) | confirmed | pressed “I have read it” in the dialog |
confirmed on 01/10 10:49 (terminal pts/2) | confirmed | answered y in a terminal window or in an ssh connection (pts) |
confirmed on 01/10 10:49 (terminal tty3) | confirmed | answered y on a console of the machine |
Above the list, rspeak status writes REVOKED on … if the message has been revoked and EXPIRED if the expiry has passed. In the TUI the same information is in the line at the top, in red for a revocation.
+
Message keys. in the Recipients tab you scroll with ↑ ↓ and PgUp PgDn; m reminds and r revokes this very message; Esc returns to the list.
6.3 · The life of a message
Every message has a history made of events: the sending, the delivery to each recipient, the postponements, the reminders, the confirmations, a possible revocation. Events change the state of a recipient at only two points: when the copy arrives in the mailbox and when the user confirms.
| Event | Who causes it | Effect on the recipient's state |
|---|---|---|
| sending | the administrator | everyone sent for an instant |
| delivery | RootSpeak | sent → delivered |
| postponement | the user: “Later” or n | none: stays delivered |
| reminder | the administrator (m, rspeak remind) | none: stays delivered, but is asked again immediately |
| confirmation | the user: “I have read it” or y | delivered → confirmed |
| revocation | the administrator (r, rspeak revoke) | none; the message becomes revoked and is no longer shown |
| expiry | time | none; the message becomes expired and is no longer shown |
!
No going back. a confirmation is final: it cannot be undone, neither from the TUI nor from the commands. To ask everyone again, send a new message.
6.4 · The history of a message
The message's History tab, opened with Tab, lists the events of the message taken from the system log, oldest first, with date and time to the second.
┌─ 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 │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ With a command, the same history is read with rspeak log:
admin@server:~$ rspeak log 2
Message 2 · Maintenance · 01/10 10:49
2026-10-01 10:49:29 message 2 delivered to admin (terminals written: 0)
2026-10-01 10:49:29 message 2 delivered to anna (terminals written: 0)
2026-10-01 10:49:29 message 2: ERROR, copy for dario not written
2026-10-01 10:49:29 message 2 delivered to mario (terminals written: 0)
2026-10-01 10:49:29 message 2 sent by root to: admin anna dario fabio kora luca mario zeno
2026-10-01 10:49:42 user anna: confirmed reading message 2 (desktop)
2026-10-01 10:50:03 user mario: postponed message 2 (terminal)
2026-10-01 10:56:36 message 2: 3 recipients reminded by admin| Line | When it appears |
|---|---|
message N delivered to U (terminals written: K) | for each copy that reached a mailbox; K is the number of terminal windows in which the text appeared when it was sent |
message N sent by A to: … | at the end of each sending, with the list of recipients |
message N: ERROR, copy for U not written | when a delivery fails |
message N delivered to U (recovery) | when RootSpeak completes a delivery that had been left behind |
user U: postponed message N (terminal) or (desktop) | when the user postpones |
user U: confirmed reading message N (channel) | on confirmation |
user U: ERROR, confirmation of message N not recorded (…) | when the confirmation could not be saved, for example with a full disk |
message N: K recipients reminded by A | at each reminder |
message N revoked by A | on revocation |
i
History and state. the history comes from the system log, which the machine may rotate and delete after a while according to its settings. The state of the recipients, on the other hand, comes from the RootSpeak message store and remains until the message is deleted.
6.5 · The system log
Every event is also written to the machine's system log, with the tag rspeak. It is the trail to use if someone asks “who sent what, and when”, even for messages that have already been deleted.
admin@server:~$ sudo journalctl -t rspeak --since today
Oct 01 10:49:29 server rspeak[20914]: message 2 delivered to anna (terminals written: 0)
Oct 01 10:49:29 server rspeak[20914]: message 2 sent by root to: admin anna dario fabio kora luca mario zeno
Oct 01 10:49:42 server rspeak[21310]: user anna: confirmed reading message 2 (desktop)| To see… | Command |
|---|---|
| all of today's RootSpeak events | sudo journalctl -t rspeak --since today |
| the events of the last hour | sudo journalctl -t rspeak --since "1 hour ago" |
| the events as they arrive | sudo journalctl -t rspeak -f |
| the history of one message, neatly ordered | rspeak log 2 |
- User events (postponements, confirmations) are written by the users themselves:
rspeak logchecks who wrote them and flags suspicious ones (chapter 11.5). - Deleting with
rspeak purgeremoves the message from the message store, but its events remain in the log.
6.6 · Searching for a message
When there are many messages, the / key of the TUI shows only those that contain a given text, searched in the title and in the whole message, ignoring upper and lower case.
┌─ RootSpeak · sent messages ──────────────────────────────────────────────────────────────── updated at 12:49:16 ─┐
│ │
│ ID DATE MESSAGE RECIPIENTS │
│ 3 01/10 12:49 Your account expires on Friday: ple ▒▒▒▒▒▒▒▒▒▒▒▒ 1 delivered │
│ > 2 01/10 12:49 Maintenance · On Saturday from 8 am ██████▒▒▒▒▒▒ 1 confirmed · 1 delivered │
│ 1 01/10 12:49 Server update · Tonight at 11 pm th ████████████ all confirmed (2) │
│ │
│ │
│ │
│ │
│ ┌─ Search ─────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Show only the messages containing: │ │
│ │ │ │
│ │ [ server ] │ │
│ │ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ █ confirmed ▒ delivered ░ sent │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Enter confirm Esc cancel │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘┌─ RootSpeak · sent messages ──────────────────────────────────────────────────────────────── updated at 12:49:20 ─┐
│ │
│ ID DATE MESSAGE RECIPIENTS │
│ > 2 01/10 12:49 Maintenance · On Saturday from 8 am ██████▒▒▒▒▒▒ 1 confirmed · 1 delivered │
│ 1 01/10 12:49 Server update · Tonight at 11 pm th ████████████ all confirmed (2) │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ █ confirmed ▒ delivered ░ sent search: «server» (Esc to clear) │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Enter open n new r revoke m remind p purge / search ? keys q quit │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘| Key | What it does |
|---|---|
| / | opens the search; if there already was one, offers it again for editing |
| Enter | applies the search |
| Esc in the search dialog | leaves the list as it was |
| Esc in the list | clears the search and shows all the messages again |
i
No results. if no message contains the text, the list says “No message contains the search text.” Accented letters must be typed in the same upper or lower case as in the message.
Chapter 7
Revoking, reminding, cleaning up
7.1 · Revoking a message
A message sent by mistake, or no longer valid, is revoked: in the TUI with r on the selected message (in the list or in the open message), from the command line with rspeak revoke. Before revoking, the TUI always asks for confirmation.
┌─ RootSpeak · sent messages ──────────────────────────────────────────────────────────────── updated at 12:49:09 ─┐
│ │
│ ID DATE MESSAGE RECIPIENTS │
│ 3 01/10 12:49 Your account expires on Friday: ple ▒▒▒▒▒▒▒▒▒▒▒▒ 1 delivered │
│ > 2 01/10 12:49 Maintenance · On Saturday from 8 am ██████▒▒▒▒▒▒ 1 confirmed · 1 delivered │
│ 1 01/10 12:49 Server update · Tonight at 11 pm th ████████████ all confirmed (2) │
│ │
│ │
│ │
│ ┌─ Revoke message 2? ──────────────────────────────────────┐ │
│ │ │ │
│ │ «Maintenance» · 1 confirmed · 1 delivered │ │
│ │ │ │
│ │ Whoever has not seen it yet will not see it; │ │
│ │ open dialogs and questions close by themselves. │ │
│ │ │ │
│ │ y Confirm n Cancel │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ █ confirmed ▒ delivered ░ sent │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ y confirm n or Esc cancel │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘admin@server:~$ rspeak revoke 4
Message 4 revoked.| Who | What happens |
|---|---|
| whoever has not seen it yet (not logged in) | will never see it: the copy disappears from their mailbox |
| whoever has a confirmation dialog open | the dialog closes by itself within a second |
| whoever has the question in the terminal | the question is interrupted with “[RootSpeak] The administrator has revoked the message.” |
| whoever had already confirmed | stays confirmed: confirmations already received count |
| whoever confirms after the revocation | the confirmation does not count: stays delivered, “not confirmed (revoked)” |
| the administrator | in the list the message has [revoked] in front; rspeak status writes REVOKED on … |
!
Text already written stays. the text that already appeared in the terminals when the message was sent cannot be erased: it is already on the user's screen. Revocation only stops the confirmation requests and the dialogs.
i
Revocation during sending. if the message is still being sent to many recipients, the revocation waits a moment and stops the delivery at the next recipient; whoever already has the copy loses it. If some mailbox cannot be reached, RootSpeak says so (“some copies could not be removed from the mailboxes”) and retries by itself.
7.2 · Reminding those who have not confirmed
Whoever postponed sees the message again after 30 minutes. If it is needed sooner, send a reminder: in the TUI with m, from the command line with rspeak remind. The question comes back at the next prompt and the dialog reappears at once on the desktop, even if the user had just postponed it.
┌─ 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 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘admin@server:~$ rspeak remind 2
Message 2: 3 recipients reminded.| Recipient | Reminded? |
|---|---|
| delivered (has the copy, has not confirmed) | yes: question at the next prompt, dialog at once |
| confirmed | no: not disturbed |
| sent | no: does not have the copy yet; RootSpeak retries the delivery by itself |
- A revoked or expired message cannot be reminded: the command replies “rspeak: message 4 has been revoked: nobody to remind” or “rspeak: message 4 has expired: nobody to remind”.
- If everyone has already confirmed, nobody is disturbed and the command says so: “Message 2: everyone has already confirmed, nobody to remind.”
- The reminder is recorded in the message's history and in the log, together with who asked for it.
- For users who are not logged in, a reminder changes nothing: they will see the message at their next login anyway.
+
In moderation. an occasional reminder works better than many: people who get the dialog in front of them every five minutes tend to confirm without reading.
7.3 · Deleting old messages
Messages and confirmations stay in the message store until they are deleted. Purging removes the messages sent more than a certain time ago, together with the copies and confirmations in the users' mailboxes.
- In the list press p: Delete old messages opens, with
90dalready filled in. - Change the duration if needed (
90ddays,12hhours,30mminutes) and press Enter. - Read the summary Delete old messages? and confirm with y.
- The next dialog shows the reply from RootSpeak, for example “Deleted 12 messages older than 90d.”
┌─ RootSpeak · sent messages ──────────────────────────────────────────────────────────────── updated at 12:49:14 ─┐
│ │
│ ID DATE MESSAGE RECIPIENTS │
│ 3 01/10 12:49 Your account expires on Friday: ple ▒▒▒▒▒▒▒▒▒▒▒▒ 1 delivered │
│ > 2 01/10 12:49 Maintenance · On Saturday from 8 am ██████▒▒▒▒▒▒ 1 confirmed · 1 delivered │
│ 1 01/10 12:49 Server update · Tonight at 11 pm th ████████████ all confirmed (2) │
│ │
│ │
│ │
│ │
│ ┌─ Delete old messages ────────────────────────────────────────┐ │
│ │ │ │
│ │ Delete the messages sent more than (for example 90d, 12h): │ │
│ │ │ │
│ │ [ 90d ] │ │
│ │ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ █ confirmed ▒ delivered ░ sent │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Enter confirm Esc cancel │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘admin@server:~$ rspeak purge 90d
Deleted 12 messages older than 90d.- A deleted message disappears from the list and from
rspeak status; if someone had not confirmed it yet, they will no longer be asked. - A sending still in progress is not touched.
- The system log keeps the events of the message and that of the deletion (“message 1 deleted by admin (older than 90d)”).
- Message numbers are not reused: the next message takes the number after the last one.
!
Final. deletion cannot be undone. If you need to keep the list of confirmations, first save the output of
rspeak status for the messages you care about.7.4 · When an action cannot be carried out
Not every action makes sense on every message. When a key has no effect, the TUI simply does nothing; the commands, instead, reply with an error.
| Action | Not possible when… | Command reply |
|---|---|---|
r / rspeak revoke | the message is already revoked | no error: “Message 4 revoked.” |
m / rspeak remind | the message is revoked | rspeak: message 4 has been revoked: nobody to remind |
m / rspeak remind | the message has expired | rspeak: message 4 has expired: nobody to remind |
m / rspeak remind | nobody is delivered | nothing in the TUI; the command replies Message 4: everyone has already confirmed, nobody to remind. or, if some copies are still sent, Message 4: 0 recipients reminded. |
Enter / rspeak status | the number does not exist | rspeak: no such message: 99 |
p / rspeak purge | the duration is badly written | rspeak: invalid duration: 3 (for example 90d, 12h, 30m) |
i
Always a confirmation. no TUI action starts without a confirmation: the message to revoke, the people to remind and the messages to delete are always shown first. n or Esc cancel.
All these actions are reserved to administrators and are recorded in the log under their name: for rspeak the author is whoever used sudo, not root (chapter 11.1).
Chapter 8
What users see
8.1 · On the desktop
On the desktop the message appears by itself, on top of the other windows, a few moments after it is sent. The user does not have to do anything to receive it: at graphical login a small RootSpeak program starts, the desktop agent, which waits for messages. RootSpeak speaks English, whatever the language of the session; the message text arrives exactly as the administrator wrote it.
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.
LaterI have read it
| The user… | What happens |
|---|---|
| presses “I have read it” | The message is confirmed and never appears again, in any session. |
| presses “Later” or closes the dialog | The message is postponed: the dialog comes back after 30 minutes, until the user confirms. |
| does nothing | The dialog stays there without blocking anything: the user can keep working in the other windows. |
| logs out | The dialog closes; the message appears again at the next login. |
- The top of the dialog shows the message title and the date it was sent; if the message has no title, only the date.
- If there are several messages, the dialogs appear one at a time, from the oldest to the most recent.
- The dialog closes by itself if the user confirms from a terminal, if the administrator revokes the message or if the message expires.
RootSpeak
RootSpeak · Confirmation not recordedThe confirmation could not be recorded: the message will be shown again.i
Confirmation not recorded. if the confirmation cannot be saved (for example because the disk is full), the desktop shows the notice above and the message is asked again: the confirmation is never lost silently. The notice requires
notify-send.8.2 · In the terminal
In every terminal window of the user, whether local, inside the desktop, in tmux or connected through ssh, the text appears the moment the message is sent, even while the user is working:
When the message is sent: header with title and date, then the textmario@server:~/projects$ make
gcc -O2 -c main.c
── RootSpeak · Message from the administrator · Maintenance · 30/09 16:55 ──
On Saturday from 8 am to 12 noon the server will be off.
────────────────────────────────────────
gcc -O2 -o test main.oAs soon as the user is back at the prompt (if already at the prompt, just press Enter), RootSpeak shows the message again and asks for confirmation:
At the next prompt: the message again, and the question── RootSpeak · Message from the administrator · Maintenance · 30/09 16:55 ──
On Saturday from 8 am to 12 noon the server will be off.
────────────────────────────────────────
[RootSpeak] Do you confirm you have read the message? [y/N] y
[RootSpeak] Confirmed.
mario@server:~/projects$| The user answers | What happens |
|---|---|
| y and Enter | “[RootSpeak] Confirmed.”: the message is confirmed everywhere. |
| anything else, even just Enter | “[RootSpeak] You will be asked again in 30 minutes.” |
| nothing, because they confirmed on the desktop | “[RootSpeak] Message already confirmed elsewhere (for example on the desktop).”: the question closes by itself |
| nothing, and the message is revoked | “[RootSpeak] The administrator has revoked the message.” |
| nothing, and the message expires | “[RootSpeak] The message has expired.” |
After a postponement, until the next question, only a one-line reminder appears at each prompt:
If the user postpones: a one-line reminder at each prompt[RootSpeak] Do you confirm you have read the message? [y/N] n
[RootSpeak] You will be asked again in 30 minutes.
mario@server:~/projects$ ls
main.c main.o test
[RootSpeak] You have 1 message from the administrator to confirm.
mario@server:~/projects$i
Full-screen programs. if the user is running a full-screen program, such as an editor, the text sent to the terminal is drawn over the screen, as happens with
wall. Nothing is lost: the screen fixes itself, or with Ctrl+L, and the question only comes when the user leaves the program.8.3 · Shells
The confirmation question in the terminal depends on the user's shell. The text shown when the message is sent, instead, always arrives, whatever the shell.
| Shell | Text when sent | Confirmation question |
|---|---|---|
| bash | yes | at every prompt; at login also if it had been postponed |
| zsh | yes | at every prompt; at login also if it had been postponed |
| fish | yes | at every prompt; at login also if it had been postponed |
sh, dash, ksh and the others that read /etc/profile | yes | only at login |
tcsh, csh and the shells that do not read /etc/profile | yes | no (the dialog remains, if the user has a desktop) |
- The question only appears in interactive shells: scripts, cron,
scp,rsyncand commands run withssh server commandnever see it. - Terminal windows already open when RootSpeak is installed receive the text, but the question only from the next window or the next login.
- If zsh is installed after RootSpeak, re-running
./install.shis enough to get the question in zsh; fish, instead, gets it even if installed later.
!
Logins with su. with
su - mario the terminal window still belongs to whoever opened it: the text sent with the message does not appear, the question at the prompt does. With ssh mario@server everything works normally.8.4 · Users who are not logged in
Users who are not logged in find the message at their next login, however they log in. Meanwhile it is already delivered: the copy is in their mailbox, waiting for them.
| Login | What the user sees |
|---|---|
| desktop | the dialog, as soon as the session opens |
| console or ssh | text and question right after login, before the first prompt; at login the question is asked even if the user had postponed it |
a command over ssh, scp, a service | nothing: it is not an interactive login |
8.5 · Several sessions, one confirmation
A user with several open sessions, for example the desktop and two ssh connections, receives the message in all of them. Confirming once is enough.
The dialog closes by itself if the user confirms from a terminal, and the question in the terminal closes if the user confirms on the desktop. The message status keeps the first confirmation, with the channel it came from: desktop or terminal pts/2.
i
Separate postponements. postponing, instead, applies to the channel where it is done: a user who presses “Later” on the desktop still sees the question in the terminal, and vice versa.
8.6 · Postponing and reminders
RootSpeak never blocks work: the user can always postpone. But whoever postpones is asked again, at regular intervals, until they confirm.
| When | In the terminal | On the desktop |
|---|---|---|
| after a postponement | a one-line reminder at each prompt | no dialog |
| after 30 minutes | text and question at the next prompt | the dialog comes back (within a minute) |
| at login | text and question at once, even if the user had postponed | the dialog when the session opens |
| after a reminder | text and question at the next prompt | the dialog at once |
| on expiry or revocation | nothing more | nothing more |
The 30-minute interval is the same for the dialog and for the terminal and can be changed in the settings (chapter 10). Meanwhile the administrator sees in the message details who postponed and when.
8.7 · Explaining RootSpeak to users
Users have no RootSpeak commands and do not need to learn anything. It can still help to answer a few questions: the table collects the most common ones, with short, accurate answers to pass on as they are.
| The user's question | Answer |
|---|---|
| “What is this window?” | A message from the administrators of the machine. “I have read it” confirms you have read it; “Later” postpones it by half an hour. |
| “Does anything happen if I press Later?” | No, you can keep working. The message comes back after 30 minutes until you confirm. |
| “Do I have to confirm in the terminal too?” | No: one confirmation is valid everywhere. The question in the terminal closes by itself. |
| “Can I read a message again after confirming it?” | No: after the confirmation it does not appear again. If needed, ask the administrator. |
| “Can I reply?” | No: RootSpeak is only for notices from the administrators. To reply, use the usual channels. |
| “Can other people see my messages?” | No: everyone sees only the messages sent to them. |
+
The first message. for an important notice it is worth telling users, with the first message, what the dialog and the question are: the first message can explain RootSpeak itself.
Chapter 9
The built-in help
9.1 · Opening the built-in help
Everything needed to use rspeak is also inside the command itself: rspeak --help (or rspeak help or rspeak -h) opens a full-screen guide, divided into five tabs.
┌─ rspeak — guide ───────────────────────────────────────────────────────────┐
│ Info Commands Options Examples Files │
├────────────────────────────────────────────────────────────────────────────┤
│ NAME │
│ rspeak — messages to users with read confirmation │
│ │
│ SYNOPSIS │
│ rspeak send --to DEST [options] [TEXT] │
│ rspeak list │
│ rspeak status ID │
│ rspeak │
│ rspeak revoke ID │
│ rspeak remind ID │
│ rspeak log ID │
│ rspeak purge DURATION │
│ rspeak version │
│ │
│ DESCRIPTION │
│ RootSpeak lets administrators send text messages to the users of the │
├────────────────────────────────────────────────────────────────────────────┤
│ ←/→ tabs · ↑/↓ scroll · PgUp/PgDn · g/G · q quit lines 1-16/25 │
└────────────────────────────────────────────────────────────────────────────┘| Tab | Contains |
|---|---|
| Info | name, syntax of all the commands, description of RootSpeak, version and path of this manual |
| Commands | rspeak on its own, send, list, status, revoke, remind, log, purge, version, help |
| Options | the options of send: recipients, title, expiry, file |
| Examples | ready-to-copy commands |
| Files | where settings, messages, log and manual are |
┌─ rspeak — guide ───────────────────────────────────────────────────────────┐
│ Info Commands Options Examples Files │
├────────────────────────────────────────────────────────────────────────────┤
│ Send options │
│ │
│ --to DEST │
│ Recipients, separated by commas without spaces: a user (mario), a Unix │
│ group (@developers), all (every human user) or online (only those │
│ logged in now). │
│ │
│ --title TITLE │
│ Title shown in the message header and in the desktop dialog. │
│ │
│ --expires DURATION │
│ Expiry, after which the message is no longer shown: 30m, 2h, 3d or a │
│ date and time ("2026-10-04 12:00"). │
│ │
│ --file FILE │
│ Reads the message text from FILE. │
├────────────────────────────────────────────────────────────────────────────┤
│ ←/→ tabs · ↑/↓ scroll · PgUp/PgDn · g/G · q quit lines 1-16/16 │
└────────────────────────────────────────────────────────────────────────────┘i
Always with sudo. like every
rspeak command, the built-in help also asks for the sudo password. The texts of the Commands and Options tabs are the same as in chapter 13 of this manual.9.2 · Moving around the built-in help
| Keys | Action |
|---|---|
| ← →, Tab Shift+Tab, h l | previous or next tab |
| Enter | next tab |
| 1 … 5 | go straight to a tab |
| ↑ ↓, k j | scroll by one line |
| PgUp PgDn, b Space | scroll by one page |
| g G, Home End | start or end of the tab |
| q, Esc | leave the built-in help |
At the bottom right the help shows which lines of the tab are being viewed, for example “lines 1-16/25”. Each tab remembers where you had got to. The help adapts when the window is resized; on exit the terminal goes back exactly as it was.
+
For vi users. the keys h j k l are the same as in vi and less: if you know them, you can use them here too.
9.3 · Small terminals and plain text
The same guide has three forms, and rspeak picks the right one by itself.
| Situation | What rspeak --help shows |
|---|---|
| a normal terminal | the tabbed guide |
| a very small terminal (fewer than 44 columns or 10 lines) | the same guide as a single page, to scroll through with the pager: less, or the program set in PAGER; q to quit |
| the output goes to a file or to another command | plain text at 80 columns, without colours; compared with the tabs it also has the environment variables and the exit status of the commands (chapter 13.5) |
admin@server:~$ rspeak --help | grep -A2 -- '--expires DURATION'
--expires DURATION
Expiry, after which the message is no longer shown: 30m, 2h, 3d or
a date and time ("2026-10-04 12:00").i
And rspeak on its own?
rspeak on its own, too, in a pipe or in a terminal smaller than 80 columns or 20 lines, shows the built-in help instead of the TUI.Chapter 10
Settings
10.1 · The settings file
RootSpeak has two settings, and they live in a single file, /etc/rootspeak/rootspeak.conf. They are fine as installed; change them only for particular needs.
# 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| Setting | Default | What it decides |
|---|---|---|
RSPEAK_REMIND_MINUTES | 30 | after how many minutes a postponed message is asked again, in the terminal and on the desktop; it is also the number written in “You will be asked again in 30 minutes” |
RSPEAK_AGENT_POLL | 60 | how often, in seconds, the desktop agent checks the messages again as a safeguard. New messages and reminders arrive at once anyway. Lower values use slightly more battery |
| File rule | Example |
|---|---|
one line per setting, KEY=value | RSPEAK_REMIND_MINUTES=15 |
| only whole numbers greater than zero, at most six digits | RSPEAK_AGENT_POLL=120 |
| spaces do not matter | RSPEAK_REMIND_MINUTES = 15 |
anything after # is a comment | RSPEAK_AGENT_POLL=30 # laptops on charge |
| invalid lines, unknown keys and wrong values are ignored: the default applies | RSPEAK_REMIND_MINUTES=half-an-hour → 30 |
i
Data only. the file contains only data: it is not a script and is never executed. A typing mistake does not stop RootSpeak, it only makes it use the default value.
10.2 · Changing a setting
- Open the file with administrator rights:
admin@server:~$ sudo nano /etc/rootspeak/rootspeak.conf - Change the value, for example
RSPEAK_REMIND_MINUTES=15, save and exit. - There is nothing to restart: the value applies at once to terminals (from the next prompt) and to the desktop from the agent's next check.
| Need | Setting |
|---|---|
| urgent notices: ask again more often | RSPEAK_REMIND_MINUTES=10 |
| users complaining about the requests | RSPEAK_REMIND_MINUTES=60 or more |
| battery-powered laptops | RSPEAK_AGENT_POLL=300: new messages still arrive at once |
!
Permissions. the file must remain owned by root and writable only by root, as the installation leaves it: all users read it, to know when to ask the messages again.
i
Upgrades. a RootSpeak upgrade does not overwrite
/etc/rootspeak/rootspeak.conf; ./install.sh --purge deletes it.10.3 · Colours, pager and editor
A few environment variables change the behaviour of rspeak for the administrator who sets them. Since rspeak always re-runs itself with sudo, they only get through if sudo keeps them.
| Variable | Effect | Default |
|---|---|---|
NO_COLOR | if set, TUI and built-in help without colours | colours |
PAGER | the program that pages the built-in help in small terminals (chapter 9.3) | less |
VISUAL, EDITOR | the editor opened with Ctrl+E in the new message (chapter 5.5) | nano, then vi |
To have sudo keep them, add a line to its settings, always with visudo:
admin@server:~$ sudo visudo -f /etc/sudoers.d/rootspeak
# in the file:
Defaults env_keep += "NO_COLOR PAGER VISUAL EDITOR"!
For all of sudo. this line applies to every command run with sudo, not just
rspeak. Add only the variables you need.+
Editor and security. the editor opened by
rspeak runs with the administrator's identity, not as root: keeping EDITOR does not give it extra powers.Chapter 11
Security and privacy
11.1 · Who can use RootSpeak
Only the machine's administrators can use rspeak: the members of the sudo group (wheel on Fedora and similar systems). RootSpeak keeps no list of its own: whoever joins or leaves the group gains or loses access from their next login to the machine (chapter 2.4).
mario@server:~$ rspeak list
bash: /usr/local/bin/rspeak: Permission deniedrspeakalways works as administrator, even to show the help or the version: if it is not already root, it restarts itself with sudo, which asks for the password.- In messages and in the log the author is the administrator who used sudo, not a generic “root”: “message 3 sent by admin to: …”. Whoever runs
rspeakdirectly as root (for example from cron) appears asroot. - Users have no RootSpeak command at all: they can neither send messages nor see who has confirmed.
11.2 · Who sees the messages
Each user sees only the messages sent to them. The message store in /var/lib/rootspeak/ is split into two parts with different permissions.
/var/lib/rootspeak/ # root, readable by everyone (listing only) ├── sent/ # root, 700: root only │ └── 3/ # message 3: text, recipients, deliveries, revocation └── users/ └── mario/ # Mario's, 700: Mario and root only ├── inbox/ # messages to confirm ├── read/ # confirmed or expired messages ├── acks/ # the confirmations, with date and channel └── state/ # the postponements
| Who | What they see |
|---|---|
| an administrator | all the messages sent, the recipients, the confirmations, the history |
| a user | only the messages addressed to them, one at a time, until they confirm them |
| the other users | nothing of a colleague's messages, not even that they exist |
i
Root does not go in as root. RootSpeak always enters a user's mailbox with that user's identity, even when the administrator is in command: this way a user cannot trick root into writing where it should not.
11.3 · What a confirmation is worth
The confirmation records that the user states they have read the message, with date, time and channel, like the read receipts of a messaging app. It cannot prove that they really read it.
| The confirmation says | The confirmation does not say |
|---|---|
| that the user pressed “I have read it” or answered “y” | that they read it carefully |
| when (day and time) and from where (desktop or which terminal) | who was in front of the screen |
| that the message had neither expired nor been revoked at that moment | that they understood the content |
i
A statement. the mailbox belongs to the user: an expert user could record a confirmation without opening the dialog. It is still their own statement, like the click on “I have read it”.
+
When more is needed. for notices that require a real commitment (a rule to follow, an authorisation) the RootSpeak confirmation is a reminder, not a signature: a separate document is needed.
11.4 · Safe text
Before saving a message, RootSpeak removes from the text and the title the invisible characters and the codes that change the colours, title or behaviour of terminal windows. A message therefore cannot alter users' terminals, even if the text was pasted from an unknown source.
| In the text | What happens |
|---|---|
| letters, digits, punctuation, accented letters, symbols | kept |
| tabs and line breaks | kept (in the title, line breaks become spaces) |
| colour and cursor-movement codes | removed |
| codes that change the terminal window's title | removed |
| other invisible control characters | removed |
What RootSpeak reads from the users' mailboxes (confirmations, postponements) is also cleaned before it is shown to the administrator.
11.5 · How reliable the log is
The system log is a convenient trail, but anyone on the machine can write lines tagged rspeak into it. That is why rspeak log and the TUI check who really wrote each event and flag the suspicious ones.
admin@server:~$ rspeak log 3
Message 3 · New password rule · 30/09 19:05
2026-09-30 19:05:12 message 3 delivered to anna (terminals written: 1)
2026-09-30 19:05:12 message 3 sent by admin to: anna luca
2026-09-30 19:06:40 [not trustworthy: written by UID 1003] user anna: confirmed reading message 3 (desktop)| Event | Must have been written by |
|---|---|
| sending, delivery, reminder, revocation, deletion | root (that is, rspeak) |
| postponement, confirmation, confirmation not recorded | the user it refers to |
!
Trust the state. a line marked “not trustworthy” must be disregarded. The true state of a recipient is the one shown in the message details and by
rspeak status, which comes not from the log but from the message store: there confirmed means that the confirmation is in the user's mailbox.Chapter 12
Troubleshooting
12.1 · Error messages
When a command fails, rspeak prints a line in red that starts with rspeak:, says what to correct and exits with status 1. In the TUI the same line appears in the result dialog.
admin@server:~$ rspeak send --to mrio "Meeting at 11."
rspeak: no such user: mrio| Message | What it means | What to do |
|---|---|---|
missing --to | no recipient | add --to (chapter 5.1) |
missing value for --to | an option without its value (the same applies to --title, --expires, --file) | write the value after the option |
no such user: NAME | the name is not a user of the machine | check the name |
no such group: NAME | the group after @ does not exist | check the group name |
no recipients | the recipients given are empty, for example online when nobody is logged in | choose other recipients |
empty message | the text is missing, or contains only spaces | write the text |
message too long: N bytes (at most 65536) | the text exceeds 64 KB | shorten it, or put the full text in a shared file and send the message with its path |
invalid expiry: X | the expiry was not understood | use 2h or "2026-10-04 12:00" (chapter 5.3) |
the expiry is already in the past | the date given is in the past | correct the date |
unknown option: X | misspelt option | rspeak --help |
unknown command: X (rspeak --help for the guide) | misspelt command | rspeak --help |
too many arguments for remind: 4 (rspeak --help for the guide) | one word too many, for example two message numbers: each command takes one | repeat the command for each message |
missing message ID | status, revoke, remind or log without a number | add the number, taken from rspeak list |
no such message: ID | no message with that number (or already deleted) | check with rspeak list |
missing duration, for example 90dinvalid duration: X (for example 90d, 12h, 30m) | rspeak purge without a duration or with a misspelt duration | write a number followed by d, h or m |
message N has been revoked: nobody to remindmessage N has expired: nobody to remind | reminder for a message that is no longer shown | nothing; to ask again, send a new message |
message N not delivered to: … (see the log; the next rspeak command will retry) | the copy could not be written for those users; the others received it | fix the cause, often a full disk (chapter 12.4) |
message N revoked, but some copies could not be removed from the mailboxes: the next rspeak command will retry | during the revocation a user's mailbox could not be reached | nothing: RootSpeak retries |
FILE: … | with --file: the file does not exist or cannot be read; the explanation is the system's own (for example No such file or directory) | check the path |
12.2 · Frequent problems
| Problem | Likely cause | Remedy |
|---|---|---|
rspeak: command not found | RootSpeak is not installed | run ./install.sh (chapter 2.2) |
Permission denied | whoever runs it is not an administrator | this is intended (chapter 11.1) |
rspeak on its own shows the help instead of the TUI | the terminal is smaller than 80 columns or 20 rows, or the output is not a terminal | enlarge the window, or use the commands |
| the TUI closed by itself | the window was shrunk below 80 × 20 | enlarge it and reopen rspeak |
| the text reaches the terminal but the question does not | the terminal window was open before the installation; or the shell is sh, dash or ksh (question only at login) or tcsh (no question); or zsh was installed after RootSpeak | open a new window or log in again; for zsh installed later, run ./install.sh again (chapter 8.3) |
| no dialog appears on the desktop | zenity is missing, or the graphical session was started before the installation and the agent did not start | install zenity; the agent starts by itself with the first new message or at the next login |
| two identical dialogs | the same message was sent twice (two different numbers in the list) | revoke the duplicate (chapter 7.1) |
a user who logged in with su does not see the text when it is sent | with su the terminal window still belongs to whoever opened it | they still see the question at the next prompt; with ssh everything works normally |
| a user sees “The confirmation could not be recorded” | their mailbox is not writable, for example because the disk is full | free some space: the message is asked again and the confirmation is not lost |
| a recipient stays sent | their copy could not be written | see chapter 12.4 |
| Ctrl+E opens nano and not my editor | sudo does not keep VISUAL and EDITOR | chapter 10.3 |
| a user says they saw nothing | — | follow the procedure in chapter 12.3 |
12.3 · “I didn't see any message”
It is the most common question. The answer is almost always in the message details and in its history.
- Open the message in the TUI (Enter) or run
rspeak status ID, and find the user's line. - If it is confirmed, the line says when and from where: for example “confirmed on 30/09 16:56 (desktop)”. The user has confirmed, perhaps without reading carefully (chapter 11.3).
- If it is delivered, look at the details: “written to 2 terminals” means that the text appeared on their screens; “postponed on …” that they saw the question or the dialog and postponed it. If neither is there, they have probably not logged in yet.
- If it is sent, the copy did not reach their mailbox: see chapter 12.4.
- In the History tab (Tab), or with
rspeak log ID, you find all the events, postponements included, to the second. - If needed, remind them (chapter 7.2): the dialog comes back on their desktop at once.
+
Unusual shells. a user who works only through ssh and with a shell such as tcsh does not get the question in the terminal: they see the text when it is sent, but can confirm only from the desktop. With bash, zsh or fish the problem does not arise.
12.4 · Interrupted sendings
If a sending is interrupted halfway (the disk fills up, rspeak is stopped, the power goes) RootSpeak does not lose the message: the next time it is used, it resumes from where it stopped.
| Notice | What it means | What to do |
|---|---|---|
rspeak: completed delivery of message N to K recipients | the missing copies have been written: those recipients are now delivered | nothing |
rspeak: message N still not delivered to K recipients (see rspeak status N) | for someone the copy still cannot be written | fix the cause, usually disk space; then use rspeak again |
rspeak: message N was interrupted before being saved and has been cancelled | the sending stopped before the message was even saved: nobody received it | send it again |
[send cancelled: interrupted before it was saved] in rspeak list | the same case, in the list | send it again |
i
When it starts. recovery starts at the beginning of
rspeak send, list, status, revoke, remind, log and when the TUI opens. Nothing is needed other than using RootSpeak.!
Full disk. with a full disk the users' confirmations cannot be saved either: users see “The confirmation could not be recorded” and the message is asked again. Freeing space in
/var/lib solves both.12.5 · Useful files and folders
| What | Where |
|---|---|
| the command | /usr/local/bin/rspeak |
| the settings | /etc/rootspeak/rootspeak.conf |
| messages and confirmations | /var/lib/rootspeak/ |
| the log | sudo journalctl -t rspeak |
| the help | rspeak --help |
| the manuals | /usr/local/share/doc/rootspeak/User Manual.html and Technical Manual.html |
| the shell hooks | /etc/profile.d/rootspeak.sh, /usr/local/lib/rootspeak/rootspeak.bash, rootspeak.zsh, /etc/fish/conf.d/rootspeak.fish |
| the desktop autostart | /etc/xdg/autostart/rootspeak-agent.desktop |
| the code | https://github.com/nic-fio/ROOTSPEAK (private) |
+
Where to look. when something does not add up, the places to look are, in order: the message details, its history, the log with
sudo journalctl -t rspeak, and the built-in help.Chapter 13
Command reference
13.1 · Syntax
This chapter lists all the commands and options of rspeak. The texts of the commands, options and examples are the same as those of the built-in help (rspeak --help, chapter 9): this page is generated from the same texts, so the two cannot diverge.
admin@server:~$ rspeak --help | head -16
RSPEAK(1) rspeak manual RSPEAK(1)
NAME
rspeak — sends messages to the users of the machine and tracks their read
confirmation
SYNOPSIS
rspeak send --to DEST [options] [TEXT]
rspeak list
rspeak status ID
rspeak
rspeak revoke ID
rspeak remind ID
rspeak log ID
rspeak purge DURATION
rspeak version| Part | Meaning |
|---|---|
ID | the number of a message, as it appears in the list |
DEST | the recipients: names, @group, all, online, separated by commas without spaces |
DURATION | a number followed by m (minutes), h (hours) or d (days); for --expires also a date and a time |
[options], [TEXT] | the parts in square brackets can be omitted |
i
Always as root. every command,
version and --help included, restarts itself with sudo if it is not already root.13.2 · Commands
The commands of rspeak, with the text of the built-in help.
- (no command)
- In a terminal, opens the interactive interface: the messages with their recipients and history; write and send, revoke, remind, delete old messages. In a pipe, shows this guide.
- send [options] [TEXT]
- Sends a message to the recipients given with --to. Without TEXT or --file, the text is read from stdin.
- list
- Lists the messages sent, with how many recipients have confirmed each one.
- status ID
- Shows the text of the message and the state of each recipient: sent, delivered (in their mailbox) or confirmed, with date, time and channel.
- revoke ID
- Revokes a message: whoever has not seen it yet will not see it, and dialogs and questions still open close by themselves.
- remind ID
- Reminds whoever has not confirmed yet: the question comes back at their next prompt and the dialog reappears on the desktop, even if they had postponed it.
- log ID
- Shows the history of the message from the system log: sending, deliveries, postponements, confirmations and revocation, with date and time.
- purge DURATION
- Deletes the messages sent more than DURATION ago (for example 90d), with the copies and confirmations in the users' mailboxes; the events stay in the system log.
- version
- Shows the RootSpeak version.
- help, --help, -h
- Shows this guide.
13.3 · Send options
The options of rspeak send. They must be written before the text of the message; in the TUI they correspond to the fields of the new message (chapter 5.4).
- --to DEST
- Recipients, separated by commas without spaces: a user (mario), a Unix group (@developers), all (every human user) or online (only those logged in now).
- --title TITLE
- Title shown in the message header and in the desktop dialog.
- --expires DURATION
- Expiry, after which the message is no longer shown: 30m, 2h, 3d or a date and time ("2026-10-04 12:00").
- --file FILE
- Reads the message text from FILE.
| Option | TUI field |
|---|---|
--to | To |
--title | Title |
--expires | Expires |
--file | Text, or Ctrl+E to open it in the editor |
13.4 · Examples
| Command | What it does |
|---|---|
rspeak send --to mario "Your account expires on Friday." | Message with read confirmation to a single user. |
rspeak send --to @developers --title Maintenance --file notice.txt | Text taken from a file, with a title, to every member of the developers group. |
rspeak send --to online --expires 15m "Reboot at 13:00." | Urgent notice to whoever is logged in now; after 15 minutes it is no longer shown or asked about. |
rspeak send --to all --expires 3d "New password policy." | To every user; after three days it stops being shown. |
rspeak list | Which messages were sent and how many confirmations they have. |
rspeak status 12 | Who confirmed message 12, when and from where. |
rspeak log 12 | The history of message 12: sending, deliveries, postponements, confirmations. |
rspeak purge 90d | Deletes the messages older than 90 days, with copies and confirmations. |
rspeak revoke 12 | Revokes message 12. |
rspeak remind 12 | Asks again, right now, whoever has not confirmed message 12. |
13.5 · Exit status and environment
| Exit status | Meaning |
|---|---|
0 | Completed successfully. |
1 | Error: the error message, starting with “rspeak:”, says which (chapter 12.1). |
The exit status makes it possible to use rspeak in scripts:
admin@server:~$ rspeak send --to online --expires 15m "Reboot at 1 pm." || echo "sending failed"
Message 7 sent to 3 users.| Variable | Effect |
|---|---|
PAGER | the program that pages the help on small terminals (default: less) |
NO_COLOR | if set, disables colours |
VISUAL, EDITOR | the editor opened with Ctrl+E in the new message |
Chapter 14
Glossary
14.1 · Terms
- all
- Special recipient: all the users of the machine with a UID of 1000 or above and a real shell.
- built-in help
- The tabbed help that opens with
rspeak --help. - channel
- Where a confirmation came from:
desktoporterminal pts/Norterminal ttyN. - confirmation
- The user's statement that they have read a message: a click on “I have read it” or the answer “y”. It is final and applies to all their sessions.
- confirmed
- Third state of a recipient: they have stated that they read the message. It is their statement, not proof that they really read it.
- delivered
- Second state: the copy of the message is in the user's mailbox, and the user has not confirmed yet. Whoever postpones stays delivered.
- desktop agent
- The small RootSpeak program that starts at every graphical login and shows the confirmation dialogs. It is not a command: it starts by itself.
- event
- A fact in the history of a message (sending, delivery, postponement, reminder, confirmation, revocation, deletion), written to the system log.
- expiry
- The moment after which a message is no longer shown (
--expires). Expired is a property of the message, not a state of the recipients. - mailbox
- The space where RootSpeak keeps a user's messages, their confirmations and their postponements. Only they (and root) can open it.
- message store
- The folder
/var/lib/rootspeak/: the reference copies of the messages and the users' mailboxes. - online
- Special recipient: among the users of
all, those logged in at the moment of sending. - postpone
- Pressing “Later” or answering anything other than “y”: the message is shown again after 30 minutes. It is not a state.
- purge
- Deleting the messages older than a given duration:
rspeak purgeor thepkey in the TUI. - recipients
- The users who receive a message: names,
@group,all,online. - recovery
- The automatic completion of a sending left halfway, the next time
rspeakis used. - remind
- Asking again, immediately, for the confirmation from those who are still delivered:
rspeak remindor themkey in the TUI. - revoke
- Withdrawing a message with
rspeak revokeor therkey: whoever has not seen it will no longer see it. Revoked is a property of the message, not a state of the recipients. - sent
- First state: the message has left, but the copy is not yet in the user's mailbox.
- session
- A user's access to the machine: the desktop, a console, an ssh connection.
- system log
- The machine's log (the journal), where RootSpeak writes its events with the tag
rspeak. - TUI
- The full-screen interface, inside the terminal, that opens when you type
rspeakon its own.