Skip to content

Reference

Environment variables

Variable Default Meaning
TZ UTC Timezone for schedules, windows, snapshot names and the UI
BACKUPKRAKE_ADMIN_USER admin Web UI login name
BACKUPKRAKE_ADMIN_PASSWORD generated Web UI password. If unset, one is generated, logged and stored in config/initial_admin_password.
BACKUPKRAKE_MAX_PARALLEL 2 Backups, restores and content checks running at the same time
BACKUPKRAKE_DATA_DIR /data Snapshot storage (change the volume instead)
BACKUPKRAKE_CONFIG_DIR /config Database, keys, logs (change the volume instead)
BACKUPKRAKE_SSH_BIN, BACKUPKRAKE_RSYNC_BIN, BACKUPKRAKE_RESTIC_BIN ssh, rsync, restic Programs to run; for development and tests
BACKUPKRAKE_SCHEDULER 1 0 disables all scheduled jobs; for tests

The web UI listens on port 8080 inside the container.

Files and directories

/data/
├── hosts/<host>/<YYYY-MM-DD_HHMMSS>/   snapshots
├── hosts/<host>/<…>.partial/           unfinished backup, resumed by the next run
├── hosts/<host>/latest                 symlink to the newest snapshot
└── restore/offsite-<id>-<time>/        restores from offsite repositories

/config/
├── backupkrake.db                      SQLite database: hosts, settings, targets, runs, pins
├── ssh/id_ed25519(.pub)                backup key
├── ssh/id_ed25519_restore(.pub)        restore key
├── ssh/id_ed25519_offsite(.pub)        offsite (SFTP) key
├── ssh/known_hosts                     host keys of clients and SFTP servers
├── logs/<run id>.log                   run logs
├── restic-cache/                       restic's local cache (rebuildable)
├── secret_key                          signs session cookies
└── initial_admin_password              only if no password was set

On the clients:

Path Used for
/var/tmp/backupkrake-restore/<host>-<snapshot>/ restores to the staging directory (whole-system hosts)
~/.backupkrake-restore/<host>-<snapshot>/ restores to the staging directory (home-folder hosts)
/var/backups/backupkrake/ dumps written by the presets (whole-system hosts)
~/.backupkrake-dumps/ dumps written by the presets (home-folder hosts)
*.bkrestore-<time> copies of files a restore overwrote or deleted

Host settings

Setting Default Notes
Kind Whole system or Home folder only
Name [A-Za-z0-9][A-Za-z0-9._-]{0,62}, can't be changed
Address, SSH port port 22 hostname, IPv4 or IPv6
SSH user root
Paths /etc /home /root /var /opt /srv /usr/local home-folder hosts: .
Excludes caches, /var/tmp/, container storage, journal, *.swp, lost+found/ rsync patterns
Preserve ACLs and extended attributes on off for home-folder hosts
Don't cross filesystem boundaries off rsync -x
Schedule 0 2 * * * empty = manual only
Backup window any time e.g. 22:00-06:00
Bandwidth limit unlimited e.g. 20M, 500K
Retry when unreachable 0 (off) minutes, up to 1440
Keep last / daily / weekly / monthly 3 / 7 / 4 / 12
Overdue alert after global default days; 0 = never
Pre-/post-backup command run via SSH; need the unrestricted key
Extra rsync arguments appended to the rsync command

Offsite target settings

Setting Default
Name
Repository URL, password, backend environment
Hosts all hosts
Schedule 0 5 * * *, disabled
Upload window any time
Keep daily / weekly / monthly / yearly 7 / 4 / 12 / 3
Upload limit 0 (unlimited), KiB/s
Upload configuration on

Verification settings

Setting Default
Plausibility: warn when files or data drop by 30 % (0 = off)
Content check schedule 0 3 1 * *, disabled
Restore test schedule 0 6 * * 0, disabled
Data read back per restore test 5 %
Files restored per host 5

Notification settings

Setting Default
ntfy server https://ntfy.sh
ntfy priority on failure 4
Pushover priority on failure 0
Notify on offsite failures / restore failures / recovery on
Notify on warnings off
Overdue after 2 days
Disk alert below free space 10 %
Disk alert when full within 30 days
Heartbeat URL none

Syntax

Cron (schedules): five fields minute hour day-of-month month day-of-week, standard crontab meaning. Day of week: 0–7 (0 and 7 = Sunday) or sun–sat. Lists (1,15), ranges (1-5) and steps (*/6) work in every field. See Schedule.

Windows (backup and upload windows): comma-separated HH:MM-HH:MM ranges in local time. A range whose end is before its start crosses midnight. 24:00 is allowed as an end. Empty = any time.

Bandwidth limit: a number with an optional unit, per second. K = KiB, M = MiB, G = GiB; no unit = KiB. 0 or empty = unlimited.

Run kinds

Kind What it is
backup pull a snapshot from a host
restore push files to a host (also dry runs)
verify content check against the client
offsite upload to an offsite target
offsite-verify offsite restore test
offsite-init, offsite-check, offsite-unlock repository maintenance
offsite-restore restore an offsite snapshot to the server

Triggers: manual (a button), schedule (the cron schedule), retry (a retry of an unreachable host). Statuses: see Runs and logs.

Commands Backupkrake runs

A backup:

rsync -aH --numeric-ids --relative --delete --delete-excluded --stats --info=progress2 \
      -e "ssh -i /config/ssh/id_ed25519 -p PORT -o BatchMode=yes …" \
      [-A -X] [-x] [--bwlimit=…] --exclude=… --link-dest=/data/hosts/HOST/PREVIOUS \
      USER@HOST:/etc USER@HOST:/home … /data/hosts/HOST/STAMP.partial/

A restore (with the restore key):

rsync -aH --numeric-ids --relative --itemize-changes [-A -X] [--delete --exclude=…] \
      [--backup --suffix=.bkrestore-STAMP] [--dry-run] \
      /data/hosts/HOST/SNAPSHOT/./PATH USER@TARGET:TARGET_DIR/

An offsite upload, per host, in the snapshot directory:

restic backup . --host HOST --tag backupkrake --tag snapshot=STAMP --ignore-ctime --parent PREVIOUS_ID
restic forget --tag backupkrake --group-by host --prune --keep-daily 7 --keep-weekly 4 …

SSH options: BatchMode=yes, IdentitiesOnly=yes, StrictHostKeyChecking=accept-new with /config/ssh/known_hosts, ConnectTimeout=20, ServerAliveInterval=30, ServerAliveCountMax=6.

Using restic by hand

The image contains restic. To work with a repository directly, e.g. to restore a single file:

docker exec -it \
  -e RESTIC_REPOSITORY='s3:https://…/bucket/backupkrake' -e RESTIC_PASSWORD='…' \
  -e AWS_ACCESS_KEY_ID='…' -e AWS_SECRET_ACCESS_KEY='…' \
  backupkrake sh

restic snapshots --host web1                       # list a host's offsite snapshots
restic ls latest --host web1 /etc/nginx            # look inside
restic dump latest --host web1 /etc/nginx/nginx.conf > /data/restore/nginx.conf
restic restore latest --host web1 --include /etc/nginx --target /data/restore/web1

Paths inside the repository are relative to the snapshot directory, e.g. /etc/nginx/nginx.conf. For SFTP repositories, add the offsite key: -e RESTIC_REPOSITORY='sftp:…' plus -o sftp.args="-i /config/ssh/id_ed25519_offsite -o UserKnownHostsFile=/config/ssh/known_hosts" on each restic command.

Warning

Don't run forget, prune or init by hand while Backupkrake might use the same repository.

HTTP endpoints

Path Meaning
/healthz {"ok": true} without login, for health checks
/login, /logout the session login

Everything else needs a login. There is no API beyond the web UI.