| blob | 1073b930dce54a3c93f4b92a97e1296ec0c9df33 |
1 ..
2 Copyright (C) 2017 Red Hat Inc.
4 This work is licensed under the terms of the GNU GPL, version 2 or
5 later. See the COPYING file in the top-level directory.
7 ============================
8 Live Block Device Operations
9 ============================
11 QEMU Block Layer currently (as of QEMU 2.9) supports four major kinds of
12 live block device jobs -- stream, commit, mirror, and backup. These can
13 be used to manipulate disk image chains to accomplish certain tasks,
14 namely: live copy data from backing files into overlays; shorten long
15 disk image chains by merging data from overlays into backing files; live
16 synchronize data from a disk image chain (including current active disk)
17 to another target image; and point-in-time (and incremental) backups of
18 a block device. Below is a description of the said block (QMP)
19 primitives, and some (non-exhaustive list of) examples to illustrate
20 their use.
22 .. note::
23 The file ``qapi/block-core.json`` in the QEMU source tree has the
24 canonical QEMU API (QAPI) schema documentation for the QMP
25 primitives discussed here.
27 .. todo (kashyapc):: Remove the ".. contents::" directive when Sphinx is
28 integrated.
30 .. contents::
32 Disk image backing chain notation
33 ---------------------------------
35 A simple disk image chain. (This can be created live using QMP
36 ``blockdev-snapshot-sync``, or offline via ``qemu-img``)::
38 (Live QEMU)
39 |
40 .
41 V
43 [A] <----- [B]
45 (backing file) (overlay)
47 The arrow can be read as: Image [A] is the backing file of disk image
48 [B]. And live QEMU is currently writing to image [B], consequently, it
49 is also referred to as the "active layer".
51 There are two kinds of terminology that are common when referring to
52 files in a disk image backing chain:
54 (1) Directional: 'base' and 'top'. Given the simple disk image chain
55 above, image [A] can be referred to as 'base', and image [B] as
56 'top'. (This terminology can be seen in in QAPI schema file,
57 block-core.json.)
59 (2) Relational: 'backing file' and 'overlay'. Again, taking the same
60 simple disk image chain from the above, disk image [A] is referred
61 to as the backing file, and image [B] as overlay.
63 Throughout this document, we will use the relational terminology.
65 .. important::
66 The overlay files can generally be any format that supports a
67 backing file, although QCOW2 is the preferred format and the one
68 used in this document.
71 Brief overview of live block QMP primitives
72 -------------------------------------------
74 The following are the four different kinds of live block operations that
75 QEMU block layer supports.
77 (1) ``block-stream``: Live copy of data from backing files into overlay
78 files.
80 .. note:: Once the 'stream' operation has finished, three things to
81 note:
83 (a) QEMU rewrites the backing chain to remove
84 reference to the now-streamed and redundant backing
85 file;
87 (b) the streamed file *itself* won't be removed by QEMU,
88 and must be explicitly discarded by the user;
90 (c) the streamed file remains valid -- i.e. further
91 overlays can be created based on it. Refer the
92 ``block-stream`` section further below for more
93 details.
95 (2) ``block-commit``: Live merge of data from overlay files into backing
96 files (with the optional goal of removing the overlay file from the
97 chain). Since QEMU 2.0, this includes "active ``block-commit``"
98 (i.e. merge the current active layer into the base image).
100 .. note:: Once the 'commit' operation has finished, there are three
101 things to note here as well:
103 (a) QEMU rewrites the backing chain to remove reference
104 to now-redundant overlay images that have been
105 committed into a backing file;
107 (b) the committed file *itself* won't be removed by QEMU
108 -- it ought to be manually removed;
110 (c) however, unlike in the case of ``block-stream``, the
111 intermediate images will be rendered invalid -- i.e.
112 no more further overlays can be created based on
113 them. Refer the ``block-commit`` section further
114 below for more details.
116 (3) ``drive-mirror`` (and ``blockdev-mirror``): Synchronize a running
117 disk to another image.
119 (4) ``drive-backup`` (and ``blockdev-backup``): Point-in-time (live) copy
120 of a block device to a destination.
123 .. _`Interacting with a QEMU instance`:
125 Interacting with a QEMU instance
126 --------------------------------
128 To show some example invocations of command-line, we will use the
129 following invocation of QEMU, with a QMP server running over UNIX
130 socket::
132 $ ./qemu-system-x86_64 -display none -no-user-config \
133 -M q35 -nodefaults -m 512 \
134 -blockdev node-name=node-A,driver=qcow2,file.driver=file,file.node-name=file,file.filename=./a.qcow2 \
135 -device virtio-blk,drive=node-A,id=virtio0 \
136 -monitor stdio -qmp unix:/tmp/qmp-sock,server=on,wait=off
138 The ``-blockdev`` command-line option, used above, is available from
139 QEMU 2.9 onwards. In the above invocation, notice the ``node-name``
140 parameter that is used to refer to the disk image a.qcow2 ('node-A') --
141 this is a cleaner way to refer to a disk image (as opposed to referring
142 to it by spelling out file paths). So, we will continue to designate a
143 ``node-name`` to each further disk image created (either via
144 ``blockdev-snapshot-sync``, or ``blockdev-add``) as part of the disk
145 image chain, and continue to refer to the disks using their
146 ``node-name`` (where possible, because ``block-commit`` does not yet, as
147 of QEMU 2.9, accept ``node-name`` parameter) when performing various
148 block operations.
150 To interact with the QEMU instance launched above, we will use the
151 ``qmp-shell`` utility (located at: ``qemu/scripts/qmp``, as part of the
152 QEMU source directory), which takes key-value pairs for QMP commands.
153 Invoke it as below (which will also print out the complete raw JSON
154 syntax for reference -- examples in the following sections)::
156 $ ./qmp-shell -v -p /tmp/qmp-sock
157 (QEMU)
159 .. note::
160 In the event we have to repeat a certain QMP command, we will: for
161 the first occurrence of it, show the ``qmp-shell`` invocation, *and*
162 the corresponding raw JSON QMP syntax; but for subsequent
163 invocations, present just the ``qmp-shell`` syntax, and omit the
164 equivalent JSON output.
167 Example disk image chain
168 ------------------------
170 We will use the below disk image chain (and occasionally spelling it
171 out where appropriate) when discussing various primitives::
173 [A] <-- [B] <-- [C] <-- [D]
175 Where [A] is the original base image; [B] and [C] are intermediate
176 overlay images; image [D] is the active layer -- i.e. live QEMU is
177 writing to it. (The rule of thumb is: live QEMU will always be pointing
178 to the rightmost image in a disk image chain.)
180 The above image chain can be created by invoking
181 ``blockdev-snapshot-sync`` commands as following (which shows the
182 creation of overlay image [B]) using the ``qmp-shell`` (our invocation
183 also prints the raw JSON invocation of it)::
185 (QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B format=qcow2
186 {
187 "execute": "blockdev-snapshot-sync",
188 "arguments": {
189 "node-name": "node-A",
190 "snapshot-file": "b.qcow2",
191 "format": "qcow2",
192 "snapshot-node-name": "node-B"
193 }
194 }
196 Here, "node-A" is the name QEMU internally uses to refer to the base
197 image [A] -- it is the backing file, based on which the overlay image,
198 [B], is created.
200 To create the rest of the overlay images, [C], and [D] (omitting the raw
201 JSON output for brevity)::
203 (QEMU) blockdev-snapshot-sync node-name=node-B snapshot-file=c.qcow2 snapshot-node-name=node-C format=qcow2
204 (QEMU) blockdev-snapshot-sync node-name=node-C snapshot-file=d.qcow2 snapshot-node-name=node-D format=qcow2
207 A note on points-in-time vs file names
208 --------------------------------------
210 In our disk image chain::
212 [A] <-- [B] <-- [C] <-- [D]
214 We have *three* points in time and an active layer:
216 - Point 1: Guest state when [B] was created is contained in file [A]
217 - Point 2: Guest state when [C] was created is contained in [A] + [B]
218 - Point 3: Guest state when [D] was created is contained in
219 [A] + [B] + [C]
220 - Active layer: Current guest state is contained in [A] + [B] + [C] +
221 [D]
223 Therefore, be aware with naming choices:
225 - Naming a file after the time it is created is misleading -- the
226 guest data for that point in time is *not* contained in that file
227 (as explained earlier)
228 - Rather, think of files as a *delta* from the backing file
231 Live block streaming --- ``block-stream``
232 -----------------------------------------
234 The ``block-stream`` command allows you to do live copy data from backing
235 files into overlay images.
237 Given our original example disk image chain from earlier::
239 [A] <-- [B] <-- [C] <-- [D]
241 The disk image chain can be shortened in one of the following different
242 ways (not an exhaustive list).
244 .. _`Case-1`:
246 (1) Merge everything into the active layer: I.e. copy all contents from
247 the base image, [A], and overlay images, [B] and [C], into [D],
248 *while* the guest is running. The resulting chain will be a
249 standalone image, [D] -- with contents from [A], [B] and [C] merged
250 into it (where live QEMU writes go to)::
252 [D]
254 .. _`Case-2`:
256 (2) Taking the same example disk image chain mentioned earlier, merge
257 only images [B] and [C] into [D], the active layer. The result will
258 be contents of images [B] and [C] will be copied into [D], and the
259 backing file pointer of image [D] will be adjusted to point to image
260 [A]. The resulting chain will be::
262 [A] <-- [D]
264 .. _`Case-3`:
266 (3) Intermediate streaming (available since QEMU 2.8): Starting afresh
267 with the original example disk image chain, with a total of four
268 images, it is possible to copy contents from image [B] into image
269 [C]. Once the copy is finished, image [B] can now be (optionally)
270 discarded; and the backing file pointer of image [C] will be
271 adjusted to point to [A]. I.e. after performing "intermediate
272 streaming" of [B] into [C], the resulting image chain will be (where
273 live QEMU is writing to [D])::
275 [A] <-- [C] <-- [D]
278 QMP invocation for ``block-stream``
279 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
281 For `Case-1`_, to merge contents of all the backing files into the
282 active layer, where 'node-D' is the current active image (by default
283 ``block-stream`` will flatten the entire chain); ``qmp-shell`` (and its
284 corresponding JSON output)::
286 (QEMU) block-stream device=node-D job-id=job0
287 {
288 "execute": "block-stream",
289 "arguments": {
290 "device": "node-D",
291 "job-id": "job0"
292 }
293 }
295 For `Case-2`_, merge contents of the images [B] and [C] into [D], where
296 image [D] ends up referring to image [A] as its backing file::
298 (QEMU) block-stream device=node-D base-node=node-A job-id=job0
300 And for `Case-3`_, of "intermediate" streaming", merge contents of
301 images [B] into [C], where [C] ends up referring to [A] as its backing
302 image::
304 (QEMU) block-stream device=node-C base-node=node-A job-id=job0
306 Progress of a ``block-stream`` operation can be monitored via the QMP
307 command::
309 (QEMU) query-block-jobs
310 {
311 "execute": "query-block-jobs",
312 "arguments": {}
313 }
316 Once the ``block-stream`` operation has completed, QEMU will emit an
317 event, ``BLOCK_JOB_COMPLETED``. The intermediate overlays remain valid,
318 and can now be (optionally) discarded, or retained to create further
319 overlays based on them. Finally, the ``block-stream`` jobs can be
320 restarted at anytime.
323 Live block commit --- ``block-commit``
324 --------------------------------------
326 The ``block-commit`` command lets you merge live data from overlay
327 images into backing file(s). Since QEMU 2.0, this includes "live active
328 commit" (i.e. it is possible to merge the "active layer", the right-most
329 image in a disk image chain where live QEMU will be writing to, into the
330 base image). This is analogous to ``block-stream``, but in the opposite
331 direction.
333 Again, starting afresh with our example disk image chain, where live
334 QEMU is writing to the right-most image in the chain, [D]::
336 [A] <-- [B] <-- [C] <-- [D]
338 The disk image chain can be shortened in one of the following ways:
340 .. _`block-commit_Case-1`:
342 (1) Commit content from only image [B] into image [A]. The resulting
343 chain is the following, where image [C] is adjusted to point at [A]
344 as its new backing file::
346 [A] <-- [C] <-- [D]
348 (2) Commit content from images [B] and [C] into image [A]. The
349 resulting chain, where image [D] is adjusted to point to image [A]
350 as its new backing file::
352 [A] <-- [D]
354 .. _`block-commit_Case-3`:
356 (3) Commit content from images [B], [C], and the active layer [D] into
357 image [A]. The resulting chain (in this case, a consolidated single
358 image)::
360 [A]
362 (4) Commit content from image only image [C] into image [B]. The
363 resulting chain::
365 [A] <-- [B] <-- [D]
367 (5) Commit content from image [C] and the active layer [D] into image
368 [B]. The resulting chain::
370 [A] <-- [B]
373 QMP invocation for ``block-commit``
374 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
376 For :ref:`Case-1 <block-commit_Case-1>`, to merge contents only from
377 image [B] into image [A], the invocation is as follows::
379 (QEMU) block-commit device=node-D base=a.qcow2 top=b.qcow2 job-id=job0
380 {
381 "execute": "block-commit",
382 "arguments": {
383 "device": "node-D",
384 "job-id": "job0",
385 "top": "b.qcow2",
386 "base": "a.qcow2"
387 }
388 }
390 Once the above ``block-commit`` operation has completed, a
391 ``BLOCK_JOB_COMPLETED`` event will be issued, and no further action is
392 required. As the end result, the backing file of image [C] is adjusted
393 to point to image [A], and the original 4-image chain will end up being
394 transformed to::
396 [A] <-- [C] <-- [D]
398 .. note::
399 The intermediate image [B] is invalid (as in: no more further
400 overlays based on it can be created).
402 Reasoning: An intermediate image after a 'stream' operation still
403 represents that old point-in-time, and may be valid in that context.
404 However, an intermediate image after a 'commit' operation no longer
405 represents any point-in-time, and is invalid in any context.
408 However, :ref:`Case-3 <block-commit_Case-3>` (also called: "active
409 ``block-commit``") is a *two-phase* operation: In the first phase, the
410 content from the active overlay, along with the intermediate overlays,
411 is copied into the backing file (also called the base image). In the
412 second phase, adjust the said backing file as the current active image
413 -- possible via issuing the command ``block-job-complete``. Optionally,
414 the ``block-commit`` operation can be cancelled by issuing the command
415 ``block-job-cancel``, but be careful when doing this.
417 Once the ``block-commit`` operation has completed, the event
418 ``BLOCK_JOB_READY`` will be emitted, signalling that the synchronization
419 has finished. Now the job can be gracefully completed by issuing the
420 command ``block-job-complete`` -- until such a command is issued, the
421 'commit' operation remains active.
423 The following is the flow for :ref:`Case-3 <block-commit_Case-3>` to
424 convert a disk image chain such as this::
426 [A] <-- [B] <-- [C] <-- [D]
428 Into::
430 [A]
432 Where content from all the subsequent overlays, [B], and [C], including
433 the active layer, [D], is committed back to [A] -- which is where live
434 QEMU is performing all its current writes).
436 Start the "active ``block-commit``" operation::
438 (QEMU) block-commit device=node-D base=a.qcow2 top=d.qcow2 job-id=job0
439 {
440 "execute": "block-commit",
441 "arguments": {
442 "device": "node-D",
443 "job-id": "job0",
444 "top": "d.qcow2",
445 "base": "a.qcow2"
446 }
447 }
450 Once the synchronization has completed, the event ``BLOCK_JOB_READY`` will
451 be emitted.
453 Then, optionally query for the status of the active block operations.
454 We can see the 'commit' job is now ready to be completed, as indicated
455 by the line *"ready": true*::
457 (QEMU) query-block-jobs
458 {
459 "execute": "query-block-jobs",
460 "arguments": {}
461 }
462 {
463 "return": [
464 {
465 "busy": false,
466 "type": "commit",
467 "len": 1376256,
468 "paused": false,
469 "ready": true,
470 "io-status": "ok",
471 "offset": 1376256,
472 "device": "job0",
473 "speed": 0
474 }
475 ]
476 }
478 Gracefully complete the 'commit' block device job::
480 (QEMU) block-job-complete device=job0
481 {
482 "execute": "block-job-complete",
483 "arguments": {
484 "device": "job0"
485 }
486 }
487 {
488 "return": {}
489 }
491 Finally, once the above job is completed, an event
492 ``BLOCK_JOB_COMPLETED`` will be emitted.
494 .. note::
495 The invocation for rest of the cases (2, 4, and 5), discussed in the
496 previous section, is omitted for brevity.
499 Live disk synchronization --- ``drive-mirror`` and ``blockdev-mirror``
500 ----------------------------------------------------------------------
502 Synchronize a running disk image chain (all or part of it) to a target
503 image.
505 Again, given our familiar disk image chain::
507 [A] <-- [B] <-- [C] <-- [D]
509 The ``drive-mirror`` (and its newer equivalent ``blockdev-mirror``)
510 allows you to copy data from the entire chain into a single target image
511 (which can be located on a different host), [E].
513 .. note::
515 When you cancel an in-progress 'mirror' job *before* the source and
516 target are synchronized, ``block-job-cancel`` will emit the event
517 ``BLOCK_JOB_CANCELLED``. However, note that if you cancel a
518 'mirror' job *after* it has indicated (via the event
519 ``BLOCK_JOB_READY``) that the source and target have reached
520 synchronization, then the event emitted by ``block-job-cancel``
521 changes to ``BLOCK_JOB_COMPLETED``.
523 Besides the 'mirror' job, the "active ``block-commit``" is the only
524 other block device job that emits the event ``BLOCK_JOB_READY``.
525 The rest of the block device jobs ('stream', "non-active
526 ``block-commit``", and 'backup') end automatically.
528 So there are two possible actions to take, after a 'mirror' job has
529 emitted the event ``BLOCK_JOB_READY``, indicating that the source and
530 target have reached synchronization:
532 (1) Issuing the command ``block-job-cancel`` (after it emits the event
533 ``BLOCK_JOB_COMPLETED``) will create a point-in-time (which is at
534 the time of *triggering* the cancel command) copy of the entire disk
535 image chain (or only the top-most image, depending on the ``sync``
536 mode), contained in the target image [E]. One use case for this is
537 live VM migration with non-shared storage.
539 (2) Issuing the command ``block-job-complete`` (after it emits the event
540 ``BLOCK_JOB_COMPLETED``) will adjust the guest device (i.e. live
541 QEMU) to point to the target image, [E], causing all the new writes
542 from this point on to happen there.
544 About synchronization modes: The synchronization mode determines
545 *which* part of the disk image chain will be copied to the target.
546 Currently, there are four different kinds:
548 (1) ``full`` -- Synchronize the content of entire disk image chain to
549 the target
551 (2) ``top`` -- Synchronize only the contents of the top-most disk image
552 in the chain to the target
554 (3) ``none`` -- Synchronize only the new writes from this point on.
556 .. note:: In the case of ``drive-backup`` (or ``blockdev-backup``),
557 the behavior of ``none`` synchronization mode is different.
558 Normally, a ``backup`` job consists of two parts: Anything
559 that is overwritten by the guest is first copied out to
560 the backup, and in the background the whole image is
561 copied from start to end. With ``sync=none``, it's only
562 the first part.
564 (4) ``incremental`` -- Synchronize content that is described by the
565 dirty bitmap
567 .. note::
568 Refer to the :doc:`bitmaps` document in the QEMU source
569 tree to learn about the detailed workings of the ``incremental``
570 synchronization mode.
573 QMP invocation for ``drive-mirror``
574 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
576 To copy the contents of the entire disk image chain, from [A] all the
577 way to [D], to a new target (``drive-mirror`` will create the destination
578 file, if it doesn't already exist), call it [E]::
580 (QEMU) drive-mirror device=node-D target=e.qcow2 sync=full job-id=job0
581 {
582 "execute": "drive-mirror",
583 "arguments": {
584 "device": "node-D",
585 "job-id": "job0",
586 "target": "e.qcow2",
587 "sync": "full"
588 }
589 }
591 The ``"sync": "full"``, from the above, means: copy the *entire* chain
592 to the destination.
594 Following the above, querying for active block jobs will show that a
595 'mirror' job is "ready" to be completed (and QEMU will also emit an
596 event, ``BLOCK_JOB_READY``)::
598 (QEMU) query-block-jobs
599 {
600 "execute": "query-block-jobs",
601 "arguments": {}
602 }
603 {
604 "return": [
605 {
606 "busy": false,
607 "type": "mirror",
608 "len": 21757952,
609 "paused": false,
610 "ready": true,
611 "io-status": "ok",
612 "offset": 21757952,
613 "device": "job0",
614 "speed": 0
615 }
616 ]
617 }
619 And, as noted in the previous section, there are two possible actions
620 at this point:
622 (a) Create a point-in-time snapshot by ending the synchronization. The
623 point-in-time is at the time of *ending* the sync. (The result of
624 the following being: the target image, [E], will be populated with
625 content from the entire chain, [A] to [D])::
627 (QEMU) block-job-cancel device=job0
628 {
629 "execute": "block-job-cancel",
630 "arguments": {
631 "device": "job0"
632 }
633 }
635 (b) Or, complete the operation and pivot the live QEMU to the target
636 copy::
638 (QEMU) block-job-complete device=job0
640 In either of the above cases, if you once again run the
641 `query-block-jobs` command, there should not be any active block
642 operation.
644 Comparing 'commit' and 'mirror': In both then cases, the overlay images
645 can be discarded. However, with 'commit', the *existing* base image
646 will be modified (by updating it with contents from overlays); while in
647 the case of 'mirror', a *new* target image is populated with the data
648 from the disk image chain.
651 QMP invocation for live storage migration with ``drive-mirror`` + NBD
652 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
654 Live storage migration (without shared storage setup) is one of the most
655 common use-cases that takes advantage of the ``drive-mirror`` primitive
656 and QEMU's built-in Network Block Device (NBD) server. Here's a quick
657 walk-through of this setup.
659 Given the disk image chain::
661 [A] <-- [B] <-- [C] <-- [D]
663 Instead of copying content from the entire chain, synchronize *only* the
664 contents of the *top*-most disk image (i.e. the active layer), [D], to a
665 target, say, [TargetDisk].
667 .. important::
668 The destination host must already have the contents of the backing
669 chain, involving images [A], [B], and [C], visible via other means
670 -- whether by ``cp``, ``rsync``, or by some storage array-specific
671 command.)
673 Sometimes, this is also referred to as "shallow copy" -- because only
674 the "active layer", and not the rest of the image chain, is copied to
675 the destination.
677 .. note::
678 In this example, for the sake of simplicity, we'll be using the same
679 ``localhost`` as both source and destination.
681 As noted earlier, on the destination host the contents of the backing
682 chain -- from images [A] to [C] -- are already expected to exist in some
683 form (e.g. in a file called, ``Contents-of-A-B-C.qcow2``). Now, on the
684 destination host, let's create a target overlay image (with the image
685 ``Contents-of-A-B-C.qcow2`` as its backing file), to which the contents
686 of image [D] (from the source QEMU) will be mirrored to::
688 $ qemu-img create -f qcow2 -b ./Contents-of-A-B-C.qcow2 \
689 -F qcow2 ./target-disk.qcow2
691 And start the destination QEMU (we already have the source QEMU running
692 -- discussed in the section: `Interacting with a QEMU instance`_)
693 instance, with the following invocation. (As noted earlier, for
694 simplicity's sake, the destination QEMU is started on the same host, but
695 it could be located elsewhere)::
697 $ ./qemu-system-x86_64 -display none -no-user-config \
698 -M q35 -nodefaults -m 512 \
699 -blockdev node-name=node-TargetDisk,driver=qcow2,file.driver=file,file.node-name=file,file.filename=./target-disk.qcow2 \
700 -device virtio-blk,drive=node-TargetDisk,id=virtio0 \
701 -S -monitor stdio -qmp unix:./qmp-sock2,server=on,wait=off \
702 -incoming tcp:localhost:6666
704 Given the disk image chain on source QEMU::
706 [A] <-- [B] <-- [C] <-- [D]
708 On the destination host, it is expected that the contents of the chain
709 ``[A] <-- [B] <-- [C]`` are *already* present, and therefore copy *only*
710 the content of image [D].
712 (1) [On *destination* QEMU] As part of the first step, start the
713 built-in NBD server on a given host (local host, represented by
714 ``::``)and port::
716 (QEMU) nbd-server-start addr={"type":"inet","data":{"host":"::","port":"49153"}}
717 {
718 "execute": "nbd-server-start",
719 "arguments": {
720 "addr": {
721 "data": {
722 "host": "::",
723 "port": "49153"
724 },
725 "type": "inet"
726 }
727 }
728 }
730 (2) [On *destination* QEMU] And export the destination disk image using
731 QEMU's built-in NBD server::
733 (QEMU) nbd-server-add device=node-TargetDisk writable=true
734 {
735 "execute": "nbd-server-add",
736 "arguments": {
737 "device": "node-TargetDisk"
738 }
739 }
741 (3) [On *source* QEMU] Then, invoke ``drive-mirror`` (NB: since we're
742 running ``drive-mirror`` with ``mode=existing`` (meaning:
743 synchronize to a pre-created file, therefore 'existing', file on the
744 target host), with the synchronization mode as 'top' (``"sync:
745 "top"``)::
747 (QEMU) drive-mirror device=node-D target=nbd:localhost:49153:exportname=node-TargetDisk sync=top mode=existing job-id=job0
748 {
749 "execute": "drive-mirror",
750 "arguments": {
751 "device": "node-D",
752 "mode": "existing",
753 "job-id": "job0",
754 "target": "nbd:localhost:49153:exportname=node-TargetDisk",
755 "sync": "top"
756 }
757 }
759 (4) [On *source* QEMU] Once ``drive-mirror`` copies the entire data, and the
760 event ``BLOCK_JOB_READY`` is emitted, issue ``block-job-cancel`` to
761 gracefully end the synchronization, from source QEMU::
763 (QEMU) block-job-cancel device=job0
764 {
765 "execute": "block-job-cancel",
766 "arguments": {
767 "device": "job0"
768 }
769 }
771 (5) [On *destination* QEMU] Then, stop the NBD server::
773 (QEMU) nbd-server-stop
774 {
775 "execute": "nbd-server-stop",
776 "arguments": {}
777 }
779 (6) [On *destination* QEMU] Finally, resume the guest vCPUs by issuing the
780 QMP command `cont`::
782 (QEMU) cont
783 {
784 "execute": "cont",
785 "arguments": {}
786 }
788 .. note::
789 Higher-level libraries (e.g. libvirt) automate the entire above
790 process (although note that libvirt does not allow same-host
791 migrations to localhost for other reasons).
794 Notes on ``blockdev-mirror``
795 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
797 The ``blockdev-mirror`` command is equivalent in core functionality to
798 ``drive-mirror``, except that it operates at node-level in a BDS graph.
800 Also: for ``blockdev-mirror``, the 'target' image needs to be explicitly
801 created (using ``qemu-img``) and attach it to live QEMU via
802 ``blockdev-add``, which assigns a name to the to-be created target node.
804 E.g. the sequence of actions to create a point-in-time backup of an
805 entire disk image chain, to a target, using ``blockdev-mirror`` would be:
807 (0) Create the QCOW2 overlays, to arrive at a backing chain of desired
808 depth
810 (1) Create the target image (using ``qemu-img``), say, ``e.qcow2``
812 (2) Attach the above created file (``e.qcow2``), run-time, using
813 ``blockdev-add`` to QEMU
815 (3) Perform ``blockdev-mirror`` (use ``"sync": "full"`` to copy the
816 entire chain to the target). And notice the event
817 ``BLOCK_JOB_READY``
819 (4) Optionally, query for active block jobs, there should be a 'mirror'
820 job ready to be completed
822 (5) Gracefully complete the 'mirror' block device job, and notice the
823 the event ``BLOCK_JOB_COMPLETED``
825 (6) Shutdown the guest by issuing the QMP ``quit`` command so that
826 caches are flushed
828 (7) Then, finally, compare the contents of the disk image chain, and
829 the target copy with ``qemu-img compare``. You should notice:
830 "Images are identical"
833 QMP invocation for ``blockdev-mirror``
834 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
836 Given the disk image chain::
838 [A] <-- [B] <-- [C] <-- [D]
840 To copy the contents of the entire disk image chain, from [A] all the
841 way to [D], to a new target, call it [E]. The following is the flow.
843 Create the overlay images, [B], [C], and [D]::
845 (QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B format=qcow2
846 (QEMU) blockdev-snapshot-sync node-name=node-B snapshot-file=c.qcow2 snapshot-node-name=node-C format=qcow2
847 (QEMU) blockdev-snapshot-sync node-name=node-C snapshot-file=d.qcow2 snapshot-node-name=node-D format=qcow2
849 Create the target image, [E]::
851 $ qemu-img create -f qcow2 e.qcow2 39M
853 Add the above created target image to QEMU, via ``blockdev-add``::
855 (QEMU) blockdev-add driver=qcow2 node-name=node-E file={"driver":"file","filename":"e.qcow2"}
856 {
857 "execute": "blockdev-add",
858 "arguments": {
859 "node-name": "node-E",
860 "driver": "qcow2",
861 "file": {
862 "driver": "file",
863 "filename": "e.qcow2"
864 }
865 }
866 }
868 Perform ``blockdev-mirror``, and notice the event ``BLOCK_JOB_READY``::
870 (QEMU) blockdev-mirror device=node-B target=node-E sync=full job-id=job0
871 {
872 "execute": "blockdev-mirror",
873 "arguments": {
874 "device": "node-D",
875 "job-id": "job0",
876 "target": "node-E",
877 "sync": "full"
878 }
879 }
881 Query for active block jobs, there should be a 'mirror' job ready::
883 (QEMU) query-block-jobs
884 {
885 "execute": "query-block-jobs",
886 "arguments": {}
887 }
888 {
889 "return": [
890 {
891 "busy": false,
892 "type": "mirror",
893 "len": 21561344,
894 "paused": false,
895 "ready": true,
896 "io-status": "ok",
897 "offset": 21561344,
898 "device": "job0",
899 "speed": 0
900 }
901 ]
902 }
904 Gracefully complete the block device job operation, and notice the
905 event ``BLOCK_JOB_COMPLETED``::
907 (QEMU) block-job-complete device=job0
908 {
909 "execute": "block-job-complete",
910 "arguments": {
911 "device": "job0"
912 }
913 }
914 {
915 "return": {}
916 }
918 Shutdown the guest, by issuing the ``quit`` QMP command::
920 (QEMU) quit
921 {
922 "execute": "quit",
923 "arguments": {}
924 }
927 Live disk backup --- ``drive-backup`` and ``blockdev-backup``
928 -------------------------------------------------------------
930 The ``drive-backup`` (and its newer equivalent ``blockdev-backup``) allows
931 you to create a point-in-time snapshot.
933 In this case, the point-in-time is when you *start* the ``drive-backup``
934 (or its newer equivalent ``blockdev-backup``) command.
937 QMP invocation for ``drive-backup``
938 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
940 Yet again, starting afresh with our example disk image chain::
942 [A] <-- [B] <-- [C] <-- [D]
944 To create a target image [E], with content populated from image [A] to
945 [D], from the above chain, the following is the syntax. (If the target
946 image does not exist, ``drive-backup`` will create it)::
948 (QEMU) drive-backup device=node-D sync=full target=e.qcow2 job-id=job0
949 {
950 "execute": "drive-backup",
951 "arguments": {
952 "device": "node-D",
953 "job-id": "job0",
954 "sync": "full",
955 "target": "e.qcow2"
956 }
957 }
959 Once the above ``drive-backup`` has completed, a ``BLOCK_JOB_COMPLETED`` event
960 will be issued, indicating the live block device job operation has
961 completed, and no further action is required.
964 Notes on ``blockdev-backup``
965 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
967 The ``blockdev-backup`` command is equivalent in functionality to
968 ``drive-backup``, except that it operates at node-level in a Block Driver
969 State (BDS) graph.
971 E.g. the sequence of actions to create a point-in-time backup
972 of an entire disk image chain, to a target, using ``blockdev-backup``
973 would be:
975 (0) Create the QCOW2 overlays, to arrive at a backing chain of desired
976 depth
978 (1) Create the target image (using ``qemu-img``), say, ``e.qcow2``
980 (2) Attach the above created file (``e.qcow2``), run-time, using
981 ``blockdev-add`` to QEMU
983 (3) Perform ``blockdev-backup`` (use ``"sync": "full"`` to copy the
984 entire chain to the target). And notice the event
985 ``BLOCK_JOB_COMPLETED``
987 (4) Shutdown the guest, by issuing the QMP ``quit`` command, so that
988 caches are flushed
990 (5) Then, finally, compare the contents of the disk image chain, and
991 the target copy with ``qemu-img compare``. You should notice:
992 "Images are identical"
994 The following section shows an example QMP invocation for
995 ``blockdev-backup``.
997 QMP invocation for ``blockdev-backup``
998 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1000 Given a disk image chain of depth 1 where image [B] is the active
1001 overlay (live QEMU is writing to it)::
1003 [A] <-- [B]
1005 The following is the procedure to copy the content from the entire chain
1006 to a target image (say, [E]), which has the full content from [A] and
1007 [B].
1009 Create the overlay [B]::
1011 (QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B format=qcow2
1012 {
1013 "execute": "blockdev-snapshot-sync",
1014 "arguments": {
1015 "node-name": "node-A",
1016 "snapshot-file": "b.qcow2",
1017 "format": "qcow2",
1018 "snapshot-node-name": "node-B"
1019 }
1020 }
1023 Create a target image that will contain the copy::
1025 $ qemu-img create -f qcow2 e.qcow2 39M
1027 Then add it to QEMU via ``blockdev-add``::
1029 (QEMU) blockdev-add driver=qcow2 node-name=node-E file={"driver":"file","filename":"e.qcow2"}
1030 {
1031 "execute": "blockdev-add",
1032 "arguments": {
1033 "node-name": "node-E",
1034 "driver": "qcow2",
1035 "file": {
1036 "driver": "file",
1037 "filename": "e.qcow2"
1038 }
1039 }
1040 }
1042 Then invoke ``blockdev-backup`` to copy the contents from the entire
1043 image chain, consisting of images [A] and [B] to the target image
1044 'e.qcow2'::
1046 (QEMU) blockdev-backup device=node-B target=node-E sync=full job-id=job0
1047 {
1048 "execute": "blockdev-backup",
1049 "arguments": {
1050 "device": "node-B",
1051 "job-id": "job0",
1052 "target": "node-E",
1053 "sync": "full"
1054 }
1055 }
1057 Once the above 'backup' operation has completed, the event,
1058 ``BLOCK_JOB_COMPLETED`` will be emitted, signalling successful
1059 completion.
1061 Next, query for any active block device jobs (there should be none)::
1063 (QEMU) query-block-jobs
1064 {
1065 "execute": "query-block-jobs",
1066 "arguments": {}
1067 }
1069 Shutdown the guest::
1071 (QEMU) quit
1072 {
1073 "execute": "quit",
1074 "arguments": {}
1075 }
1076 "return": {}
1077 }
1079 .. note::
1080 The above step is really important; if forgotten, an error, "Failed
1081 to get shared "write" lock on e.qcow2", will be thrown when you do
1082 ``qemu-img compare`` to verify the integrity of the disk image
1083 with the backup content.
1086 The end result will be the image 'e.qcow2' containing a
1087 point-in-time backup of the disk image chain -- i.e. contents from
1088 images [A] and [B] at the time the ``blockdev-backup`` command was
1089 initiated.
1091 One way to confirm the backup disk image contains the identical content
1092 with the disk image chain is to compare the backup and the contents of
1093 the chain, you should see "Images are identical". (NB: this is assuming
1094 QEMU was launched with ``-S`` option, which will not start the CPUs at
1095 guest boot up)::
1097 $ qemu-img compare b.qcow2 e.qcow2
1098 Warning: Image size mismatch!
1099 Images are identical.
1101 NOTE: The "Warning: Image size mismatch!" is expected, as we created the
1102 target image (e.qcow2) with 39M size.