Skip to the content

Back up and restore Central Lite

Write Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Write Central Lite's encrypted backups by hand and on a schedule, shred the ones you no longer keep, and restore one into a state directory that holds only the keystore that sealed it. The restored Central Lite signs nothing until its enrolled nodes have reported what they hold, so when you finish it numbers every new policy, registry and revocation list above the nodes' anti-rollback marks and no node refuses it.

1. Write a backup and list them

garm-central backup create works while serve runs. It takes a consistent copy of Central Lite's database, encrypts it under a fresh key of its own, writes it to a new 0600 file central-<id>.agcb under the state directory's backups (or --dir), and prints its id, path, size and SHA-256. An edited, reordered or cut-short file never decrypts.

Each backup's key is sealed in Central Lite's keystore, never in the file, and the keystore is in no backup: a backup opens only with the keystore that wrote it. backup list shows every backup, newest first, with its time, size, schema version and path.

garm-central backup create
garm-central backup list

Checked by the walk: this command ran as written on a Central Lite host.

2. Set the schedule serve keeps

While it runs, serve writes a backup every 24 hours by default, the first a period after it starts, and crypto-shreds all but the newest 7. --backup-every takes seconds, minutes or hours (s, m, h; at least 60s), or off; --backup-keep how many to keep; --backup-dir another directory. A failed backup is logged, alerted as backup_failed and tried again at the next tick.

By default the backups sit beside the keystore in the state directory, and in the container image the database, the backups and the software keystore all live in the one volume: whoever holds the volume holds Central Lite's keys. Copy the backups somewhere else, and keep the keystore (the state directory's keys under software custody) backed up apart from them under its own custody.

garm-central serve --listen 0.0.0.0:8443 --backup-every 6h --backup-keep 28

3. Shred the backups you no longer keep

garm-central backup prune --keep N crypto-shreds every backup beyond the newest N: it erases the backup's key, removes its file and prints how many it shredded. Copies of that file elsewhere, offsite included, can then never be decrypted. backup list keeps the row, marked SHREDDED with when and why, and a restore of it is refused.

An erasure shreds backups too: once dsar erase deletes anything, Central Lite writes a fresh backup and shreds every backup taken before the erasure, so no backup still holds what was erased.

garm-central backup prune --keep 7

Checked by the walk: this command ran as written on a Central Lite host.

See also

Set retention, legal holds and data-subject requests

Set how long Central Lite keeps each class of record, put a legal hold on the records a case needs, and answer a person's access or erasure request.

4. Restore into a state directory that holds only the keystore

garm-central restore --from FILE refuses while a serve holds the state directory (serve.lock), so stop it first, or restore into another state directory, created 0700 if it is missing, that holds nothing but the keystore. On a new host, that is /var/lib/agentgarm-central itself, created as root for Central Lite's account. The keystore must be there first: under software custody, put back the keys directory from the keystore's own backup; a key in the host's TPM opens only on that TPM, and restoring onto another keystore is not built. Without it the restore refuses: the backup's key is not in this keystore.

The restore decrypts the copy, checks its size, SHA-256, integrity and org, verifies every audit chain, and swaps it in in restore mode: every enrolment token issued before is void, and Central Lite signs nothing. A database it replaces moves under the state directory's replaced for restore mode only, and is removed at restore finish or by the first erasure. As a drill, this restores the newest backup into restored beside the live Central Lite, with a copy of its keys standing in for the keystore's backup, and leaves the live Central Lite serving. Remove the drill's directory afterwards: it holds a copy of Central Lite's keys.

install -d -m 0700 restored
cp -a /var/lib/agentgarm-central/keys restored/
garm-central --state-dir restored restore --from "$(ls -t /var/lib/agentgarm-central/backups/central-*.agcb | head -n 1)"
garm-central --state-dir restored restore status
rm -rf restored

Checked by the walk: this command ran as written on a Central Lite host.

5. Serve, and let the nodes report

Start serve on the restored state directory at Central Lite's usual URL: its TLS key came back with the keystore, so the nodes' pin still matches. In restore mode it takes uploads and reports, but sends nothing on the control channel and enrols no one; a node renewing its certificate keeps the one it has and retries. Like any start of serve, it signs every console admin out.

garm-central restore status shows the floors, Central Lite's own newest versions, each node's marks since the restore (policy, revocations, identity registry, MCP registry, root, catalog and legal hold list), the nodes not reported since the restore, and what the restore lost: uploads a node had sent after the backup, recorded as lost entries per stream. A node enrolled after the backup is unknown to the restored Central Lite: leave on it and enrol it again with a new token.

Restore mode also refuses kill order requests and approvals. A kill order issued after the backup is still in force on the nodes it reached, and they report it, so garm-central kill list shows its id as unknown here, with how many nodes report it in force. Once restore mode ends, lift it with garm-central kill lift; an order only nodes report takes at least the root's threshold for a wide order. Until then a task's evidence export cannot skip its legal hold.

Single sign-on's client key or secret and every SIEM sink's credential live in the keystore, never in a backup. A restored Central Lite stops each SIEM sink with “credential not in this Central's keystore” until you remove the sink and add it again (rotate a credential). SCIM tokens are kept in the database as hashes, so they are back as they stood at the backup: revoke again any you revoked since, and make a new one for a source added since. In restore mode every SCIM write is answered 503 with a wait of five minutes, so your identity provider retries rather than giving up. What SCIM changed after the backup, offboardings included, is lost with the rest: once restore mode ends, have the provider send its users again before you rely on who is suspended.

garm-central serve --listen 0.0.0.0:8443
garm-central restore status
garm-central kill list

See also

Enrol developer machines

Enrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys.

6. Finish above the anti-rollback floors

Nodes refuse a policy bundle, revocation list, identity registry, MCP registry snapshot or legal hold list at or below the version they hold, and a revocation list that drops an entry. A restored Central Lite would otherwise issue numbers its fleet already holds from after the backup, and forget revocations made since. garm-central restore finish raises the floors past every mark the nodes reported (and the replaced database's, when there was one), re-imports revocations, and re-issues the revocation list, identity registry, MCP registry snapshot and legal hold list above them. Floors only rise.

It refuses while Central Lite lacks the newest revocation list a node holds: pass that node's copy, /var/lib/agentgarm/update/revocations/central:<org id>.rl on a Linux node (the org id is garm-central status's org), with --revocations. It also refuses while an enrolled node has not reported, unless --allow-missing with a --reason; then give floors above anything that node may hold, since it never reported its marks. A node that trusts a newer org root metadata version than the backup holds must have it installed first. The policy bundle is not re-issued, and identities, policies and holds made after the backup are not in it: re-create them, and run policy publish, which numbers the next bundle above the floor. Central Lite signs no compliance settings for nodes until you check them with compliance show and sign them with compliance publish after restore finish, since its nodes may hold newer ones.

garm-central restore finish --revocations revocations.rl
garm-central policy publish
garm-central restore finish --allow-missing --reason "laptop lost" --floor-policy N --floor-revocation N --floor-identity N --floor-registry N --floor-legal-holds N

See also

Prepare a works-council or DPIA pack

Generate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks.