NuKVM/libvirt
3
0
Fork 0
mirror of https://github.com/libvirt/libvirt.git synced 2025-02-25 18:55:26 -06:00
Code Issues Packages Projects Releases Wiki Activity

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 * destination files already exist as a non-empty regular file, the
* snapshot is rejected to avoid losing contents of those files. * snapshot is rejected to avoid losing contents of those files.
* However, if @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT, * However, if @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT,
* then the destination files must already exist and contain content * then the destination files must be pre-created manually with
* identical to the source files (this allows a management app to * the correct image format and metadata including backing store path
* pre-create files with relative backing file names, rather than the * (this allows a management app to pre-create files with relative backing
* default of creating with absolute backing file names). * 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 * Be aware that although libvirt prefers to report errors up front with
* no other effect, some hypervisors have certain types of failures where * 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 * 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), * (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 * 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 and sufficient
* allows a management app to pre-create files with relative backing file * size to hold the copy. In case the VIR_DOMAIN_BLOCK_REBASE_SHALLOW flag
* names, rather than the default of absolute backing file names; as a * is used the pre-created file has to exhibit the same guest visible contents
* security precaution, you should generally only use reuse_ext with the * as the backing file of the original image. This allows a management app to
* shallow flag and a non-raw destination file). * 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 * 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 * 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. shares the backing chain.
If I<--reuse-external> is specified, then I<dest> must exist and have If I<--reuse-external> is specified, then I<dest> must exist and have
contents identical to the resulting backing file (that is, it must sufficient space to hold the copy. If I<--shallow> is used in
start with contents matching the backing file I<disk> if I<--shallow> conjunction with I<--reuse-external> then the pre-created image must have
is used, otherwise it must start empty); this option is typically used guest visible contents identical to guest visible contents of the backing
to set up a relative backing file name in the destination. 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 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 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 If I<--reuse-external> is specified, and the snapshot XML requests an
external snapshot with a destination of an existing file, then the 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. to avoid losing contents of the existing files.
If I<--quiesce> is specified, libvirt will try to use guest agent 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> If I<--reuse-external> is specified, and the domain XML or I<diskspec>
option requests an external snapshot with a destination of an existing option requests an external snapshot with a destination of an existing
file, then the destination must exist, and is reused; otherwise, a file, then the destination must exist and be pre-created with correct
snapshot is refused to avoid losing contents of the existing files. 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 If I<--quiesce> is specified, libvirt will try to use guest agent
to freeze and unfreeze domain's mounted file systems. However, to freeze and unfreeze domain's mounted file systems. However,