Upgrading, backing up and restoring the hub

This page covers the hub: what to keep, how to move to a new release, and how to get back if something goes wrong. How agents move to a new release is in Updating the agent; how to check a download is in verify-release.md.

What the hub keeps#

The hub reads two folders. In the Docker Compose recipe they are ./config and ./data; for a plain executable they are YARRIX_CONFIG_DIR and YARRIX_DATA_DIR.

Where	What	Back it up?
Config folder	`yarrix.yaml`, `defaults.yaml`, `alerts.yaml`, `hosts/`, `checks/`, `scripts/` (configuration.md). If the folder is a git repository, saving through the API also makes a local commit.	Yes. Plain text; a git remote or a copy is enough.
`yarrix.db` (data folder)	Everything the hub has measured and decided: samples, incidents, users and sessions, enrollment tokens, agent update history. SQLite; also writes `yarrix.db-wal` and `yarrix.db-shm` while running.	Yes: use the scheduled copies below.
`backups/` (data folder)	The hub's own scheduled copies of `yarrix.db`.	Copy it off the machine; a backup on the same disk does not survive the disk.
`ssh/` and `known_hosts` (data folder)	The per-host SSH keys the hub made for agentless hosts, and the host keys it has accepted.	Yes. Losing the keys means re-authorising each agentless host.
`recordings/` (data folder)	Web terminal session recordings, pruned automatically.	Only if you need the audit trail.
`secrets.json` (data folder)	The hub's encrypted secret store: values typed into the web app, as ciphertext (security.md).	Yes, with `yarrix.db`. Useless without the hub key.
`secret.key` (data folder), or `YARRIX_SECRET_KEY`	The hub key that opens the store.	Yes, and keep it apart from the data folder backups: a store copied together with its key is not protected, and a store without it cannot be read. The recovery key you saved at set-up also opens the store; it is not kept anywhere on the hub.
Secrets your config refers to	Values behind `${env:NAME}` and files behind `${file:/path}` (configuration.md). They are not in the config folder.	Yes, wherever you keep them (an `.env` file, a secrets folder).

The hub's own backup#

By default the hub copies its own database every day at 03:00 (cron 0 3 * * *) into <data folder>/backups, keeps the newest 7 and prunes older ones. The copies are named yarrix-<UTC timestamp>.db and are made with SQLite's VACUUM INTO, so each one is a consistent, standalone database written while the hub runs. The copy is checked with PRAGMA integrity_check and shows up in the Backups view as the job yarrix-db, so a failed or stale copy raises the same alerts as any other backup.

Change it under self_monitor.db_backup in yarrix.yaml (schedule, keep, path); see config-reference.md. A custom path must be an absolute directory and can only be set by a signed-in admin.

This copies the database only. It is not a copy of the config folder, the SSH keys or your secrets, and it sits on the same machine unless you point path at another disk or copy the folder off. Like any backup, test it: Yarrix has not proven these copies restorable (see the note in backups.md).

Upgrading the hub#

The hub does not update itself and never contacts a release server. You decide when.

Back up first. Take a fresh copy of the database (stop the hub and copy the data folder, or copy the newest file from backups/) and keep a copy of the config folder.
Read the release notes for the version you are moving to.
Replace the hub.
- Docker Compose: change the tag in YARRIX_IMAGE (the default is ghcr.io/yarrix-io/yarrix:latest; release images are also tagged with the version, for example 1.2.3, and with 1.2), then docker compose pull && docker compose up -d.
- Plain executable: stop the hub, replace the yarrix-hub-<os>-<arch> file with the new one (after verifying it) and start it again.
Check it came up. docker compose logs hub, yarrix-hub healthcheck (exit 0 when it answers) and the web app. yarrix-hub config check validates the config folder against the new version; a config file that fails to load keeps its last good version active and the error is listed at GET /api/v1/config/errors.

Database migrations run on start. When the hub starts it brings yarrix.db up to the schema the new version needs. Each migration runs in its own transaction, so one that fails is rolled back and the hub does not start on a half-migrated database. Your data is kept.

You cannot go back by swapping the old version in. A database that has been migrated is newer than the old hub understands, and an older hub refuses to start on it ("database schema vN is newer than this build; upgrade Yarrix"). To downgrade, restore the database copy you took in step 1 (below) and then run the older version.

Agents after a hub upgrade. The hub shows which agents are behind the release it serves. An agent that is behind is information, not an alert. Whether the hub then moves them is the update mode you chose per host: see Updating the agent. If you serve agent files (YARRIX_AGENT_DIST), drop in the new release's agents/ folder or use the new image, which ships them.

The update channel#

There is no remote "latest release" feed. Yarrix never calls home, so nothing tells a hub that a newer release exists. A release reaches your fleet in two steps, both started by you:

You give the hub the new release. The hub serves agent files from the folder YARRIX_AGENT_DIST points at (the Docker image ships the release's set in its own folder) and reads the release's VERSION and MANIFEST.json from there. Upgrading the hub image, or dropping a newer release's agents/ folder in, is what makes a newer agent version available. The fleet view picks up a new folder without a restart.
The hub offers it to agents, and each agent decides. Per host, agent_updates.mode is one_click (default: an admin clicks Update), automatic (the hub starts updates in a time window, one canary host first, at most max_concurrent at once, and stops if two hosts fail on the same release) or notify (shown, never started). The hub only ever sends a version number; the agent downloads from its own hub and installs a build only if its manifest has a valid minisign signature from a trusted key, the version is newer, and the size and SHA-256 match. A new build runs as a trial and the agent rolls back to the old one if it crashes or cannot reach the hub. Details and the API are in Updating the agent.

What follows from that:

Unsigned releases are not offered. A hub checks the manifest signature against its release key (the built-in key, or YARRIX_RELEASE_PUBKEYS when set) and will not offer files whose signature does not verify, and an agent refuses them regardless. A release is published only after a maintainer has signed it (verify-release.md).
No downgrades. An agent never moves to a version that is not newer.
Containers are updated by image, not by the hub (container in the host's update status). Agents that cannot update themselves show why on the host.
You can stay where you are. Set notify or never place a newer release on the hub; nothing updates on its own.

Restoring#

You need a database copy (a file from backups/, or one you made yourself) and the config folder.

Stop the hub.
In the data folder, move the current yarrix.db, yarrix.db-wal and yarrix.db-shm aside (do not delete them until the restore works).
Copy the backup in as yarrix.db. Do not put the old -wal or -shm files next to it.
Make sure the config folder, the ssh/ folder, known_hosts, secrets.json with its secret.key (or YARRIX_SECRET_KEY set) and the secrets your config refers to are in place and readable by the user the hub runs as (in Docker, YARRIX_UID / YARRIX_GID).
Start the hub. If the copy came from an older version, the migrations bring it up to date on start.

What to expect afterwards:

History after the copy was taken is gone. Hosts, incidents and users created after it are not in the restored database.
An agent enrolled after the copy was taken is not known to the restored hub. Mint a new token for it (yarrix-hub enroll create --host <id>) and enroll it again. Agents that were enrolled before the copy should reconnect by themselves.
Signed-in sessions are in the database, so people who signed in only after the copy must sign in again.

If secret.key did not come back, the hub starts and reports secret NAME can't be decrypted for each stored secret. Sign in, open the secret store settings and enter the recovery key from set-up (or use it at /recover if you cannot sign in): the hub makes a new secret.key and everything reads again. If you have neither the key file nor the recovery key, re-enter the secrets.

Moving the hub to another machine#

Stop the hub, copy the config folder, the whole data folder (or the database file, ssh/, known_hosts and secrets.json), secret.key and your secrets to the new machine, and start the new hub there with the same YARRIX_PUBLIC_URL (or point the old address at the new machine) so agents find it. Keep the old hub stopped; two hubs on one database is not supported.