docs/live-block-ops.txt

   1 LIVE BLOCK OPERATIONS
   2 =====================
   3
   4 High level description of live block operations. Note these are not
   5 supported for use with the raw format at the moment.
   6
   7 Note also that this document is incomplete and it currently only
   8 covers the 'stream' operation. Other operations supported by QEMU such
   9 as 'commit', 'mirror' and 'backup' are not described here yet. Please
  10 refer to the qapi/block-core.json file for an overview of those.
  11
  12 Snapshot live merge
  13 ===================
  14
  15 Given a snapshot chain, described in this document in the following
  16 format:
  17
  18 [A] <- [B] <- [C] <- [D] <- [E]
  19
  20 Where the rightmost object ([E] in the example) described is the current
  21 image which the guest OS has write access to. To the left of it is its base
  22 image, and so on accordingly until the leftmost image, which has no
  23 base.
  24
  25 The snapshot live merge operation transforms such a chain into a
  26 smaller one with fewer elements, such as this transformation relative
  27 to the first example:
  28
  29 [A] <- [E]
  30
  31 Data is copied in the right direction with destination being the
  32 rightmost image, but any other intermediate image can be specified
  33 instead. In this example data is copied from [C] into [D], so [D] can
  34 be backed by [B]:
  35
  36 [A] <- [B] <- [D] <- [E]
  37
  38 The operation is implemented in QEMU through image streaming facilities.
  39
  40 The basic idea is to execute 'block_stream virtio0' while the guest is
  41 running. Progress can be monitored using 'info block-jobs'. When the
  42 streaming operation completes it raises a QMP event. 'block_stream'
  43 copies data from the backing file(s) into the active image. When finished,
  44 it adjusts the backing file pointer.
  45
  46 The 'base' parameter specifies an image which data need not be
  47 streamed from. This image will be used as the backing file for the
  48 destination image when the operation is finished.
  49
  50 In the first example above, the command would be:
  51
  52 (qemu) block_stream virtio0 file-A.img
  53
  54 In order to specify a destination image different from the active
  55 (rightmost) one we can use its node name instead.
  56
  57 In the second example above, the command would be:
  58
  59 (qemu) block_stream node-D file-B.img
  60
  61 Live block copy
  62 ===============
  63
  64 To copy an in use image to another destination in the filesystem, one
  65 should create a live snapshot in the desired destination, then stream
  66 into that image. Example:
  67
  68 (qemu) snapshot_blkdev ide0-hd0 /new-path/disk.img qcow2
  69
  70 (qemu) block_stream ide0-hd0
  71
  72