Backups and recovery

A relay is not a backup. The node’s authoritative state includes its private key and SQLite database, plus any state owned by configured adapters.

What to back up

Always protect:

• The flock private key
• birdd.toml, or the NixOS configuration used to generate it
• The SQLite database
• Runtime credential files

When enabled, separately back up Signal account state, the Grist database, and media object storage. None of those are contained in birdd.sqlite.

Important

Test that a restored key produces the public key you expect. Restoring the database with a different key creates an identity mismatch that federation cannot repair.

Consistent SQLite backups

SQLite runs in WAL mode. A live node may have -wal and -shm files beside the main database, so copying only birdd.sqlite while a writer is active can lose committed data.

The simplest safe filesystem backup is to stop every process that can write the database, copy the complete state directory, and then restart them. This can include the main node, Signal adapter, Grist webhook, Grist reconciliation job, and operator commands.

For an online database backup, use SQLite’s backup command instead of copying the live database file:

sqlite3 /var/lib/birdd/birdd.sqlite \
  ".backup '/var/backups/birdd/birdd.sqlite'"

Copy the private key and configuration through a secret-aware backup mechanism, preserving restrictive ownership and permissions.

Restore

1. Stop all birdd processes that use the database.
2. Restore the database, private key, configuration, credentials, and enabled integration stores.
3. Restore ownership and restrictive permissions for the service account.
4. Start the node and verify its identity and health.
5. Run a synchronization pass and inspect federation status.

birdd --config birdd.toml identity
birdd --config birdd.toml list --json
birdd --config birdd.toml federation-status --json
birdd --config birdd.toml sync

On NixOS, use birdd-admin for these checks.

Export and rebuild

birdd export writes retained signed events as newline-delimited JSON. It does not include the private key, trust decisions, restricted delivery state, credentials, or adapter data, so it is not a complete backup format.

birdd rebuild regenerates materialized observations and flock metadata from retained events. It does not repair a damaged SQLite file or recreate all operational tables. Use it when retained events are intact but a derived view needs to be regenerated.