AgrarianGameArchive/Docs/Ops/AgrarianVmBackupRunbook.md

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:

/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:

/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:

/bin/bash /boot/config/custom/agrarian-vm-backup.sh --dry-run

Back up one VM during maintenance:

/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:

cd /mnt/user/backups/agrarian-game/vms/snapshots/<timestamp>
sha256sum -c SHA256SUMS

Inspect a backed-up disk:

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.

Record VM restore tests in Docs/Ops/BackupRestoreTestLog.md with the snapshot timestamp, checksum result, disk inspection result, and cleanup status.