[libvirt] [PATCH v2] doc: Fix doc for backingStore
I spent quite some time figuring that backingStore info isn't included in the dom xml, unless guest is up and running. Hopefully putting that in the doc should help. This patch adds that info to the doc. Signed-off-by: Deepak C Shetty <deepakcs@redhat.com> --- docs/formatdomain.html.in | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index ab51982..a41c2c6 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -2113,7 +2113,12 @@ and only used for output to describe the detected backing chains. <span class="since">Since 1.2.4</span>. An empty <code>backingStore</code> element means the sibling source is - self-contained and is not based on any backing store. The following + self-contained and is not based on any backing store. Note that + <code>backingStore</code> info is included in the output only when + the guest is up and running, otherwise it's not included. For accurate + <code>backingStore</code> info, when using external snapshot with the + destination of a existing file, the snapshot must be created with + backing file format specified in the metadata. The following attributes and sub-elements are supported in <code>backingStore</code>: <dl> -- 1.9.3
On 03/18/2015 07:48 AM, Deepak Shetty wrote:
I spent quite some time figuring that backingStore info isn't included in the dom xml, unless guest is up and running. Hopefully putting that in the doc should help.
This patch adds that info to the doc.
Signed-off-by: Deepak C Shetty <deepakcs@redhat.com> --- docs/formatdomain.html.in | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)
I hope you don't mind that I took liberty with your wording, and added myself as a second signoff. Here's the text that I committed: This element describes the backing store used by the disk specified by sibling <code>source</code> element. It is currently ignored on input and only used for output to describe the detected backing chains of running domains <span class="since">since 1.2.4</span> (although a future version of libvirt may start accepting chains on input, or output information for offline domains). An empty <code>backingStore</code> element means the sibling source is self-contained and is not based on any backing store. For backing chain information to be accurate, the backing format must be correctly specified in the metadata of each file of the chain (files created by libvirt satisfy this property, but using existing external files for snapshot or block copy operations requires the end user to pre-create the file correctly). The following attributes and sub-elements are supported in <code>backingStore</code>: -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
On Thu, Mar 19, 2015 at 2:45 AM, Eric Blake <eblake@redhat.com> wrote:
On 03/18/2015 07:48 AM, Deepak Shetty wrote:
I spent quite some time figuring that backingStore info isn't included in the dom xml, unless guest is up and running. Hopefully putting that in the doc should help.
This patch adds that info to the doc.
Signed-off-by: Deepak C Shetty <deepakcs@redhat.com> --- docs/formatdomain.html.in | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)
I hope you don't mind that I took liberty with your wording, and added myself as a second signoff. Here's the text that I committed:
This element describes the backing store used by the disk specified by sibling <code>source</code> element. It is currently ignored on input and only used for output to describe the detected backing chains of running domains <span class="since">since 1.2.4</span> (although a future version of libvirt may start accepting chains on input, or output information for offline domains). An empty <code>backingStore</code> element means the sibling source is self-contained and is not based on any backing store. For backing chain information to be accurate, the backing format must be correctly specified in the metadata of each file of the chain (files created by libvirt satisfy this property, but using existing external files for snapshot or block copy operations requires the end user to pre-create the file correctly). The following attributes and sub-elements are supported in <code>backingStore</code>:
Looks good, just that it would have been even better if the fact that one needs to specify -o backing_fmt=qcow2 when creating files manually was explicitly mentioned. I see it being mentioned in the commit, but users typically visit the doc not commit :) Anyways, as long as there is a hint, 'guess we should be fine Thanks for adding clarity and commiting thanx, deepak
-- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
participants (2)
-
Deepak Shetty -
Eric Blake