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.

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

---

5. External Backup Integration (Vinchin Backup & Recovery)

In addition to native internal backup capabilities, Cockpit supports integration with third-party enterprise backup solutions, such as Vinchin Backup & Recovery, via the cockpit-ovirt-shim service interface.

5.1 Enabling the oVirt API Shim Service

To allow external backup solutions like Vinchin to communicate with Cockpit's management API:

1. Access the Cockpit appliance management interface.
2. Navigate to Services.
3. Locate the cockpit-ovirt-shim service.
4. Enable and start the service, verifying that it is active and listening on its dedicated port.

5.2 Connecting Vinchin to Cockpit

1. Log into the Vinchin Backup & Recovery administration console.
2. Navigate to Infrastructure > Virtual Platform.
3. Click Add to register a new virtual platform.
4. Select oVirt as the platform type (Vinchin uses the oVirt API shim to interact with Cockpit).
5. Enter the target Cockpit IP address and administrator credentials, then confirm the connection.
6. Once registered, all virtual machines managed by Cockpit will be listed automatically under Vinchin's virtual platform inventory.

5.3 Performing External VM Backups

1. In Vinchin, navigate to VM Backup > Backup to create a backup job.
2. Select the target Cockpit virtual machines.
3. Choose the target backup storage destination.
4. Under Transmission Strategy, set Transfer via to Image I/O (Required for optimal and reliable disk block transfer).
5. Configure job scheduling, submission, and run the backup task.

5.4 External VM Restoration

1. In Vinchin, navigate to VM Restore > Restore to create a restore job.
2. Select the desired backup point of the Cockpit virtual machine.
3. Choose the target Cockpit destination host.
4. Configure VM restore parameters (e.g., target storage pool, guest OS settings, or disk renaming to prevent naming conflicts).
5. Under Transmission Strategy, set Transfer via to Image I/O.
6. Submit and execute the restore job, then verify that the virtual machine powers on successfully on the target Cockpit host.