clavarium 0.0.2 → 0.1.0-next.2

package/deploy/clavarium-host

@@ -0,0 +1,720 @@
+#!/bin/bash
+# ---------------------------------------------------------------------------
+# THE ONLY PRIVILEGED THING THE SERVER MAY DO.
+#
+# The server runs as an account with no rights. Everything that needs root --
+# driving the VM manager, making a read-only view, loading network rules --
+# goes through this one program, called with sudo, and the sudoers rule names
+# this program and nothing else.
+#
+# It accepts a FIXED LIST of verbs, in the exact forms the server makes, and
+# refuses everything else by name. It is not a general tool and must not
+# become one: each verb added here is a thing a compromised server can do.
+#
+# WHAT IT WILL NOT DO, whatever is asked:
+#   - mount anything but a shared folder, a view of one, a work folder or
+#     the read-only view of the tools folder into a VM. A mount is served as root: any other path would be a way to
+#     read the host's files;
+#   - follow a path the server could have bent. A compromised server could
+#     replace a folder by a link to /etc and ask for it to be mounted, or
+#     swap a directory between our check and the mount. Hence: everything
+#     this program mounts, unmounts or moves lives under $MNT (below), on a
+#     chain root owns; the entries are made and moved by this program only,
+#     and the chain is checked before each use;
+#   - touch a VM whose name is not one of ours ("clv-" + a conversation name,
+#     or "clvshelf-" + a date for a ready-made machine: see "shelf" below);
+#   - load a network rule that is not, line for line, one of the known shapes.
+#
+# Every name is checked HERE, even though the server checked it already: this
+# is where a string becomes a root command.
+#
+#   --say-only   print the command instead of running it. For tests: a flag,
+#                never an environment variable -- in a privileged program, a
+#                variable that changes what runs is the hole being closed.
+#   --data DIR   the data directory; honoured ONLY with --say-only. Otherwise
+#                it is read from /etc/clavarium/host.conf, which root owns.
+#   --mnt DIR    where the shared folders live ($MNT, see below); the same
+#                rule: --say-only only, else MNT= in host.conf.
+#
+# WHY THE SHARED FOLDERS ARE NOT IN THE DATA DIRECTORY. The data directory
+# belongs to the server's account, so a compromised server could rename any
+# of its directories between our check and the moment mount or systemd walks
+# the path. So everything that gets mounted, unmounted or moved as root lives
+# under $MNT instead -- resources/ (the folders), views/ (their read-only
+# views), work/ and work-disks/ (the conversations' work disks), removed/
+# (what was put aside), toolbox/ (the tools every machine sees at /tools) -- a chain of directories that root owns from / down:
+# no component of it can be swapped by the server (renaming needs write
+# access to the parent). `held` checks that chain before each use. The data
+# directory keeps only the server's own files, which root never touches.
+#
+# Exit codes: the command's own; 64 usage; 78 refused, with the reason.
+# "git read" has its own fixed codes, listed at that verb.
+# ---------------------------------------------------------------------------
+set -euo pipefail
+
+MULTIPASS="multipass"
+IMAGE="24.04"
+DISK="8G"
+LAUNCH_SECONDS="900"
+BRIDGE="mpqemubr0"
+TABLE="clavarium"
+VM_ID="1000"
+# The size of the disk a conversation works in, in megabytes: 10 GB unless
+# /etc/clavarium/host.conf says otherwise (WORK_MB=...). Room on the host is
+# taken only as the disk is filled, and given back when files are removed.
+WORK_MB="10240"
+# THE READY-MADE MACHINE ("shelf"): a machine prepared in advance -- system
+# updated, shared folders possible, Node.js and the tools installed -- then
+# stopped, and COPIED for each new conversation with `multipass clone`
+# (Multipass 1.15 and later). A copy boots in a minute or two instead of being
+# built for six. It is only ever a source: no conversation runs in it.
+SHELF_MEMORY="1536M"
+# Where the VM manager keeps its machines' disks: a rebuild is refused when
+# less than this is free there, so that a new copy cannot fill the host.
+SHELF_STORE="/var/snap/multipass/common"
+SHELF_INSTANCES="$SHELF_STORE/data/multipassd/vault/instances"
+SHELF_MIN_FREE_MB="6144"
+CONF="/etc/clavarium/host.conf"
+# THE GIT READER (verb "git read"): an empty root-owned directory used as the
+# sandbox's root, and the fixed script run inside it. Both made by install.sh.
+RUNNER_ROOT="/var/lib/clavarium/runner-root"
+GIT_READ="/usr/lib/clavarium/git-read"
+LOCKS="/run/clavarium"
+# THE UPDATER (verbs "update ..."): the release that runs, its Node.js and its
+# updater, all root's (install.sh, deploy/updater.mjs). A request for the
+# updater's service is written where only root writes.
+CODE="/opt/clavarium"
+UPDATER_NODE="$CODE/current/node/bin/node"
+UPDATER="$CODE/current/app/deploy/updater.mjs"
+UPDATE_STATE="/var/lib/clavarium/update"
+
+refuse() { echo "REFUSED: $*" >&2; exit 78; }
+usage() { echo "usage: clavarium-host [--say-only [--data DIR] [--mnt DIR]] <vm|shelf|folder|work|view|tools|net|git|server|update> <verb> [arguments]" >&2; exit 64; }
+
+SAY="no"; DATA=""; MNT=""
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --say-only) SAY="yes"; shift ;;
+        --data) [ "$SAY" = "yes" ] || refuse "--data is only for --say-only"; DATA="${2:-}"; shift 2 ;;
+        --mnt) [ "$SAY" = "yes" ] || refuse "--mnt is only for --say-only"; MNT="${2:-}"; shift 2 ;;
+        *) break ;;
+    esac
+done
+if [ -z "$DATA" ]; then
+    [ -r "$CONF" ] || refuse "$CONF is missing: the data directory is not declared"
+    DATA="$(sed -n 's/^DATA=//p' "$CONF" | head -1)"
+fi
+if [ -z "$MNT" ]; then
+    if [ "$SAY" = "yes" ]; then MNT="$DATA"
+    else
+        MNT="$(sed -n 's/^MNT=//p' "$CONF" | head -1)"
+        [ -n "$MNT" ] || refuse "MNT is not declared in $CONF: run install.sh again"
+    fi
+fi
+if [ -r "$CONF" ]; then
+    asked="$(sed -n 's/^WORK_MB=//p' "$CONF" | head -1)"
+    if [ -n "$asked" ]; then
+        [[ "$asked" =~ ^[0-9]{2,7}$ ]] && [ "$asked" -ge 64 ] || refuse "WORK_MB in $CONF must be a number of megabytes, 64 at least"
+        WORK_MB="$asked"
+    fi
+fi
+case "$DATA" in /*) : ;; *) refuse "the data directory must be an absolute path" ;; esac
+case "$DATA" in *[!A-Za-z0-9/._-]*|*..*) refuse "the data directory has an unexpected character" ;; esac
+# MNT goes into a systemd property list (git read): a space or a colon there
+# would split it. The same characters as DATA, nothing else.
+case "$MNT" in /*) : ;; *) refuse "MNT must be an absolute path" ;; esac
+case "$MNT" in *[!A-Za-z0-9/._-]*|*..*) refuse "MNT has an unexpected character" ;; esac
+
+run() { if [ "$SAY" = "yes" ]; then printf '%s\n' "$*"; else exec "$@"; fi; }
+
+# A conversation or folder name: lower-case letters, digits, hyphens; starts
+# with a letter; no trailing hyphen; 32 at most. The same rule as the server.
+is_name() { [[ "$1" =~ ^[a-z]([a-z0-9-]{0,30}[a-z0-9])?$ ]]; }
+vm_of() { is_name "${1#clv-}" && [ "$1" != "${1#clv-}" ] || refuse "not one of our VMs: ${1:-<empty>}"; }
+number() { [[ "$1" =~ ^[0-9]{1,6}$ ]] || refuse "not a number: ${1:-<empty>}"; }
+# A ready-made machine: "clvshelf-" and the moment it was started, in UTC.
+# Never "clv-...": no conversation verb can reach it, and no shelf verb can
+# reach a conversation.
+shelf_of() { [[ "${1:-}" =~ ^clvshelf-[0-9]{8}-[0-9]{6}$ ]] || refuse "not one of our ready-made machines: ${1:-<empty>}"; }
+memory_ok() { number "$1"; [ "$1" -ge 512 ] && [ "$1" -le 65536 ] || refuse "memory out of bounds: $1"; }
+# Megabytes free where the VM manager keeps its disks.
+store_free() { local at="$SHELF_STORE"; [ -d "$at" ] || at="/var"; df -m --output=avail "$at" | tail -1 | tr -d ' '; }
+# The largest disk a conversation's machine may have, in gigabytes: the
+# server's own bound (DISK_MAX_GB in server/conversations.mjs).
+DISK_MAX_GB="256"
+# Whole gigabytes of a size as the VM manager writes it ("8.0GiB", "16G",
+# "16384M", bytes), rounded down; nothing when it has another shape.
+size_gb() {
+    [[ "${1:-}" =~ ^([0-9]{1,12})(\.[0-9]{1,3})?([KMGT]?)(i?B)?$ ]] || return 0
+    local n="${BASH_REMATCH[1]}"
+    case "${BASH_REMATCH[3]}" in T) echo $((n * 1024)) ;; G) echo "$n" ;; M) echo $((n / 1024)) ;; K) echo $((n / 1048576)) ;; *) echo $((n / 1073741824)) ;; esac
+}
+# Room to grow a disk from <has> to <wants> gigabytes, with <free> megabytes
+# free where the VM manager keeps its disks: what it grows by may all be
+# filled, and the same minimum as for a ready-made machine must stay free.
+grow_room() {
+    local has="$1" wants="$2" free="$3" need
+    need=$(( (wants > has ? wants - has : 0) * 1024 + SHELF_MIN_FREE_MB ))
+    [ "$free" -ge "$need" ] || refuse "only ${free} MB free for machines; growing this disk from ${has} to ${wants} GB needs ${need} MB"
+}
+
+# HELD: the path cannot be bent by anyone but root. Every component from /
+# down to the entry's parent is a real directory (not a link), belongs to
+# root, and is writable by nobody else; the entry itself is a real directory.
+# Then what systemd or mount walks a moment later is the path checked here:
+# swapping a component (rename, RENAME_EXCHANGE) needs write access to its
+# parent, which only root has. The entry itself may be the server's (a
+# folder it fills); what is inside it is the agent's business, not a path.
+held() { [ "$SAY" = "yes" ] || held_check "$1"; }
+held_check() {
+    local path="$1" at="" part
+    case "$path" in /*) : ;; *) refuse "not an absolute path: $path" ;; esac
+    local parent="${path%/*}"
+    IFS='/' read -r -a parts <<< "${parent#/}"
+    [ -d / ] && [ "$(stat -c %u /)" = "0" ] || refuse "/ is not root's"
+    for part in "${parts[@]}"; do
+        [ -n "$part" ] || continue
+        at="$at/$part"
+        [ -d "$at" ] && [ ! -L "$at" ] || refuse "$at is not a plain directory"
+        [ "$(stat -c %u "$at")" = "0" ] || refuse "$at does not belong to root"
+        case "$(stat -c %A "$at")" in ?????w????|????????w?) refuse "$at may be written by others than root" ;; esac
+        # The mode bits are not the whole story: an access list can give
+        # another account write access while they still read 0755. ls marks
+        # such a directory with a '+' after the mode.
+        acl_free "$at" || refuse "$at has an access list (getfacl): only root may write it"
+    done
+    [ -d "$path" ] && [ ! -L "$path" ] || refuse "not a plain directory: $path"
+}
+acl_free() { local mode; mode="$(ls -ld -- "$1" | cut -d' ' -f1)"; [ "${#mode}" -eq 10 ]; }
+# One of the directories under $MNT that only root may arrange (resources,
+# views, work, work-disks, removed, toolbox): made if missing, refused if it is a link
+# or belongs to anyone else -- then its entries cannot be trusted either --
+# and HELD (above), with the whole chain above it.
+kept() {
+    [ "$SAY" = "yes" ] && return 0
+    case "$1" in resources|views|work|work-disks|removed|toolbox) : ;; *) refuse "not one of root's directories: $1" ;; esac
+    local d="$MNT/$1"
+    [ -e "$d" ] || [ -L "$d" ] || install -d -o root -g root -m 0755 "$d"
+    [ -d "$d" ] && [ ! -L "$d" ] && [ "$(stat -c %u "$d")" = "0" ] \
+        || refuse "$d must be a directory that belongs to root (chown root:root, once, by hand)"
+    held "$d"
+    # It is itself the parent of what gets mounted or moved: only root may
+    # write it, or an entry could be swapped there.
+    held "$d/."
+}
+# A folder of ours: a real directory, directly under resources/, on a held chain.
+folder_of() {
+    kept resources
+    [ "$SAY" = "yes" ] && return 0
+    [ -d "$MNT/resources/$1" ] && [ ! -L "$MNT/resources/$1" ] || refuse "no such folder: $1"
+    held "$MNT/resources/$1"
+}
+
+# How a finished read unit is said to the server: from what systemd recorded,
+# never from what the code inside printed. See "git read".
+unit_code() {
+    local result="$1" how="$2" status="$3"
+    case "$result" in
+        timeout) echo 80 ;;
+        oom-kill) echo 81 ;;
+        signal|core-dump) echo 82 ;;
+        exit-code)
+            # 1: the process exited (2 killed, 3 dumped: told by Result above).
+            if [ "$how" != "1" ] || ! [[ "$status" =~ ^[0-9]{1,3}$ ]]; then echo 79
+            elif [ "$status" = "128" ]; then echo 65
+            elif [ "$status" = "3" ]; then echo 67
+            # 200-243: systemd could not start the process. The wrapper turns
+            # every other code of git into 66, so these are systemd's own.
+            elif [ "$status" -ge 200 ] && [ "$status" -le 243 ]; then echo 79
+            else echo 66
+            fi ;;
+        *) echo 79 ;;
+    esac
+}
+
+[ $# -ge 2 ] || usage
+AREA="$1"; VERB="$2"; shift 2
+
+case "$AREA $VERB" in
+    "vm launch")
+        [ $# -eq 2 ] || usage; vm_of "$1"; memory_ok "$2"
+        run "$MULTIPASS" launch "$IMAGE" --name "$1" --memory "${2}M" --disk "$DISK" --cpus 1 --timeout "$LAUNCH_SECONDS" ;;
+    "vm clone")
+        # <shelf> <vm> <memory>: a conversation's machine, copied from the
+        # ready-made one (which must be stopped: Multipass refuses otherwise).
+        # A copy has the size of its source; its memory is set before its
+        # first start, while it is still stopped.
+        [ $# -eq 3 ] || usage; shelf_of "$1"; vm_of "$2"; memory_ok "$3"
+        if [ "$SAY" = "yes" ]; then
+            printf '%s\n' "$MULTIPASS clone $1 --name $2" "$MULTIPASS set local.$2.memory=${3}M"; exit 0
+        fi
+        "$MULTIPASS" clone "$1" --name "$2"
+        exec "$MULTIPASS" set "local.$2.memory=${3}M" ;;
+    "vm exec")
+        [ $# -ge 1 ] || usage; vm_of "$1"; [ "${2:-}" = "--" ] || refuse "exec takes: <vm> -- <command...>"
+        [ $# -ge 3 ] || usage
+        vm="$1"; shift 2
+        run "$MULTIPASS" exec "$vm" -- "$@" ;;
+    "vm info")
+        [ $# -eq 1 ] || usage; vm_of "$1"
+        run "$MULTIPASS" info "$1" --format json ;;
+    "vm start"|"vm stop"|"vm suspend")
+        [ $# -eq 1 ] || usage; vm_of "$1"
+        run "$MULTIPASS" "$VERB" "$1" ;;
+    "vm kill")
+        # A stop that does not wait for the system inside: asked only after a
+        # clean stop hung or failed (a restart the owner asked for).
+        [ $# -eq 1 ] || usage; vm_of "$1"
+        run "$MULTIPASS" stop --force "$1" ;;
+    "vm set")
+        # <vm> memory <megabytes> | <vm> disk <gigabytes>. The VM manager
+        # takes it only from a stopped machine, and a disk only ever grows:
+        # both are its own refusals, passed on as they are.
+        vm_of "${1:-}"; [ $# -eq 3 ] || usage
+        case "$2" in
+            memory) memory_ok "$3"; run "$MULTIPASS" set "local.$1.memory=${3}M" ;;
+            disk)   [[ "$3" =~ ^[0-9]{1,4}$ ]] && [ "$3" -ge 5 ] && [ "$3" -le "$DISK_MAX_GB" ] || refuse "disk out of bounds: $3"
+                    # Refused when the host has not the room for it, whatever
+                    # the server said (its size unknown: counted from nothing).
+                    if [ "$SAY" != "yes" ]; then
+                        has="$(size_gb "$("$MULTIPASS" get "local.$1.disk" 2>/dev/null | head -1 | tr -d ' ')")"
+                        grow_room "${has:-0}" "$3" "$(store_free)"
+                    fi
+                    run "$MULTIPASS" set "local.$1.disk=${3}G" ;;
+            *) refuse "only memory and disk can be set" ;;
+        esac ;;
+    "vm size")
+        # What the machine really has, as the VM manager says it: one line
+        # for its memory, one for its disk. Anything of an unexpected shape
+        # is left out rather than passed on.
+        [ $# -eq 1 ] || usage; vm_of "$1"
+        if [ "$SAY" = "yes" ]; then printf '%s\n' "$MULTIPASS get local.$1.memory" "$MULTIPASS get local.$1.disk"; exit 0; fi
+        for key in memory disk; do
+            value="$("$MULTIPASS" get "local.$1.$key" 2>/dev/null | head -1 | tr -d ' ')" || value=""
+            if [[ "$value" =~ ^[0-9]{1,12}(\.[0-9]{1,3})?[A-Za-z]{0,3}$ ]]; then printf '%s %s\n' "$key" "$value"; fi
+        done
+        exit 0 ;;
+    "vm delete")
+        [ $# -eq 1 ] || usage; vm_of "$1"
+        run "$MULTIPASS" delete --purge "$1" ;;
+    "vm mount")
+        # <vm> <folder|view> <resource> <uid> <gid>
+        [ $# -eq 5 ] || usage; vm_of "$1"; is_name "$3" || refuse "not a folder name: $3"; number "$4"; number "$5"
+        target="$1:/resources/$3"
+        case "$2" in
+            folder) folder_of "$3"; source="$MNT/resources/$3" ;;
+            view)   kept views; source="$MNT/views/$3"; held "$source"
+                    # A read attachment must meet the VIEW, never a bare directory.
+                    [ "$SAY" = "yes" ] || mountpoint -q "$source" || refuse "the read-only view of $3 is not in place" ;;
+            work)   # The work folder of a conversation goes to ITS machine, and to no other.
+                    [ "$1" = "clv-$3" ] || refuse "a work folder belongs to its own conversation"
+                    kept work; source="$MNT/work/$3"; held "$source"
+                    # Its DISK must be in place: a bare directory there would be the
+                    # host's own disk, with no limit.
+                    [ "$SAY" = "yes" ] || mountpoint -q "$source" || refuse "the work disk of $3 is not in place"
+                    target="$1:/work" ;;
+            tools)  # The tools every machine is given, through their read-only view only.
+                    [ "$3" = "tools" ] || refuse "the tools are mounted by that name only"
+                    kept toolbox; source="$MNT/toolbox/view"; held "$source"
+                    [ "$SAY" = "yes" ] || mountpoint -q "$source" || refuse "the read-only view of the tools is not in place"
+                    target="$1:/tools" ;;
+            *) refuse "a mount is of a folder, of a view, of a work folder or of the tools" ;;
+        esac
+        run "$MULTIPASS" mount -u "$4:$VM_ID" -g "$5:$VM_ID" "$source" "$target" ;;
+    "vm unwork")
+        # The work folder is taken out of its machine (its work moves to the
+        # machine's own disk, or a move is undone).
+        [ $# -eq 1 ] || usage; vm_of "$1"
+        run "$MULTIPASS" umount "$1:/work" ;;
+    "vm umount")
+        [ $# -eq 2 ] || usage; vm_of "$1"; is_name "$2" || refuse "not a folder name: $2"
+        run "$MULTIPASS" umount "$1:/resources/$2" ;;
+    "vm untools")
+        # The tools are taken out of a machine, to be mounted again (a mount
+        # that came loose: the VM manager may still believe it is there).
+        [ $# -eq 1 ] || usage; vm_of "$1"
+        run "$MULTIPASS" umount "$1:/tools" ;;
+    "shelf launch")
+        # A new ready-made machine, from the stock image. Refused here too when
+        # the disk is short, whatever the server said: a copy of it is made for
+        # every new conversation.
+        [ $# -eq 1 ] || usage; shelf_of "$1"
+        if [ "$SAY" != "yes" ]; then
+            free="$(store_free)"
+            [ "$free" -ge "$SHELF_MIN_FREE_MB" ] || refuse "only ${free} MB free for machines; a ready-made machine needs ${SHELF_MIN_FREE_MB} MB"
+        fi
+        run "$MULTIPASS" launch "$IMAGE" --name "$1" --memory "$SHELF_MEMORY" --disk "$DISK" --cpus 1 --timeout "$LAUNCH_SECONDS" ;;
+    "shelf exec")
+        # The preparation steps (the same argument vectors as a conversation's
+        # build), run in the ready-made machine only.
+        [ $# -ge 3 ] || usage; shelf_of "$1"; [ "$2" = "--" ] || refuse "exec takes: <shelf> -- <command...>"
+        vm="$1"; shift 2
+        run "$MULTIPASS" exec "$vm" -- "$@" ;;
+    "shelf seal")
+        # Prepared: what makes a machine ITSELF is wiped, so that every copy
+        # makes its own at its first start instead of being a twin of the
+        # others. `cloud-init clean` forgets this instance (its next start is
+        # a first start: new SSH host keys, network set for the copy's own
+        # address) and empties /etc/machine-id (a new one is made at start;
+        # two machines with the same one ask for the same address). Then it
+        # is stopped: only a stopped machine can be copied.
+        [ $# -eq 1 ] || usage; shelf_of "$1"
+        if [ "$SAY" = "yes" ]; then
+            printf '%s\n' "$MULTIPASS exec $1 -- sudo -n cloud-init clean --logs --machine-id" "$MULTIPASS stop $1"; exit 0
+        fi
+        "$MULTIPASS" exec "$1" -- sudo -n cloud-init clean --logs --machine-id
+        exec "$MULTIPASS" stop "$1" ;;
+    "shelf info")
+        [ $# -eq 1 ] || usage; shelf_of "$1"
+        run "$MULTIPASS" info "$1" --format json ;;
+    "shelf delete")
+        [ $# -eq 1 ] || usage; shelf_of "$1"
+        run "$MULTIPASS" delete --purge "$1" ;;
+    "shelf size")
+        # Megabytes it takes on the host (shown in Settings).
+        [ $# -eq 1 ] || usage; shelf_of "$1"
+        if [ "$SAY" = "yes" ]; then printf 'du -sm %s\n' "$SHELF_INSTANCES/$1"; exit 0; fi
+        [ -d "$SHELF_INSTANCES/$1" ] || refuse "no such ready-made machine: $1"
+        printf 'size %s\n' "$(du -sm "$SHELF_INSTANCES/$1" | cut -f1)"
+        exit 0 ;;
+    "shelf room")
+        [ $# -eq 0 ] || usage
+        if [ "$SAY" = "yes" ]; then printf 'df %s\n' "$SHELF_STORE"; exit 0; fi
+        printf 'free %s\n' "$(store_free)"
+        exit 0 ;;
+    "shelf list")
+        # The names of the ready-made machines that exist, and of no other
+        # machine: a rebuild cut short by a restart is found and removed.
+        [ $# -eq 0 ] || usage
+        if [ "$SAY" = "yes" ]; then printf '%s\n' "$MULTIPASS list --format csv (ready-made machines only)"; exit 0; fi
+        "$MULTIPASS" list --format csv | cut -d, -f1 | grep -E '^clvshelf-[0-9]{8}-[0-9]{6}$' || true
+        exit 0 ;;
+    "server room")
+        # WHAT THE SERVER HAS LEFT, for Settings (This server) and for the
+        # reserve that creating, starting, waking or growing a machine must
+        # leave. Read-only, no argument, nothing asked of any machine (a
+        # machine asleep stays asleep). Numbers and our own names only:
+        #   place <machines|data|folders> <device> <size MB> <free MB>
+        #   memory <total MB> <available MB>
+        #   machine <one of our VMs> <resident MB>
+        [ $# -eq 0 ] || usage
+        if [ "$SAY" = "yes" ]; then printf '%s\n' "df $SHELF_STORE $DATA $MNT" "/proc/meminfo" "resident memory of the processes of our machines"; exit 0; fi
+        store="$SHELF_STORE"; [ -d "$store" ] || store="/var"
+        for place in "machines:$store" "data:$DATA" "folders:$MNT"; do
+            what="${place%%:*}"; at="${place#*:}"
+            [ -d "$at" ] || continue
+            sizes="$(df -Pm -- "$at" | awk 'NR==2 && $2 ~ /^[0-9]+$/ && $4 ~ /^[0-9]+$/ {print $2, $4}')" || sizes=""
+            [ -n "$sizes" ] && printf 'place %s %s %s\n' "$what" "$(stat -c %d -- "$at")" "$sizes"
+        done
+        awk '/^MemTotal:/{t=$2} /^MemAvailable:/{a=$2} END{printf "memory %d %d\n", t/1024, a/1024}' /proc/meminfo
+        # A machine is a qemu process whose disk is in one of our instances.
+        for pid in $(pgrep qemu-system || true); do
+            vm="$(tr '\0' '\n' < "/proc/$pid/cmdline" 2>/dev/null | grep -oE '/instances/clv(shelf)?-[a-z0-9-]+/' | head -1 | cut -d/ -f3)" || vm=""
+            [ -n "$vm" ] || continue
+            rss="$(awk '/^VmRSS:/{print int($2/1024)}' "/proc/$pid/status" 2>/dev/null)" || rss=""
+            [ -n "$rss" ] && printf 'machine %s %s\n' "$vm" "$rss"
+        done
+        exit 0 ;;
+    "server usage")
+        # WHAT TAKES THE ROOM, for Settings: this server's own data, the
+        # folders given to machines, their work disks, what was put aside,
+        # the tools; the disks of the machines, the ready-made machine and
+        # the images the VM manager keeps. Read-only, no argument; each
+        # measure bounded in time (slow: the server asks it now and then).
+        #   used <data|folders|work|removed|tools|shelf|images|others> <MB>
+        #   used machine <one of our VMs> <MB>
+        [ $# -eq 0 ] || usage
+        if [ "$SAY" = "yes" ]; then printf '%s\n' "du $DATA $MNT/resources $MNT/work-disks $MNT/removed $MNT/toolbox/files" "du $SHELF_INSTANCES $SHELF_STORE/cache"; exit 0; fi
+        mb() { { timeout 60 du -smx "$@" 2>/dev/null || true; } | awk '$1 ~ /^[0-9]+$/ {s+=$1} END{print s+0}'; }
+        # The data directory may hold the shared folders (MNT the same, or
+        # under it): they are counted once, in their own lines.
+        printf 'used data %s\n' "$(mb --exclude="$MNT/resources" --exclude="$MNT/views" --exclude="$MNT/work" --exclude="$MNT/work-disks" --exclude="$MNT/removed" --exclude="$MNT/toolbox" -- "$DATA")"
+        for part in "folders:resources" "work:work-disks" "removed:removed" "tools:toolbox/files"; do
+            at="$MNT/${part#*:}"
+            if [ -d "$at" ] && [ ! -L "$at" ]; then printf 'used %s %s\n' "${part%%:*}" "$(mb -- "$at")"; fi
+        done
+        ours=0; shelf=0
+        if [ -d "$SHELF_INSTANCES" ]; then
+            for at in "$SHELF_INSTANCES"/clv-* "$SHELF_INSTANCES"/clvshelf-*; do
+                [ -d "$at" ] && [ ! -L "$at" ] || continue
+                vm="${at##*/}"; size="$(mb -- "$at")"
+                if [[ "$vm" =~ ^clvshelf-[0-9]{8}-[0-9]{6}$ ]]; then shelf=$((shelf + size)); ours=$((ours + size))
+                elif is_name "${vm#clv-}"; then printf 'used machine %s %s\n' "$vm" "$size"; ours=$((ours + size)); fi
+            done
+            all="$(mb -- "$SHELF_INSTANCES")"
+            printf 'used shelf %s\n' "$shelf"
+            printf 'used others %s\n' "$(( all > ours ? all - ours : 0 ))"
+        fi
+        [ -d "$SHELF_STORE/cache" ] && printf 'used images %s\n' "$(mb -- "$SHELF_STORE/cache")"
+        exit 0 ;;
+    "folder make")
+        # The folder is made here, and given to the account that owns the data
+        # directory: the server fills it, but cannot replace it.
+        [ $# -eq 1 ] || usage; is_name "$1" || refuse "not a folder name: $1"
+        kept resources; owner="OWNER:GROUP"
+        if [ "$SAY" != "yes" ]; then
+            [ ! -e "$MNT/resources/$1" ] && [ ! -L "$MNT/resources/$1" ] || refuse "this folder exists already: $1"
+            owner="$(stat -c %u:%g "$DATA")"
+        fi
+        run install -d -o "${owner%:*}" -g "${owner#*:}" -m 0755 "$MNT/resources/$1" ;;
+    "folder aside")
+        # Taken off the list: MOVED ASIDE, never erased.
+        [ $# -eq 1 ] || usage; is_name "$1" || refuse "not a folder name: $1"
+        folder_of "$1"; kept removed
+        if [ "$SAY" != "yes" ]; then
+            ! mountpoint -q "$MNT/views/$1" || refuse "the read-only view of $1 is still open"
+        fi
+        run mv -T -n "$MNT/resources/$1" "$MNT/removed/$1-$(date -u +%Y%m%dT%H%M%SZ)-$$" ;;
+    "work make")
+        # Where a conversation's tool works: kept by the server, so that what
+        # the tool makes is seen from the page and outlives its machine.
+        #
+        # IT IS A DISK OF ITS OWN, OF A FIXED SIZE: a file of this host,
+        # formatted and mounted. A shared folder has no limit by itself, and a
+        # tool that ran away would fill the host's disk and stop everything.
+        # Here it fills ITS disk, gets an error, and nobody else notices
+        # (tried on a real machine). The file takes room only as it is filled.
+        #
+        # Asked again at each start of the server and for a machine built
+        # again: what is already in place is left as it is.
+        [ $# -eq 1 ] || usage; is_name "$1" || refuse "not a conversation name: $1"
+        img="$MNT/work-disks/$1.img"; at="$MNT/work/$1"
+        if [ "$SAY" = "yes" ]; then printf 'disk %s %sM mounted at %s\n' "$img" "$WORK_MB" "$at"; exit 0; fi
+        kept work; kept work-disks
+        [ ! -L "$at" ] && [ ! -L "$img" ] || refuse "the work folder of $1 is not what it should be"
+        [ ! -e "$img" ] || [ -f "$img" ] || refuse "the work disk of $1 is not a plain file"
+        owner="$(stat -c %u:%g "$DATA")"
+        mkdir -p "$at"
+        held "$at"
+        if [ ! -e "$img" ]; then
+            truncate -s "${WORK_MB}M" "$img.new"
+            mkfs.ext4 -q -m 0 -E "root_owner=$owner" "$img.new"
+            # Files found in a plain directory (a backup just put back) go
+            # INTO the disk: mounting over them would hide them.
+            if ! mountpoint -q "$at" && [ -n "$(ls -A "$at")" ]; then
+                tmp="$(mktemp -d -p "$MNT/work-disks")"
+                mount -o loop,nosuid,nodev "$img.new" "$tmp"
+                cp -a "$at/." "$tmp/"; umount "$tmp"; rmdir "$tmp"
+                find "$at" -mindepth 1 -delete
+            fi
+            mv "$img.new" "$img"
+        fi
+        if ! mountpoint -q "$at"; then
+            mount -o loop,nosuid,nodev,discard "$img" "$at"
+            rmdir "$at/lost+found" 2>/dev/null || true
+        fi
+        exit 0 ;;
+    "work room")
+        # How much room is left, in megabytes: in the conversation's work
+        # disk, and on the host that holds it. Asked before a move, so that
+        # one is refused instead of filling either.
+        [ $# -eq 1 ] || usage; is_name "$1" || refuse "not a conversation name: $1"
+        at="$MNT/work/$1"
+        if [ "$SAY" = "yes" ]; then printf 'df %s %s\n' "$at" "$MNT/work-disks"; exit 0; fi
+        kept work; kept work-disks
+        mountpoint -q "$at" || refuse "the work disk of $1 is not in place"
+        # "host": the room left where the disks' files grow.
+        printf 'disk %s host %s\n' "$(df -m --output=avail "$at" | tail -1 | tr -d ' ')" "$(df -m --output=avail "$MNT/work-disks" | tail -1 | tr -d ' ')"
+        exit 0 ;;
+    "work aside")
+        # The conversation is archived: its work is PUT ASIDE, never erased --
+        # as its disk, which root can mount again to read it.
+        [ $# -eq 1 ] || usage; is_name "$1" || refuse "not a conversation name: $1"
+        img="$MNT/work-disks/$1.img"; at="$MNT/work/$1"
+        if [ "$SAY" = "yes" ]; then printf 'disk %s put aside in %s\n' "$img" "$MNT/removed"; exit 0; fi
+        kept work; kept work-disks; kept removed
+        if mountpoint -q "$at"; then umount "$at"; fi
+        if [ -d "$at" ] && [ ! -L "$at" ]; then rmdir "$at" 2>/dev/null || true; fi
+        if [ -f "$img" ] && [ ! -L "$img" ]; then mv -n "$img" "$MNT/removed/$1-work-$(date -u +%Y%m%dT%H%M%SZ)-$$.img"; fi
+        exit 0 ;;
+    "view make")
+        [ $# -eq 1 ] || usage; is_name "$1" || refuse "not a folder name: $1"
+        folder_of "$1"; kept views
+        if [ "$SAY" != "yes" ]; then
+            mkdir -p "$MNT/views/$1"
+            held "$MNT/views/$1"
+            mountpoint -q "$MNT/views/$1" && exit 0
+        fi
+        run bindfs -r -o allow_other "$MNT/resources/$1" "$MNT/views/$1" ;;
+    "tools make")
+        # THE TOOLS FOLDER: what every machine is given to install by itself
+        # (an archive and an index, put there by the server), seen in each
+        # machine at /tools through a READ-ONLY VIEW -- the one way a folder
+        # was proven to stay read-only against root in the machine (see
+        # "view make"). toolbox/files is the server's to fill; toolbox/view
+        # is root's. Asked at each start of the server: what is in place
+        # stays as it is.
+        [ $# -eq 0 ] || usage
+        files="$MNT/toolbox/files"; view="$MNT/toolbox/view"
+        if [ "$SAY" = "yes" ]; then printf '%s\n' "install -d -o OWNER -g GROUP -m 0755 $files" "bindfs -r -o allow_other $files $view"; exit 0; fi
+        kept toolbox
+        [ ! -L "$files" ] && [ ! -L "$view" ] || refuse "the tools folder is not what it should be"
+        if [ ! -e "$files" ]; then owner="$(stat -c %u:%g "$DATA")"; install -d -o "${owner%:*}" -g "${owner#*:}" -m 0755 "$files"; fi
+        held "$files"
+        [ -e "$view" ] || install -d -o root -g root -m 0755 "$view"
+        held "$view"
+        mountpoint -q "$view" && exit 0
+        exec bindfs -r -o allow_other "$files" "$view" ;;
+    "view close")
+        [ $# -eq 1 ] || usage; is_name "$1" || refuse "not a folder name: $1"
+        kept views
+        if [ "$SAY" != "yes" ]; then
+            [ -e "$MNT/views/$1" ] || exit 0
+            held "$MNT/views/$1"
+            mountpoint -q "$MNT/views/$1" || exit 0
+        fi
+        run umount "$MNT/views/$1" ;;
+    "net taps")
+        [ $# -eq 0 ] || usage
+        run pgrep -a qemu-system ;;
+    "net bridge")
+        [ $# -eq 0 ] || usage
+        run ip -4 -o addr show "$BRIDGE" ;;
+    "net apply")
+        # <ruleset>: the whole table, as text. Each line must be one of the
+        # shapes the server writes; one unknown line refuses the whole.
+        [ $# -eq 1 ] || usage
+        tap='"tap-[0-9a-f]{1,12}"'; addr='[0-9]{1,3}(\.[0-9]{1,3}){3}'
+        while IFS= read -r line; do
+            [[ -z "$line"
+            || "$line" =~ ^(delete\ )?table\ bridge\ $TABLE(\ \{)?$
+            || "$line" =~ ^\ \ chain\ (between_vms|from_vm)\ \{$
+            || "$line" =~ ^\ \ \ \ type\ filter\ hook\ (forward|input)\ priority\ 0\;$
+            || "$line" =~ ^\ \ \ \ iifname\ $tap\ (drop|udp\ dport\ 67\ accept|ether\ type\ arp\ accept)$
+            || "$line" =~ ^\ \ \ \ iifname\ $tap\ ip\ daddr\ $addr\ (accept|meta\ l4proto\ \{\ tcp,\ udp\ \}\ th\ dport\ 53\ drop)$
+            || "$line" =~ ^(\ \ )?\}$ ]] || refuse "a network rule of an unknown shape: $line"
+        done <<< "$1"
+        run nft "$1" ;;
+    "git read")
+        # <name>: the branches of the agent's repository, as ONE FULL BUNDLE
+        # on stdout. The server never runs git on a folder the agent writes
+        # (its config, hooks, gitfile, links could make git do anything as the
+        # server); this verb runs ONE fixed read of it in a throw-away
+        # sandbox -- a dynamic user, no network, nothing writable, only that
+        # folder, read-only -- and the server treats what comes out as hostile.
+        #
+        # Exit codes, FIXED HERE (the code inside chooses only among 0, 65,
+        # 66, 67): 0 read; 65 git said 128 (with exactly the 17 bytes of an
+        # empty bundle: no branches); 66 git or the wrapper failed; 67 refs
+        # unreadable; 78 refused before anything ran; 79 the unit did not
+        # start or its state is unknown; 80 time limit; 81 memory limit;
+        # 82 killed by a signal.
+        [ $# -eq 1 ] || usage; is_name "$1" || refuse "not a folder name: $1"
+        case "$1" in *-origin) refuse "the reference of a repository is never read this way: $1" ;; esac
+        name="$1"
+        rand="RANDOM16"
+        [ "$SAY" = "yes" ] || rand="$(od -An -N8 -tx1 /dev/urandom | tr -d ' \n')"
+        unit="clvread-${name}_${rand}"
+        vector=(systemd-run --quiet --wait --pipe --service-type=exec "--unit=$unit"
+            -p DynamicUser=yes -p "RootDirectory=$RUNNER_ROOT" -p MountAPIVFS=no
+            -p "TemporaryFileSystem=/dev:ro /tmp:ro /var/tmp:ro /resources:ro" -p "BindPaths=/dev/null /dev/zero /dev/urandom"
+            -p DevicePolicy=closed -p "DeviceAllow=/dev/null rw" -p "DeviceAllow=/dev/zero r" -p "DeviceAllow=/dev/urandom r"
+            -p "BindReadOnlyPaths=/usr /usr/bin:/bin /usr/lib:/lib /usr/lib64:/lib64 $MNT/resources/$name:/resources/$name"
+            -p PrivateNetwork=yes -p RestrictAddressFamilies=AF_UNIX -p NoNewPrivileges=yes
+            -p CapabilityBoundingSet= -p AmbientCapabilities= -p RestrictNamespaces=yes -p RestrictSUIDSGID=yes
+            -p RestrictRealtime=yes -p LockPersonality=yes -p MemoryDenyWriteExecute=yes
+            -p SystemCallArchitectures=native -p SystemCallFilter=@system-service
+            -p "SystemCallFilter=~@aio @keyring @setuid @chown @memlock @privileged @resources userfaultfd kcmp process_vm_readv process_vm_writev msgget msgsnd msgrcv msgctl semget semop semctl shmget shmat shmdt shmctl mq_open mq_unlink"
+            -p SystemCallErrorNumber=EPERM
+            -p RuntimeMaxSec=300 -p MemoryMax=1G -p MemorySwapMax=0 -p TasksMax=8 -p CPUQuota=100%
+            -p LimitFSIZE=0 -p LimitCORE=0 -p LimitNOFILE=256 -p "WorkingDirectory=/resources/$name"
+            -E PATH=/usr/bin -E HOME=/nonexistent -E XDG_CONFIG_HOME=/nonexistent -E LC_ALL=C -E GIT_CONFIG_NOSYSTEM=1
+            -E GIT_CONFIG_GLOBAL=/dev/null -E GIT_CEILING_DIRECTORIES=/resources -E GIT_NO_LAZY_FETCH=1
+            -E GIT_TERMINAL_PROMPT=0 -E GIT_OPTIONAL_LOCKS=0 -E GIT_NO_REPLACE_OBJECTS=1
+            "$GIT_READ" "$name")
+        if [ "$SAY" = "yes" ]; then printf '%s\n' "${vector[@]}"; exit 0; fi
+        folder_of "$name"
+        [ -d "$RUNNER_ROOT" ] && [ ! -L "$RUNNER_ROOT" ] && [ -x "$GIT_READ" ] || refuse "the git reader is not installed (run install.sh again)"
+        # Nothing to read from us; and what comes out must go to the server
+        # as it is: a regular file would be killed by LimitFSIZE=0 (tried).
+        # A pipe, or a socket (what Node.js gives a child for "pipe").
+        exec 0</dev/null
+        { [ -p /dev/stdout ] || [ -S /dev/stdout ]; } && { [ -p /dev/stderr ] || [ -S /dev/stderr ]; } || refuse "stdout and stderr must be pipes"
+        install -d -o root -g root -m 0700 "$LOCKS"
+        exec 9>"$LOCKS/read-$name.lock"
+        flock -n 9 || refuse "busy: $name is being read already"
+        # Stopped whatever happens to us (the server gave up, a signal, an
+        # error here): a read never outlives the one who asked for it. The
+        # unit runs as a child we WAIT for: bash runs a trap only between
+        # commands, and `wait` is a command a signal cuts short, where a
+        # plain systemd-run in the foreground would hold the trap back
+        # until the read ended by itself.
+        child=""
+        stop_unit() { systemctl stop "$unit.service" >/dev/null 2>&1 || true; systemctl reset-failed "$unit.service" >/dev/null 2>&1 || true; }
+        gone() { stop_unit; [ -z "$child" ] || wait "$child" 2>/dev/null; exit 82; }
+        trap gone TERM INT HUP PIPE
+        trap stop_unit EXIT
+        set +e
+        "${vector[@]}" &
+        child=$!
+        wait "$child"
+        rc=$?
+        set -e
+        code=0
+        if [ "$rc" -ne 0 ]; then
+            props="$(systemctl show -p Result -p ExecMainCode -p ExecMainStatus "$unit.service" 2>/dev/null || true)"
+            code="$(unit_code "$(sed -n 's/^Result=//p' <<< "$props")" "$(sed -n 's/^ExecMainCode=//p' <<< "$props")" "$(sed -n 's/^ExecMainStatus=//p' <<< "$props")")"
+        fi
+        trap - TERM INT HUP PIPE EXIT
+        stop_unit
+        exit "$code" ;;
+    "git stop")
+        # <name>: every read of that repository is stopped, and forgotten
+        # (asked after the server gave up on a read, and at its start).
+        [ $# -eq 1 ] || usage; is_name "$1" || refuse "not a folder name: $1"
+        if [ "$SAY" = "yes" ]; then printf '%s\n' "systemctl stop clvread-$1_*.service" "systemctl reset-failed clvread-$1_*.service"; exit 0; fi
+        systemctl stop "clvread-$1_*.service" >/dev/null 2>&1 || true
+        systemctl reset-failed "clvread-$1_*.service" >/dev/null 2>&1 || true
+        exit 0 ;;
+    "update check")
+        # Asks the registry what is out on the channel, now, and prints what
+        # the updater knows (state.json). No argument: the registry, the name
+        # of the package and the channel are the updater's own, not asked.
+        [ $# -eq 0 ] || usage
+        run "$UPDATER_NODE" "$UPDATER" check ;;
+    "update set")
+        # <mode|channel|window> <value>: one setting of /etc/clavarium/update.conf.
+        [ $# -eq 2 ] || usage
+        case "$1" in
+            mode) [[ "$2" =~ ^(auto|asap|ask|off)$ ]] || refuse "not a mode: $2" ;;
+            channel) [[ "$2" =~ ^(latest|next)$ ]] || refuse "not a channel: $2" ;;
+            window) [[ "$2" =~ ^([01][0-9]|2[0-3]):[0-5][0-9]-([01][0-9]|2[0-3]):[0-5][0-9]$ ]] && [ "${2%-*}" != "${2#*-}" ] || refuse "not a window: $2" ;;
+            *) refuse "not a setting: $1" ;;
+        esac
+        run "$UPDATER_NODE" "$UPDATER" set "$1" "$2" ;;
+    "update apply"|"update rollback")
+        # <version>: done by the updater's own service, in the background, so
+        # that restarting this server does not cut it. The updater checks it
+        # again: apply only to a newer version, from the registry, verified;
+        # rollback only to a release that is kept.
+        [ $# -eq 1 ] || usage
+        [[ "$1" =~ ^[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,6}(-[0-9A-Za-z.-]{1,40})?$ ]] || { [ "$VERB" = "rollback" ] && [[ "$1" =~ ^local-[0-9]{8}-[0-9]{6}$ ]]; } || refuse "not a version: $1"
+        if [ "$SAY" = "yes" ]; then printf '%s\n' "echo $VERB $1 > $UPDATE_STATE/request" "systemctl start --no-block clavarium-update.service"; exit 0; fi
+        install -d -o root -g root -m 0755 "$UPDATE_STATE"
+        printf '%s %s\n' "$VERB" "$1" > "$UPDATE_STATE/request.new"
+        mv -f -- "$UPDATE_STATE/request.new" "$UPDATE_STATE/request"
+        exec systemctl start --no-block clavarium-update.service ;;
+    "path held")
+        # <dir>: the check `held` makes, run for real on that path, as the
+        # caller (root not needed to refuse). --say-only only: it exists so
+        # that the check can be tested without root; it changes nothing.
+        [ "$SAY" = "yes" ] || refuse "unknown verb: path held"
+        [ $# -eq 1 ] || usage
+        held_check "$1"; echo "held: $1"; exit 0 ;;
+    "disk room")
+        # <has GB> <wants GB> <free MB>: the check `vm set disk` makes, with
+        # these figures. --say-only only: it exists so that the check can be
+        # tested without a VM manager; it changes nothing.
+        [ "$SAY" = "yes" ] || refuse "unknown verb: disk room"
+        [ $# -eq 3 ] || usage; number "$1"; number "$2"; [[ "$3" =~ ^[0-9]{1,9}$ ]] || refuse "not a number: $3"
+        grow_room "$1" "$2" "$3"; echo "room: $2 GB"; exit 0 ;;
+    "git code")
+        # <Result> <ExecMainCode> <ExecMainStatus>: the exit code "git read"
+        # gives for a unit that ended so. --say-only only: it exists so that
+        # the mapping can be tested without root; it does nothing.
+        [ "$SAY" = "yes" ] || refuse "unknown verb: git code"
+        [ $# -eq 3 ] || usage
+        unit_code "$1" "$2" "$3"; exit 0 ;;
+    *)
+        refuse "unknown verb: $AREA $VERB" ;;
+esac