devel/migration/CPR.rst

5 VM is migrated to a new QEMU instance on the same host.  It is
6 intended for use when the goal is to update host software components
7 that run the VM, such as QEMU or even the host kernel.  At this time,
8 the cpr-reboot and cpr-transfer modes are available.
10 Because QEMU is restarted on the same host, with access to the same
18 cpr-reboot mode
19 ---------------
23 resumes by running QEMU with the ``-incoming`` option.  Because the
31 After state and memory are saved, the user may update userland host
34 then the user may reboot to a new host kernel before restarting QEMU.
38 ``guest-suspend-ram`` command to the QEMU guest agent.  The agent
39 must be pre-installed in the guest, and the guest must support
48 memory, such as ``memory-backend-file,share=on``, and that the
49 ``x-ignore-shared`` capability be set.  This combination allows memory
54   * Set the migration mode parameter to ``cpr-reboot``.
55   * Set the ``x-ignore-shared`` capability if desired.
56   * Issue the ``migrate`` command.  It is recommended the URI be a
58     provided the command captures all the data from the outgoing side,
63   * Start QEMU with the ``-incoming defer`` option.
64   * Set the migration mode parameter to ``cpr-reboot``.
65   * Set the ``x-ignore-shared`` capability if desired.
66   * Issue the ``migrate-incoming`` command.
67   * If the VM was running when the outgoing ``migrate`` command was
74   # qemu-kvm -monitor stdio
75   -object memory-backend-file,id=ram0,size=4G,mem-path=/dev/dax0.0,align=2M,share=on -m 4G
80   (qemu) migrate_set_parameter mode cpr-reboot
81   (qemu) migrate_set_capability x-ignore-shared on
82   (qemu) migrate -d file:vm.state
92   # qemu-kvm ... -incoming defer
95   (qemu) migrate_set_parameter mode cpr-reboot
96   (qemu) migrate_set_capability x-ignore-shared on
105   # qemu-kvm -monitor stdio
106   -object memory-backend-file,id=ram0,size=4G,mem-path=/dev/dax0.0,align=2M,share=on -m 4G
107   -device vfio-pci, ...
108   -chardev socket,id=qga0,path=qga.sock,server=on,wait=off
109   -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0
115   # echo '{"execute":"guest-suspend-ram"}' | ncat --send-only -U qga.sock
119   (qemu) migrate_set_parameter mode cpr-reboot
120   (qemu) migrate_set_capability x-ignore-shared on
121   (qemu) migrate -d file:vm.state
131   # qemu-kvm ... -incoming defer
134   (qemu) migrate_set_parameter mode cpr-reboot
135   (qemu) migrate_set_capability x-ignore-shared on
146 cpr-reboot mode may not be used with postcopy, background-snapshot,
149 cpr-transfer mode
150 -----------------
153 on the same host with minimal guest pause time, by preserving guest
158 The user starts new QEMU on the same host as old QEMU, with command-
159 line arguments to create the same machine, plus the ``-incoming``
161 In addition, the user adds a second -incoming option with channel
165 To initiate CPR, the user issues a migrate command to old QEMU,
173 migrate-incoming command.  It may only be specified on the command
181 The VM must be started with the ``-machine aux-ram-share=on``
183 a memory-backend object) to be allocated by mmap'ing a memfd.
187   * Set the migration mode parameter to ``cpr-transfer``.
188   * Issue the ``migrate`` command, containing a main channel and
192   * Start new QEMU with two ``-incoming`` options.
193   * If the VM was running when the outgoing ``migrate`` command was
199 cpr-transfer mode may not be used with postcopy, background-snapshot,
202 memory-backend-epc is not supported.
209 When using ``-incoming defer``, you must issue the migrate command to
213 command is issued.  However, new QEMU does not open and read the
214 main migration channel until you issue the migrate incoming command.
222 has issued the migrate command.  The outgoing side uses QMP because
230   # qemu-kvm -qmp stdio
231   -object memory-backend-file,id=ram0,size=4G,
232   mem-path=/dev/shm/ram0,share=on -m 4G
233   -machine memory-backend=ram0
234   -machine aux-ram-share=on
236                                         # qemu-kvm -monitor stdio
237                                         -incoming tcp:0:44444
238                                         -incoming '{"channel-type": "cpr",
244   {"execute": "query-status"}
248   {"execute":"migrate-set-parameters",
249    "arguments":{"mode":"cpr-transfer"}}
252     {"channel-type": "main",
254                "host": "0", "port": "44444" }},
255     {"channel-type": "cpr",
263   {"execute": "query-status"}
270 This example uses ``-incoming defer`` to hot plug a device before
272 migrate command to old QEMU before you can issue any monitor
280   # qemu-kvm -monitor stdio
281   -object memory-backend-file,id=ram0,size=4G,
282   mem-path=/dev/shm/ram0,share=on -m 4G
283   -machine memory-backend=ram0
284   -machine aux-ram-share=on
286                                         # qemu-kvm -monitor stdio
287                                         -incoming defer
288                                         -incoming '{"channel-type": "cpr",
295    "arguments": {"driver": "pcie-root-port"}}
297   {"execute":"migrate-set-parameters",
298    "arguments":{"mode":"cpr-transfer"}}
301     {"channel-type": "main",
303                "host": "0", "port": "44444" }},
304     {"channel-type": "cpr",
311                                         (qemu) device_add pcie-root-port
316   {"execute": "query-status"}
323 cpr-transfer mode is based on a capability to transfer open file