Unraid VM Backup

VM backup, restore, retention, and recovery testing for Unraid.

Important

Verify backups and complete a restore or Recovery Test before relying on any backup product for important workloads.

Unraid VM Backup is a native Unraid WebGUI plugin for live and offline VM backup. It records recovery metadata with the repository so an existing repository can be connected from a replacement Unraid server without the original plugin state.

Installation

1. Open Unraid → Plugins → Install Plugin.

2. Enter:

   https://raw.githubusercontent.com/MiranoVerhoef/Unraid-VM-Backup/main/unraid.vmbackup.plg
   

3. Open Settings → User Utilities → Unraid VM Backup.

4. Complete First Setup.

Capabilities

• Live VM backup through libvirt/QEMU.
• QEMU changed-block incremental backup for supported running QCOW2 disks.
• Full backups and repository-side synthetic full backups.
• Sparse capture and restore to preserve thin disk allocation where supported.
• Schedule-aware hourly, daily, weekly, and monthly GFS retention.
• Guided disk restore and optional VM recreation from saved libvirt metadata.
• Scheduled and manually started Recovery Testing.
• QEMU Guest Agent validation, cached console screenshots, and manual review when automated validation is unavailable.
• SMTP notifications for backup, restore, warning, failure, and Recovery Testing results.
• Repository capacity, verification, deletion grace, undo, purge, and garbage-collection controls.
• Per-VM backup history, transfer timing, and Source, Network, or Destination bottleneck analysis.
• Repository reconnection after complete loss of the original Unraid server or boot device.

Requirements

• Unraid OS 7.2 or newer.
• VM Manager/libvirt, virsh, qemu-img, PHP cURL, OpenSSL, and Node.js 22 or newer.
• An NFS or SMB backup destination hosted outside the protected Unraid server is required by default. A guarded advanced override is available for same-host storage.
• QCOW2 VM disks for changed-block incrementals. Raw disks, block devices, and stopped VMs use sparse full capture.

The installer validates required commands and the Node.js major version before starting the service.

First Setup

1. Select or create a mounted repository directory under /mnt/. External NFS or SMB storage is required by default.
2. Initialize a new repository or connect an existing repository.
3. Select protected VMs and configure the global or custom backup schedules.
4. Configure retention. GFS tiers can retain only recovery points produced by the selected schedule.
5. Review performance, notification, Recovery Testing, and service settings as needed.
6. Run a backup, verify the recovery point, and complete a restore or Recovery Test.

Configuration is stored on the Unraid boot device. Recovery-point data, catalog data, VM definitions, history links, and recovery-test reports are stored with the repository.

The advanced Allow a same-host repository option requires an explicit warning acknowledgement. It permits locally attached storage or a share served by the same Unraid host, but does not relax the /mnt/ path requirement or repository create, write, synchronization, read, rename, and delete checks. Host, controller, pool, filesystem, or power failures can affect both the protected VM and a same-host repository.

Backup consistency

VM state and coordination	Recorded consistency
Running VM with successful QEMU Guest Agent filesystem freeze	Filesystem-coordinated
Running VM when guest freeze is unavailable or fails	Crash-consistent, with a warning
Stopped VM	Offline

Filesystem freeze does not by itself provide application-aware database or service quiescence. Configure application-specific guest procedures where required.

Backup formats

Operation	Storage behavior
Full backup	Reads allocated source regions and records sparse regions without storing full zero ranges
Incremental backup	Reads blocks marked dirty by the QEMU/libvirt checkpoint chain
Synthetic full	Creates a complete recovery-point map from existing repository data without rereading the VM disk
Restore	Materializes the selected recovery point as sparse output where the destination supports sparse files

Each recovery point has an independent disk map. Restore does not require an older parent manifest to remain present.

Restore

1. Open Storage and Recovery.
2. Select the VM and recovery point.
3. Review destination paths, capacity preflight, overwrite behavior, and VM recreation settings.
4. Restore the disks.
5. Review the restored VM definition, storage paths, network interfaces, and passthrough devices before production use.

Restore capacity is reserved before work begins to reduce conflicts between simultaneous restore and Recovery Testing operations.

Recovery Testing

Recovery Testing restores a selected point into an isolated temporary VM. Network interfaces, PCI passthrough devices, host filesystem mounts, and production disk paths are excluded by default. CPU allocation can follow the source VM or use a configured test allocation.

A result is Verified only after repeated QEMU Guest Agent responses. If the guest agent is absent or the timeout expires, the result requires manual review. The console screenshot is cached for later viewing and can be included in SMTP reporting.

Recovery Testing consumes temporary storage and CPU. Configure the timeout, schedule, VM selection, test CPU allocation, SMTP delivery, and network policy under Settings.

Upgrade

Use the update control on the Unraid Plugins page when a newer public release is available. The package upgrade retains local configuration and repository data.

Manual update:

wget -O /boot/config/plugins/unraid.vmbackup/unraid.vmbackup.plg \
  https://raw.githubusercontent.com/MiranoVerhoef/Unraid-VM-Backup/main/unraid.vmbackup.plg
plugin install /boot/config/plugins/unraid.vmbackup/unraid.vmbackup.plg forced && rm -f -- /boot/config/plugins/unraid.vmbackup/unraid.vmbackup.plg

Do not replace a published .plg or .txz with an asset from another version.

Uninstallation

Uninstalling removes the plugin service, WebGUI files, local configuration, local state, logs, package records, and plugin-managed temporary working data. External backup repositories and restored VM disks are not deleted.

Reconnect the same repository after reinstalling by selecting Connect existing. The original Unraid boot device and previous local state are not required.

Recovery after server loss

1. Repair or replace the Unraid server.
2. Mount the repository. Use read-only storage access first if repository damage is suspected.
3. Install Unraid VM Backup from the public plugin URL.
4. Select Connect existing and choose the repository.
5. Review repository health and verify the required recovery point.
6. Run Recovery Testing where capacity permits.
7. Restore disks and review the recreated VM configuration before enabling production networking.

Diagnostics and security

The diagnostics export applies structured redaction to credentials, SMTP identity, email addresses, VM identity, UUIDs, MAC addresses, IP addresses, domain XML, and filesystem paths. Automated tests cover redaction before diagnostic events are written and when legacy diagnostic files are loaded.

Always review a diagnostic file before sharing it. Do not attach VM disks, repository data, private keys, API tokens, SMTP passwords, or unrelated system diagnostics to a public issue.

Report vulnerabilities through GitHub private vulnerability reporting as described in SECURITY.md.

Known limitations

• Changed-block incrementals require a running VM with supported QCOW2 disks and valid libvirt checkpoint metadata.
• Raw disks, ZFS zvols/block devices, and stopped VMs require sparse full capture.
• Automated Recovery Testing verification requires a working QEMU Guest Agent in the restored guest.
• Filesystem freeze is not application-aware backup for every database or service.
• Network repository performance and available temporary restore capacity can limit backup and Recovery Testing throughput.
• Same-host repositories do not protect against failures that affect both the VM storage and backup storage. External storage remains the default.
• The public compatibility record is still developing across Unraid host, guest, storage, and network combinations.

See Known limitations for operational detail.

Support

• Bug report
• Feature request
• Compatibility report
• Questions and configuration
• Security policy
• Support guidance

Release channels

• Pre-release: requires additional compatibility validation or operational observation. GitHub marks the release as a pre-release.
• Stable: a release may be designated stable only after explicit maintainer approval and completion of the acceptance checklist.

Public releases use the Unraid date version format YYYY.MM.DD.REVISION. Source, tag, plugin metadata, and package asset use the same release identifier. Published releases are not replaced; corrections receive a new date version.

License

Copyright © 2026 Mirano Verhoef.

Unraid VM Backup is free software licensed under the GNU Affero General Public License version 3, with no option to use a later version (AGPL-3.0-only). You may use, study, modify, and redistribute the software under that license. Modified versions offered to users over a network must provide access to their corresponding source as required by AGPL section 13.

See Project identity and official builds for provenance and naming guidance. The AGPL licenses the repository's copyrighted contents; it does not represent third-party endorsement or grant third-party trademark rights.

Unraid is a trademark of Lime Technology, Inc. This project is independent and is not endorsed by Lime Technology.