Implement Unraid VM backup job

2026-05-14 13:01:18 -07:00
parent 3fd347d1f6
commit 95166b0dab
4 changed files with 398 additions and 4 deletions
@@ -0,0 +1,91 @@
+# Agrarian VM Backup Runbook
+
+Agrarian VM backups run on Unraid `DevBox` and protect the VM definitions,
+NVRAM, and virtual disks for the development/build machines.
+
+## VMs
+
+- `Windows-Builder`
+- `Ubuntu-Codex`
+
+## Paths
+
+- Persistent script: `/boot/config/custom/agrarian-vm-backup.sh`
+- Runtime helper path: `/usr/local/sbin/agrarian-vm-backup`
+- Backup root: `/mnt/user/backups/agrarian-game/vms`
+- Snapshots: `/mnt/user/backups/agrarian-game/vms/snapshots`
+- Cron definition: `/boot/config/plugins/dynamix/agrarian-vm-backup.cron`
+
+## Safety Model
+
+The scheduled job is safe by default. It skips VMs that are currently running,
+because copying a live VM disk image is not considered a reliable backup.
+
+For a real VM backup during a maintenance window, run:
+
+```bash
+/boot/config/custom/agrarian-vm-backup.sh --shutdown-running
+```
+
+If running directly from the persistent flash path fails because `/boot` is
+mounted noexec, invoke it through bash:
+
+```bash
+/bin/bash /boot/config/custom/agrarian-vm-backup.sh --shutdown-running
+```
+
+That command gracefully shuts down any running target VM, backs up its XML,
+NVRAM, Unraid VM/share config, and compressed `qcow2` disk image, then starts
+the VM again after the backup completes.
+
+Preview what would happen:
+
+```bash
+/bin/bash /boot/config/custom/agrarian-vm-backup.sh --dry-run
+```
+
+Back up one VM during maintenance:
+
+```bash
+/bin/bash /boot/config/custom/agrarian-vm-backup.sh --shutdown-running --vm Ubuntu-Codex
+```
+
+## Schedule
+
+The installed cron job runs weekly. Without `--shutdown-running`, it only backs
+up VMs that are already off. This avoids an unexpected Windows build machine or
+Ubuntu-Codex outage during active work.
+
+## Retention
+
+Snapshots older than 120 days are pruned after a successful backup. Manual
+pre-change backups can be copied or renamed before pruning if they need to be
+kept longer.
+
+## Restore Notes
+
+Each snapshot contains:
+
+- `MANIFEST.txt`
+- `SHA256SUMS`
+- VM XML under `vms/<VM>/xml/`
+- NVRAM files under `vms/<VM>/nvram/` when present
+- compressed `qcow2` disk images under `vms/<VM>/disks/`
+- selected Unraid config under `unraid-config/`
+
+Verify a snapshot:
+
+```bash
+cd /mnt/user/backups/agrarian-game/vms/snapshots/<timestamp>
+sha256sum -c SHA256SUMS
+```
+
+Inspect a backed-up disk:
+
+```bash
+qemu-img info vms/Ubuntu-Codex/disks/hdc-vdisk1.img.qcow2
+```
+
+Restore should be done to a new VM or a test path first. Do not overwrite a
+working VM disk until the backup has been verified and the original disk has
+been preserved.