mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-08 02:45:45 +00:00
kbase: Add document outlining backing chain XML config and troubleshooting
Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This commit is contained in:
Peter Krempa
parent
3615e8b39b
commit
5949ac0f59
@ -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>
|
||||
|
||||
|
||||
185
docs/kbase/backing_chains.rst
Normal file
185
docs/kbase/backing_chains.rst
Normal file
@ -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
|
||||
doesn't contain it.
|
||||
|
||||
Libvirt also might lack support for 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
|
||||
===============
|
||||
|
||||
A 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 malicious 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 a 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``.
|
||||
Loading…
Reference in New Issue
Block a user