External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-03-20 07:59:00 +00:00
Code

doc: Be more specific about semantics of _REUSE_EXT flag

Browse Source 
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
This commit is contained in:
Peter Krempa 2014-07-07 14:38:10 +02:00
parent 500f80a595
commit 6f04fb151b
2 changed files with 24 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
src/libvirt.c
View File

@ -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

17
tools/virsh.pod
View File

@ -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,