doc: Document that snapshot name of block-backed disk isn't autogenerated

Libvirt generates external snapshot target file names for file backed
storage but not for block backed storage. Document the limitation.

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=1032363

diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in
index 1f9a6c68cf04d7ec63bd4a0a50181ddf9a781c21..4f7b7b244549d9f211e5b0f50cdd2824bc133066 100644 (file)
--- a/docs/formatsnapshot.html.in
+++ b/docs/formatsnapshot.html.in
@@ -164,9 +164,11 @@
             attribute <code>type</code> giving the driver type (such
             as qcow2), of the new file created by the external
             snapshot of the new file.  If <code>source</code> is not
-            given, a file name is generated that consists of the
-            existing file name with anything after the trailing dot
-            replaced by the snapshot name.  Remember that with external
+            given and the disk is backed by a local image file (not
+            a block device or remote storage), a file name is
+            generated that consists of the existing file name
+            with anything after the trailing dot replaced by the
+            snapshot name.  Remember that with external
             snapshots, the original file name becomes the read-only
             snapshot, and the new file name contains the read-write
             delta of all disk changes since the snapshot.

diff --git a/tools/virsh.pod b/tools/virsh.pod
index a5e8406e125c64fe776cf8b403946eac844d97ac..5da71c3f34d34510dcd35caaaa227d0ac9434522 100644 (file)
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -3219,7 +3219,9 @@ The I<--diskspec> option can be used to control how I<--disk-only> and
 external checkpoints create external files.  This option can occur
 multiple times, according to the number of <disk> elements in the domain
 xml.  Each <diskspec> is in the
-form B<disk[,snapshot=type][,driver=type][,file=name]>.  To include a
+form B<disk[,snapshot=type][,driver=type][,file=name]>.  A I<diskspec>
+must be provided for disks backed by block devices as libvirt doesn't
+auto-generate file names for those.  To include a
 literal comma in B<disk> or in B<file=name>, escape it with a second
 comma.  A literal I<--diskspec> must precede each B<diskspec> unless
 all three of I<domain>, I<name>, and I<description> are also present.