Re: [PATCH 3/6] kbase: incrementalbackupinternals: Add secion on bitmap handling in shell

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(a)redhat.com&gt; --- docs/kbase/incrementalbackupinternals.rst | 58 ++++++++++++++++------- 1 file changed, 40 insertions(+), 18 deletions(-)

@@ -186,6 +174,40 @@ following rules: refcount bits: 16 corrupt: false +The ``flags`` have following meanings: + +``auto`` - **recording** + + The bitmap is automatically activated when the image is opened for wrinting

+ 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 conistently record all the changed sectors.

+ +It's reccomended 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 bitmap with the same name is contained in one of the backing images it

+ must be a contiguougs 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 ``src/qemu/qemu_block.c``)