On 12/17/19 12:35 PM, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> ---
+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.
s/don't/doesn't/
+ +Libvirt also may not support a network disk storage technology and thus may be
s/also may not support/also might lack support for/
+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.
s/Few/A few/
+ +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
s/mallicious/malicious/
+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:
s/has/has a/
+ +:: + + $ 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
Adding -u can make this operation faster (blindly update the image metadata, rather than actually crawling the entire image to perform a data operation in the process). But I'm not sure whether we want to document that here.
+ +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 +
Odd to mention -u here but not above. Should we be consistent between the two examples?
+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``.
-- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
