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 `drive-backup
-<qemu-qmp-ref.html#index-drive_002dbackup>`_ and `blockdev-backup
-<qemu-qmp-ref.html#index-blockdev_002dbackup>`_ QMP commands to create both
+blocks out to a destination. We will be using the `blockdev-backup
+<qemu-qmp-ref.html#index-blockdev_002dbackup>`_ QMP command to create both
full and incremental backups.
-Both of these commands are jobs, which have their own QMP API for querying and
+The command is a background job, which has its own QMP API for querying and
management documented in `Background jobs
<qemu-qmp-ref.html#Background-jobs>`_.
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 `blockdev-add
+<qemu-qmp-ref.html#index-blockdev_002dadd>`_ or `blockdev-create
+<qemu-qmp-ref.html#index-blockdev_002dcreate>`_ command.
+
.. 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
}
},
{
- "type": "drive-backup",
+ "type": "blockdev-backup",
"data": {
"device": "drive0",
- "target": "/path/to/drive0.full.qcow2",
- "sync": "full",
- "format": "qcow2"
+ "target": "target0",
+ "sync": "full"
}
}
]
}
},
{
- "type": "drive-backup",
+ "type": "blockdev-backup",
"data": {
"device": "drive0",
- "target": "/path/to/drive0.new_full.qcow2",
- "sync": "full",
- "format": "qcow2"
+ "target": "target0",
+ "sync": "full"
}
}
]
$ qemu-img create -f qcow2 drive0.inc0.qcow2 \
-b drive0.full.qcow2 -F qcow2
+#. Add target block node:
+
+ .. code-block:: QMP
+
+ -> {
+ "execute": "blockdev-add",
+ "arguments": {
+ "node-name": "target0",
+ "driver": "qcow2",
+ "file": {
+ "driver": "file",
+ "filename": "drive0.inc0.qcow2"
+ }
+ }
+ }
+
+ <- { "return": {} }
+
#. Issue an incremental backup command:
.. code-block:: QMP
-> {
- "execute": "drive-backup",
+ "execute": "blockdev-backup",
"arguments": {
"device": "drive0",
"bitmap": "bitmap0",
- "target": "drive0.inc0.qcow2",
- "format": "qcow2",
- "sync": "incremental",
- "mode": "existing"
+ "target": "target0",
+ "sync": "incremental"
}
}
$ qemu-img create -f qcow2 drive0.inc1.qcow2 \
-b drive0.inc0.qcow2 -F qcow2
+#. Add target block node:
+
+ .. code-block:: QMP
+
+ -> {
+ "execute": "blockdev-add",
+ "arguments": {
+ "node-name": "target0",
+ "driver": "qcow2",
+ "file": {
+ "driver": "file",
+ "filename": "drive0.inc1.qcow2"
+ }
+ }
+ }
+
+ <- { "return": {} }
+
#. Issue a new incremental backup command. The only difference here is that we
have changed the target image below.
.. code-block:: QMP
-> {
- "execute": "drive-backup",
+ "execute": "blockdev-backup",
"arguments": {
"device": "drive0",
"bitmap": "bitmap0",
- "target": "drive0.inc1.qcow2",
- "format": "qcow2",
- "sync": "incremental",
- "mode": "existing"
+ "target": "target0",
+ "sync": "incremental"
}
}
file for you, but you lose control over format options like
compatibility and preallocation presets.
+#. Add target block node:
+
+ .. code-block:: QMP
+
+ -> {
+ "execute": "blockdev-add",
+ "arguments": {
+ "node-name": "target0",
+ "driver": "qcow2",
+ "file": {
+ "driver": "file",
+ "filename": "drive0.inc2.qcow2"
+ }
+ }
+ }
+
+ <- { "return": {} }
+
#. Issue a new incremental backup command. Apart from the new destination
image, there is no difference from the last two examples.
.. code-block:: QMP
-> {
- "execute": "drive-backup",
+ "execute": "blockdev-backup",
"arguments": {
"device": "drive0",
"bitmap": "bitmap0",
- "target": "drive0.inc2.qcow2",
- "format": "qcow2",
- "sync": "incremental",
- "mode": "existing"
+ "target": "target0",
+ "sync": "incremental"
}
}
$ qemu-img create -f qcow2 drive0.full.qcow2 64G
$ qemu-img create -f qcow2 drive1.full.qcow2 64G
+#. Add target block nodes:
+
+ .. code-block:: QMP
+
+ -> {
+ "execute": "blockdev-add",
+ "arguments": {
+ "node-name": "target0",
+ "driver": "qcow2",
+ "file": {
+ "driver": "file",
+ "filename": "drive0.full.qcow2"
+ }
+ }
+ }
+
+ <- { "return": {} }
+
+ -> {
+ "execute": "blockdev-add",
+ "arguments": {
+ "node-name": "target1",
+ "driver": "qcow2",
+ "file": {
+ "driver": "file",
+ "filename": "drive1.full.qcow2"
+ }
+ }
+ }
+
+ <- { "return": {} }
+
#. Create a full (anchor) backup for each drive, with accompanying bitmaps:
.. code-block:: QMP
}
},
{
- "type": "drive-backup",
+ "type": "blockdev-backup",
"data": {
"device": "drive0",
- "target": "/path/to/drive0.full.qcow2",
- "sync": "full",
- "format": "qcow2"
+ "target": "target0",
+ "sync": "full"
}
},
{
- "type": "drive-backup",
+ "type": "blockdev-backup",
"data": {
"device": "drive1",
- "target": "/path/to/drive1.full.qcow2",
- "sync": "full",
- "format": "qcow2"
+ "target": "target1",
+ "sync": "full"
}
}
]
$ qemu-img create -f qcow2 drive1.inc0.qcow2 \
-b drive1.full.qcow2 -F qcow2
+#. Add target block nodes:
+
+ .. code-block:: QMP
+
+ -> {
+ "execute": "blockdev-add",
+ "arguments": {
+ "node-name": "target0",
+ "driver": "qcow2",
+ "file": {
+ "driver": "file",
+ "filename": "drive0.inc0.qcow2"
+ }
+ }
+ }
+
+ <- { "return": {} }
+
+ -> {
+ "execute": "blockdev-add",
+ "arguments": {
+ "node-name": "target1",
+ "driver": "qcow2",
+ "file": {
+ "driver": "file",
+ "filename": "drive1.inc0.qcow2"
+ }
+ }
+ }
+
+ <- { "return": {} }
+
#. Issue a multi-drive incremental push backup transaction:
.. code-block:: QMP
"arguments": {
"actions": [
{
- "type": "drive-backup",
+ "type": "blockev-backup",
"data": {
"device": "drive0",
"bitmap": "bitmap0",
- "format": "qcow2",
- "mode": "existing",
"sync": "incremental",
- "target": "drive0.inc0.qcow2"
+ "target": "target0"
}
},
{
- "type": "drive-backup",
+ "type": "blockdev-backup",
"data": {
"device": "drive1",
"bitmap": "bitmap0",
- "format": "qcow2",
- "mode": "existing",
"sync": "incremental",
- "target": "drive1.inc0.qcow2"
+ "target": "target1"
}
},
]
$ qemu-img create -f qcow2 drive0.inc0.qcow2 \
-b drive0.full.qcow2 -F qcow2
+#. Add target block node:
+
+ .. code-block:: QMP
+
+ -> {
+ "execute": "blockdev-add",
+ "arguments": {
+ "node-name": "target0",
+ "driver": "qcow2",
+ "file": {
+ "driver": "file",
+ "filename": "drive0.inc0.qcow2"
+ }
+ }
+ }
+
+ <- { "return": {} }
+
#. Attempt to create an incremental backup via QMP:
.. code-block:: QMP
-> {
- "execute": "drive-backup",
+ "execute": "blockdev-backup",
"arguments": {
"device": "drive0",
"bitmap": "bitmap0",
- "target": "drive0.inc0.qcow2",
- "format": "qcow2",
- "sync": "incremental",
- "mode": "existing"
+ "target": "target0",
+ "sync": "incremental"
}
}
"event": "BLOCK_JOB_COMPLETED"
}
+#. Remove target node:
+
+ .. code-block:: QMP
+
+ -> {
+ "execute": "blockdev-del",
+ "arguments": {
+ "node-name": "target0",
+ }
+ }
+
+ <- { "return": {} }
+
#. Delete the failed image, and re-create it.
.. code:: bash
$ qemu-img create -f qcow2 drive0.inc0.qcow2 \
-b drive0.full.qcow2 -F qcow2
+#. Add target block node:
+
+ .. code-block:: QMP
+
+ -> {
+ "execute": "blockdev-add",
+ "arguments": {
+ "node-name": "target0",
+ "driver": "qcow2",
+ "file": {
+ "driver": "file",
+ "filename": "drive0.inc0.qcow2"
+ }
+ }
+ }
+
+ <- { "return": {} }
+
#. Retry the command after fixing the underlying problem, such as
freeing up space on the backup volume:
.. code-block:: QMP
-> {
- "execute": "drive-backup",
+ "execute": "blockdev-backup",
"arguments": {
"device": "drive0",
"bitmap": "bitmap0",
- "target": "drive0.inc0.qcow2",
- "format": "qcow2",
- "sync": "incremental",
- "mode": "existing"
+ "target": "target0",
+ "sync": "incremental"
}
}
Example: Partial Transactional Failures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-QMP commands like `drive-backup <qemu-qmp-ref.html#index-drive_002dbackup>`_
+QMP commands like `blockdev-backup
+<qemu-qmp-ref.html#index-blockdev_002dbackup>`_
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.
"arguments": {
"actions": [
{
- "type": "drive-backup",
+ "type": "blockdev-backup",
"data": {
"device": "drive0",
"bitmap": "bitmap0",
- "format": "qcow2",
- "mode": "existing",
"sync": "incremental",
- "target": "drive0.inc0.qcow2"
+ "target": "target0"
}
},
{
- "type": "drive-backup",
+ "type": "blockdev-backup",
"data": {
"device": "drive1",
"bitmap": "bitmap0",
- "format": "qcow2",
- "mode": "existing",
"sync": "incremental",
- "target": "drive1.inc0.qcow2"
+ "target": "target1"
}
}]
}
},
"actions": [
{
- "type": "drive-backup",
+ "type": "blockdev-backup",
"data": {
"device": "drive0",
"bitmap": "bitmap0",
- "format": "qcow2",
- "mode": "existing",
"sync": "incremental",
- "target": "drive0.inc0.qcow2"
+ "target": "target0"
}
},
{
- "type": "drive-backup",
+ "type": "blockdev-backup",
"data": {
"device": "drive1",
"bitmap": "bitmap0",
- "format": "qcow2",
- "mode": "existing",
"sync": "incremental",
- "target": "drive1.inc0.qcow2"
+ "target": "target1"
}
}]
}
(3) ``drive-mirror`` (and ``blockdev-mirror``): Synchronize a running
disk to another image.
-(4) ``drive-backup`` (and ``blockdev-backup``): Point-in-time (live) copy
- of a block device to a destination.
+(4) ``blockdev-backup`` (and the deprecated ``drive-backup``):
+ Point-in-time (live) copy of a block device to a destination.
.. _`Interacting with a QEMU instance`:
(3) ``none`` -- Synchronize only the new writes from this point on.
- .. note:: In the case of ``drive-backup`` (or ``blockdev-backup``),
- the behavior of ``none`` synchronization mode is different.
- Normally, a ``backup`` job consists of two parts: Anything
- that is overwritten by the guest is first copied out to
- the backup, and in the background the whole image is
- copied from start to end. With ``sync=none``, it's only
- the first part.
+ .. note:: In the case of ``blockdev-backup`` (or deprecated
+ ``drive-backup``), the behavior of ``none``
+ synchronization mode is different. Normally, a
+ ``backup`` job consists of two parts: Anything that is
+ overwritten by the guest is first copied out to the
+ backup, and in the background the whole image is copied
+ from start to end. With ``sync=none``, it's only the
+ first part.
(4) ``incremental`` -- Synchronize content that is described by the
dirty bitmap
}
-Live disk backup --- ``drive-backup`` and ``blockdev-backup``
--------------------------------------------------------------
+Live disk backup --- ``blockdev-backup`` and the deprecated``drive-backup``
+---------------------------------------------------------------------------
-The ``drive-backup`` (and its newer equivalent ``blockdev-backup``) allows
+The ``blockdev-backup`` (and the deprecated ``drive-backup``) allows
you to create a point-in-time snapshot.
-In this case, the point-in-time is when you *start* the ``drive-backup``
-(or its newer equivalent ``blockdev-backup``) command.
+In this case, the point-in-time is when you *start* the
+``blockdev-backup`` (or deprecated ``drive-backup``) command.
QMP invocation for ``drive-backup``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Note that ``drive-backup`` command is deprecated since QEMU 6.2 and
+will be removed in future.
+
Yet again, starting afresh with our example disk image chain::
[A] <-- [B] <-- [C] <-- [D]
completed, and no further action is required.
+Moving from the deprecated ``drive-backup`` to newer ``blockdev-backup``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``blockdev-backup`` differs from ``drive-backup`` in how you specify
+the backup target. With ``blockdev-backup`` you can't specify filename
+as a target. Instead you use ``node-name`` of existing block node,
+which you may add by ``blockdev-add`` or ``blockdev-create`` commands.
+Correspondingly, ``blockdev-backup`` doesn't have ``mode`` and
+``format`` arguments which don't apply to an existing block node. See
+following sections for details and examples.
+
+
Notes on ``blockdev-backup``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``blockdev-backup`` command is equivalent in functionality to
-``drive-backup``, except that it operates at node-level in a Block Driver
+The ``blockdev-backup`` command operates at node-level in a Block Driver
State (BDS) graph.
E.g. the sequence of actions to create a point-in-time backup