libvirt/docs/kbase/backing_chains.rst

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.

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.