docs/interop/bitmaps.rst

9 Dirty Bitmaps and Incremental Backup
12 Dirty Bitmaps are in-memory objects that track writes to block devices. They
29 Bitmaps are bit vectors where each '1' bit in the vector indicates a modified
46 QEMU uses these bitmaps when making incremental backups to know which sections
50 Bitmaps can be created at any time and can be attached to any arbitrary block
59 QEMU supports persisting these bitmaps to disk via the qcow2 image format.
60 Bitmaps which are stored or loaded in this way are called "persistent",
61 whereas bitmaps that are not are called "transient".
63 QEMU also supports the migration of both transient bitmaps (tracking any
64 arbitrary image format) or persistent bitmaps (qcow2) via live migration.
76 For example, Dirty Bitmaps can be combined with the 'raw' image format, but
79 .. warning:: Transient bitmaps will not be saved on QEMU exit! Persistent
80              bitmaps are available only on qcow2 images.
86 managed bitmaps have a human-readable name chosen by the user at creation
89 - A bitmap's name is unique to the node, but bitmaps attached to different
90   nodes can share the same name. Therefore, all bitmaps are addressed via
95 - Transient bitmaps can have JSON unicode names that are effectively not
99   and namespaces. Presently, only qcow2 supports persistent bitmaps. See
104    - No two bitmaps saved to the same qcow2 file may share the same name.
106 - QEMU occasionally uses bitmaps for internal use which have no name. They are
128 commands documented below will refuse to work on such bitmaps.
242 Deletes a bitmap. Bitmaps that are ``+busy`` cannot be removed.
244 - Deleting a bitmap does not impact any other bitmaps attached to the same
248 - Because bitmaps are only unique to the node to which they are attached, you
274 Clears all dirty bits from a bitmap. ``+busy`` bitmaps cannot be cleared.
301 begin being recorded. ``+busy`` bitmaps cannot be enabled.
303 - Bitmaps default to being enabled when created, unless configured otherwise.
305 - Persistent enabled bitmaps will remember their ``+recording`` status on
330 writes to begin being ignored. ``+busy`` bitmaps cannot be disabled.
335   there are disabled bitmaps on a node, and will not mark any disabled bitmaps
337   bitmaps will not be able to be used to reconstruct a coherent image.
343 - Persistent disabled bitmaps will remember their ``-recording`` status on
367 Merges one or more bitmaps into a target bitmap. For any segment that is dirty
370 - Merge takes one or more bitmaps as a source and merges them together into a
381   be unmodified. The operation may fail if the source or destination bitmaps
384 - Bitmaps can only be merged on the same node. There is only one "node"
385   argument, so all bitmaps must be attached to that same node.
402          "bitmaps": [ "bitmap0" ]
414 Not strictly a bitmaps command, but will return information about any bitmaps
436          "dirty-bitmaps": [ {
452 As outlined in `Supported Image Formats`_, QEMU can persist bitmaps to qcow2
457 Persistent bitmaps will be automatically loaded into memory upon load, and
463 for any operation. At this point, the only valid operation on such bitmaps is
475 together. The interaction of bitmaps and transactions are demonstrated below.
483 Bitmaps can generally be modified at any time, but certain operations often
704          remember which bitmaps are associated with which backups.
1014 #. Create a full (anchor) backup for each drive, with accompanying bitmaps:
1508 cancelled, their associated bitmaps will all be held at their existing