Backrest — Reference

Links

• Website: https://garethgeorge.github.io/backrest/
• API docs: https://garethgeorge.github.io/backrest/docs/api/
• Operations guide: https://garethgeorge.github.io/backrest/docs/operations
• GitHub: https://github.com/garethgeorge/backrest
• Restic docs: https://restic.readthedocs.io

Infrastructure

Host	Internal	URL
cajita-elite (bare metal)	192.168.1.196:9898	https://backrest.eva-00.network

API (ConnectRPC)

Backrest exposes a ConnectRPC API at http://localhost:9898 on cajita-elite. All requests use POST with JSON body.

Trigger a backup plan

ssh -i ~/.ssh/id_ed25519_cajita [email protected] \
  "curl -s -X POST http://localhost:9898/v1.Backrest/Backup \
  -H 'Content-Type: application/json' \
  -d '{\"value\":\"<plan-id>\"}'"

Plan IDs: vault-snapshot, app-configs, databasement-dumps, immich-media, archivebox-archives

The request blocks until the operation completes. 200 = success.

Get operation history

ssh -i ~/.ssh/id_ed25519_cajita [email protected] \
  "curl -s -X POST http://localhost:9898/v1.Backrest/GetOperations \
  -H 'Content-Type: application/json' \
  -d '{\"planId\":\"vault-snapshot\"}'"

List snapshots for a repo

ssh -i ~/.ssh/id_ed25519_cajita [email protected] \
  "curl -s -X POST http://localhost:9898/v1.Backrest/ListSnapshots \
  -H 'Content-Type: application/json' \
  -d '{\"repoId\":\"local-backrest\"}'"

Repo IDs: local-backrest, mac-backup

Restic CLI

Restic is the underlying backup engine. Use it directly on cajita-elite for operations not available in the Backrest UI/API.

List snapshots

# Homelab repo
ssh -i ~/.ssh/id_ed25519_cajita [email protected] \
  "RESTIC_REPOSITORY=/opt/backrest/repos/homelab \
  RESTIC_PASSWORD=<password> \
  restic snapshots"

# Mac backup repo
ssh -i ~/.ssh/id_ed25519_cajita [email protected] \
  "RESTIC_REPOSITORY=/mnt/datastore/mac-backups \
  RESTIC_PASSWORD=<password> \
  restic snapshots"

Restore files from a snapshot

restic restore <snapshot-id> --target /tmp/restore --include "/path/to/file"

Mount a snapshot (browse interactively via FUSE)

restic mount /mnt/restic-mount
# then: ls /mnt/restic-mount/snapshots/<date>/

Check repo integrity

restic check
restic check --read-data-subset=5%   # verify 5% of data blobs

Repo stats

restic stats --mode raw-data

Unlock stale locks

restic unlock

Restic CLI (Mac — local backup)

From the Mac, for the SFTP-based backup to cajita-elite:

export RESTIC_REPOSITORY="sftp:[email protected]:/mnt/datastore/mac-backups"
export RESTIC_PASSWORD=$(security find-generic-password -a restic-cajita -s restic-cajita -w)
export RESTIC_SSH_COMMAND="ssh -i ~/.ssh/id_ed25519_cajita"

# List snapshots
restic snapshots

# Browse a snapshot
restic ls latest

# Restore a specific file
restic restore latest --target /tmp/restore --include "Documents/important.pdf"

# Interactive mount
restic mount /tmp/restic-mount

Config

Path (cajita-elite)	Contents
/root/.config/backrest/config.json	Backrest config (repos, plans, hooks, auth)
/opt/backrest/repos/homelab/	Restic repo for homelab infra backups
/mnt/datastore/mac-backups/	Restic repo for Mac backups
/opt/backrest/dumps/vault/	Vault raft snapshots (pre-backup hook)
/opt/backrest/dumps/configs/	App configs collected via SCP (pre-backup hook)
/opt/backrest/.vault-token	Vault token for raft snapshot hook

What the API/CLI Cannot Do

Gap	Workaround
No API to edit config (repos, plans, hooks)	Edit config.json directly or use the web UI
No API to create/delete repos	Edit config.json and restart Backrest
Cannot restore files through the Backrest UI/API	Use restic restore CLI directly
Cannot mount snapshots through the API	Use restic mount CLI (requires FUSE)
No built-in notifications — relies on hook commands	Hooks use curl to ntfy for notifications
Backrest UI shows limited error details for failed hooks	Check journalctl -u backrest for full error output
Cannot browse snapshot contents in the UI (only tree view of operations)	Use restic ls <snapshot-id> CLI
Restic password is in config.json in plaintext	Config.json is mode 0640; IaC templates from Vault