qm-migrate
Migrate virtual machines between Proxmox nodes
TLDR
Migrate a specific virtual machine
Override the current I/O bandwidth limit with 10 KiB/s
Allow migration of virtual machines using local devices (root only)
Use online/live migration if a virtual machine is running
Enable live storage migration for local disks
SYNOPSIS
qm migrate
PARAMETERS
The ID of the virtual machine or container to migrate.
The target Proxmox VE host.
--online
Perform a live (online) migration. This minimizes downtime. Requires shared storage for best results. Equivalent to `-with-hv`.
--with-local-disks
Migrate also the local disks. This is usually not needed when using shared storage.
--targetstorage
Specify the target storage for disks. If not specified, the storage will be automatically selected.
--target
The target node name. Required for migrations when multiple nodes are possible (e.g. with HA groups).
--delete
Delete the source VM/container after successful migration.
--migration_network
Specify the network to use for migration. If not specified, Proxmox VE will automatically choose a suitable network.
--migration_type
Specify the migration type. Defaults to 'downtime'. 'secure' enforces encryption. 'tcp' and 'unix' dictate transport methods, with unix sockets being faster.
--compress
Enable compression during migration.
--max_workers
Number of workers. Defaults to 16. Useful to increase the migration speed.
--restart
Restart the VM/CT after migration.
--unprotected
Disable HA protection during the migration. Implies --skiplock.
--skiplock
Skip locking the VM during the migration. Use with extreme caution, as it can lead to data corruption.
--debug
Enable debug logging.
--profile
Select a pre-configured migration profile. See `qm migrate profile`.
--with-hv
Alias for --online.
DESCRIPTION
The `qm migrate` command is a powerful tool used within the Proxmox Virtual Environment (Proxmox VE) to migrate virtual machines (VMs) and containers between different Proxmox VE hosts. It allows for live or offline migration, minimizing downtime during infrastructure maintenance, upgrades, or hardware rebalancing.
The command facilitates the transfer of VM/container disk images, configuration files, and memory state (in live migration) from a source host to a destination host. It relies on Proxmox VE's cluster functionality and requires a properly configured and healthy Proxmox VE cluster for successful operation. Options control aspects like network configuration, migration speed, compression, and whether the migration should be performed online (live) or offline (stop the VM, then migrate). Successful migration relies on shared storage access between hosts (though this isn't mandatory, it's strongly recommended for live migrations), and ensuring compatible CPU architectures between hosts can be critical for avoiding issues.
The command integrates with Proxmox's High Availability (HA) system to ensure services remain available. It's crucial to carefully plan and test migrations, especially live migrations, to ensure minimal disruption. The command returns zero when everything is correct and non-zero when it fails.
CAVEATS
Live migration requires shared storage accessible by both the source and destination hosts for optimal performance and minimal downtime. Incompatible CPU architectures between hosts can prevent successful live migration or cause issues after migration. Ensure the Proxmox VE cluster is healthy before attempting any migrations. Pay special attention when migrating HA configured resources. The --skiplock option can lead to data corruption if not used carefully.
MIGRATION PROFILES
Migration profiles allows you to pre-configure migration settings. This is useful for complex migration scenarios or for automating migration tasks. You can create and manage migration profiles using the `qm migrate profile` command.
Run `man qm` to see all possible parameters for migration profiles.
NETWORK CONFIGURATION
Ensure that the migration network is properly configured and accessible between the source and destination hosts. Use the `--migration_network` option to explicitly specify the network interface to use for migration traffic. Proper network configuration significantly impacts the speed and reliability of the migration process.
HISTORY
The `qm migrate` command is a core component of the Proxmox VE virtualization platform. It was developed as part of the initial Proxmox VE releases and has been continuously improved over time to enhance migration performance, stability, and feature set. Features such as live migration, support for various storage types, and integration with the Proxmox VE API have been added over the years to meet the evolving needs of users managing virtualized environments. The command's design reflects a focus on providing a flexible and reliable mechanism for moving workloads between Proxmox VE hosts.