Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
docs/kbase.html.in | 4 +
docs/kbase/backing_chains.rst | 185 ++++++++++++++++++++++++++++++++++
2 files changed, 189 insertions(+)
create mode 100644 docs/kbase/backing_chains.rst
diff --git a/docs/kbase.html.in b/docs/kbase.html.in
index a5504a540f..c156414c41 100644
--- a/docs/kbase.html.in
+++ b/docs/kbase.html.in
@@ -25,6 +25,10 @@
<dt><a href="kbase/rpm-deployment.html">RPM deployment</a></dt>
<dd>Explanation of the different RPM packages and illustration of
which to pick for installation</dd>
+
+ <dt><a href="kbase/backing_chains.html">Backing chain management</a></dt>
+ <dd>Explanation of how disk backing chain specification impacts libvirt's
+ behaviour and basic troubleshooting steps of disk problems.</dd>
</dl>
</div>
diff --git a/docs/kbase/backing_chains.rst b/docs/kbase/backing_chains.rst
new file mode 100644
index 0000000000..ec8f1b33b8
--- /dev/null
+++ b/docs/kbase/backing_chains.rst
@@ -0,0 +1,185 @@
+=================
+Disk image chains
+=================
+
+Modern disk image formats allow users to create an overlay on top of an
+existing image which will be the target of the new guest writes. This allows us
+to do snapshots of the disk state of a VM efficiently. The following text
+describes how libvirt manages such image chains and some problems which can
+occur. Note that many of the cases mentioned below are currently only relevant
+for the qemu driver.
+
+.. contents::
+
+Domain XML image and chain specification
+========================================
+
+Disk image chains can be partially or fully configured in the domain XML. The
+basic approach is to use the ``<backingStore>`` elements in the configuration.
+
+The ``<backingStore>`` elements present in the live VM xml represent the actual
+topology that libvirt knows of.
+
+Basic disk setup
+----------------
+
+Any default configuration or example usually refers only to the top (active)
+image of the backing chain.
+
+::
+
+ <disk type='file' device='disk'>
+ <driver name='qemu' type='qcow2'/>
+ <source file='/tmp/pull4.qcow2'/>
+ <target dev='vda' bus='virtio'/>
+ <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
+ </disk>
+
+This configuration will prompt libvirt to detect the backing image of the source
+image and recursively do the same thing until the end of the chain.
+
+Importance of properly setup backing chain
+------------------------------------------
+
+The disk image locations are used by libvirt to properly setup the security
+system used on the host so that the hypervisor can access the files and possibly
+also directly to configure the hypervisor to use the appropriate images. Thus
+it's important to properly setup the formats and paths of the backing images.
+
+Image detection caveats
+-----------------------
+
+Detection of the backing chain requires libvirt to read and understand the
+``backing file`` field recorded in the image metadata and also being able to
+recurse and read the backing file. Due to security implications libvirt
+will not attempt to detect the format of the backing image if the image metadata
+don't contain it.
+
+Libvirt also may not support a network disk storage technology and thus may be
+unable to visit and detect backing chains on such storage. This may result in
+the backing chain present in the live XML to look incomplete or some operations
+not being possible. To prevent this it's possible to specify the image metadata
+explicitly in the XML.
+
+Advanced backing chain specifications
+-------------------------------------
+
+To specify the topology of disk images explicitly the following XML
+specification can be used:
+
+::
+
+ <disk type='file' device='disk'>
+ <driver name='qemu' type='qcow2'/>
+ <source file='/tmp/pull4.qcow2'/>
+ <backingStore type='file'>
+ <format type='qcow2'/>
+ <source file='/tmp/pull3.qcow2'/>
+ <backingStore type='file'>
+ <format type='qcow2'/>
+ <source file='/tmp/pull2.qcow2'/>
+ <backingStore type='file'>
+ <format type='qcow2'/>
+ <source file='/tmp/pull1.qcow2'/>
+ <backingStore type='file'>
+ <format type='qcow2'/>
+ <source file='/tmp/pull0.qcow2'/>
+ <backingStore/>
+ </backingStore>
+ </backingStore>
+ </backingStore>
+ </backingStore>
+ <target dev='vda' bus='virtio'/>
+ <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
+ </disk>
+
+This makes libvirt follow the settings as configured in the XML. Note that this
+is supported only when the https://libvirt.org/formatdomaincaps.html#featureBackingStoreInput
+capability is present.
+
+An empty ``<backingStore/>`` element signals the end of the chain. Using this
+will prevent libvirt or qemu from probing the backing chain.
+
+Note that it's also possible to partially specify the chain in the XML but omit
+the terminating element. This will result into probing from the last specified
+``<backingStore>``
+
+
+Manual image creation
+=====================
+
+When creating disk images manually outside of libvirt it's important to create
+them properly so that they work with libvirt as expected. The created disk
+images must contain the format of the backing image in the metadata. This
+means that the **-F** parameter of ``qemu-img`` must always be used.
+
+Troubleshooting
+===============
+
+Few common problems which occur when managing chains of disk images.
+
+VM refuses to start due to misconfigured backing store format
+-------------------------------------------------------------
+
+This problem happens on VMs where the backing chain was created manually outside
+of libvirt and can have multiple symptoms:
+
+- permission denied error reported on a backing image
+- ``format of backing image '%s' of image '%s' was not specified in the image metadata`` error reported
+- disk image looking corrupt inside the guest
+
+The cause of the above problem is that the image metadata does not record the
+format of the backing image along with the location of the image. When the
+format is not specified libvirt or qemu would have to do image format probing
+which is insecure to do as a mallicious guest could rewrite the header of the
+disk leading to access of host files. Libvirt thus does not try to assume
+the format of the backing image. The following command can be used to check if
+the image has backing image format specified:
+
+::
+
+ $ qemu-img info /tmp/copy4.qcow2
+ image: /tmp/copy4.qcow2
+ file format: qcow2
+ virtual size: 10 MiB (10485760 bytes)
+ disk size: 196 KiB
+ cluster_size: 65536
+ backing file: copy3.qcow2 (actual path: /tmp/copy3.qcow2)
+ backing file format: qcow2
+ Format specific information:
+ compat: 1.1
+ lazy refcounts: false
+ refcount bits: 16
+ corrupt: false
+
+If the ``backing file format:`` field is missing above the format was not
+specified properly. The image can be fixed by the following command:
+
+::
+
+ qemu-img rebase -f $IMAGE_FORMAT -F $BACKING_IMAGE_FORMAT -b $BACKING_IMAGE_PATH $IMAGE_PATH
+
+It is important to fill out ``$BACKING_IMAGE_FORMAT`` and ``$IMAGE_FORMAT``
+properly. ``$BACKING_IMAGE_PATH`` should be specified as a full absolute path.
+If relative referencing of the backing image is desired, the path must be
+relative to the location of image described by ``$IMAGE_PATH``.
+
+Missing images reported after after moving disk images into a different path
+----------------------------------------------------------------------------
+
+The path to the backing image which is recorded in the image metadata often
+contains a full path to the backing image. This is the default libvirt-created
+image configuration. When such images are moved to a different location the
+top image will no longer point to the correct image.
+
+To fix such issue you can either fully specify the image chain in the domain XML
+as pointed out above or the following ``qemu-img`` command can be used:
+
+::
+
+ qemu-img rebase -u -f $IMAGE_FORMAT -F $BACKING_IMAGE_FORMAT -b $BACKING_IMAGE_PATH $IMAGE_PATH
+
+It is important to fill out ``$BACKING_IMAGE_FORMAT`` and ``$IMAGE_FORMAT``
+properly. ``$BACKING_IMAGE_PATH`` should be specified as a full absolute path.
+If relative referencing of the backing image is desired, the path must be
+relative to the location of image described by ``$IMAGE_PATH``.
--
2.23.0
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list
