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 | 23 ++++++++++++++--------- tools/virsh.pod | 17 ++++++++++------- 2 files changed, 24 insertions(+), 16 deletions(-) diff --git a/src/libvirt.c b/src/libvirt.c index 8684298..79bcdf1 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -18394,10 +18394,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 @@ -19864,11 +19866,14 @@ 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 - * 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 - * shallow flag and a non-raw destination file). + * which was pre-created with the correct format and metadata and sufficient + * size to hold the copy. In case the VIR_DOMAIN_BLOCK_REBASE_SHALLOW flag + * is used the pre-created file has to exhibit the same guest visible contents + * as the backing file of the original image. 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 shallow flag and a non-raw + * destination file. * * A copy job has two parts; in the first phase, the @bandwidth parameter * affects how fast the source is pulled into the destination, and the job diff --git a/tools/virsh.pod b/tools/virsh.pod index 5da71c3..1a2b01f 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -876,10 +876,11 @@ 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> -is used, otherwise it must start empty); this option is typically used -to set up a relative backing file name in the destination. +sufficient space to hold the copy. If I<--shallow> is used in +conjunction with I<--reuse-external> then the pre-created image must have +guest visible contents identical to guest visible contents of the backing +file of the original image. This may be used to modify the backing file +names on the destination. The format of the destination is determined by the first match in the following list: if I<--raw> is specified, it will be raw; if @@ -3172,7 +3173,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 @@ -3233,8 +3235,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