[libvirt] [PATCHv2 1/2] doc: Document that snapshot name of block-backed disk isnt 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 --- docs/formatsnapshot.html.in | 8 +++++--- tools/virsh.pod | 4 +++- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in index 1f9a6c6..4f7b7b2 100644 --- 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 a5e8406..5da71c3 100644 --- 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. -- 2.0.0