Automated encrypted backups to Backblaze B2 using Restic. Runs daily at 3AM with GFS retention.
What is covered, grouped by what it costs to lose:
| Group | Paths |
|---|---|
| Recovery keys | /persist/var/keys, /persist/etc/ssh,
/persist/var/dkim, /persist/var/lib/sbctl |
| Host identity | /persist/etc/secrets (initrd SSH key),
/persist/etc/machine-id, .ssh and
.config/syncthing under
/persist/home/user |
| Host bookkeeping | /persist/var/lib/nixos (UID/GID map),
/persist/etc/{opencloud,NetworkManager,containers} |
| Service state | forgejo, postgresql (Keycloak, Miniflux,
Invidious), trilium, opencloud,
n8n, navidrome, anki-sync-server,
slskd, memos, open-webui,
open-terminal, openbao, acme
under /persist/var/lib |
/persist/var/vmail, postfix and
dovecot under /persist/var/lib |
|
| Personal data | Documents, Pictures, Music,
Videos, Projects, Software, agent
data in .claude and .pi, and the
nixos, dotfiles, nvim repos under
/persist/home/user |
| Application config | .app-state under /persist/home/user —
Krita, Blender, Okular and opencode rewrite their own config, so no
repository carries it |
| Bulk | /mnt/atlas, OpenCloud storage under
/mnt/aether/network/opencloud |
Service users get no fixed UID, so
/persist/var/lib/nixos is what keeps a restored state
directory owned by the same user after a reinstall: restore it before
the host first activates.
Deliberately excluded because they are reproducible: container images
and volumes, Incus storage pools, Ceph monitor and OSD data, Talos nodes
(declarative in talos-config/), and logs.
Syncthing’s index (~/.config/syncthing/index-*) is
excluded on purpose. It lists every file the host held, so restoring it
next to any file the backup lacks makes Syncthing report that file
deleted to every peer. A host restored without it rescans and pulls what
it lacks from the peers.
Exclude patterns match by name anywhere in a path
(build, tmp, cache,
*.log, LaTeX by-products and others in
modules/features/restic-backup.nix), so data kept under
such a name is never backed up.
Retention: 3 daily, 2 weekly, 3 monthly, 2 yearly snapshots
Everything under /persist is read from a read-only btrfs
snapshot rather than the live subvolume. A backup that copies files
straight off a running system reads each one at a different moment, and
can catch a SQLite or PostgreSQL file mid-transaction — a defect that
surfaces only at restore time.
flowchart LR
P["@persist (live)"] -->|"btrfs subvolume snapshot -r"| S["@restic-persist"]
S -->|"mounted at /run/restic-persist"| B["bind over /persist"]
B -->|"read"| R["restic"]
R --> X["Backblaze B2"]
restic-persist-snapshot.service rotates the snapshot and
mounts it, then the backup unit binds it over /persist
inside its own mount namespace. Every path in a given snapshot therefore
comes from the same instant, which both database engines recover from by
design since it is indistinguishable from a power cut.
Paths under /persist are spelled with that prefix rather
than their runtime bind-mount target: impermanence binds such as
/var/lib/forgejo resolve to the live subvolume, so only the
/persist spelling is covered by the snapshot.
The previous snapshot is dropped at the start of the next run rather than after the backup, because unmounting it from inside the backup’s namespace is not possible. One read-only snapshot therefore survives between runs, pinning a day of overwritten extents and doubling as a local rollback point.
Note: All commands in this guide run on the server. SSH to
[email protected]first.
Most restic commands require credentials. Export these before running commands:
export $(cat /run/secrets/restic/b2-credentials | xargs)
export RESTIC_PASSWORD_FILE=/run/secrets/restic/password
export RESTIC_REPOSITORY=b2:yhkze-infra-backups:nixosBuckets → Create a Bucketyhkze-infra-backups (or your choice)PrivateDisable (restic encrypts client-side)DisableCreate BucketApp Keys → Add a New Application Keyserver-restic-backupRead and WriteCreate New KeyB2_ACCOUNT_IDB2_ACCOUNT_KEYGenerate restic password:
openssl rand -base64 32Edit hosts/server/secrets/secrets.yaml:
restic:
password: <output-from-openssl>
b2-credentials: |
B2_ACCOUNT_ID=<keyID>
B2_ACCOUNT_KEY=<applicationKey>Encrypt:
sops -e -i hosts/server/secrets/secrets.yamlEdit modules/features/restic-backup.nix:
repository = "b2:<bucket-name>:<path>";Example: b2:yhkze-infra-backups:nixos
rebuild 10.100.0.1First backup runs automatically after deployment.
systemctl status restic-backups-b2.servicesystemctl list-timers | grep resticjournalctl -u restic-backups-b2.service -n 50systemctl start restic-backups-b2.service
journalctl -fu restic-backups-b2.service # Follow logsLoad credentials first (reference top of document).
restic snapshotsrestic ls latest # Latest snapshot
restic ls <snapshot-id> # Specific snapshotrestic find "*.jpg" # All JPG images
restic find "myfile.txt" # Specific file
restic find "/home/user/Documents" # Directory contentsrestic diff <old-id> <new-id>restic stats # Overall stats
restic stats <snapshot-id> # Specific snapshot
restic stats --mode raw-data # Before deduplicationBrowse backups with Nemo or any file manager via FUSE mount.
Create mount:
mkdir -p /tmp/restic-mount
restic mount /tmp/restic-mount
# Leave terminal open, mount stays activeIn another terminal:
nemo /tmp/restic-mountMount structure:
/tmp/restic-mount/
├── snapshots/
│ ├── 2026-04-12T23:21:38-05:00/ # Dated snapshot directories
│ │ ├── mnt/atlas/
│ │ └── persist/
│ ├── 2026-04-13T03:00:00-05:00/
│ └── latest → <most-recent>
├── hosts/
│ └── server/
└── tags/
Browse to the file you need, then copy it:
cp /tmp/restic-mount/snapshots/latest/persist/home/user/Documents/file.pdf ~/Unmount: Ctrl+C in the terminal running
restic mount
Load credentials first (reference top of document).
restic restore latest --target /tmp/full-restorerestic restore latest --target /tmp/restore --include /persist/home/user/Documentsrestic restore latest --target /tmp/restore --include /persist/home/user/Documents/file.pdfFile appears at:
/tmp/restore/persist/home/user/Documents/file.pdf
restic snapshots # Find snapshot ID
restic restore <snapshot-id> --target /tmp/restorerestic restore latest --target /tmp/restore --include "*.jpg"
restic restore latest --target /tmp/restore --include "/persist/home/user/nixos/**"A full restore onto a new disk happens from the installer, before the first activation, from B2 or a local replica. Reference Server Reinstall.
Load credentials first (reference top of document).
restic check # Quick check (metadata)
restic check --read-data # Full check (downloads data)Run monthly.
restic forget --dry-run --keep-daily 3 --keep-weekly 2 --keep-monthly 3 --keep-yearly 2If backup interrupted:
restic unlockrestic pruneNote: Auto-pruning runs after each backup.
journalctl -u restic-backups-b2.service -n 100Common issues:
restic unlockrestic initLimit upload speed in
modules/features/restic-backup.nix:
extraBackupArgs = [
"--limit-upload 10000" # KB/s
];restic mount /tmp/restic-mount
# In another terminal:
ls -lah /tmp/restic-mount/snapshots/latest/persist/home/user/Check exclusion patterns if files missing.
Encryption:
Access control:
Backup the backup — store restic password and B2 credentials securely:
B2 pricing (2026):
| Item | Cost |
|---|---|
| Storage | $6/TB/month |
| Download | $10/TB (1GB/day free) |
| API calls | 2,500/day free |
100GB backup: ~$0.60/month + free API calls
Deduplication means incremental backups only upload changes.
modules/features/restic-backup.nix