[libvirt] [PATCH] doc: Be more specific about semantics of _REUSE_EXT flag

Snapshots and block-copy have a flag that forces qemu to re-use existing file. Our docs weren't exactly clear on what the existing file should contain for this to actually work. Re-word the docs a bit to state that the file needs to be pre-created in the desired format and the backing chain metadata needs to be set prior to handing it over to qemu. Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=1084360 --- src/libvirt.c | 12 +++++++----- tools/virsh.pod | 12 +++++++----- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/src/libvirt.c b/src/libvirt.c index b80b484..e7a6aca 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -18274,10 +18274,12 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) * destination files already exist as a non-empty regular file, the * snapshot is rejected to avoid losing contents of those files. * However, if @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT, - * then the destination files must already exist and contain content - * identical to the source files (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). + * then the destination files must be pre-created manually with + * 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. * * Be aware that although libvirt prefers to report errors up front with * no other effect, some hypervisors have certain types of failures where @@ -19731,7 +19733,7 @@ virDomainBlockPull(virDomainPtr dom, const char *disk, * by adding VIR_DOMAIN_BLOCK_REBASE_COPY_RAW to force the copy to be raw * (does not make sense with the shallow flag unless the source is also raw), * or by using VIR_DOMAIN_BLOCK_REBASE_REUSE_EXT to reuse an existing file - * with initial contents identical to the backing file of the source (this + * which was pre-created with the correct format and metadata (this * allows a management app to pre-create files with relative backing file * names, rather than the default of absolute backing file names; as a * security precaution, you should generally only use reuse_ext with the diff --git a/tools/virsh.pod b/tools/virsh.pod index 1b6f3c4..39fe423 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -875,8 +875,8 @@ flattens the entire chain; but if I<--shallow> is specified, the copy shares the backing chain. If I<--reuse-external> is specified, then I<dest> must exist and have -contents identical to the resulting backing file (that is, it must -start with contents matching the backing file I<disk> if I<--shallow> +metadata identical to the resulting backing file (that is, it must +start with metadata matching the backing file I<disk> if I<--shallow> is used, otherwise it must start empty); this option is typically used to set up a relative backing file name in the destination. @@ -3165,7 +3165,8 @@ metadata again). If I<--reuse-external> is specified, and the snapshot XML requests an external snapshot with a destination of an existing file, then the -destination must exist, and is reused; otherwise, a snapshot is refused +destination must exist and be pre-created with correct format and +metadata. The file is then reused; otherwise, a snapshot is refused to avoid losing contents of the existing files. If I<--quiesce> is specified, libvirt will try to use guest agent @@ -3224,8 +3225,9 @@ results in the following XML: If I<--reuse-external> is specified, and the domain XML or I<diskspec> option requests an external snapshot with a destination of an existing -file, then the destination must exist, and is reused; otherwise, a -snapshot is refused to avoid losing contents of the existing files. +file, then the destination must exist and be pre-created with correct +format and metadata. The file is then reused; otherwise, a snapshot +is refused to avoid losing contents of the existing files. If I<--quiesce> is specified, libvirt will try to use guest agent to freeze and unfreeze domain's mounted file systems. However, -- 2.0.0