[libvirt] [PATCH] doc: Correct the default werror policy
<quote> @item werror=@var{action},rerror=@var{action} Specify which @var{action} to take on write and read errors. Valid actions are: "ignore" (ignore the error and try to continue), "stop" (pause QEMU), "report" (report the error to the guest), "enospc" (pause QEMU only if the host disk is full; report the error to the guest otherwise). The default setting is @option{werror=enospc} and @option{rerror=report}. @item readonly </quote> libvirt doesn't set any default value for "(r)error_policy", the original doc should mean QEMU sets "report" as the default value for "werror", but it's not true, QEMU uses "enospc" as the default. And it's better to document "(r)error_policy" are only supported by QEMU. --- docs/formatdomain.html.in | 20 +++++++++----------- 1 files changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index dc6b152..e98e709 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1011,19 +1011,17 @@ The optional <code>error_policy</code> attribute controls how the hypervisor will behave on a disk read or write error, possible values are "stop", "report", "ignore", and - "enospace".<span class="since">Since 0.8.0, "report" since - 0.9.7</span> The default setting of error_policy is "report". - There is also an - optional <code>rerror_policy</code> that controls behavior - for read errors only. <span class="since">Since - 0.9.7</span>. If no rerror_policy is given, error_policy - is used for both read and write errors. If rerror_policy - is given, it overrides the <code>error_policy</code> for - read errors. Also note that "enospace" is not a valid + "enospace".<span class="since">Since 0.8.0 (QEMU and KVM only), + "report" since 0.9.7</span>. QEMU sets error_policy as "enospc" + by default. There is also an optional <code>rerror_policy</code> + that controls behavior for read errors only. <span class="since"> + Since 0.9.7 (QEMU and KVM only)</span>. If no rerror_policy is + given, error_policy is used for both read and write errors. If + rerror_policy is given, it overrides the <code>error_policy</code> + for read errors. Also note that "enospace" is not a valid policy for read errors, so if <code>error_policy</code> is set to "enospace" and no <code>rerror_policy</code> is - given, the read error policy will be left at its default, - which is "report". + given, QEMU will set the read error policy as "report" by default. </li> <li> The optional <code>io</code> attribute controls specific -- 1.7.6
On 10/24/2011 07:46 AM, Osier Yang wrote:
<quote> @item werror=@var{action},rerror=@var{action} Specify which @var{action} to take on write and read errors. Valid actions are: "ignore" (ignore the error and try to continue), "stop" (pause QEMU), "report" (report the error to the guest), "enospc" (pause QEMU only if the host disk is full; report the error to the guest otherwise). The default setting is @option{werror=enospc} and @option{rerror=report}. @item readonly </quote>
libvirt doesn't set any default value for "(r)error_policy", the original doc should mean QEMU sets "report" as the default value for "werror", but it's not true, QEMU uses "enospc" as the default. And it's better to document "(r)error_policy" are only supported by QEMU. --- docs/formatdomain.html.in | 20 +++++++++----------- 1 files changed, 9 insertions(+), 11 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index dc6b152..e98e709 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1011,19 +1011,17 @@ The optional<code>error_policy</code> attribute controls how the hypervisor will behave on a disk read or write error, possible values are "stop", "report", "ignore", and - "enospace".<span class="since">Since 0.8.0, "report" since - 0.9.7</span> The default setting of error_policy is "report". - There is also an - optional<code>rerror_policy</code> that controls behavior - for read errors only.<span class="since">Since - 0.9.7</span>. If no rerror_policy is given, error_policy - is used for both read and write errors. If rerror_policy - is given, it overrides the<code>error_policy</code> for - read errors. Also note that "enospace" is not a valid
+ "enospace".<span class="since">Since 0.8.0 (QEMU and KVM only), + "report" since 0.9.7</span>. QEMU sets error_policy as "enospc" + by default.
This is definitely more correct than what's already there. My only issue is that the description mixes libvirt's name of the attribute "error_policy" with QEMU's value "enospc". Maybe instead it can just say that QEMU defaults to "werror=enospc,rerror=report" when neither error_policy nor rerror_policy are specified.
There is also an optional<code>rerror_policy</code> + that controls behavior for read errors only.<span class="since"> + Since 0.9.7 (QEMU and KVM only)</span>. If no rerror_policy is + given, error_policy is used for both read and write errors. If + rerror_policy is given, it overrides the<code>error_policy</code> + for read errors. Also note that "enospace" is not a valid policy for read errors, so if<code>error_policy</code> is set to "enospace" and no<code>rerror_policy</code> is - given, the read error policy will be left at its default, - which is "report". + given, QEMU will set the read error policy as "report" by default.
Maybe instead say '...the read error policy will be left at QEMU's default setting, which is "report"'
</li> <li> The optional<code>io</code> attribute controls specific
Other than that, ACK.
On 10/27/2011 01:08 AM, Laine Stump wrote:
On 10/24/2011 07:46 AM, Osier Yang wrote:
<quote> @item werror=@var{action},rerror=@var{action} Specify which @var{action} to take on write and read errors. Valid actions are: "ignore" (ignore the error and try to continue), "stop" (pause QEMU), "report" (report the error to the guest), "enospc" (pause QEMU only if the host disk is full; report the error to the guest otherwise). The default setting is @option{werror=enospc} and @option{rerror=report}. @item readonly </quote>
libvirt doesn't set any default value for "(r)error_policy", the original doc should mean QEMU sets "report" as the default value for "werror", but it's not true, QEMU uses "enospc" as the default. And it's better to document "(r)error_policy" are only supported by QEMU. --- docs/formatdomain.html.in | 20 +++++++++----------- 1 files changed, 9 insertions(+), 11 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index dc6b152..e98e709 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1011,19 +1011,17 @@ The optional<code>error_policy</code> attribute controls how the hypervisor will behave on a disk read or write error, possible values are "stop", "report", "ignore", and - "enospace".<span class="since">Since 0.8.0, "report" since - 0.9.7</span> The default setting of error_policy is "report". - There is also an - optional<code>rerror_policy</code> that controls behavior - for read errors only.<span class="since">Since - 0.9.7</span>. If no rerror_policy is given, error_policy - is used for both read and write errors. If rerror_policy - is given, it overrides the<code>error_policy</code> for - read errors. Also note that "enospace" is not a valid
+ "enospace".<span class="since">Since 0.8.0 (QEMU and KVM only), + "report" since 0.9.7</span>. QEMU sets error_policy as "enospc" + by default.
This is definitely more correct than what's already there. My only issue is that the description mixes libvirt's name of the attribute "error_policy" with QEMU's value "enospc". Maybe instead it can just say that QEMU defaults to "werror=enospc,rerror=report" when neither error_policy nor rerror_policy are specified.
Oh, you are right, it shouldn't mix them together. "rerror" is clarified later, so how about following (with your next suggestion) ? if no "error_policy" is given, the write error policy will be left at QEMU's default setting, which is "enospc".
There is also an optional<code>rerror_policy</code> + that controls behavior for read errors only.<span class="since"> + Since 0.9.7 (QEMU and KVM only)</span>. If no rerror_policy is + given, error_policy is used for both read and write errors. If + rerror_policy is given, it overrides the<code>error_policy</code> + for read errors. Also note that "enospace" is not a valid policy for read errors, so if<code>error_policy</code> is set to "enospace" and no<code>rerror_policy</code> is - given, the read error policy will be left at its default, - which is "report". + given, QEMU will set the read error policy as "report" by default.
Maybe instead say '...the read error policy will be left at QEMU's default setting, which is "report"'
This is better, :)
</li> <li> The optional<code>io</code> attribute controls specific
Other than that, ACK.
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On 10/30/2011 10:11 PM, Osier Yang wrote:
The optional<code>error_policy</code> attribute controls how the hypervisor will behave on a disk read or write error, possible values are "stop", "report", "ignore", and
+ "enospace".<span class="since">Since 0.8.0 (QEMU and KVM only), + "report" since 0.9.7</span>. QEMU sets error_policy as "enospc" + by default.
This is definitely more correct than what's already there. My only issue is that the description mixes libvirt's name of the attribute "error_policy" with QEMU's value "enospc". Maybe instead it can just say that QEMU defaults to "werror=enospc,rerror=report" when neither error_policy nor rerror_policy are specified.
Oh, you are right, it shouldn't mix them together.
"rerror" is clarified later, so how about following (with your next suggestion) ?
if no "error_policy" is given, the write error policy will be left at QEMU's default setting, which is "enospc".
We're still mixing things up. "enospc" is an internal detail of qemu, and should not be leaked in the docs; we should only be using the term "enospace" which is the XML we are documenting. How about: possible value are "stop", "report", "ignore", and "enospace" (since ...). If no "error_policy" is given, the write error policy is left at qemu's default of "enospace".
Other than that, ACK.
There's been enough churn (aka "bike-shedding") that it would probably be wise to send a v2 before pushing. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
participants (3)
-
Eric Blake -
Laine Stump -
Osier Yang