[pve-devel] [PATCH docs 3/3] add details about online migration for qemu

[Dominik Csapak]

this adds the distinction between online/offline migration for vms,
and explains what happens during an online migration and explains,
what the requirements are

Signed-off-by: Dominik Csapak <d.csapak at proxmox.com>
---
i added the requirements, so that we can refer to the documentation,
when you can do a live migration

also, when this reaches the wiki, we should add a "live migration" page
which links to this chapter

 qm.adoc | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/qm.adoc b/qm.adoc
index c1d79b9..7444661 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -512,10 +512,48 @@ If you have a cluster, you can migrate your VM to another host with
 
  qm migrate <vmid> <target>
 
+There are generally two mechanisms for this
+
+* Online Migration (aka Live Migration)
+* Offline Migration
+
+Online Migration
+~~~~~~~~~~~~~~~~
+
 When your VM is running and it has no local resources defined (such as disks
 on local storage, passed through devices, etc.) you can initiate a live
 migration with the -online flag.
 
+How it works
+^^^^^^^^^^^^
+
+This starts a Qemu Process on the target host with the 'incoming' flag, which
+means that the process starts and waits for the memory data and device states
+from the source Virtual Machine (since all other resources, e.g. disks,
+are shared, the memory content and device state are the only things left
+to transmit).
+
+Once this connection is established, the source begins to send the memory
+content asynchronously to the target. If the memory on the source changes,
+those sections are marked dirty and there will be another pass of sending data.
+This happens until the amount of data to send is so small that it can
+pause the VM on the source, send the remaining data to the target and start
+the VM on the target in under a second.
+
+Requirements
+^^^^^^^^^^^^
+
+For Live Migration to work, there are some things required:
+
+* The VM has no local resources (e.g. passed through devices, local disks, etc.)
+* The hosts are in the same {pve} cluster.
+* The hosts have a working (and reliable) network connection.
+* The target host must have the same or higher versions of the
+  {pve} packages. (It *might* work the other way, but this is never guaranteed)
+
+Offline Migration
+~~~~~~~~~~~~~~~~~
+
 If you have local resources, you can still offline migrate your VMs,
 as long as all disk are on storages, which are defined on both hosts.
 Then the migration will copy the disk over the network to the target host.
-- 
2.1.4