kvm.full_backup

kvm.full_backup

Create a full backup of a KVM virtual machine.

Before starting, RVC checks that the target directory is under the directory configured for full_backup, that the destination filename does not already exist, and that the partition has room for both the disk copy and its optimized copy (roughly twice the VM directory's size). The VM is shut down only long enough to copy its disk; it's started again before the copy is optimized and packed into the archive.

From RVC 3.13.0, the archive contains the VM's disk image, its definition, and, when the VM has them, its UEFI NVRAM store and its vTPM state, so a VM restored from it keeps its firmware settings and TPM identity. The NVRAM and vTPM locations are read from the VM's definition. A VM with neither gets no empty placeholders in the archive. Archives created before RVC 3.13.0 hold the disk only, so a VM restored from one loses its firmware variables and TPM identity and needs its configuration repaired by hand. See Backing up and restoring your virtual machines.

To describe an existing archive without extracting it, see kvm.full_backup_info.

Backup archive contents

From RVC 3.13.0, archives use layout format=3. The disk is always the last member of the archive.

MemberPresentContents
backup.metadataAlwaysHow, when, and where the backup was taken.
xml/vm/vm.xmlAlwaysThe VM definition.
xml/vm/vm.iniAlwaysA summary of the VM definition, including its firmware, NVRAM, Secure Boot, TPM, disk, and graphics settings. The TPM fields are empty when the VM has no TPM.
nvram/OVMF_VARS.fdUEFI VMsThe UEFI variable store, including the Secure Boot keys.
swtpm/tpm2-00.permallVMs with a vTPMThe vTPM state.
lost+foundWhen the VM's directory has oneThe lost+found directory of the VM's file system. A cluster-managed VM's directory is its own file system, so its archive includes one.
disk0.qcow2AlwaysThe VM disk.

backup.metadata has a [backup] section describing the backup, followed by sections describing the VM: [vm], and one [disk.N], [interface.N], and [graphics.N] section for each disk, network interface, and graphics device. For a UEFI or vTPM VM, files also lists nvram/OVMF_VARS.fd and swtpm/tpm2-00.permall, and the NVRAM and TPM fields in [vm] are filled in.

The following is an example backup.metadata file for a VM that uses neither UEFI nor a vTPM:

[backup]
rvc=3.13.0
vm=kvm1
host=sit0001red0
created=2026-10-09 16:55:46 UTC
uncompressed_size=2072248320
files=backup.metadata, xml/vm/vm.xml, xml/vm/vm.ini, lost+found, disk0.qcow2
format=3
libvirt=11.3.0
hypervisor=QEMU 10.0.2
optimized=false
compressed=true
automatic=false
cluster_managed=true
snapshots=0
vm_xml=xml/vm/vm.xml
vm_ini=xml/vm/vm.ini
disk_file=disk0.qcow2
disk_files=disk0.qcow2
disk_path=/kvm/kvm1/disk0.qcow2
disk_virtual_size=34359738368
disk_cluster_size=65536
file_sizes=0, 3951, 738, 4096, 2072248320

[vm]
name=kvm1
uuid=00000000-0000-0000-0000-000000000001
title=
description=
vm_type=kvm
machine=pc-i440fx-7.2
os_type=hvm
arch=x86_64
firmware=bios
loader=
nvram=
nvram_template=
secure_boot=false
tpm=
tpm_model=
tpm_version=
tpm_state=
emulator=/usr/bin/kvm
vcpus=4
cpu_mode=host-model
cpu_model=
memory=8589934592
current_memory=8589934592
clock=localtime
boot=hd
on_reboot=restart
video=qxl
guest_agent=true

[disk.0]
path=/kvm/kvm1/disk0.qcow2
device=disk
target=vda
bus=scsi
format=qcow2

[disk.1]
path=/mnt/gold-images/iso/debian-13.3.0-amd64-netinst.iso
device=cdrom
target=hdc
bus=ide
format=raw

[interface.0]
mac=52:54:00:00:00:01
model=virtio
type=bridge
source=br0

[graphics.0]
type=spice
listen=192.0.2.10
port=5902

In RVC 3.13.0, uncompressed_size counts only the disk, not the other members of the archive, and the first value in file_sizes, which is the size of backup.metadata itself, is reported as 0.

JSON-RPC Request

{"jsonrpc":"2.0","id":1,"method":"kvm.full_backup","params":{"hostname":"kvm1","filename":"kvm1-backup-1.tar","optimize":true}}

Request Parameters

ArgumentTypeDescriptionRequiredDefault
hostnameStringThe name of the virtual machine.Yes-
filenameStringThe backup file name.Yes-
targetStringThe directory where the backup file should be stored. When omitted, the directory configured for full_backup in the RVC configuration file is used.Nonil
automaticBooleanWhether or not to write the backup into a <kvm_hostname>/scheduled/ subdirectory of the target directory. The backup is built in <kvm_hostname>/scheduled/temporary/ and then moved into <kvm_hostname>/scheduled/. Any backup already in <kvm_hostname>/scheduled/ is deleted, so only the most recent automatic backup is kept. Backups elsewhere in the target directory are not affected.Nofalse
compressBooleanWhether or not to compress the full backup tar archive. .gz is appended to filename unless it already ends in .gz. Compression runs in parallel when pigz is available on the node; otherwise it is single-threaded, which is considerably slower on large disks.Nofalse
optimizeBooleanWhether or not to compact the copy of the disk stored in the backup, reclaiming unallocated space. The VM's own disk is not modified. The optimized copy doesn't include the VM's internal snapshots, so their definitions are left out of the archive.Nofalse
notify-uriStringWhere to send the backup progress updates.Nonil

In RVC 3.13.0, the CLI help text for --automatic, --compress, and --optimize does not match their behavior. The descriptions above are correct.

JSON-RPC Response

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "Starting full backup for kvm1"
}

RVC CLI Example

rvc kvm full-backup --hostname kvm1 --filename kvm1-backup-2.tar.gz --optimize --compress

Response

Starting full backup for kvm1
Shutting down kvm1...
checking status 30...
checking status 29...
checking status 28...
checking status 27...
checking status 26...
kvm1 successfully shut off.
Copying /kvm/kvm1/disk0.qcow2 to /mnt/backups/workdir-for-kvm1/copy-of-kvm1-disk0.qcow2. Disk size: 1.17G
Virtual Machine kvm1 disk copied to /mnt/backups/workdir-for-kvm1/copy-of-kvm1-disk0.qcow2 in 5 seconds.
Starting kvm1...
checking status 30...
kvm1 successfully started.
Optimizing /mnt/backups/workdir-for-kvm1/copy-of-kvm1-disk0.qcow2 into /mnt/backups/workdir-for-kvm1/disk0.qcow2.
Optimizing kvm1 backup disk: 0.00
Optimizing kvm1 backup disk: 5.00
Optimizing kvm1 backup disk: 9.01
Optimizing kvm1 backup disk: 13.01
Optimizing kvm1 backup disk: 17.01
Optimizing kvm1 backup disk: 21.02
Optimizing kvm1 backup disk: 25.02
Optimizing kvm1 backup disk: 29.02
Optimizing kvm1 backup disk: 34.03
Optimizing kvm1 backup disk: 38.03
Optimizing kvm1 backup disk: 42.03
Optimizing kvm1 backup disk: 46.04
Optimizing kvm1 backup disk: 50.04
Optimizing kvm1 backup disk: 54.04
Optimizing kvm1 backup disk: 59.07
Optimizing kvm1 backup disk: 63.07
Optimizing kvm1 backup disk: 67.08
Optimizing kvm1 backup disk: 71.08
Optimizing kvm1 backup disk: 75.08
Optimizing kvm1 backup disk: 79.09
Optimizing kvm1 backup disk: 83.09
Optimizing kvm1 backup disk: 87.09
Optimizing kvm1 backup disk: 91.10
Optimizing kvm1 backup disk: 95.12
Optimizing kvm1 backup disk: 100.00
Creating /mnt/backups/kvm1-backup-2.tar.gz file...
Creation of backup file /mnt/backups/kvm1-backup-2.tar.gz took 2 minutes and 3 seconds.
Full backup successfully finished.

Output for a cluster managed Virtual Machine:

Starting full backup for kvm1
Maintenance mode set to enabled.
Shutting down kvm1...
checking status 30...
checking status 29...
checking status 28...
checking status 27...
checking status 26...
kvm1 successfully shut off.
Copying /kvm/kvm1/disk0.qcow2 to /mnt/backups/workdir-for-kvm1/copy-of-kvm1-disk0.qcow2. Disk size: 1.17G
Virtual Machine kvm1 disk copied to /mnt/backups/workdir-for-kvm1/copy-of-kvm1-disk0.qcow2 in 5 seconds.
Starting kvm1...
checking status 30...
kvm1 successfully started.
Optimizing /mnt/backups/workdir-for-kvm1/copy-of-kvm1-disk0.qcow2 into /mnt/backups/workdir-for-kvm1/disk0.qcow2.
Optimizing kvm1 backup disk: 0.00
Optimizing kvm1 backup disk: 5.00
Optimizing kvm1 backup disk: 9.01
Optimizing kvm1 backup disk: 13.01
Optimizing kvm1 backup disk: 17.01
Optimizing kvm1 backup disk: 21.02
Optimizing kvm1 backup disk: 25.02
Optimizing kvm1 backup disk: 29.02
Optimizing kvm1 backup disk: 34.03
Optimizing kvm1 backup disk: 38.03
Optimizing kvm1 backup disk: 42.03
Optimizing kvm1 backup disk: 46.04
Optimizing kvm1 backup disk: 50.04
Optimizing kvm1 backup disk: 54.04
Optimizing kvm1 backup disk: 59.07
Optimizing kvm1 backup disk: 63.07
Optimizing kvm1 backup disk: 67.08
Optimizing kvm1 backup disk: 71.08
Optimizing kvm1 backup disk: 75.08
Optimizing kvm1 backup disk: 79.09
Optimizing kvm1 backup disk: 83.09
Optimizing kvm1 backup disk: 87.09
Optimizing kvm1 backup disk: 91.10
Optimizing kvm1 backup disk: 95.12
Optimizing kvm1 backup disk: 100.00
Creating /mnt/backups/kvm1-backup-2.tar.gz file...
Creation of backup file /mnt/backups/kvm1-backup-2.tar.gz took 2 minutes and 3 seconds.
Waiting for the refresh of all cluster VM resources statuses.
Maintenance mode set to disabled.
Full backup successfully finished.

© 2026 Scale Computing, Inc. All rights reserved.

Scale Computing, SC//AcuVigil, SC//Connect, and SC//Reliant are trademarks of Scale Computing, Inc.