Scenarios step by step

Go to the contents

The scenarios join the single functions into complete procedures. Host names, paths and keys are examples.

17.1 Scenario A: backing up a KVM guest over the network (daily, a new generation on Sundays)#

Starting point: the guest icinga lies on the LVM volume /dev/vg0/icinga.disk of a KVM host. The backup server backup.example.org is already running (Chapter 4). The guest is to be backed up application-consistently at night, kept for 30 days, and every week a physically independent base is to be created.

1. On the server create a key for the host: bkp_maintenance acl-add --acl-file /etc/bkp/acl --dir kvm01 and systemctl reload bkp_target.
2. On the KVM host copy target.crt to /etc/bkp/, put the key into /etc/bkp/kvm01.key (chmod 600).
3. Create a wrapper script that passes on additional options.

/usr/local/sbin/bkp_icinga.sh (make it executable with chmod 755)

#!/bin/sh
# /usr/local/sbin/bkp_icinga.sh [--type full]
set -eu
exec /usr/local/bin/bkp_agent \
    --source /dev/vg0/icinga.disk \
    --target backup.example.org:9990 --target-dir kvm01 \
    --tls-ca /etc/bkp/target.crt --api-key file:/etc/bkp/kvm01.key \
    --name icinga --hash blake3 --retention 30d --threads 4 --no-progress \
    --snapshot-size 5G \
    --pre-snapshot  'virsh domfsfreeze icinga' \
    --post-snapshot 'virsh domfsthaw icinga' "$@"

Schedule

# /etc/cron.d/bkp_icinga
30 1 * * 1-6  root  /usr/local/sbin/bkp_icinga.sh             >> /var/log/bkp_icinga.log 2>&1
30 1 * * 0    root  /usr/local/sbin/bkp_icinga.sh --type full >> /var/log/bkp_icinga.log 2>&1

1. Test once by hand: /usr/local/sbin/bkp_icinga.sh. Besides done: full run ... the log must show the note on the snapshot and the consistency window.
2. After one week check with bkp_restore --list that there are seven runs: Full in a new generation on Sundays (column STORE), otherwise Incremental.
3. On the server set up a daily maint-prune job (scenario E) so that expired runs and empty generations disappear.
4. Once a month carry out the restore test from scenario C.

17.2 Scenario B: backing up a Windows server with VSS#

1. On the server set up a key and a directory (acl-add --dir srv-win01). Copy target.crt and the key to C:\ProgramData\AegisGrid\.
2. Install bkp_agent.exe with aegisgrid-setup.exe (components agent, restore and sched).
3. Start a first run in an administrator command prompt:

"C:\Program Files\AegisGrid\bin\bkp_agent.exe" --source \\.\PhysicalDrive0 ^
    --target backup.example.org:9990 --target-dir srv-win01 ^
    --tls-ca C:\ProgramData\AegisGrid\target.crt --api-key file:C:\ProgramData\AegisGrid\srv-win01.key ^
    --name srv-win01 --vss-mode copy

The job scheduler takes over the runs: component sched in bkp_setup. Then the service aegisgrid-sched runs (account LocalSystem, starts automatically with a delay), and the jobs are in C:\ProgramData\AegisGrid\bkp_sched.cfg (only command=agent). Changes take effect without a restart. bkp_sched list shows the state, the logs of every run are under C:\ProgramData\AegisGrid\logs\bkp_sched-jobs\<job>\, those of the service itself in ...\logs\bkp_sched.log. C:\ProgramData\AegisGrid (settings, keys) and ...\logs are readable only for SYSTEM and administrators; bkp_setup and bkp_updater set this up.

bkp_sched.cfg: daily at 01:30 (local time), a new generation every month

[srv-win01]
command=agent
args=--source \\.\PhysicalDrive0 --target backup.example.org:9990 --target-dir srv-win01 --tls-ca C:\ProgramData\AegisGrid\target.crt --api-key file:C:\ProgramData\AegisGrid\srv-win01.key --name srv-win01 --store-generation 1m
retention=30d
schedule=30 1 * * *

Stopping the service, an update and shutting down hold a running backup: it continues one minute after the next start of the service where it stood, without a mail. The service waits for other jobs. bkp_sched stop <job> (as administrator) on the other hand cancels it and discards the backup begun. Mail ([mail]) and the HTTPS API ([api], docs/sched-api.txt) are handled by the process bkp_sched_net, which runs as NT AUTHORITY\LocalService. Without the job scheduler it also works with the Task Scheduler (schtasks /create ... /sc daily), then with --retention 30d on the command line. Jobs can also be viewed, created and started with the management console, from the server itself or from a workstation (Chapter 14).

17.3 Scenario C: complete restore after a disk failure#

Starting point: the volume /dev/vg0/data is lost. It is to be restored onto a new volume /dev/vg0/data_new.

1. Create a new volume at least the size of the source (the source size is in bkp_restore --list in the column SOURCE): lvcreate -L 100G -n data_new vg0.
2. Look at the available backups:

bkp_restore --server backup.example.org:9990 --server-dir vm1 --tls-ca /etc/bkp/target.crt \
            --api-key file:/etc/bkp/vm1.key --list --name data

1. Restore the newest backup (for an encrypted store add --decrypt-key file:<path>):

bkp_restore --server backup.example.org:9990 --server-dir vm1 --tls-ca /etc/bkp/target.crt \
            --api-key file:/etc/bkp/vm1.key --name data --target /dev/vg0/data_new

1. Check the exit code: 0 means complete, 3 means that damaged areas were filled with zeros (log and --damage-file, Chapter 7).
2. Check the result: fsck -n /dev/vg0/data_new, then mount it in a directory (mount -o ro) and check the data by samples.
3. Only then switch the service over to the new volume.

Important for a failure of the backed-up machine itself: the restore only needs bkp_restore, target.crt, the API key and, if applicable, the encryption key. Keep these things ready outside the backed-up system (password manager, emergency USB stick), otherwise after a total failure you are left without access to the backups.

17.4 Scenario D: restoring to a certain point in time#

Starting point: the day before yesterday something was deleted by mistake. The state of the night before yesterday is needed, not the newest one.

1. Look with bkp_restore ... --list --name data which backups there are; the column CREATED is local time.
2. Choose the state with --at (the newest run up to this point in time) or the run from the list with --run:

bkp_restore --server backup.example.org:9990 --server-dir vm1 --tls-ca /etc/bkp/target.crt \
            --api-key file:/etc/bkp/vm1.key --name data --at "2026-10-13 06:00" \
            --target /dev/vg0/data_pit

1. Mount the restored volume read-only, copy out the files wanted and discard the volume. The running system stays untouched.

17.5 Scenario E: tidying up and mirroring storage#

Starting point: the server has been storing backups of kvm01 for months. Expired runs are to disappear regularly, the storage is to be checked weekly, and every new backup is also to be on a second server rz2. In addition the state at the beginning of the month is to go as an archive onto a USB disk.

1. First look at what the store uses and what a prune would delete:

bkp_maintenance store-info --store /srv/backups/kvm01/default.cbs --exclusive
bkp_maintenance prune --search-dir /srv/backups/kvm01 --dry-run

1. If the selection fits, plan the maintenance in the target scheduler (/etc/bkp/bkp_target_sched.cfg, then bkp_target --sched-validate):

/etc/bkp/bkp_target_sched.cfg

[prune-kvm01]
command=maint-prune
schedule=30 6 * * *
args=--search-dir {storage}/kvm01

[scrub-kvm01]
command=maint-scrub
schedule=0 8 * * 6
args=--search-dir {storage}/kvm01

[mirror-kvm01]
command=maint-mirror
on=backup-success
match-dir=kvm01
args=--store {store} --to server:rz2.example.net:9990 --to-server-dir kvm01 --to-tls-ca /etc/bkp/rz2.crt --to-api-key file:/etc/bkp/rz2.key

1. At the beginning of the month write the state as an archive (or as a maint-export job):

bkp_maintenance export --store /srv/backups/kvm01/default.cbs --name icinga --at "2026-10-01 03:00" --to /mnt/usb/

1. If a scrub reports damage (exit 1 in the job log), replace the objects concerned from the mirror and check again: bkp_maintenance repair --store /srv/backups/kvm01/default.cbs --from server:rz2.example.net:9990 --from-server-dir kvm01 --from-store default --tls-ca /etc/bkp/rz2.crt --api-key file:/etc/bkp/rz2.key.

17.6 Scenario F: renewing the server certificate and exchanging the API key#

1. Create a new certificate: bkp_maintenance tls-init --cert /etc/bkp/target.crt --key /etc/bkp/target.key --cn backup.example.org --days 3650 --force.
2. Distribute target.crt to all clients (agents pin to it; an old certificate leads to a TLS error, see Chapter 26).
3. systemctl restart bkp_target.
4. For a new key: bkp_maintenance acl-add --acl-file /etc/bkp/acl --dir vm1, copy the key printed to the client, then remove the old line from the ACL and restart the server.
5. On a client check with bkp_restore ... --list that certificate and key work.