Virtual Machine Backups

Vapor provides built-in mechanisms to protect virtual machine disk images and state against data corruption, hardware failures, or administrative errors. The system supports full, incremental, and differential backup topologies, utilizing Changed Block Tracking (CBT) and Guest Agent synchronization to guarantee application consistency and storage efficiency.

---

1. Backup Topologies

Full Backups

A full backup copies the entire virtual disk image (.qcow2) from start to finish. This creates a standalone, self-contained restore point. While simple, it requires significant storage capacity and time, making it less suitable for frequent execution on large datasets.

Incremental Backups (Changed Block Tracking - CBT)

Incremental backups utilize Changed Block Tracking (CBT) to monitor disk sectors modified since the last backup session.

• Dirty Bitmaps: Vapor creates and maintains a persistent "dirty bitmap" tracking modified blocks within the QCOW2 image.
• Efficiency: During incremental execution, Vapor queries the dirty bitmap and copies only the modified blocks. This significantly reduces backup windows and storage footprints.
• Restore Requirements: Restoring an incremental backup requires the baseline full backup and all intermediate incremental checkpoints.

---

2. Advanced Integration & Consistency

For third-party backup integrations (such as enterprise agents) or custom automation scripts, Vapor exposes deep hypervisor control endpoints:

Filesystem Quiescing (FSFreeze & FSThaw)

To guarantee application and filesystem consistency during active database transactions or write-heavy workloads, Vapor uses the QEMU Guest Agent inside the VM:

• FSFreeze: Before capturing the backup checkpoint, a call to POST /virtualization/computes/{uuid}/guest-agent/fsfreeze instructs the guest operating system to flush cache buffers to disk and temporarily freeze filesystem I/O operations.
• FSThaw: Immediately after the hypervisor registers the checkpoint, a call to POST /virtualization/computes/{uuid}/guest-agent/fsthaw unfreezes the filesystem, allowing the guest to resume writes. This process takes under a second, preventing guest applications from timing out.

Network Block Device (NBD) Pull-Mode Backups

Vapor exposes raw virtual disks over the network using the NBD (Network Block Device) protocol. This enables external backup systems to read blocks directly without host CPU overhead:

• Session Lifecycle: An NBD session is initialized via POST /virtualization/computes/{uuid}/backups/nbd/start, which accepts parameters like incremental_from_checkpoint, nbd_port, and nbd_listen.
• Direct Stream: The NBD server binds to the designated port (e.g. 10899) on the host, exposing the raw block stream of the VM disk.
• Teardown: The session is cleanly closed using POST /virtualization/computes/{uuid}/backups/nbd/stop.

---

3. Resumable Uploads via TUS Protocol

For importing or uploading large VM backups (multi-gigabyte .qcow2 files), Vapor implements the TUS (Resumable Upload) protocol v1.0.0 to handle network interruptions gracefully.

• Initiation: POST /virtualization/computes/backups/upload with headers Upload-Length and Upload-Metadata (base64-encoded properties: filename, vm_name, backup_type, compression, encryption, description, retention_days).
• Data Transfer: PATCH /virtualization/computes/backups/upload/{upload_id} streams binary chunks with Upload-Offset.
• Finalization: POST /virtualization/computes/backups/upload/{upload_id}/complete registers the uploaded file as a completed restore point.

---

4. UI and API Backup Operations

Creating a Backup via Web UI

1. Navigate to Virtualization > Virtual Machines and select the target compute instance.
2. Open the Backups tab and click Create Backup.
3. Configure settings:
   • Mode: Select Full or Incremental (requires an existing CBT baseline checkpoint).
   • Storage Pool: Select the destination pool where the backup archive will be stored.
   • FSFreeze: Enable to enforce filesystem-level transaction consistency.
   • Retention: Define the lifecycle (number of days) before the backup is pruned.
4. Click Submit to dispatch the backup job.

API Endpoint Reference

• List Backups: GET /api/v1/virtualization/computes/{id}/backups
• Create Backup: POST /api/v1/virtualization/computes/{id}/backups
• Delete Backup: DELETE /api/v1/virtualization/computes/backups/{backup_id}
• Restore Backup: POST /api/v1/virtualization/computes/restore (accepts backup_id, new_vm_name, overwrite)
• Import Backup: POST /api/v1/virtualization/computes/backups/import (registers an existing backup path on the host)