12.6. Migrating a virtual machine using the command-line interface
If the current host of a virtual machine (VM) becomes unsuitable or cannot be used anymore, or if you want to redistribute the hosting workload, you can migrate the VM to another KVM host. The following procedure provides instructions and examples for various scenarios of such migrations.
Conditions préalables
- The source host and the destination host both use the KVM hypervisor.
-
The source host and the destination host are able to reach each other over the network. Use the
ping
utility to verify this. Ensure the following ports are open on the destination host.
- Port 22 is needed for connecting to the destination host by using SSH.
- Port 16509 is needed for connecting to the destination host by using TLS.
- Port 16514 is needed for connecting to the destination host by using TCP.
- Ports 49152-49215 are needed by QEMU for transfering the memory and disk migration data.
- For the migration to be supportable by Red Hat, the source host and destination host must be using specific operating systems and machine types. To ensure this is the case, see Supported hosts for virtual machine migration.
- The VM must be compatible with the CPU features of the destination host. To ensure this is the case, see Verifying host CPU compatibility for virtual machine migration.
The disk images of VMs that will be migrated are located on a separate networked location accessible to both the source host and the destination host. This is optional for offline migration, but required for migrating a running VM.
For instructions to set up such shared VM storage, see Sharing virtual machine disk images with other hosts.
When migrating a running VM, your network bandwidth must be higher than the rate in which the VM generates dirty memory pages.
To obtain the dirty page rate of your VM before you start the live migration, do the following:
Monitor the rate of dirty page generation of the VM for a short period of time.
# virsh domdirtyrate-calc vm-name 30
After the monitoring finishes, obtain its results:
# virsh domstats vm-name --dirtyrate Domain: 'vm-name' dirtyrate.calc_status=2 dirtyrate.calc_start_time=200942 dirtyrate.calc_period=30 dirtyrate.megabytes_per_second=2
In this example, the VM is generating 2 MB of dirty memory pages per second. Attempting to live-migrate such a VM on a network with a bandwidth of 2 MB/s or less will cause the live migration not to progress if you do not pause the VM or lower its workload.
To ensure that the live migration finishes successfully, Red Hat recommends that your network bandwidth is significantly greater than the VM’s dirty page generation rate.
- When migrating an existing VM in a public bridge tap network, the source and destination hosts must be located on the same network. Otherwise, the VM network will not operate after migration.
When performing a VM migration, the
virsh
client on the source host can use one of several protocols to connect to the libvirt daemon on the destination host. Examples in the following procedure use an SSH connection, but you can choose a different one.If you want libvirt to use an SSH connection, ensure that the
virtqemud
socket is enabled and running on the destination host.# systemctl enable --now virtqemud.socket
If you want libvirt to use a TLS connection, ensure that the
virtproxyd-tls
socket is enabled and running on the destination host.# systemctl enable --now virtproxyd-tls.socket
If you want libvirt to use a TCP connection, ensure that the
virtproxyd-tcp
socket is enabled and running on the destination host.# systemctl enable --now virtproxyd-tcp.socket
Procédure
Use the
virsh migrate
command with options appropriate for your migration requirements.The following migrates the
wanderer1
VM from your local host to the system connection of thedest-example
host using an SSH tunnel. The VM will remain running during the migration.# virsh migrate --persistent --live wanderer1 qemu+ssh://dest-example/system
The following enables you to make manual adjustments to the configuration of the
wanderer2
VM running on your local host, and then migrates the VM to thedest-example
host. The migrated VM will automatically use the updated configuration.# virsh dumpxml --migratable wanderer2 >wanderer2.xml # vi wanderer2.xml # virsh migrate --live --persistent --xml wanderer2.xml wanderer2 qemu+ssh://dest-example/system
This procedure can be useful for example when the destination host needs to use a different path to access the shared VM storage or when configuring a feature specific to the destination host.
The following suspends the
wanderer3
VM from thesource-example
host, migrates it to thedest-example
host, and instructs it to use the adjusted XML configuration, provided by thewanderer3-alt.xml
file. When the migration is completed,libvirt
resumes the VM on the destination host.# virsh migrate wanderer3 qemu+ssh://source-example/system qemu+ssh://dest-example/system --xml wanderer3-alt.xml
After the migration, the VM is in the shut off state on the source host, and the migrated copy is deleted after it is shut down.
The following deletes the shut-down
wanderer4
VM from thesource-example
host, and moves its configuration to thedest-example
host.# virsh migrate --offline --persistent --undefinesource wanderer4 qemu+ssh://source-example/system qemu+ssh://dest-example/system
Note that this type of migration does not require moving the VM’s disk image to shared storage. However, for the VM to be usable on the destination host, you also need to migrate the VM’s disk image. For example:
# scp root@source-example:/var/lib/libvirt/images/wanderer4.qcow2 root@dest-example:/var/lib/libvirt/images/wanderer4.qcow2
Wait for the migration to complete. The process may take some time depending on network bandwidth, system load, and the size of the VM. If the
--verbose
option is not used forvirsh migrate
, the CLI does not display any progress indicators except errors.When the migration is in progress, you can use the
virsh domjobinfo
utility to display the migration statistics.
Vérification
On the destination host, list the available VMs to verify if the VM has been migrated:
# virsh list Id Name State ---------------------------------- 10 wanderer1 running
If the migration is still running, this command will list the VM state as
paused
.
Résolution de problèmes
-
In some cases, the target host will not be compatible with certain values of the migrated VM’s XML configuration, such as the network name or CPU type. As a result, the VM will fail to boot on the target host. To fix these problems, you can update the problematic values by using the
virsh edit
command. After updating the values, you must restart the VM for the changes to be applied. If a live migration is taking a long time to complete, this may be because the VM is under heavy load and too many memory pages are changing for live migration to be possible. To fix this problem, change the migration to a non-live one by suspending the VM.
# virsh suspend wanderer1
Ressources supplémentaires
-
The
virsh migrate --help
command -
The
virsh
man page