External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-03-20 07:59:00 +00:00
Code

kbase: incrementalbackupinternals: Add secion on bitmap handling in shell

Browse Source 
Add a section that outlines usage of tools to handle bitmaps and
introduce terms corresponding to the output of qemu-img to be used in
further sections.

With this we can simplify the section about checking bitmap health as we
don't have to explain the qemu-img output but can refer to the newly
defined terms.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
This commit is contained in:
Peter Krempa 2020-06-24 11:26:29 +02:00
parent de56070c9d
commit a4e81e0c32
1 changed files with 40 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
docs/kbase/incrementalbackupinternals.rst
View File

@ -139,29 +139,17 @@ After taking a snapshot of the ``vda`` disk from the example above placed into
| | | | | | | |
+----------------+ +----------------+ +----------------+ +----------------+
Checking bitmap health Manipulating bitmaps in shell
---------------------- -----------------------------
QEMU optimizes disk writes by only updating the bitmaps in certain cases. This **NOTE:** Any of the examples expect that the full image chain isn't used by any
also can cause problems in cases when e.g. QEMU crashes. running VM at the time.
For a chain of corresponding bitmaps in a backing chain to be considered valid ``qemu-img info`` command reports information about dirty bitmaps in an image:
and eligible for use with ``virDomainBackupBegin`` it must conform to the
following rules:
1) Top image must contain the bitmap
2) If any of the backing images in the chain contain the bitmap too, all
contiguous images must have the bitmap (no gaps)
3) all of the above bitmaps must be marked as active
(``auto`` flag in ``qemu-img`` output, ``recording`` in qemu)
4) none of the above bitmaps can be inconsistent
(``in-use`` flag in ``qemu-img`` provided that it's not used on image which
is currently in use by a qemu instance, or ``inconsistent`` in qemu)
:: ::
# check that image has bitmaps $ qemu-img info -f qcow2 vda-1.qcow2
$ qemu-img info vda-1.qcow2
image: vda-1.qcow2 image: vda-1.qcow2
file format: qcow2 file format: qcow2
virtual size: 100 MiB (104857600 bytes) virtual size: 100 MiB (104857600 bytes)
@ -186,6 +174,40 @@ following rules:
refcount bits: 16 refcount bits: 16
corrupt: false corrupt: false
The ``flags`` have following meanings:
``auto`` - **recording**
The bitmap is automatically activated when the image is opened for writing
and thus it's actively recording writes.
``in-use`` - **inconsistent**
The bitmap was not properly saved when the qemu process was shut down last
time thus didn't consistently record all the changed sectors.
It's recommended to use ``--output=json`` parameter to work with a machine
readable output rather than trying to process the human readable output by
scripts. For processing JSON in shell the ``jq`` tool can be used.
Checking bitmap health
----------------------
QEMU optimizes disk writes by only updating the bitmaps in certain cases. This
also can cause problems in cases when e.g. QEMU crashes.
For a chain of corresponding bitmaps in a backing chain images to be considered
valid and eligible for use for an incremental backup with
``virDomainBackupBegin`` the bitmaps intended to be used must conform to the
following rules:
1) active/topmost image must contain the bitmap
2) if a bitmap with the same name is contained in one of the backing images it
must be a contiguous subchain starting from the topmost image which contains
the bitmaps (no gaps)
3) all of the above bitmaps must be marked as **recording**
4) all of the above bitmaps must not be **inconsistent**
(See also the ``qemuBlockBitmapChainIsValid`` helper method in (See also the ``qemuBlockBitmapChainIsValid`` helper method in
``src/qemu/qemu_block.c``) ``src/qemu/qemu_block.c``)