9.9 KiB
9.9 KiB
05 — The tools each module serves
A first catalogue for the modules of research 026 and 027, as the operator asked: "all kinds of useful
tools for all these modules". Each tool is served by the node's runtime (ADR 0175), on the machine the
module runs on. Through discovery (ADR 0195) it is reachable from any machine as
<machine>/<module>.<tool>, or as <machine>/<seat>.<verb> where a seat defines it.
Conventions:
- (r) reads.
- (a) acts on the machine, escalating where it must, as the packet filter does (to-be 38 WP4).
- (d) is a desktop act that needs the operator's session.
- A tool that changes something a module declares says so in its answer: the next push restores the declaration.
- Every tool answers structured data, not prose (issue 229).
- Seat verbs (marked seat) are the protocol every holder of that seat serves. The rest are the module's own.
The graphical session (026)
| module | tools |
|---|---|
xorg (node-display-server) |
seat displays (r: outputs, modes, rates, connected monitors with their identity) · seat layout (r/a: list, save, apply an autorandr profile) · set-mode (a: one output's resolution, rate, rotation, scale) · primary (a) · dpi (r/a) · input-devices (r) · input-set (a: touchpad tap, natural scroll, pointer speed) · keyboard (r/a: layout and options) · screenshot (d: one screen or all, as a file) · x-log (r: the server's errors since start) |
i3 (node-display-session) |
seat reload (a) · seat workspaces (r) · seat windows (r: tree with classes, titles, workspaces) · focus (d: window or workspace) · move (d: window to workspace or output) · layout-save / layout-restore (d: a workspace's arrangement) · exec (d: start a program in the session) · kill (d) · bindings (r: every key binding and what it runs) · config-check (r: validate the composed configuration before a reload) · marks (r) · scratchpad (d) |
sway (node-display-server, node-display-session) |
the same seat verbs over Wayland, plus outputs (r) and idle-inhibitors (r) |
lemurs (node-login-manager) |
seat sessions (r: what the login screen offers) · seat default-session (r/a) · logins (r: who logged in when, from the journal) |
xterm (node-terminal-emulator) |
seat open (d: a terminal, optionally running a command, in a directory) · font (r/a: face and size) · colours (r) |
i3status-rust (node-bar) |
seat reload (a) · blocks (r: what the bar shows and each block's current value) · block-run (r: run one block once and answer its output) · themes (r) |
picom (node-compositor) |
seat restart (a) · rules (r: opacity, shadow and blur rules in force) · window-opacity (d) · toggle (d: compositing off and on, for a game or a test) |
rofi (node-launcher) |
seat menu (d: show a list, answer the chosen line: the dmenu-compatible command as a tool) · applications (r: the desktop entries it would offer) · themes (r) · run (d) |
dmenu (node-launcher) |
seat menu (d) |
dunst (node-notifier) |
seat send (d: title, body, urgency, actions) · seat history (r) · pause / resume (d: do not disturb) · close-all (d) · rules (r) · count (r: shown, waiting, history) |
| lock module (node-lock-screen) | seat lock (d) · idle (r/a: screensaver and display power timeouts) · inhibit (d: keep the screen on for a while) · locked (r: is the session locked now, and since when) |
| clipboard manager (node-clipboard) | seat history (r: entries, newest first, length-limited) · seat copy (d: put text on the clipboard) · paste (r: what the clipboard holds now) · clear (d) · delete (d: one entry) |
xclip |
copy (d) · paste (r): the plain clipboard without a manager |
feh (wallpaper) |
set (d: an image, per output) · current (r) |
fonts |
families (r: installed faces) · match (r: what monospace, sans-serif and emoji resolve to) · glyph (r: which installed font has a given character) · cache-rebuild (a) |
| theme module | appearance (r/a: dark or light, for GTK, Qt and the portal at once) · cursor (r/a) · icons (r) · portal-check (r: which portal backend answers which interface) |
gnome-keyring (node-secret-service) |
seat unlocked (r) · lock (d) · collections (r: names and item counts, never secrets) · ssh-keys (r: what the agent holds, by fingerprint) |
| desktop hardware module (laptop) | brightness (r/a: panel and keyboard) · battery (r: charge, health, cycles, limit) · charge-limit (r/a) · gpu-mode (r/a: integrated, hybrid, discrete) · seat profile (r/a: quiet, balanced, performance) · thermals (r: temperatures and fan speeds) · power-draw (r) |
The system and the account (027)
| module | tools |
|---|---|
docker (node-container-runtime, ADR 0166) |
seat list, inspect, logs, stats, start, stop, restart (r/a) · images (r: with size and which container uses each) · prune (a: dangling images, stopped containers not held by the mesh, build cache, with a dry run first) · disk-usage (r) · networks (r) · volumes (r: with what mounts each and whether the mesh holds it) · events (r: the last hour) · daemon-config (r) |
docker-compose |
projects (r: compose projects running and where their files are) · up / down / restart (a: one project, by directory) · logs (r) · ps (r) |
sudo |
rules (r: what the account may run, without a prompt and with one) · check (r: does the escalation the mesh relies on work here) |
pacman |
search (r) · installed (r: with version and explicitly or as a dependency) · info (r) · owns (r: which package owns a path) · files (r) · updates (r: what an upgrade would change) · upgrade (a: with the news first) · orphans (r) · remove-orphans (a) · cache (r/a: size, clean to the last N versions) · history (r: installs and upgrades from the log) · mirrors (r/a: rank and refresh) · news (r: distribution news since the last upgrade) |
| AUR (package repository, 027 question 1) | search (r) · build (a: on the build machine, into the mesh's repository) · outdated (r) · published (r) |
snapd, flatpak |
list (r) · install / remove (a) · update (a) · runtimes (r) · disk-usage (r) |
time-sync |
status (r: synchronised, offset, server) · servers (r) · sync-now (a) |
localization |
get (r: locale, time zone, keymap) · time-zone (r/a) · locales (r) |
kernel |
running (r: version, command line, uptime) · installed (r) · modules (r: loaded, with what uses them) · reboot-needed (r: a newer kernel or library than the one running) · microcode (r) · boot-entries (r) · initramfs-rebuild (a) · dmesg (r: errors since boot) |
logrotate |
status (r: last rotation per log) · force (a: one configuration) · big-logs (r: the largest logs on the machine) |
avahi |
browse (r: services on the local network) · resolve (r) |
cups |
printers (r) · queue (r) · cancel (a) · print (a: a file to a printer) · default (r/a) |
bluetooth |
devices (r: paired, connected, battery where reported) · connect / disconnect (a) · scan (r) · power (r/a) |
ssh-client (owns ~/.ssh) |
hosts (r: every Host and where it came from: the mesh, a module, the operator) · check (r: modes, keys without a passphrase, keys unused for a year, stale known_hosts entries) · authorized (r: who may log in, by fingerprint and comment) · revoke (a: one authorized key, into the operator's region) · known-host (r/a: verify, refresh one host's key) · test (r: can this machine reach a host and authenticate, batch mode) |
sshd |
sessions (r: who is logged in, from where) · config-effective (r: sshd -T) · failed-logins (r: since a time, with fail2ban's verdicts) |
| scripts modules | list (r: each script with its one-line description) · run (a: one script by name with arguments, as the account, bounded like execute) · which (r: which module ships a command) |
node-env (node-environment) |
show (r: every variable and PATH entry with the module that contributed it) · diff (r: what a shell actually has versus what the mesh composed) |
zsh (node-login-shell) |
seat execute · zsh_config (r) · history-search (r: the account's history, by pattern) · functions (r: aliases and functions in force, with where each came from) · startup-time (r: how long an interactive shell takes to start, per slot) |
memory-pressure |
status (r: memory, swap, compressed swap ratio, pressure stall) · top (r: the largest processes) · oom-history (r: what was killed, when) |
zfs |
pools (r: health, capacity, fragmentation) · datasets (r) · snapshots (r/a: list, create, destroy by name) · scrub (r/a: status, start) · errors (r) · arc (r: cache statistics) |
nfs-server, samba |
exports / shares (r) · clients (r: who has it mounted now) · reload (a) |
nfs-client, smb-client |
mounts (r: each share, mounted or not, and since when) · mount / unmount (a) · test (r: is the server reachable, is the export offered) |
| hosts-file holder (node-hosts-file, ADR 0199) | seat entries, add, remove |
vnstat, lm_sensors |
traffic (r: per interface, day, month) · sensors (r) |
| mail consumer (future effort) | accounts (r) · search (r) · unread (r) · read (r: one message) · mark (a) · send (a) |
What this catalogue is for
It is a starting list, not a contract. A tool becomes a contract only when it is a seat's verb, and each seat's verbs are decided in that seat's record (ADR 0132). A module's own tools can grow freely. Every row above is a tool the operator would otherwise run by hand over ssh. That is the measure of whether one is worth writing.