lib: snapshot: Explain that only one layer of images is inserted

When creating a snapshot with _REUSE_EXTERNAL when the pre-created image
does not directly link to the current active layer libvirt would
re-detect the backing chain incorrectly and it would not match with
qemu's view. Since the configuration is an operator mistake, document
that only the top layer image gets inserted.

diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c
index ac858ba8bf1cbf29a853d9906c04cfd12eb05af3..55826fd813728755131955447c37a55ed3ff3238 100644 (file)
--- a/src/libvirt-domain-snapshot.c
+++ b/src/libvirt-domain-snapshot.c
@@ -177,8 +177,9 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
  * the correct image format and metadata including backing store path
  * (this allows a management app to pre-create files with relative backing
  * file names, rather than the default of creating with absolute backing
- * file names). Note that setting incorrect metadata in the pre-created
- * image may lead to the VM being unable to start.
+ * file names). Note that only the file specified in the snapshot XML is
+ * inserted as a snapshot thus setting incorrect metadata in the pre-created
+ * image may lead to the VM being unable to start or other block jobs may fail.
  *
  * Be aware that although libvirt prefers to report errors up front with
  * no other effect, some hypervisors have certain types of failures where