[libvirt] [PATCH 4/4] kbase: Add document outlining backing chain XML config and troubleshooting

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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