Virtual Machine Backups

Cockpit provides comprehensive virtual machine backup and restore capabilities, allowing administrators to secure virtual machine states, disks, and configurations through manual backups and automated schedules.

---

1. Backup Specifications

When creating a backup, either manually or via a schedule, administrators can configure the following technical parameters:

1.1 Backup Types

• Full: Copies the entire virtual disk volume. This serves as the independent baseline.
• Incremental: Copies only the blocks that have changed since the last backup (Full or Incremental). This forms a backing chain of changes to minimize storage footprint.
• Differential: Copies only the blocks that have changed since the last Full backup.

1.2 Target Destination

Backups are stored as .qcow2 images (or compressed variants) in one of the host's configured datastores (storage pools). The target storage pool tracks capacity limits and directory sweeps.

1.3 Compression

To optimize storage utilization, disk blocks can be compressed during the backup process. Supported formats include:

• None: No compression (fastest execution).
• Gzip: Standard compression.
• Zstd (Zstandard): High performance, optimal compression ratio and speed.
• Xz: Maximum compression ratio (high CPU overhead).

1.4 Encryption

For security compliance, backups can be encrypted at the block level using symmetric encryption algorithms:

• None: Plaintext storage.
• AES-128: Symmetric encryption using a 128-bit key.
• AES-256: Symmetric encryption using a 256-bit key. Note: A secure passphrase/key must be provided during creation and is required for subsequent restoration.

1.5 Memory Dumps

Administrators can enable the Include Memory option. This captures the active runtime RAM state of the VM, permitting the VM to be restored to an active running state rather than booting from a powered-off state.

---

2. Auto Backup Scheduler

Cockpit automates VM data protection through the backup schedule manager. Schedules are mapped to the database and executed by the backend task runner.

2.1 Schedule Configuration

• Periodicity: Daily, Weekly, or Monthly.
• Backup Type: Full, Incremental, or Differential.
• Target Storage Pool: The datastore destination.
• Retention Policy: Specifies the retention window in days (e.g., 7 days). Backups exceeding this limit are automatically purged by the backend cleanup worker.
• Description: Text metadata describing the job's context.

---

3. Streaming and Uploads (TUS Protocol)

For importing external backups or uploading existing virtual disks, Cockpit integrates the TUS (Resumable Upload) Protocol via tus-js-client.

[Client / Browser]                                      [Vapor Host Host Agent]
        │                                                        │
        │ ─── Initiate Upload (POST /backups/upload) ──────────> │ (Pre-allocates space)
        │ <── Receive Upload URL & Unique ID ─────────────────── │
        │                                                        │
        │ ─── Stream Chunks (PATCH /upload/{id} via TUS) ──────> │ (Appends data)
        │     [Handles network disconnects and resumes]          │
        │                                                        │
        │ ─── Finalize Upload ─────────────────────────────────> │ (Validates image)

• Resumability: If network connectivity is interrupted during a large .qcow2 upload, the client automatically queries the target server for the last offset and resumes streaming from that byte offset without re-uploading completed data.
• Supported Formats: Supports .qcow2 along with compressed variants .qcow2.gz, .qcow2.zst, and .qcow2.xz.

---

4. Restore Workflows

Restoring a backup recreates the VM configuration and disk images from the stored archive.

4.1 Restore Options

1. Restore as New VM: Creates a new virtual machine instance using a different name (e.g., vm-restored). This is non-disruptive and allows testing the guest OS side-by-side with production.
2. Overwrite In-place: Overwrites the existing virtual machine disks.

   CAUTION

   Overwriting a VM is destructive and replaces the current disk contents. The target VM must be powered off before commencing the overwrite.

3. Decryption Key: If the backup archive was encrypted during creation, the correct AES key must be provided; otherwise, the hypervisor will fail to attach and read the disk block signatures.