One Hat Cyber Team

Your IP : 216.73.216.216

Server IP : 194.44.31.54

Server : Linux zen.imath.kiev.ua 4.18.0-553.77.1.el8_10.x86_64 #1 SMP Fri Oct 3 14:30:23 UTC 2025 x86_64

Server Software : Apache/2.4.37 (Rocky Linux) OpenSSL/1.1.1k

PHP Version : 5.6.40

Buat File | Buat Folder

Dir : ~/usr/share/doc/qemu-kvm/interop/

Edit File: bitmaps.html

<!DOCTYPE html>

 <html class="no-js" lang="en" > 
<head>
 <meta charset="utf-8">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
 <title>Dirty Bitmaps and Incremental Backup &mdash; QEMU qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4 documentation</title>

</head>

<a href="../index.html" class="icon icon-home"> QEMU

</div>

<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
 
 
 
 
 
 
 Contents:
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../about/index.html">About QEMU</a></li>
<li class="toctree-l1"><a class="reference internal" href="../system/index.html">System Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">User Mode Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Tools</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">System Emulation Management and Interoperability</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="barrier.html">Barrier client protocol</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Dirty Bitmaps and Incremental Backup</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#overview">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#supported-image-formats">Supported Image Formats</a></li>
<li class="toctree-l3"><a class="reference internal" href="#dirty-bitmap-names">Dirty Bitmap Names</a></li>
<li class="toctree-l3"><a class="reference internal" href="#bitmap-status">Bitmap Status</a></li>
<li class="toctree-l3"><a class="reference internal" href="#basic-qmp-usage">Basic QMP Usage</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#supported-commands">Supported Commands</a></li>
<li class="toctree-l4"><a class="reference internal" href="#creation-block-dirty-bitmap-add">Creation: block-dirty-bitmap-add</a></li>
<li class="toctree-l4"><a class="reference internal" href="#deletion-block-dirty-bitmap-remove">Deletion: block-dirty-bitmap-remove</a></li>
<li class="toctree-l4"><a class="reference internal" href="#resetting-block-dirty-bitmap-clear">Resetting: block-dirty-bitmap-clear</a></li>
<li class="toctree-l4"><a class="reference internal" href="#enabling-block-dirty-bitmap-enable">Enabling: block-dirty-bitmap-enable</a></li>
<li class="toctree-l4"><a class="reference internal" href="#enabling-block-dirty-bitmap-disable">Enabling: block-dirty-bitmap-disable</a></li>
<li class="toctree-l4"><a class="reference internal" href="#merging-copying-block-dirty-bitmap-merge">Merging, Copying: block-dirty-bitmap-merge</a></li>
<li class="toctree-l4"><a class="reference internal" href="#querying-query-block">Querying: query-block</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#bitmap-persistence">Bitmap Persistence</a></li>
<li class="toctree-l3"><a class="reference internal" href="#transactions">Transactions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#justification">Justification</a></li>
<li class="toctree-l4"><a class="reference internal" href="#supported-bitmap-transactions">Supported Bitmap Transactions</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#incremental-backups-push-model">Incremental Backups - Push Model</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#example-new-incremental-backup-anchor-point">Example: New Incremental Backup Anchor Point</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-resetting-an-incremental-backup-anchor-point">Example: Resetting an Incremental Backup Anchor Point</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-first-incremental-backup">Example: First Incremental Backup</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-second-incremental-backup">Example: Second Incremental Backup</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-incremental-push-backups-without-backing-files">Example: Incremental Push Backups without Backing Files</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-multi-drive-incremental-backup">Example: Multi-drive Incremental Backup</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#push-backup-errors-recovery">Push Backup Errors &amp; Recovery</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#example-individual-failures">Example: Individual Failures</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-partial-transactional-failures">Example: Partial Transactional Failures</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-grouped-completion-mode">Example: Grouped Completion Mode</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="dbus.html">D-Bus</a></li>
<li class="toctree-l2"><a class="reference internal" href="dbus-vmstate.html">D-Bus VMState</a></li>
<li class="toctree-l2"><a class="reference internal" href="live-block-operations.html">Live Block Device Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="pr-helper.html">Persistent reservation helper protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemu-ga.html">QEMU Guest Agent</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemu-ga-ref.html">QEMU Guest Agent Protocol Reference</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemu-qmp-ref.html">QEMU QMP Reference Manual</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemu-storage-daemon-qmp-ref.html">QEMU Storage Daemon QMP Reference Manual</a></li>
<li class="toctree-l2"><a class="reference internal" href="vhost-user.html">Vhost-user Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="vhost-user-gpu.html">Vhost-user-gpu Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="vhost-vdpa.html">Vhost-vdpa Protocol</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../specs/index.html">System Emulation Guest Hardware Specifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devel/index.html">Developer Information</a></li>
</ul>

</div>
 </div>
 </nav>

<ul class="wy-breadcrumbs">
 
 <li><a href="../index.html">Docs</a> &raquo;</li>
 
 <li><a href="index.html">System Emulation Management and Interoperability</a> &raquo;</li>
 
 <li>Dirty Bitmaps and Incremental Backup</li>
 
 
 <li class="wy-breadcrumbs-aside">
 
 
 
 <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/interop/bitmaps.rst" class="fa fa-gitlab"> Edit on GitLab</a>
 
 
 
 </li>
 
 </ul>

<hr/>
</div>
 <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
 <div itemprop="articleBody">
 
 <div class="section" id="dirty-bitmaps-and-incremental-backup">
<h1><a class="toc-backref" href="#id3">Dirty Bitmaps and Incremental Backup</a><a class="headerlink" href="#dirty-bitmaps-and-incremental-backup" title="Permalink to this headline">¶</a></h1>
Dirty Bitmaps are in-memory objects that track writes to block devices. They
can be used in conjunction with various block job operations to perform
incremental or differential backup regimens.
This document explains the conceptual mechanisms, as well as up-to-date,
complete and comprehensive documentation on the API to manipulate them.
(Hopefully, the “why”, “what”, and “how”.)
The intended audience for this document is developers who are adding QEMU
backup features to management applications, or power users who run and
administer QEMU directly via QMP.
<div class="contents topic" id="contents">
Contents
<ul class="simple">
<li><a class="reference internal" href="#dirty-bitmaps-and-incremental-backup" id="id3">Dirty Bitmaps and Incremental Backup</a><ul>
<li><a class="reference internal" href="#overview" id="id4">Overview</a></li>
<li><a class="reference internal" href="#supported-image-formats" id="id5">Supported Image Formats</a></li>
<li><a class="reference internal" href="#dirty-bitmap-names" id="id6">Dirty Bitmap Names</a></li>
<li><a class="reference internal" href="#bitmap-status" id="id7">Bitmap Status</a></li>
<li><a class="reference internal" href="#basic-qmp-usage" id="id8">Basic QMP Usage</a><ul>
<li><a class="reference internal" href="#supported-commands" id="id9">Supported Commands</a></li>
<li><a class="reference internal" href="#creation-block-dirty-bitmap-add" id="id10">Creation: block-dirty-bitmap-add</a></li>
<li><a class="reference internal" href="#deletion-block-dirty-bitmap-remove" id="id11">Deletion: block-dirty-bitmap-remove</a></li>
<li><a class="reference internal" href="#resetting-block-dirty-bitmap-clear" id="id12">Resetting: block-dirty-bitmap-clear</a></li>
<li><a class="reference internal" href="#enabling-block-dirty-bitmap-enable" id="id13">Enabling: block-dirty-bitmap-enable</a></li>
<li><a class="reference internal" href="#enabling-block-dirty-bitmap-disable" id="id14">Enabling: block-dirty-bitmap-disable</a></li>
<li><a class="reference internal" href="#merging-copying-block-dirty-bitmap-merge" id="id15">Merging, Copying: block-dirty-bitmap-merge</a></li>
<li><a class="reference internal" href="#querying-query-block" id="id16">Querying: query-block</a></li>
</ul>
</li>
<li><a class="reference internal" href="#bitmap-persistence" id="id17">Bitmap Persistence</a></li>
<li><a class="reference internal" href="#transactions" id="id18">Transactions</a><ul>
<li><a class="reference internal" href="#justification" id="id19">Justification</a></li>
<li><a class="reference internal" href="#supported-bitmap-transactions" id="id20">Supported Bitmap Transactions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#incremental-backups-push-model" id="id21">Incremental Backups - Push Model</a><ul>
<li><a class="reference internal" href="#example-new-incremental-backup-anchor-point" id="id22">Example: New Incremental Backup Anchor Point</a></li>
<li><a class="reference internal" href="#example-resetting-an-incremental-backup-anchor-point" id="id23">Example: Resetting an Incremental Backup Anchor Point</a></li>
<li><a class="reference internal" href="#example-first-incremental-backup" id="id24">Example: First Incremental Backup</a></li>
<li><a class="reference internal" href="#example-second-incremental-backup" id="id25">Example: Second Incremental Backup</a></li>
<li><a class="reference internal" href="#example-incremental-push-backups-without-backing-files" id="id26">Example: Incremental Push Backups without Backing Files</a></li>
<li><a class="reference internal" href="#example-multi-drive-incremental-backup" id="id27">Example: Multi-drive Incremental Backup</a></li>
</ul>
</li>
<li><a class="reference internal" href="#push-backup-errors-recovery" id="id28">Push Backup Errors &amp; Recovery</a><ul>
<li><a class="reference internal" href="#example-individual-failures" id="id29">Example: Individual Failures</a></li>
<li><a class="reference internal" href="#example-partial-transactional-failures" id="id30">Example: Partial Transactional Failures</a></li>
<li><a class="reference internal" href="#example-grouped-completion-mode" id="id31">Example: Grouped Completion Mode</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="overview">
<h2><a class="toc-backref" href="#id4">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
Bitmaps are bit vectors where each ‘1’ bit in the vector indicates a modified
(“dirty”) segment of the corresponding block device. The size of the segment
that is tracked is the granularity of the bitmap. If the granularity of a
bitmap is 64K, each ‘1’ bit means that a 64K region as a whole may have
changed in some way, possibly by as little as one byte.
Smaller granularities mean more accurate tracking of modified disk data, but
requires more computational overhead and larger bitmap sizes. Larger
granularities mean smaller bitmap sizes, but less targeted backups.
<dl class="docutils">
<dt>The size of a bitmap (in bytes) can be computed as such:</dt>
<dd><code class="docutils literal notranslate">size</code> = ceil(ceil(<code class="docutils literal notranslate">image_size</code> / <code class="docutils literal notranslate">granularity</code>) / 8)</dd>
<dt>e.g. the size of a 64KiB granularity bitmap on a 2TiB image is:</dt>
<dd><dl class="first last docutils">
<dt><code class="docutils literal notranslate">size</code> = ((2147483648K / 64K) / 8)</dt>
<dd>= 4194304B = 4MiB.</dd>
</dl>
</dd>
</dl>
QEMU uses these bitmaps when making incremental backups to know which sections
of the file to copy out. They are not enabled by default and must be
explicitly added in order to begin tracking writes.
Bitmaps can be created at any time and can be attached to any arbitrary block
node in the storage graph, but are most useful conceptually when attached to
the root node attached to the guest’s storage device model.
That is to say: It’s likely most useful to track the guest’s writes to disk,
but you could theoretically track things like qcow2 metadata changes by
attaching the bitmap elsewhere in the storage graph. This is beyond the scope
of this document.
QEMU supports persisting these bitmaps to disk via the qcow2 image format.
Bitmaps which are stored or loaded in this way are called “persistent”,
whereas bitmaps that are not are called “transient”.
QEMU also supports the migration of both transient bitmaps (tracking any
arbitrary image format) or persistent bitmaps (qcow2) via live migration.
</div>
<div class="section" id="supported-image-formats">
<h2><a class="toc-backref" href="#id5">Supported Image Formats</a><a class="headerlink" href="#supported-image-formats" title="Permalink to this headline">¶</a></h2>
QEMU supports all documented features below on the qcow2 image format.
However, qcow2 is only strictly necessary for the persistence feature, which
writes bitmap data to disk upon close. If persistence is not required for a
specific use case, all bitmap features excepting persistence are available for
any arbitrary image format.
For example, Dirty Bitmaps can be combined with the ‘raw’ image format, but
any changes to the bitmap will be discarded upon exit.
<div class="admonition warning">
Warning
Transient bitmaps will not be saved on QEMU exit! Persistent
bitmaps are available only on qcow2 images.
</div>
</div>
<div class="section" id="dirty-bitmap-names">
<h2><a class="toc-backref" href="#id6">Dirty Bitmap Names</a><a class="headerlink" href="#dirty-bitmap-names" title="Permalink to this headline">¶</a></h2>
Bitmap objects need a method to reference them in the API. All API-created and
managed bitmaps have a human-readable name chosen by the user at creation
time.
<ul>
<li>A bitmap’s name is unique to the node, but bitmaps attached to different
nodes can share the same name. Therefore, all bitmaps are addressed via
their (node, name) pair.
</li>
<li>The name of a user-created bitmap cannot be empty (“”).
</li>
<li>Transient bitmaps can have JSON unicode names that are effectively not
length limited. (QMP protocol may restrict messages to less than 64MiB.)
</li>
<li>Persistent storage formats may impose their own requirements on bitmap names
and namespaces. Presently, only qcow2 supports persistent bitmaps. See
docs/interop/qcow2.txt for more details on restrictions. Notably:
<blockquote>
<div><ul class="simple">
<li>qcow2 bitmap names are limited to between 1 and 1023 bytes long.</li>
<li>No two bitmaps saved to the same qcow2 file may share the same name.</li>
</ul>
</div></blockquote>
</li>
<li>QEMU occasionally uses bitmaps for internal use which have no name. They are
hidden from API query calls, cannot be manipulated by the external API, are
never persistent, nor ever migrated.
</li>
</ul>
</div>
<div class="section" id="bitmap-status">
<h2><a class="toc-backref" href="#id7">Bitmap Status</a><a class="headerlink" href="#bitmap-status" title="Permalink to this headline">¶</a></h2>
Dirty Bitmap objects can be queried with the QMP command <a class="reference external" href="qemu-qmp-ref.html#index-query_002dblock">query-block</a>, and are visible via the
<a class="reference external" href="qemu-qmp-ref.html#index-BlockDirtyInfo">BlockDirtyInfo</a> QAPI structure.
This struct shows the name, granularity, and dirty byte count for each bitmap.
Additionally, it shows several boolean status indicators:
<ul class="simple">
<li><code class="docutils literal notranslate">recording</code>: This bitmap is recording writes.</li>
<li><code class="docutils literal notranslate">busy</code>: This bitmap is in-use by an operation.</li>
<li><code class="docutils literal notranslate">persistent</code>: This bitmap is a persistent type.</li>
<li><code class="docutils literal notranslate">inconsistent</code>: This bitmap is corrupted and cannot be used.</li>
</ul>
The <code class="docutils literal notranslate">+busy</code> status prohibits you from deleting, clearing, or otherwise
modifying a bitmap, and happens when the bitmap is being used for a backup
operation or is in the process of being loaded from a migration. Many of the
commands documented below will refuse to work on such bitmaps.
The <code class="docutils literal notranslate">+inconsistent</code> status similarly prohibits almost all operations,
notably allowing only the <code class="docutils literal notranslate">block-dirty-bitmap-remove</code> operation.
There is also a deprecated <code class="docutils literal notranslate">status</code> field of type <a class="reference external" href="qemu-qmp-ref.html#index-DirtyBitmapStatus">DirtyBitmapStatus</a>. A bitmap historically had
five visible states:
<blockquote>
<div><ol class="arabic">
<li><code class="docutils literal notranslate">Frozen</code>: This bitmap is currently in-use by an operation and is
immutable. It can’t be deleted, renamed, reset, etc.
(This is now <code class="docutils literal notranslate">+busy</code>.)
</li>
<li><code class="docutils literal notranslate">Disabled</code>: This bitmap is not recording new writes.
(This is now <code class="docutils literal notranslate">-recording -busy</code>.)
</li>
<li><code class="docutils literal notranslate">Active</code>: This bitmap is recording new writes.
(This is now <code class="docutils literal notranslate">+recording -busy</code>.)
</li>
<li><code class="docutils literal notranslate">Locked</code>: This bitmap is in-use by an operation, and is immutable.
The difference from “Frozen” was primarily implementation details.
(This is now <code class="docutils literal notranslate">+busy</code>.)
</li>
<li><code class="docutils literal notranslate">Inconsistent</code>: This persistent bitmap was not saved to disk
correctly, and can no longer be used. It remains in memory to serve as
an indicator of failure.
(This is now <code class="docutils literal notranslate">+inconsistent</code>.)
</li>
</ol>
</div></blockquote>
These states are directly replaced by the status indicators and should not be
used. The difference between <code class="docutils literal notranslate">Frozen</code> and <code class="docutils literal notranslate">Locked</code> is an implementation
detail and should not be relevant to external users.
</div>
<div class="section" id="basic-qmp-usage">
<h2><a class="toc-backref" href="#id8">Basic QMP Usage</a><a class="headerlink" href="#basic-qmp-usage" title="Permalink to this headline">¶</a></h2>
The primary interface to manipulating bitmap objects is via the QMP
interface. If you are not familiar, see docs/interop/qmp-intro.txt for a broad
overview, and <a class="reference external" href="qemu-qmp-ref.html">qemu-qmp-ref</a> for a full reference of all
QMP commands.
<div class="section" id="supported-commands">
<h3><a class="toc-backref" href="#id9">Supported Commands</a><a class="headerlink" href="#supported-commands" title="Permalink to this headline">¶</a></h3>
There are six primary bitmap-management API commands:
<ul class="simple">
<li><code class="docutils literal notranslate">block-dirty-bitmap-add</code></li>
<li><code class="docutils literal notranslate">block-dirty-bitmap-remove</code></li>
<li><code class="docutils literal notranslate">block-dirty-bitmap-clear</code></li>
<li><code class="docutils literal notranslate">block-dirty-bitmap-disable</code></li>
<li><code class="docutils literal notranslate">block-dirty-bitmap-enable</code></li>
<li><code class="docutils literal notranslate">block-dirty-bitmap-merge</code></li>
</ul>
And one related query command:
<ul class="simple">
<li><code class="docutils literal notranslate">query-block</code></li>
</ul>
</div>
<div class="section" id="creation-block-dirty-bitmap-add">
<h3><a class="toc-backref" href="#id10">Creation: block-dirty-bitmap-add</a><a class="headerlink" href="#creation-block-dirty-bitmap-add" title="Permalink to this headline">¶</a></h3>
<a class="reference external" href="qemu-qmp-ref.html#index-block_002ddirty_002dbitmap_002dadd">block-dirty-bitmap-add</a>:
Creates a new bitmap that tracks writes to the specified node. granularity,
persistence, and recording state can be adjusted at creation time.
<div class="admonition-example admonition">
Example
to create a new, actively recording persistent bitmap:
<div class="last highlight-QMP notranslate"><div class="highlight"><pre>-&gt; { &quot;execute&quot;: &quot;block-dirty-bitmap-add&quot;,
 &quot;arguments&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;name&quot;: &quot;bitmap0&quot;,
 &quot;persistent&quot;: true,
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</div>
<ul class="simple">
<li>This bitmap will have a default granularity that matches the cluster size of
its associated drive, if available, clamped to between [4KiB, 64KiB]. The
current default for qcow2 is 64KiB.</li>
</ul>
<div class="admonition-example admonition">
Example
To create a new, disabled (<code class="docutils literal notranslate">-recording</code>), transient bitmap that tracks
changes in 32KiB segments:
<div class="last highlight-QMP notranslate"><div class="highlight"><pre>-&gt; { &quot;execute&quot;: &quot;block-dirty-bitmap-add&quot;,
 &quot;arguments&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;name&quot;: &quot;bitmap1&quot;,
 &quot;granularity&quot;: 32768,
 &quot;disabled&quot;: true
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</div>
</div>
<div class="section" id="deletion-block-dirty-bitmap-remove">
<h3><a class="toc-backref" href="#id11">Deletion: block-dirty-bitmap-remove</a><a class="headerlink" href="#deletion-block-dirty-bitmap-remove" title="Permalink to this headline">¶</a></h3>
<a class="reference external" href="qemu-qmp-ref.html#index-block_002ddirty_002dbitmap_002dremove">block-dirty-bitmap-remove</a>:
Deletes a bitmap. Bitmaps that are <code class="docutils literal notranslate">+busy</code> cannot be removed.
<ul class="simple">
<li>Deleting a bitmap does not impact any other bitmaps attached to the same
node, nor does it affect any backups already created from this bitmap or
node.</li>
<li>Because bitmaps are only unique to the node to which they are attached, you
must specify the node/drive name here, too.</li>
<li>Deleting a persistent bitmap will remove it from the qcow2 file.</li>
</ul>
<div class="admonition-example admonition">
Example
Remove a bitmap named <code class="docutils literal notranslate">bitmap0</code> from node <code class="docutils literal notranslate">drive0</code>:
<div class="last highlight-QMP notranslate"><div class="highlight"><pre>-&gt; { &quot;execute&quot;: &quot;block-dirty-bitmap-remove&quot;,
 &quot;arguments&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;name&quot;: &quot;bitmap0&quot;
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</div>
</div>
<div class="section" id="resetting-block-dirty-bitmap-clear">
<h3><a class="toc-backref" href="#id12">Resetting: block-dirty-bitmap-clear</a><a class="headerlink" href="#resetting-block-dirty-bitmap-clear" title="Permalink to this headline">¶</a></h3>
<a class="reference external" href="qemu-qmp-ref.html#index-block_002ddirty_002dbitmap_002dclear">block-dirty-bitmap-clear</a>:
Clears all dirty bits from a bitmap. <code class="docutils literal notranslate">+busy</code> bitmaps cannot be cleared.
<ul class="simple">
<li>An incremental backup created from an empty bitmap will copy no data, as if
nothing has changed.</li>
</ul>
<div class="admonition-example admonition">
Example
Clear all dirty bits from bitmap <code class="docutils literal notranslate">bitmap0</code> on node <code class="docutils literal notranslate">drive0</code>:
<div class="last highlight-QMP notranslate"><div class="highlight"><pre>-&gt; { &quot;execute&quot;: &quot;block-dirty-bitmap-clear&quot;,
 &quot;arguments&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;name&quot;: &quot;bitmap0&quot;
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</div>
</div>
<div class="section" id="enabling-block-dirty-bitmap-enable">
<h3><a class="toc-backref" href="#id13">Enabling: block-dirty-bitmap-enable</a><a class="headerlink" href="#enabling-block-dirty-bitmap-enable" title="Permalink to this headline">¶</a></h3>
<a class="reference external" href="qemu-qmp-ref.html#index-block_002ddirty_002dbitmap_002denable">block-dirty-bitmap-enable</a>:
“Enables” a bitmap, setting the <code class="docutils literal notranslate">recording</code> bit to true, causing writes to
begin being recorded. <code class="docutils literal notranslate">+busy</code> bitmaps cannot be enabled.
<ul class="simple">
<li>Bitmaps default to being enabled when created, unless configured otherwise.</li>
<li>Persistent enabled bitmaps will remember their <code class="docutils literal notranslate">+recording</code> status on
load.</li>
</ul>
<div class="admonition-example admonition">
Example
To set <code class="docutils literal notranslate">+recording</code> on bitmap <code class="docutils literal notranslate">bitmap0</code> on node <code class="docutils literal notranslate">drive0</code>:
<div class="last highlight-QMP notranslate"><div class="highlight"><pre>-&gt; { &quot;execute&quot;: &quot;block-dirty-bitmap-enable&quot;,
 &quot;arguments&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;name&quot;: &quot;bitmap0&quot;
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</div>
</div>
<div class="section" id="enabling-block-dirty-bitmap-disable">
<h3><a class="toc-backref" href="#id14">Enabling: block-dirty-bitmap-disable</a><a class="headerlink" href="#enabling-block-dirty-bitmap-disable" title="Permalink to this headline">¶</a></h3>
<a class="reference external" href="qemu-qmp-ref.html#index-block_002ddirty_002dbitmap_002ddisable">block-dirty-bitmap-disable</a>:
“Disables” a bitmap, setting the <code class="docutils literal notranslate">recording</code> bit to false, causing further
writes to begin being ignored. <code class="docutils literal notranslate">+busy</code> bitmaps cannot be disabled.
<div class="admonition warning">
Warning
This is potentially dangerous: QEMU makes no effort to stop any writes if
there are disabled bitmaps on a node, and will not mark any disabled bitmaps
as <code class="docutils literal notranslate">+inconsistent</code> if any such writes do happen. Backups made from such
bitmaps will not be able to be used to reconstruct a coherent image.
</div>
<ul class="simple">
<li>Disabling a bitmap may be useful for examining which sectors of a disk
changed during a specific time period, or for explicit management of
differential backup windows.</li>
<li>Persistent disabled bitmaps will remember their <code class="docutils literal notranslate">-recording</code> status on
load.</li>
</ul>
<div class="admonition-example admonition">
Example
To set <code class="docutils literal notranslate">-recording</code> on bitmap <code class="docutils literal notranslate">bitmap0</code> on node <code class="docutils literal notranslate">drive0</code>:
<div class="last highlight-QMP notranslate"><div class="highlight"><pre>-&gt; { &quot;execute&quot;: &quot;block-dirty-bitmap-disable&quot;,
 &quot;arguments&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;name&quot;: &quot;bitmap0&quot;
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</div>
</div>
<div class="section" id="merging-copying-block-dirty-bitmap-merge">
<h3><a class="toc-backref" href="#id15">Merging, Copying: block-dirty-bitmap-merge</a><a class="headerlink" href="#merging-copying-block-dirty-bitmap-merge" title="Permalink to this headline">¶</a></h3>
<a class="reference external" href="qemu-qmp-ref.html#index-block_002ddirty_002dbitmap_002dmerge">block-dirty-bitmap-merge</a>:
Merges one or more bitmaps into a target bitmap. For any segment that is dirty
in any one source bitmap, the target bitmap will mark that segment dirty.
<ul class="simple">
<li>Merge takes one or more bitmaps as a source and merges them together into a
single destination, such that any segment marked as dirty in any source
bitmap(s) will be marked dirty in the destination bitmap.</li>
<li>Merge does not create the destination bitmap if it does not exist. A blank
bitmap can be created beforehand to achieve the same effect.</li>
<li>The destination is not cleared prior to merge, so subsequent merge
operations will continue to cumulatively mark more segments as dirty.</li>
<li>If the merge operation should fail, the destination bitmap is guaranteed to
be unmodified. The operation may fail if the source or destination bitmaps
are busy, or have different granularities.</li>
<li>Bitmaps can only be merged on the same node. There is only one “node”
argument, so all bitmaps must be attached to that same node.</li>
<li>Copy can be achieved by merging from a single source to an empty
destination.</li>
</ul>
<div class="admonition-example admonition">
Example
Merge the data from <code class="docutils literal notranslate">bitmap0</code> into the bitmap <code class="docutils literal notranslate">new_bitmap</code> on node
<code class="docutils literal notranslate">drive0</code>. If <code class="docutils literal notranslate">new_bitmap</code> was empty prior to this command, this achieves
a copy.
<div class="last highlight-QMP notranslate"><div class="highlight"><pre>-&gt; { &quot;execute&quot;: &quot;block-dirty-bitmap-merge&quot;,
 &quot;arguments&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;target&quot;: &quot;new_bitmap&quot;,
 &quot;bitmaps&quot;: [ &quot;bitmap0&quot; ]
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</div>
</div>
<div class="section" id="querying-query-block">
<h3><a class="toc-backref" href="#id16">Querying: query-block</a><a class="headerlink" href="#querying-query-block" title="Permalink to this headline">¶</a></h3>
<a class="reference external" href="qemu-qmp-ref.html#index-query_002dblock">query-block</a>:
Not strictly a bitmaps command, but will return information about any bitmaps
attached to nodes serving as the root for guest devices.
<ul class="simple">
<li>The “inconsistent” bit will not appear when it is false, appearing only when
the value is true to indicate there is a problem.</li>
</ul>
<div class="admonition-example admonition">
Example
Query the block sub-system of QEMU. The following json has trimmed irrelevant
keys from the response to highlight only the bitmap-relevant portions of the
API. This result highlights a bitmap <code class="docutils literal notranslate">bitmap0</code> attached to the root node of
device <code class="docutils literal notranslate">drive0</code>.
<div class="last highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;query-block&quot;,
 &quot;arguments&quot;: {}
 }

&lt;- {
 &quot;return&quot;: [ {
 &quot;dirty-bitmaps&quot;: [ {
 &quot;status&quot;: &quot;active&quot;,
 &quot;count&quot;: 0,
 &quot;busy&quot;: false,
 &quot;name&quot;: &quot;bitmap0&quot;,
 &quot;persistent&quot;: false,
 &quot;recording&quot;: true,
 &quot;granularity&quot;: 65536
 } ],
 &quot;device&quot;: &quot;drive0&quot;,
 } ]
 }
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="bitmap-persistence">
<h2><a class="toc-backref" href="#id17">Bitmap Persistence</a><a class="headerlink" href="#bitmap-persistence" title="Permalink to this headline">¶</a></h2>
As outlined in <a class="reference internal" href="#supported-image-formats">Supported Image Formats</a>, QEMU can persist bitmaps to qcow2
files. Demonstrated in <a class="reference internal" href="#creation-block-dirty-bitmap-add">Creation: block-dirty-bitmap-add</a>, passing
<code class="docutils literal notranslate">persistent: true</code> to <code class="docutils literal notranslate">block-dirty-bitmap-add</code> will persist that bitmap to
disk.
Persistent bitmaps will be automatically loaded into memory upon load, and
will be written back to disk upon close. Their usage should be mostly
transparent.
However, if QEMU does not get a chance to close the file cleanly, the bitmap
will be marked as <code class="docutils literal notranslate">+inconsistent</code> at next load and considered unsafe to use
for any operation. At this point, the only valid operation on such bitmaps is
<code class="docutils literal notranslate">block-dirty-bitmap-remove</code>.
Losing a bitmap in this way does not invalidate any existing backups that have
been made from this bitmap, but no further backups will be able to be issued
for this chain.
</div>
<div class="section" id="transactions">
<h2><a class="toc-backref" href="#id18">Transactions</a><a class="headerlink" href="#transactions" title="Permalink to this headline">¶</a></h2>
Transactions are a QMP feature that allows you to submit multiple QMP commands
at once, being guaranteed that they will all succeed or fail atomically,
together. The interaction of bitmaps and transactions are demonstrated below.
See <a class="reference external" href="qemu-qmp.ref.html#index-transaction">transaction</a> in the QMP reference
for more details.
<div class="section" id="justification">
<h3><a class="toc-backref" href="#id19">Justification</a><a class="headerlink" href="#justification" title="Permalink to this headline">¶</a></h3>
Bitmaps can generally be modified at any time, but certain operations often
only make sense when paired directly with other commands. When a VM is paused,
it’s easy to ensure that no guest writes occur between individual QMP
commands. When a VM is running, this is difficult to accomplish with
individual QMP commands that may allow guest writes to occur between each
command.
For example, using only individual QMP commands, we could:
<ol class="arabic simple">
<li>Boot the VM in a paused state.</li>
<li>Create a full drive backup of drive0.</li>
<li>Create a new bitmap attached to drive0, confident that nothing has been
written to drive0 in the meantime.</li>
<li>Resume execution of the VM.</li>
<li>At a later point, issue incremental backups from <code class="docutils literal notranslate">bitmap0</code>.</li>
</ol>
At this point, the bitmap and drive backup would be correctly in sync, and
incremental backups made from this point forward would be correctly aligned to
the full drive backup.
This is not particularly useful if we decide we want to start incremental
backups after the VM has been running for a while, for which we would want to
perform actions such as the following:
<ol class="arabic simple">
<li>Boot the VM and begin execution.</li>
<li>Using a single transaction, perform the following operations:<ul>
<li>Create <code class="docutils literal notranslate">bitmap0</code>.</li>
<li>Create a full drive backup of <code class="docutils literal notranslate">drive0</code>.</li>
</ul>
</li>
<li>At a later point, issue incremental backups from <code class="docutils literal notranslate">bitmap0</code>.</li>
</ol>
<div class="admonition note">
Note
As a consideration, if <code class="docutils literal notranslate">bitmap0</code> is created prior to the full
drive backup, incremental backups can still be authored from this
bitmap, but they will copy extra segments reflecting writes that
occurred prior to the backup operation. Transactions allow us to
narrow critical points in time to reduce waste, or, in the other
direction, to ensure that no segments are omitted.
</div>
</div>
<div class="section" id="supported-bitmap-transactions">
<h3><a class="toc-backref" href="#id20">Supported Bitmap Transactions</a><a class="headerlink" href="#supported-bitmap-transactions" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><code class="docutils literal notranslate">block-dirty-bitmap-add</code></li>
<li><code class="docutils literal notranslate">block-dirty-bitmap-clear</code></li>
<li><code class="docutils literal notranslate">block-dirty-bitmap-enable</code></li>
<li><code class="docutils literal notranslate">block-dirty-bitmap-disable</code></li>
<li><code class="docutils literal notranslate">block-dirty-bitmap-merge</code></li>
</ul>
The usages for these commands are identical to their respective QMP commands,
but see the sections below for concrete examples.
</div>
</div>
<div class="section" id="incremental-backups-push-model">
<h2><a class="toc-backref" href="#id21">Incremental Backups - Push Model</a><a class="headerlink" href="#incremental-backups-push-model" title="Permalink to this headline">¶</a></h2>
Incremental backups are simply partial disk images that can be combined with
other partial disk images on top of a base image to reconstruct a full backup
from the point in time at which the incremental backup was issued.
The “Push Model” here references the fact that QEMU is “pushing” the modified
blocks out to a destination. We will be using the <a class="reference external" href="qemu-qmp-ref.html#index-blockdev_002dbackup">blockdev-backup</a> QMP command to create both
full and incremental backups.
The command is a background job, which has its own QMP API for querying and
management documented in <a class="reference external" href="qemu-qmp-ref.html#Background-jobs">Background jobs</a>.
<div class="section" id="example-new-incremental-backup-anchor-point">
<h3><a class="toc-backref" href="#id22">Example: New Incremental Backup Anchor Point</a><a class="headerlink" href="#example-new-incremental-backup-anchor-point" title="Permalink to this headline">¶</a></h3>
As outlined in the Transactions - <a class="reference internal" href="#justification">Justification</a> section, perhaps we want to
create a new incremental backup chain attached to a drive.
This example creates a new, full backup of “drive0” and accompanies it with a
new, empty bitmap that records writes from this point in time forward.
The target can be created with the help of <a class="reference external" href="qemu-qmp-ref.html#index-blockdev_002dadd">blockdev-add</a> or <a class="reference external" href="qemu-qmp-ref.html#index-blockdev_002dcreate">blockdev-create</a> command.
<div class="admonition note">
Note
Any new writes that happen after this command is issued, even while
the backup job runs, will be written locally and not to the backup
destination. These writes will be recorded in the bitmap
accordingly.
</div>
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;transaction&quot;,
 &quot;arguments&quot;: {
 &quot;actions&quot;: [
 {
 &quot;type&quot;: &quot;block-dirty-bitmap-add&quot;,
 &quot;data&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;name&quot;: &quot;bitmap0&quot;
 }
 },
 {
 &quot;type&quot;: &quot;blockdev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;target&quot;: &quot;target0&quot;,
 &quot;sync&quot;: &quot;full&quot;
 }
 }
 ]
 }
 }

&lt;- { &quot;return&quot;: {} }

&lt;- {
 &quot;timestamp&quot;: {
 &quot;seconds&quot;: 1555436945,
 &quot;microseconds&quot;: 179620
 },
 &quot;data&quot;: {
 &quot;status&quot;: &quot;created&quot;,
 &quot;id&quot;: &quot;drive0&quot;
 },
 &quot;event&quot;: &quot;JOB_STATUS_CHANGE&quot;
 }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 68719476736,
 &quot;offset&quot;: 68719476736
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;status&quot;: &quot;concluded&quot;,
 &quot;id&quot;: &quot;drive0&quot;
 },
 &quot;event&quot;: &quot;JOB_STATUS_CHANGE&quot;
 }

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;status&quot;: &quot;null&quot;,
 &quot;id&quot;: &quot;drive0&quot;
 },
 &quot;event&quot;: &quot;JOB_STATUS_CHANGE&quot;
 }
</pre></div>
</div>
A full explanation of the job transition semantics and the JOB_STATUS_CHANGE
event are beyond the scope of this document and will be omitted in all
subsequent examples; above, several more events have been omitted for brevity.
<div class="admonition note">
Note
Subsequent examples will omit all events except BLOCK_JOB_COMPLETED
except where necessary to illustrate workflow differences.
Omitted events and json objects will be represented by ellipses:
<code class="docutils literal notranslate">...</code>
</div>
</div>
<div class="section" id="example-resetting-an-incremental-backup-anchor-point">
<h3><a class="toc-backref" href="#id23">Example: Resetting an Incremental Backup Anchor Point</a><a class="headerlink" href="#example-resetting-an-incremental-backup-anchor-point" title="Permalink to this headline">¶</a></h3>
If we want to start a new backup chain with an existing bitmap, we can also
use a transaction to reset the bitmap while making a new full backup:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;transaction&quot;,
 &quot;arguments&quot;: {
 &quot;actions&quot;: [
 {
 &quot;type&quot;: &quot;block-dirty-bitmap-clear&quot;,
 &quot;data&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;name&quot;: &quot;bitmap0&quot;
 }
 },
 {
 &quot;type&quot;: &quot;blockdev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;target&quot;: &quot;target0&quot;,
 &quot;sync&quot;: &quot;full&quot;
 }
 }
 ]
 }
 }

&lt;- { &quot;return&quot;: {} }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 68719476736,
 &quot;offset&quot;: 68719476736
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }

...
</pre></div>
</div>
The result of this example is identical to the first, but we clear an existing
bitmap instead of adding a new one.
<div class="admonition tip">
Tip
In both of these examples, “bitmap0” is tied conceptually to the
creation of new, full backups. This relationship is not saved or
remembered by QEMU; it is up to the operator or management layer to
remember which bitmaps are associated with which backups.
</div>
</div>
<div class="section" id="example-first-incremental-backup">
<h3><a class="toc-backref" href="#id24">Example: First Incremental Backup</a><a class="headerlink" href="#example-first-incremental-backup" title="Permalink to this headline">¶</a></h3>
<ol class="arabic">
<li>Create a full backup and sync it to a dirty bitmap using any method:
<ul class="simple">
<li>Either of the two live backup method demonstrated above,</li>
<li>Using QMP commands with the VM paused as in the <a class="reference internal" href="#justification">Justification</a> section,
or</li>
<li>With the VM offline, manually copy the image and start the VM in a paused
state, careful to add a new bitmap before the VM begins execution.</li>
</ul>
Whichever method is chosen, let’s assume that at the end of this step:
<ul class="simple">
<li>The full backup is named <code class="docutils literal notranslate">drive0.full.qcow2</code>.</li>
<li>The bitmap we created is named <code class="docutils literal notranslate">bitmap0</code>, attached to <code class="docutils literal notranslate">drive0</code>.</li>
</ul>
</li>
<li>Create a destination image for the incremental backup that utilizes the
full backup as a backing image.
<ul class="simple">
<li>Let’s assume the new incremental image is named <code class="docutils literal notranslate">drive0.inc0.qcow2</code>:</li>
</ul>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre>$ qemu-img create -f qcow2 drive0.inc0.qcow2 \
 -b drive0.full.qcow2 -F qcow2
</pre></div>
</div>
</li>
<li>Add target block node:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-add&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target0&quot;,
 &quot;driver&quot;: &quot;qcow2&quot;,
 &quot;file&quot;: {
 &quot;driver&quot;: &quot;file&quot;,
 &quot;filename&quot;: &quot;drive0.inc0.qcow2&quot;
 }
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Issue an incremental backup command:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-backup&quot;,
 &quot;arguments&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;target&quot;: &quot;target0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;
 }
 }

&lt;- { &quot;return&quot;: {} }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 68719476736,
 &quot;offset&quot;: 68719476736
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }

...
</pre></div>
</div>
</li>
</ol>
This copies any blocks modified since the full backup was created into the
<code class="docutils literal notranslate">drive0.inc0.qcow2</code> file. During the operation, <code class="docutils literal notranslate">bitmap0</code> is marked
<code class="docutils literal notranslate">+busy</code>. If the operation is successful, <code class="docutils literal notranslate">bitmap0</code> will be cleared to
reflect the “incremental” backup regimen, which only copies out new changes
from each incremental backup.
<div class="admonition note">
Note
Any new writes that occur after the backup operation starts do not
get copied to the destination. The backup’s “point in time” is when
the backup starts, not when it ends. These writes are recorded in a
special bitmap that gets re-added to bitmap0 when the backup ends so
that the next incremental backup can copy them out.
</div>
</div>
<div class="section" id="example-second-incremental-backup">
<h3><a class="toc-backref" href="#id25">Example: Second Incremental Backup</a><a class="headerlink" href="#example-second-incremental-backup" title="Permalink to this headline">¶</a></h3>
<ol class="arabic">
<li>Create a new destination image for the incremental backup that points to
the previous one, e.g.: <code class="docutils literal notranslate">drive0.inc1.qcow2</code>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre>$ qemu-img create -f qcow2 drive0.inc1.qcow2 \
 -b drive0.inc0.qcow2 -F qcow2
</pre></div>
</div>
</li>
<li>Add target block node:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-add&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target0&quot;,
 &quot;driver&quot;: &quot;qcow2&quot;,
 &quot;file&quot;: {
 &quot;driver&quot;: &quot;file&quot;,
 &quot;filename&quot;: &quot;drive0.inc1.qcow2&quot;
 }
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Issue a new incremental backup command. The only difference here is that we
have changed the target image below.
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-backup&quot;,
 &quot;arguments&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;target&quot;: &quot;target0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;
 }
 }

&lt;- { &quot;return&quot;: {} }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 68719476736,
 &quot;offset&quot;: 68719476736
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }

...
</pre></div>
</div>
</li>
</ol>
Because the first incremental backup from the previous example completed
successfully, <code class="docutils literal notranslate">bitmap0</code> was synchronized with <code class="docutils literal notranslate">drive0.inc0.qcow2</code>. Here,
we use <code class="docutils literal notranslate">bitmap0</code> again to create a new incremental backup that targets the
previous one, creating a chain of three images:
<div class="admonition-diagram admonition">
Diagram
<div class="code text last highlight-default notranslate"><div class="highlight"><pre>+-------------------+ +-------------------+ +-------------------+
| drive0.full.qcow2 |&lt;--| drive0.inc0.qcow2 |&lt;--| drive0.inc1.qcow2 |
+-------------------+ +-------------------+ +-------------------+
</pre></div>
</div>
</div>
Each new incremental backup re-synchronizes the bitmap to the latest backup
authored, allowing a user to continue to “consume” it to create new backups on
top of an existing chain.
In the above diagram, neither drive0.inc1.qcow2 nor drive0.inc0.qcow2 are
complete images by themselves, but rely on their backing chain to reconstruct
a full image. The dependency terminates with each full backup.
Each backup in this chain remains independent, and is unchanged by new entries
made later in the chain. For instance, drive0.inc0.qcow2 remains a perfectly
valid backup of the disk as it was when that backup was issued.
</div>
<div class="section" id="example-incremental-push-backups-without-backing-files">
<h3><a class="toc-backref" href="#id26">Example: Incremental Push Backups without Backing Files</a><a class="headerlink" href="#example-incremental-push-backups-without-backing-files" title="Permalink to this headline">¶</a></h3>
Backup images are best kept off-site, so we often will not have the preceding
backups in a chain available to link against. This is not a problem at backup
time; we simply do not set the backing image when creating the destination
image:
<ol class="arabic">
<li>Create a new destination image with no backing file set. We will need to
specify the size of the base image, because the backing file isn’t
available for QEMU to use to determine it.
<div class="code bash highlight-default notranslate"><div class="highlight"><pre>$ qemu-img create -f qcow2 drive0.inc2.qcow2 64G
</pre></div>
</div>
<div class="admonition note">
Note
Alternatively, you can omit <code class="docutils literal notranslate">mode: &quot;existing&quot;</code> from the push
backup commands to have QEMU create an image without a backing
file for you, but you lose control over format options like
compatibility and preallocation presets.
</div>
</li>
<li>Add target block node:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-add&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target0&quot;,
 &quot;driver&quot;: &quot;qcow2&quot;,
 &quot;file&quot;: {
 &quot;driver&quot;: &quot;file&quot;,
 &quot;filename&quot;: &quot;drive0.inc2.qcow2&quot;
 }
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Issue a new incremental backup command. Apart from the new destination
image, there is no difference from the last two examples.
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-backup&quot;,
 &quot;arguments&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;target&quot;: &quot;target0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;
 }
 }

&lt;- { &quot;return&quot;: {} }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 68719476736,
 &quot;offset&quot;: 68719476736
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }

...
</pre></div>
</div>
</li>
</ol>
The only difference from the perspective of the user is that you will need to
set the backing image when attempting to restore the backup:
<div class="code bash highlight-default notranslate"><div class="highlight"><pre>$ qemu-img rebase drive0.inc2.qcow2 \
 -u -b drive0.inc1.qcow2
</pre></div>
</div>
This uses the “unsafe” rebase mode to simply set the backing file to a file
that isn’t present.
It is also possible to use <code class="docutils literal notranslate">--image-opts</code> to specify the entire backing
chain by hand as an ephemeral property at runtime, but that is beyond the
scope of this document.
</div>
<div class="section" id="example-multi-drive-incremental-backup">
<h3><a class="toc-backref" href="#id27">Example: Multi-drive Incremental Backup</a><a class="headerlink" href="#example-multi-drive-incremental-backup" title="Permalink to this headline">¶</a></h3>
Assume we have a VM with two drives, “drive0” and “drive1” and we wish to back
both of them up such that the two backups represent the same crash-consistent
point in time.
<ol class="arabic">
<li>For each drive, create an empty image:
<div class="code bash highlight-default notranslate"><div class="highlight"><pre>$ qemu-img create -f qcow2 drive0.full.qcow2 64G
$ qemu-img create -f qcow2 drive1.full.qcow2 64G
</pre></div>
</div>
</li>
<li>Add target block nodes:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-add&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target0&quot;,
 &quot;driver&quot;: &quot;qcow2&quot;,
 &quot;file&quot;: {
 &quot;driver&quot;: &quot;file&quot;,
 &quot;filename&quot;: &quot;drive0.full.qcow2&quot;
 }
 }
 }

&lt;- { &quot;return&quot;: {} }

-&gt; {
 &quot;execute&quot;: &quot;blockdev-add&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target1&quot;,
 &quot;driver&quot;: &quot;qcow2&quot;,
 &quot;file&quot;: {
 &quot;driver&quot;: &quot;file&quot;,
 &quot;filename&quot;: &quot;drive1.full.qcow2&quot;
 }
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Create a full (anchor) backup for each drive, with accompanying bitmaps:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;transaction&quot;,
 &quot;arguments&quot;: {
 &quot;actions&quot;: [
 {
 &quot;type&quot;: &quot;block-dirty-bitmap-add&quot;,
 &quot;data&quot;: {
 &quot;node&quot;: &quot;drive0&quot;,
 &quot;name&quot;: &quot;bitmap0&quot;
 }
 },
 {
 &quot;type&quot;: &quot;block-dirty-bitmap-add&quot;,
 &quot;data&quot;: {
 &quot;node&quot;: &quot;drive1&quot;,
 &quot;name&quot;: &quot;bitmap0&quot;
 }
 },
 {
 &quot;type&quot;: &quot;blockdev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;target&quot;: &quot;target0&quot;,
 &quot;sync&quot;: &quot;full&quot;
 }
 },
 {
 &quot;type&quot;: &quot;blockdev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;target&quot;: &quot;target1&quot;,
 &quot;sync&quot;: &quot;full&quot;
 }
 }
 ]
 }
 }

&lt;- { &quot;return&quot;: {} }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 68719476736,
 &quot;offset&quot;: 68719476736
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 68719476736,
 &quot;offset&quot;: 68719476736
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }

...
</pre></div>
</div>
</li>
<li>Later, create new destination images for each of the incremental backups
that point to their respective full backups:
<div class="code bash highlight-default notranslate"><div class="highlight"><pre>$ qemu-img create -f qcow2 drive0.inc0.qcow2 \
 -b drive0.full.qcow2 -F qcow2
$ qemu-img create -f qcow2 drive1.inc0.qcow2 \
 -b drive1.full.qcow2 -F qcow2
</pre></div>
</div>
</li>
<li>Add target block nodes:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-add&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target0&quot;,
 &quot;driver&quot;: &quot;qcow2&quot;,
 &quot;file&quot;: {
 &quot;driver&quot;: &quot;file&quot;,
 &quot;filename&quot;: &quot;drive0.inc0.qcow2&quot;
 }
 }
 }

&lt;- { &quot;return&quot;: {} }

-&gt; {
 &quot;execute&quot;: &quot;blockdev-add&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target1&quot;,
 &quot;driver&quot;: &quot;qcow2&quot;,
 &quot;file&quot;: {
 &quot;driver&quot;: &quot;file&quot;,
 &quot;filename&quot;: &quot;drive1.inc0.qcow2&quot;
 }
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Issue a multi-drive incremental push backup transaction:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;transaction&quot;,
 &quot;arguments&quot;: {
 &quot;actions&quot;: [
 {
 &quot;type&quot;: &quot;blockev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;,
 &quot;target&quot;: &quot;target0&quot;
 }
 },
 {
 &quot;type&quot;: &quot;blockdev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;,
 &quot;target&quot;: &quot;target1&quot;
 }
 },
 ]
 }
 }

&lt;- { &quot;return&quot;: {} }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 68719476736,
 &quot;offset&quot;: 68719476736
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 68719476736,
 &quot;offset&quot;: 68719476736
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }

...
</pre></div>
</div>
</li>
</ol>
</div>
</div>
<div class="section" id="push-backup-errors-recovery">
<h2><a class="toc-backref" href="#id28">Push Backup Errors &amp; Recovery</a><a class="headerlink" href="#push-backup-errors-recovery" title="Permalink to this headline">¶</a></h2>
In the event of an error that occurs after a push backup job is successfully
launched, either by an individual QMP command or a QMP transaction, the user
will receive a <code class="docutils literal notranslate">BLOCK_JOB_COMPLETE</code> event with a failure message,
accompanied by a <code class="docutils literal notranslate">BLOCK_JOB_ERROR</code> event.
In the case of a job being cancelled, the user will receive a
<code class="docutils literal notranslate">BLOCK_JOB_CANCELLED</code> event instead of a pair of COMPLETE and ERROR
events.
In either failure case, the bitmap used for the failed operation is not
cleared. It will contain all of the dirty bits it did at the start of the
operation, plus any new bits that got marked during the operation.
Effectively, the “point in time” that a bitmap is recording differences
against is kept at the issuance of the last successful incremental backup,
instead of being moved forward to the start of this now-failed backup.
Once the underlying problem is addressed (e.g. more storage space is allocated
on the destination), the incremental backup command can be retried with the
same bitmap.
<div class="section" id="example-individual-failures">
<h3><a class="toc-backref" href="#id29">Example: Individual Failures</a><a class="headerlink" href="#example-individual-failures" title="Permalink to this headline">¶</a></h3>
Incremental Push Backup jobs that fail individually behave simply as
described above. This example demonstrates the single-job failure case:
<ol class="arabic">
<li>Create a target image:
<div class="code bash highlight-default notranslate"><div class="highlight"><pre>$ qemu-img create -f qcow2 drive0.inc0.qcow2 \
 -b drive0.full.qcow2 -F qcow2
</pre></div>
</div>
</li>
<li>Add target block node:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-add&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target0&quot;,
 &quot;driver&quot;: &quot;qcow2&quot;,
 &quot;file&quot;: {
 &quot;driver&quot;: &quot;file&quot;,
 &quot;filename&quot;: &quot;drive0.inc0.qcow2&quot;
 }
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Attempt to create an incremental backup via QMP:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-backup&quot;,
 &quot;arguments&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;target&quot;: &quot;target0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Receive a pair of events indicating failure:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;action&quot;: &quot;report&quot;,
 &quot;operation&quot;: &quot;write&quot;
 },
 &quot;event&quot;: &quot;BLOCK_JOB_ERROR&quot;
 }

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;speed&quot;: 0,
 &quot;offset&quot;: 0,
 &quot;len&quot;: 67108864,
 &quot;error&quot;: &quot;No space left on device&quot;,
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }
</pre></div>
</div>
</li>
<li>Remove target node:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-del&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target0&quot;,
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Delete the failed image, and re-create it.
<div class="code bash highlight-default notranslate"><div class="highlight"><pre>$ rm drive0.inc0.qcow2
$ qemu-img create -f qcow2 drive0.inc0.qcow2 \
 -b drive0.full.qcow2 -F qcow2
</pre></div>
</div>
</li>
<li>Add target block node:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-add&quot;,
 &quot;arguments&quot;: {
 &quot;node-name&quot;: &quot;target0&quot;,
 &quot;driver&quot;: &quot;qcow2&quot;,
 &quot;file&quot;: {
 &quot;driver&quot;: &quot;file&quot;,
 &quot;filename&quot;: &quot;drive0.inc0.qcow2&quot;
 }
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Retry the command after fixing the underlying problem, such as
freeing up space on the backup volume:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;blockdev-backup&quot;,
 &quot;arguments&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;target&quot;: &quot;target0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;
 }
 }

&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Receive confirmation that the job completed successfully:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 67108864,
 &quot;offset&quot;: 67108864
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }
</pre></div>
</div>
</li>
</ol>
</div>
<div class="section" id="example-partial-transactional-failures">
<h3><a class="toc-backref" href="#id30">Example: Partial Transactional Failures</a><a class="headerlink" href="#example-partial-transactional-failures" title="Permalink to this headline">¶</a></h3>
QMP commands like <a class="reference external" href="qemu-qmp-ref.html#index-blockdev_002dbackup">blockdev-backup</a>
conceptually only start a job, and so transactions containing these commands
may succeed even if the job it created later fails. This might have surprising
interactions with notions of how a “transaction” ought to behave.
This distinction means that on occasion, a transaction containing such job
launching commands may appear to succeed and return success, but later
individual jobs associated with the transaction may fail. It is possible that
a management application may have to deal with a partial backup failure after
a “successful” transaction.
If multiple backup jobs are specified in a single transaction, if one of those
jobs fails, it will not interact with the other backup jobs in any way by
default. The job(s) that succeeded will clear the dirty bitmap associated with
the operation, but the job(s) that failed will not. It is therefore not safe
to delete any incremental backups that were created successfully in this
scenario, even though others failed.
This example illustrates a transaction with two backup jobs, where one fails
and one succeeds:
<ol class="arabic">
<li>Issue the transaction to start a backup of both drives.
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;transaction&quot;,
 &quot;arguments&quot;: {
 &quot;actions&quot;: [
 {
 &quot;type&quot;: &quot;blockdev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;,
 &quot;target&quot;: &quot;target0&quot;
 }
 },
 {
 &quot;type&quot;: &quot;blockdev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;,
 &quot;target&quot;: &quot;target1&quot;
 }
 }]
 }
 }
</pre></div>
</div>
</li>
<li>Receive notice that the Transaction was accepted, and jobs were
launched:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Receive notice that the first job has completed:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 67108864,
 &quot;offset&quot;: 67108864
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }
</pre></div>
</div>
</li>
<li>Receive notice that the second job has failed:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;action&quot;: &quot;report&quot;,
 &quot;operation&quot;: &quot;read&quot;
 },
 &quot;event&quot;: &quot;BLOCK_JOB_ERROR&quot;
 }

...

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;speed&quot;: 0,
 &quot;offset&quot;: 0,
 &quot;len&quot;: 67108864,
 &quot;error&quot;: &quot;Input/output error&quot;,
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;type&quot;: &quot;backup&quot;
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }
</pre></div>
</div>
</li>
</ol>
At the conclusion of the above example, <code class="docutils literal notranslate">drive0.inc0.qcow2</code> is valid and
must be kept, but <code class="docutils literal notranslate">drive1.inc0.qcow2</code> is incomplete and should be
deleted. If a VM-wide incremental backup of all drives at a point-in-time is
to be made, new backups for both drives will need to be made, taking into
account that a new incremental backup for drive0 needs to be based on top of
<code class="docutils literal notranslate">drive0.inc0.qcow2</code>.
For this example, an incremental backup for <code class="docutils literal notranslate">drive0</code> was created, but not
for <code class="docutils literal notranslate">drive1</code>. The last VM-wide crash-consistent backup that is available in
this case is the full backup:
<div class="code text highlight-default notranslate"><div class="highlight"><pre>[drive0.full.qcow2] &lt;-- [drive0.inc0.qcow2]
[drive1.full.qcow2]
</pre></div>
</div>
To repair this, issue a new incremental backup across both drives. The result
will be backup chains that resemble the following:
<div class="code text highlight-default notranslate"><div class="highlight"><pre>[drive0.full.qcow2] &lt;-- [drive0.inc0.qcow2] &lt;-- [drive0.inc1.qcow2]
[drive1.full.qcow2] &lt;-------------------------- [drive1.inc1.qcow2]
</pre></div>
</div>
</div>
<div class="section" id="example-grouped-completion-mode">
<h3><a class="toc-backref" href="#id31">Example: Grouped Completion Mode</a><a class="headerlink" href="#example-grouped-completion-mode" title="Permalink to this headline">¶</a></h3>
While jobs launched by transactions normally complete or fail individually,
it’s possible to instruct them to complete or fail together as a group. QMP
transactions take an optional properties structure that can affect the
behavior of the transaction.
The <code class="docutils literal notranslate">completion-mode</code> transaction property can be either <code class="docutils literal notranslate">individual</code>
which is the default legacy behavior described above, or <code class="docutils literal notranslate">grouped</code>, detailed
below.
In <code class="docutils literal notranslate">grouped</code> completion mode, no jobs will report success until all jobs are
ready to report success. If any job fails, all other jobs will be cancelled.
Regardless of if a participating incremental backup job failed or was
cancelled, their associated bitmaps will all be held at their existing
points-in-time, as in individual failure cases.
Here’s the same multi-drive backup scenario from <a class="reference internal" href="#example-partial-transactional-failures">Example: Partial
Transactional Failures</a>, but with the <code class="docutils literal notranslate">grouped</code> completion-mode property
applied:
<ol class="arabic">
<li>Issue the multi-drive incremental backup transaction:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>-&gt; {
 &quot;execute&quot;: &quot;transaction&quot;,
 &quot;arguments&quot;: {
 &quot;properties&quot;: {
 &quot;completion-mode&quot;: &quot;grouped&quot;
 },
 &quot;actions&quot;: [
 {
 &quot;type&quot;: &quot;blockdev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;,
 &quot;target&quot;: &quot;target0&quot;
 }
 },
 {
 &quot;type&quot;: &quot;blockdev-backup&quot;,
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;bitmap&quot;: &quot;bitmap0&quot;,
 &quot;sync&quot;: &quot;incremental&quot;,
 &quot;target&quot;: &quot;target1&quot;
 }
 }]
 }
 }
</pre></div>
</div>
</li>
<li>Receive notice that the Transaction was accepted, and jobs were launched:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>&lt;- { &quot;return&quot;: {} }
</pre></div>
</div>
</li>
<li>Receive notification that the backup job for <code class="docutils literal notranslate">drive1</code> has failed:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;action&quot;: &quot;report&quot;,
 &quot;operation&quot;: &quot;read&quot;
 },
 &quot;event&quot;: &quot;BLOCK_JOB_ERROR&quot;
 }

&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;speed&quot;: 0,
 &quot;offset&quot;: 0,
 &quot;len&quot;: 67108864,
 &quot;error&quot;: &quot;Input/output error&quot;,
 &quot;device&quot;: &quot;drive1&quot;,
 &quot;type&quot;: &quot;backup&quot;
 },
 &quot;event&quot;: &quot;BLOCK_JOB_COMPLETED&quot;
 }
</pre></div>
</div>
</li>
<li>Receive notification that the job for <code class="docutils literal notranslate">drive0</code> has been cancelled:
<div class="highlight-QMP notranslate"><div class="highlight"><pre>&lt;- {
 &quot;timestamp&quot;: {...},
 &quot;data&quot;: {
 &quot;device&quot;: &quot;drive0&quot;,
 &quot;type&quot;: &quot;backup&quot;,
 &quot;speed&quot;: 0,
 &quot;len&quot;: 67108864,
 &quot;offset&quot;: 16777216
 },
 &quot;event&quot;: &quot;BLOCK_JOB_CANCELLED&quot;
 }
</pre></div>
</div>
</li>
</ol>
At the conclusion of this example, both jobs have been aborted due to a
failure. Both destination images should be deleted and are no longer of use.
The transaction as a whole can simply be re-issued at a later time.
<!--
The FreeBSD Documentation License

Redistribution and use in source (ReST) and 'compiled' forms (SGML, HTML,
PDF, PostScript, RTF and so forth) with or without modification, are
permitted provided that the following conditions are met:

Redistributions of source code (ReST) must retain the above copyright notice,
this list of conditions and the following disclaimer of this file unmodified.

Redistributions in compiled form (transformed to other DTDs, converted to
PDF, PostScript, RTF and other formats) must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.
--></div>
</div>
</div>

</div>
 
 </div>
 <footer>
 
 <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 
 <a href="dbus.html" class="btn btn-neutral float-right" title="D-Bus" accesskey="n" rel="next">Next </a>
 
 
 <a href="barrier.html" class="btn btn-neutral" title="Barrier client protocol" accesskey="p" rel="prev"> Previous</a>
 
 </div>

<hr/>

</div>
 Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

This documentation is for QEMU version 6.2.0.

<a href="../about/license.html">QEMU and this manual are released under the
GNU General Public License, version 2.</a>

</footer>

</div>
 </div>

</section>

</div>

</body>
</html>