[PATCH 6/6] kbase: incrementalbackupinternals: Describe 'block commit'

Peter Krempa pkrempa at redhat.com
Wed Jun 24 14:07:53 UTC 2020

oVirt does merge images out of libvirt in some cases. Add docs outlining
how it's done from a high level.

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
 docs/kbase/incrementalbackupinternals.rst | 37 +++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/kbase/incrementalbackupinternals.rst b/docs/kbase/incrementalbackupinternals.rst
index 9a96ef6df3..e50bf52e89 100644
--- a/docs/kbase/incrementalbackupinternals.rst
+++ b/docs/kbase/incrementalbackupinternals.rst
@@ -245,3 +245,40 @@ the snapshot.

         create RECORDING bitmap named BITMAP in OVERLAY with GRANULARITY
+Commiting external snapshots manually
+``block commit`` refers to an operation where data from a subchain of the
+backing chain is merged down into the backing image of the subchain removing all
+images in the subchain .
+``COMMIT_TOP`` refers to the top of the subchain to merge into ``COMMIT_BASE``
+(which stays in the new chain).
+It's strongly advised to use ``virDomainBlockCommit`` API in libvirt directly if
+possible. Inactive VMs can be started with ``VIR_DOMAIN_START_PAUSED`` flag
+(``virsh start --paused``) to prevent OS from running.
+Otherwise the following pseudo-algorithm can be used:
+Note: A ``valid`` bitmap chain is a set of images containing bitmaps which
+conform to the rules about valid bitmaps mentioned above.
+    commit data from COMMIT_TOP to COMMIT_BASE
+    let BITMAPS = valid bitmap chains in COMMIT_TOP
+    for each BITMAP in BITMAPS
+        let GRANULARITY = granularity of BITMAP in ACTIVE
+        if BITMAP is not present in COMMIT_BASE:
+            create RECORDING bitmap named BITMAP in COMMIT_BASE with GRANULARITY
+        for each IMAGE between COMMIT_TOP(inclusive) and COMMIT_BASE(exclusive):
+            if BITMAP is not present in IMAGE:
+                break
+            merge BITMAP in IMAGE into BITMAP in COMMIT_BASE

More information about the libvir-list mailing list