提交 6f04fb15 编写于 作者: P Peter Krempa

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
上级 500f80a5
...@@ -18394,10 +18394,12 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) ...@@ -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, ...@@ -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
......
...@@ -876,10 +876,11 @@ flattens the entire chain; but if I<--shallow> is specified, the copy ...@@ -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). ...@@ -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: ...@@ -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,
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册