Every screen, every command, every flag

This page is the whole surface in one place: every screen of the web interface, the three destination surfaces that live inside one of them, and the terminal docked under them all; the twenty-four commands of the retnd command line; and every subcommand and flag of the installer. The first-run tutorial walks the one path a new install takes; this one does not walk anything, it enumerates. Scripted workflows have a guide of their own, because the hook lifecycle needs prose around its pictures rather than a table of controls.

The web interface

Seven items in the sidebar — Dashboard, Backup sets, Backups, Activity, Quarantine, Repositories, Settings — one screen behind each, detail screens you reach by opening a row on the list above them, the four incremental-engine screens a snapshot-taking backup set adds to its own page, a catalog-recovery screen reached from the footer, and a terminal docked to the bottom of all of them. The top bar carries the service badge (running, and which version), a light/dark toggle and Sign out. The sidebar footer says which platform the deployment thinks it is on, which is the thing to check first when a NAS-specific feature is missing.

Three of the surfaces below have no route of their own: the storage destinations list and the two wizards that add and configure one all live inside Settings. They are enumerated separately anyway, because each is a screenful of controls that write configuration, and a reader looking one up should not have to find it inside a table row about a card.

Nearly everything on these screens is reachable from the command line as well, and several screens say so in place: a control that changes configuration prints the retnd command that does the same thing, right underneath itself. Where the command cannot carry a field the screen is about to save, the screen prints the command and names the fields it leaves out, rather than printing a line that quietly configures less than was asked for.

Dashboard

Backup sets

Backup set detail

Snapshots

Only on a backup set running the incremental engine, reached from the set's own page. Every snapshot run this set has on record, newest first, with the phase it reached and the verification level a check actually achieved. Only a run at SUCCESS is a restore point.

Each row carries five separate measurements and no total: entries scanned, logical size, read from source, written to repository, and reused. A single “backed up” figure would report a 100 GB tree deduplicated down to 200 MB of new content as a 100 GB upload every night. A counter nobody took prints not measured and never 0, because “reused 0 bytes” sends somebody hunting a fault in a backup that is working. Row actions open the inspector, Restore, and the hold controls on Snapshot retention. The equivalent command is retnd snapshot list <source>/<set>.

Snapshot detail

One run in full: the five measurements as a metric strip, the repository domain it was stored in, the source-consistency mode that was in force when the pass ran rather than the one configured now, the verification level asked for beside the level achieved, and the transition log that says how the run reached the phase it is in. A failed verification carries no achieved level at all. retnd snapshot show <source>/<set> <run-id>.

Restore from a snapshot

Reads a restore point this deployment holds and writes a tree onto a disk it can reach. Which snapshot (the set's last known good by default), optionally one path inside it, the local directory to write into — required, and never invented, because an engine that chose the disk would fill it — and what to do when the destination already holds something: refuse (the default, which stops rather than replacing anything), skip, or overwrite. It submits one durable operation and then watches it.

Snapshot retention and holds

What snapshot retention would decide about each of this set's snapshots right now, oldest first, and it deletes nothing: KEEP names every tier that selected the snapshot, DELETE means nothing did and every safety check passed, and REFUSE means it was a delete candidate and something stopped it — the only one of the three that needs somebody to look at it. The same GFS chain that retains artifacts decides this; there is no second policy.

Place a hold stops retention deleting one snapshot until somebody releases it, and a reason is required: a hold nobody explained is one nobody dares release, which makes it permanent by accident. A hold names who placed it and why, and separately who released it and when. Release this hold deletes nothing — it returns the snapshot to whatever the policy already said about it. retnd snapshot retention, snapshot hold, snapshot holds, snapshot unhold.

Backups

Each row opens that artifact's own detail page.

Backup detail

Two cards and a list, and no button among them. Artifact is the recorded facts: id, remote original path, the ingestion path (a path on disk, not proof a readable file is sitting there), producer and received timestamps, size, checksum, and which retention classes selected it. Lifecycle is the same timeline the dashboard's live view feeds, at rest: discovered, transferred, verified, committed, remote source removed. Below both, the copies list names where the bytes actually are, one row per storage medium, each with its own verification class and whether reading it back needs a restore first.

Workflow run

Reached from the Workflow panel on a backup set, at /workflow-runs/{run}. One run of the hook lifecycle wrapped around one backup: all five stages in execution order, including the ones that had no directory to run, because “the global after stage did not run” and “this deployment has no global after directory” are opposite facts when a database has been left quiesced.

Three statuses, side by side, none derived from the others — backup, workflow and cleanup — since “the backup succeeded and the cleanup did not” means a machine may still be sitting quiesced with a good backup beside it. A failed workflow names the script that ended it. A run whose hooks were bypassed reports its workflow status as skipped and says so, rather than showing a verdict for scripts nothing executed. Each step carries a read-only terminal of exactly what that hook printed, streamed by cursor while the run is live. A step killed on its timeout whose exit was never confirmed is called out at the top of the page, because the consequence is a process that may still be running on a machine this product cannot reach. The equivalent commands are retnd workflow run show, workflow run steps and workflow run log --step.

A run left needing recovery keeps the set refused and offers exactly the two ways out the API has: resume the cleanup from that run's own retained spool, or acknowledge it in words that are recorded. There is no dismiss.

This page enumerates the screen. What the five stages mean, what a .local.sh hook is for, which credential a .remote.sh hook needs, how the environment is built and what the six BSH rules refuse a save over are on the scripted workflows guide, with clips of each of these surfaces in motion.

Activity

Each row is one recorded lifecycle transition: discovered, transferred, verified, committed, remote deleted, retention completed, host key changed, storage warning, configuration updated. The severity icon is the thing to scan: an error is a halt or a failure, a warning is a state that will become one, and information is the pipeline doing its job.

This is the same feed retnd activity prints, and it is durable: it survives a restart, which is what separates it from the docked terminal below.

Quarantine

Settings

Backup defaults

Reached from Settings. What a new backup set starts with — engine, repository domain, source-consistency mode, verification level and sample size, the two verification cadences, poll interval — so a fleet is not configured one wizard at a time. These are the answers Add backup set opens with; they are defaults for the next set and change nothing about a set that already exists.

It also lists who maintains each repository domain. Ownership is shown and not transferable from here: there is no API route that moves maintenance ownership in this build, and the card says so rather than offering a control that would fail.

Repository domains

A repository domain is a security boundary, not a folder: one encrypted store, one passphrase, one deduplication span, one maintenance owner, one corruption fate. A backup set running the incremental engine names exactly one, and two sets sharing a domain share all six of those things — which is where the storage saving comes from, and why the choice is never defaulted.

This screen lists every domain the configuration declares, whether it is shared or isolated, which backup sets store snapshots in it, and its health. retnd repository health is the same answer at a terminal.

Define a repository domain

The form that declares one. POST /repositories persists the domain — its id, its description, its sharing rule and a REFERENCE to the passphrase that opens it — into config.yaml, atomically, and the deployment hot-reloads, so the domain is nameable by a backup set immediately and without a restart. retnd repository create <domain> --isolation shared|isolated --passphrase-file F is the same write from a terminal, and it is the surface that also takes --passphrase-command, which is a program and its arguments rather than a single box.

Declaring is not creating. What is written is the declaration; the encrypted store itself is created by the first backup run that stores a snapshot in the domain, which is the lifecycle a domain named on the Add backup set wizard's repository step already had. So the create opens no storage and resolves no passphrase — the passphrase box takes a path or a variable name, and the secret never travels over this API — and the new domain shows on the fleet list as answering but holding no repository yet, rather than as a green row nobody measured. A deployment that does not run the incremental engine refuses the write with INCREMENTAL_ENGINE_DISABLED, and the screen prints that refusal's own sentence, which names the configuration key that answers it.

The sharing choice is the decision the screen exists for: picking Shared or Isolated states what each answer commits every set in the domain to, and the request always names one, because the API refuses a declaration that does not. Stating it here rather than in a help page is deliberate — co-tenancy is named where the decision is made. The maintenance-ownership answer is a gate on this one write and records nothing: this instance is refused if a maintenance record already names somebody else, and ownership itself still moves only by transfer (ADR 0017).

Repository health

Each domain's own verdict, which is a different question from any backup set's: a set can be perfectly fresh while the repository holding its snapshots is unwritable, out of maintenance, or reached by a process whose clock has drifted far enough to mis-order manifests. Every probe is reported separately rather than reduced to one boolean, because the remedies are different — unreachable is a mount, unwritable is a permission, invalid credentials is a passphrase, and overdue maintenance is a schedule.

The verdict uses the same three words a backup set uses, so one dashboard carries one severity scale. FAILING is reserved for a repository that cannot take a backup at all; overdue maintenance, a drifted clock and a failed verification are DEGRADED. Clock skew is signed, and the sign is the message: behind the history already stored is the direction that dates a new snapshot before an older one. retnd repository health prints the same rows and exits non-zero when any repository is failing.

Repository maintenance

Compaction and reclamation, per domain. Retention deleting a snapshot frees nothing on its own — the content behind the manifest stays in the store's packs until maintenance collects it — and full maintenance is what actually reclaims storage, so a domain with recent quick runs and no full run is growing.

Ownership is a first-class column, because exactly one instance may maintain a domain: two processes rewriting one store's indexes concurrently is how a repository loses content it still references. A domain another instance owns has its actions disabled with the reason in the card, since “press it and find out” is how that happens. retnd repository maintenance <domain> answers the same question at a terminal, and opens nothing, so it still answers while the repository itself is unreachable.

Storage destinations

A backend is described by a manifest the build carries — data, not code — and the manifest is what decides which fields a destination has, and which steps its connection test runs. Two are registered: local_volume, a directory on a disk this machine can see, and s3, a bucket on Amazon's service or anything that speaks its API. The drive backups already land on is an instance too, called local, and the only thing still special about it is that its location comes from the deployment's backup root rather than from a field, so it has no Edit.

Declaring a destination moves nothing. Backups arrive somewhere only once a retention tier names it, which is the card above this one and a separate decision with its own disclosure.

Three chips appear beside a destination's name, and each is a claim about a different thing. Default is where a newly created tier starts. reads need a restore is an archival storage class: a copy here cannot be read until the provider is asked to thaw it, which is billed and takes hours. never proven is a destination declared with the check skipped — --no-verify on the command line — so nothing has yet shown that its credential is accepted or that an object written there can be read back.

Adding a destination

Choosing and naming are two steps rather than one, and that will look like ceremony in a release that registers two backends. It is the shape the rest of this holds up: several instances of one backend is the normal case, and a single screen that collapses “pick S3” and “call it cold_archive” into one act has quietly said again that a destination is a backend type.

Configuring a destination

Three steps: fill in what the manifest declares, prove it, then look at what is about to be written. The order is the point — what gets written is what was proven — and it is enforced rather than advised: editing any field makes an earlier pass stale, the screen says so where the edit was made, and Save configuration is out of reach until a check against the values now on screen has passed.

Eight steps are a closed vocabulary the engine and the manifests share, and a manifest declares for each one whether this backend runs it and, when it does not, the sentence saying why. So the skipped rows and their reasons are on screen from the start: an operator learns that a local volume reads no credential rather than wondering why nothing checked their key. The drive on this machine and a declared local volume both add a ninth answer, space, which is the one failure a bucket cannot have.

A step after a failing one is not tried, and the list says that rather than drawing it as a pass or leaving it blank. Every sentence beside a row is the engine's own; none of them carries the text of what actually came back, because that names a path on the host or the name of an environment variable, and the classified cause goes to this manager's log instead.

The review step is the last of the three: what is about to be written, whether it was proven, and a checkbox offering to make this the destination new tiers start on. The offer is never taken as a side effect of saving — it is a second call, after the save — and the consequence is written beside it, naming the destination that stops being the default and therefore becomes removable. It is not offered at all to a destination that already holds the mark.

Catalog recovery

Every backup this manager commits gets a sidecar recovery manifest written beside it, and this screen is what those are for. Scan backup storage reads file metadata and checksums, reports how many artifacts it found and how many need review, and writes nothing. Artifacts it cannot make sense of go to Quarantine, not to a delete. The command line spells it retnd catalog rebuild, and --dry-run is the same read-only pass.

The docked terminal

Two feeds in one panel, and the chips choose between them. Engine and the per-set chips are the serving process's own live output. This browser is what you have done in this tab, including the retnd command each action was equivalent to: the $ retnd backup-set patch production/auth-config --stale-after 48h line in the picture is the echo of somebody editing a set in the interface a moment earlier.

It is live, not durable. It starts again when the serving process restarts, and it says so when that happens. For history that survives, read Activity. Copy and Save .txt take what is on screen, filter and all.

The command line

The engine and the command line are two binaries in one image. retnd-web serves the API and the interface; retnd is what an operator types. Almost everything the interface does is here, and several things it does not: retention previews with per-run overrides, artifact-level validation with a full re-download, catalog rebuilds, and the storage-destination verbs. The exception runs the other way and is named under medium below: a destination on a local volume can be declared from the browser and not from here.

On the standard deployment it is reached through the engine container:

docker compose exec retnd /retnd status

On a CLI-only install the installer writes a wrapper and you type ~/retnd/bin/retnd status instead. Every command except version takes --config, which defaults to /etc/retnd/config/config.yaml and also accepts the directory, because that is what packaging mounts.

Every command

Twenty-four of them. This table is checked against the binary's own dispatch table on every run of the repository's gate, so a command that is added, removed or renamed and not reflected here fails the build rather than going quietly stale.

Where a change is written, and how you know

A configuration write goes one of three ways, and every command that makes one says which on a mode: line.

The route is three environment variables, never flags, because a password on a command line is in every process listing on the host: RETND_API_URL is the engine's address (its own listener from inside its container, or the published Web UI port from a shell on the host), and RETND_API_USERNAME and RETND_API_PASSWORD are the administrator credentials the interface takes. They are held for the one invocation and written nowhere.

Reads never refuse for want of a route. status, sources, artifacts and retention announce which world the answer is about instead: mode: engine-attached is a serving process holding the same configuration and asked the same question, mode: direct is nothing serving, and mode: unconfirmed is an answer read out of config.yaml that could not be checked against the serving process and can disagree with it.

Exit codes

install_docker_host.py

One file, no checkout, nothing outside the Python standard library. Copy it to the machine on its own and run it: it carries the canonical Compose definition inside itself, generated from container/compose.yaml and held to it byte for byte by a test, so there is nothing to clone on the host.

curl -fsSLO https://raw.githubusercontent.com/retnd/retnd/main/scripts/install/install_docker_host.py
python3 install_docker_host.py install

Every flag below has a default that works, which is what makes that second line the whole command. The install section on the home page is the short version of this.

Its eight subcommands

This table is checked against the parser's own subcommand list, and so is that number, because a count in a heading is the part that stays wrong after the missing row has been added.

Every flag

Grouped the way --help groups them, and the subcommands each one exists on are named beside it, because they are scoped: status and uninstall never read a credential path or an image reference and no longer declare those flags at all. This table is checked against the parser itself, so a flag that is added, removed or renamed and not reflected here fails the installer's own test suite.

Its exit codes

Every refusal has its own code, so a script can tell “this architecture has no image” from “that port is taken”, which call for completely different reactions.