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

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; ---

+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. +

+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``.