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

Eric Blake eblake at redhat.com
Tue Dec 17 19:17:22 UTC 2019


On 12/17/19 12:35 PM, Peter Krempa wrote:
> Signed-off-by: Peter Krempa <pkrempa at redhat.com>
> ---

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




More information about the libvir-list mailing list