docs/interop/live-block-operations.rst

13 QEMU Block Layer currently (as of QEMU 2.9) supports four major kinds of
25     The file ``qapi/block-core.json`` in the QEMU source tree has the
26     canonical QEMU API (QAPI) schema documentation for the QMP
40                    (Live QEMU)
50 [B].  And live QEMU is currently writing to image [B], consequently, it
77 QEMU block layer supports.
85                 (a) QEMU rewrites the backing chain to remove
89                 (b) the streamed file *itself* won't be removed by QEMU,
99     chain).  Since QEMU 2.0, this includes "active ``block-commit``"
105                 (a) QEMU rewrites the backing chain to remove reference
109                 (b) the committed file *itself* won't be removed by QEMU
125 .. _`Interacting with a QEMU instance`:
127 Interacting with a QEMU instance
131 following invocation of QEMU, with a QMP server running over UNIX
143 QEMU 2.9 onwards.  In the above invocation, notice the ``node-name``
151 of QEMU 2.9, accept ``node-name`` parameter) when performing various
154 To interact with the QEMU instance launched above, we will use the
156 QEMU source directory), which takes key-value pairs for QMP commands.
161     (QEMU)
180 overlay images; image [D] is the active layer -- i.e. live QEMU is
181 writing to it.  (The rule of thumb is: live QEMU will always be pointing
189 …(QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B for…
200 Here, "node-A" is the name QEMU internally uses to refer to the base
207 …(QEMU) blockdev-snapshot-sync node-name=node-B snapshot-file=c.qcow2 snapshot-node-name=node-C for…
208 …(QEMU) blockdev-snapshot-sync node-name=node-C snapshot-file=d.qcow2 snapshot-node-name=node-D for…
254     into it (where live QEMU writes go to)::
270 (3) Intermediate streaming (available since QEMU 2.8): Starting afresh
277     live QEMU is writing to [D])::
290     (QEMU) block-stream device=node-D job-id=job0
302     (QEMU) block-stream device=node-D base-node=node-A job-id=job0
308     (QEMU) block-stream device=node-C base-node=node-A job-id=job0
313     (QEMU) query-block-jobs
320 Once the ``block-stream`` operation has completed, QEMU will emit an
331 images into backing file(s).  Since QEMU 2.0, this includes "live active
333 image in a disk image chain where live QEMU will be writing to, into the
338 QEMU is writing to the right-most image in the chain, [D]::
383     (QEMU) block-commit device=node-D base=a.qcow2 top=b.qcow2 job-id=job0
438 QEMU is performing all its current writes).
442     (QEMU) block-commit device=node-D base=a.qcow2 top=d.qcow2 job-id=job0
461     (QEMU) query-block-jobs
484     (QEMU) block-job-complete device=job0
545     QEMU) to point to the target image, [E], causing all the new writes
573     Refer to the :doc:`bitmaps` document in the QEMU source
585     (QEMU) drive-mirror device=node-D target=e.qcow2 sync=full job-id=job0
600 'mirror' job is "ready" to be completed (and QEMU will also emit an
603     (QEMU) query-block-jobs
632         (QEMU) block-job-cancel device=job0
640 (b) Or, complete the operation and pivot the live QEMU to the target
643         (QEMU) block-job-complete device=job0
661 and QEMU's built-in Network Block Device (NBD) server.  Here's a quick
691 of image [D] (from the source QEMU) will be mirrored to::
696 And start the destination QEMU (we already have the source QEMU running
697 -- discussed in the section: `Interacting with a QEMU instance`_)
699 simplicity's sake, the destination QEMU is started on the same host, but
711 Given the disk image chain on source QEMU::
719 (1) [On *destination* QEMU] As part of the first step, start the
723         (QEMU) nbd-server-start addr={"type":"inet","data":{"host":"::","port":"49153"}}
737 (2) [On *destination* QEMU] And export the destination disk image using
738     QEMU's built-in NBD server::
740         (QEMU) nbd-server-add device=node-TargetDisk writable=true
748 (3) [On *source* QEMU] Then, invoke ``drive-mirror`` (NB: since we're
754 …(QEMU) drive-mirror device=node-D target=nbd:localhost:49153:exportname=node-TargetDisk sync=top m…
766 (4) [On *source* QEMU] Once ``drive-mirror`` copies the entire data, and the
768     gracefully end the synchronization, from source QEMU::
770         (QEMU) block-job-cancel device=job0
778 (5) [On *destination* QEMU] Then, stop the NBD server::
780         (QEMU) nbd-server-stop
786 (6) [On *destination* QEMU] Finally, resume the guest vCPUs by issuing the
789         (QEMU) cont
808 created (using ``qemu-img``) and attach it to live QEMU via
820     ``blockdev-add`` to QEMU
852 …(QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B for…
853 …(QEMU) blockdev-snapshot-sync node-name=node-B snapshot-file=c.qcow2 snapshot-node-name=node-C for…
854 …(QEMU) blockdev-snapshot-sync node-name=node-C snapshot-file=d.qcow2 snapshot-node-name=node-D for…
860 Add the above created target image to QEMU, via ``blockdev-add``::
862     (QEMU) blockdev-add driver=qcow2 node-name=node-E file={"driver":"file","filename":"e.qcow2"}
877     (QEMU) blockdev-mirror device=node-B target=node-E sync=full job-id=job0
890     (QEMU) query-block-jobs
914     (QEMU) block-job-complete device=job0
927     (QEMU) quit
947 Note that ``drive-backup`` command is deprecated since QEMU 6.2 and
958     (QEMU) drive-backup device=node-D sync=full target=e.qcow2 job-id=job0
1002     ``blockdev-add`` to QEMU
1022 overlay (live QEMU is writing to it)::
1032 …(QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B for…
1048 Then add it to QEMU via ``blockdev-add``::
1050     (QEMU) blockdev-add driver=qcow2 node-name=node-E file={"driver":"file","filename":"e.qcow2"}
1067     (QEMU) blockdev-backup device=node-B target=node-E sync=full job-id=job0
1084     (QEMU) query-block-jobs
1092     (QEMU) quit
1115 QEMU was launched with ``-S`` option, which will not start the CPUs at