Explanation of how disk backing chain specification impacts libvirt's
+ behaviour and basic troubleshooting steps of disk problems.
diff --git a/docs/kbase/backing_chains.rst b/docs/kbase/backing_chains.rst
new file mode 100644
index 0000000000..3b3f0583e5
--- /dev/null
+++ b/docs/kbase/backing_chains.rst
@@ -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 ```` elements in the configuration.
+
+The ```` 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.
+
+::
+
+
+
+
+
+
+
+
+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:
+
+::
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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 ```` 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
+````
+
+
+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``.