qmrestore

Restore virtual machine from given backup file on the original storage

$ qmrestore [path/to/vzdump-qemu-100.vma.lzo] [100]

$ qmrestore [path/to/vzdump-qemu-100.vma.lzo] [100] --force true

$ qmrestore [path/to/vzdump-qemu-100.vma.lzo] [100] --storage [local]

$ qmrestore [path/to/vzdump-qemu-100.vma.lzo] [100] --live-restore true

qmrestore <backup_file> <target_vmid> [OPTIONS]

    
The path to the backup archive. This can be
a local file path (e.g., /var/lib/vz/dump/vzdump-qemu-100-2023_10_26-12_00_00.vma.gz)
or a reference to a backup on a Proxmox storage
(e.g., local:backup/vzdump-qemu-100-2023_10_26-12_00_00.vma.gz).


    
The virtual machine ID for the restored guest.
This can be a new, unused ID, or an existing one if
used with the --force option.

--storage
    
Specifies the target storage for the virtual machine's disks.
This can be the ID of any configured storage in Proxmox VE
(e.g., local-lvm, cephfs, nfs-storage).

--format
    
Sets the disk image format for the restored disks.
Supported formats include raw, qcow2, or vmdk.
Defaults to the format from the backup if not specified.

--name
    
Assigns a new name to the restored virtual machine.
If not specified, the VM will be named using its ID.

--pool
    
Assigns the restored virtual machine to a specific
resource pool after creation.

--cores
    
Sets the number of CPU cores for the restored VM.

--memory
    
Defines the amount of memory in MiB for the restored VM.

--disk
    
Allows resizing the main disk of the VM during restore.
For example, scsi0=size=30G.
Only applicable for VMA backups and can increase or decrease size.

--network
    
Provides mapping for network interfaces.
For example, --network 'net0=name=eth0,bridge=vmbr1'.
Useful when the target network configuration differs.

--start
    
Automatically starts the virtual machine after a
successful restore operation.

--force
    
Forces the restore operation even if the target_vmid
already exists, potentially overwriting an existing VM.
Use with extreme caution!

--dryrun
    
Performs a dry run, showing what the command would do
without actually restoring the VM.
Useful for testing configurations.

qmrestore is a command-line utility within the
Proxmox Virtual Environment (PVE) suite, specifically designed
for restoring KVM (Kernel-based Virtual Machine) guests from
existing backup archives. It serves as a crucial tool for
disaster recovery, system migration, or creating clones of
virtual machines. The command takes a backup file, typically
created by the
vzdump utility, and unpacks its contents
to recreate a fully functional virtual machine.

It supports various backup formats, including the default
Proxmox-specific
VMA (Virtual Machine Archive) format,
which is highly optimized for efficiency.
qmrestore can place the restored VM's disks
on different storage types supported by Proxmox VE,
such as local directories, LVM-Thin, ZFS, Ceph,
NFS, or iSCSI. Users can specify a new VMID for the
restored guest, or overwrite an existing one (with caution).
Furthermore, it provides extensive options to modify the
restored VM's configuration, such as CPU cores, memory,
disk format, network interface mappings, and more,
allowing for flexible deployments and adjustments
to the target environment.

qmrestore is an integral part of Proxmox VE and
requires a running Proxmox VE host to function.

Permissions: Users must have appropriate
permissions on the Proxmox VE host to perform
restore operations, including access to the backup
storage and the target storage for the VM's disks.

Disk Space: Adequate free disk space on the
specified target storage is critical for a successful restore.
Insufficient space will lead to failure.

VMID Conflicts: Restoring to an existing VMID
without the --force option will result in an error.
Using --force will completely overwrite the existing VM,
leading to data loss if not intended.

Hardware Differences: If restoring to different
hardware, adjustments to network configuration via
--network or SCSI controller types via
--scsihw might be necessary to ensure the
restored VM boots correctly.

qmrestore can directly restore backups
stored on a Proxmox Backup Server. When specifying
the backup_file, you can use the format
<pbs_storage_id>:<backup_id> (e.g.,
pbstest:backup/ct/100/2023-10-26T12:00:00Z)
to pull the backup from the PBS repository.

Primarily, qmrestore works with backups
created by vzdump, which by default uses
the highly efficient VMA (Virtual Machine Archive) format.
It can also handle older vzdump formats
(e.g., plain raw disk images) and compressed archives
(gzip, zstd) that wrap these formats.

Restored virtual machine disks can be placed
on a wide range of storage types configured in
Proxmox VE, including:
Local Directory, LVM-Thin, ZFS
(on local pools or ZFS over iSCSI), Ceph RBD,
NFS, and SMB/CIFS shares.
The choice of storage affects performance and features
available to the VM.

The qmrestore command has been a core component
of the Proxmox Virtual Environment since its early versions.
Proxmox VE, first released in 2007, was built upon
Debian Linux and KVM/LXC technologies.
As Proxmox VE matured, qmrestore evolved alongside,
gaining support for new features like various storage types
(ZFS, Ceph, etc.), improved backup formats (e.g., VMA),
and a wider array of configuration options to match
the growing capabilities of the platform.
A significant development was its integration with
the dedicated Proxmox Backup Server (PBS) in later versions
of Proxmox VE (PVE 6.x onwards), allowing seamless
restores directly from PBS repositories.

qm(1), vzdump(1), pve-manager(1), proxmox-backup-client(1)