# 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.

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