From 2256db09e8b86b58be3c86b1575d64d7a9f5d05c Mon Sep 17 00:00:00 2001
Message-Id: <2256db09e8b86b58be3c86b1575d64d7a9f5d05c@dist-git>
From: Peter Krempa <pkrempa@redhat.com>
Date: Fri, 28 Feb 2020 10:24:44 +0100
Subject: [PATCH] kbase: backing_chains: Clarify some aspects of image probing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
(cherry picked from commit d552b93448e253552c7e53a1240132c9763d2b24)

https://bugzilla.redhat.com/show_bug.cgi?id=1798148
Message-Id: <b44052c081a18bec62762ab2a7358abd0e914a3a.1582881363.git.pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
---
 docs/kbase/backing_chains.rst | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/docs/kbase/backing_chains.rst b/docs/kbase/backing_chains.rst
index 3b3f0583e5..12ed6253ac 100644
--- a/docs/kbase/backing_chains.rst
+++ b/docs/kbase/backing_chains.rst
@@ -46,14 +46,17 @@ 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.
 
+Any externally created image should always use the -F switch of ``qemu-img``
+to specify the format of the backing file to avoid probing.
+
 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.
+will refuse to use backing images of any image whose format was not specified
+explicitly in the XML or the overlay image itself.
 
 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
@@ -104,6 +107,8 @@ 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>``
 
+Any image specified explicitly will not be probed for backing file or format.
+
 
 Manual image creation
 =====================
@@ -113,6 +118,13 @@ 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.
 
+::
+
+  qemu-img -f qcow2 -F qcow2 -b /path/to/backing /path/to/overlay
+
+Note that if '/path/to/backing' is relative the path is considered relative to
+the location of '/path/to/overlay'.
+
 Troubleshooting
 ===============
 
-- 
2.25.1