[libvirt] [PATCH] docs: clarify that virsh setvcpus and setmem only work on active domains
Addresses BZ # 622534: https://bugzilla.redhat.com/show_bug.cgi?id=622534 --- tools/virsh.pod | 28 ++++++++++++++++++---------- 1 files changed, 18 insertions(+), 10 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 0e03d68..b4c6ff7 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -568,13 +568,16 @@ XEN_CREDIT scheduler and are now I<DEPRECATED>. =item B<setmem> I<domain-id> B<kilobytes> -Change the current memory allocation in the guest domain. This should take -effect immediately. The memory limit is specified in -kilobytes. +Change the current memory allocation in an B<active> guest domain. This +should take effect immediately. The memory limit is specified in kilobytes. For Xen, you can only adjust the memory of a running domain if the domain is paravirtualized or running the PV balloon driver. +B<Note>, this command only works on active guest domains. To change the +number of virtual CPUs in a inactive guest domain, use the virsh B<edit> +command to update the XML <memory> element. + =item B<setmaxmem> I<domain-id> B<kilobytes> Change the maximum memory allocation limit in the guest domain. This should @@ -593,24 +596,29 @@ QEMU/KVM supports I<--hard-limit>, I<--soft-limit>, and I<--swap-hard-limit>. =item B<setvcpus> I<domain-id> I<count> optional I<--maximum> I<--config> I<--live> -Change the number of virtual CPUs active in the guest domain. Note that -I<count> may be limited by host, hypervisor or limit coming from the -original description of domain. +Change the number of virtual CPUs active in an B<active> guest domain. + +The I<count> value may be limited by host, hypervisor or limit coming from +the original description of the guest domain. For Xen, you can only adjust the virtual CPUs of a running domain if the domain is paravirtualized. If I<--config> is specified, the change will only affect the next boot of a domain. If I<--live> is specified, the domain must be -running, and the change takes place immediately. Both flags may be -specified, if supported by the hypervisor. If neither flag is given, -then I<--live> is implied and it is up to the hypervisor whether -I<--config> is also implied. +running, and the change takes place immediately. Both I<--config> and +I<--live> flags may be specified, if supported by the hypervisor. If +neither flag is given, then I<--live> is implied and it is up to the +hypervisor whether I<--config> is also implied. If I<--maximum> is specified, then you must use I<--config> and avoid I<--live>; this flag controls the maximum limit of vcpus that can be hot-plugged the next time the domain is booted. +B<Note>, this command only works on active guest domains. To change the +number of virtual CPUs in a inactive guest domain, use the virsh B<edit> +command to update the XML <vcpu> element. + =item B<shutdown> I<domain-id> Gracefully shuts down a domain. This coordinates with the domain OS -- 1.7.3.2
On 01/12/2011 02:24 PM, Justin Clift wrote:
Addresses BZ # 622534:
https://bugzilla.redhat.com/show_bug.cgi?id=622534 --- tools/virsh.pod | 28 ++++++++++++++++++---------- 1 files changed, 18 insertions(+), 10 deletions(-)
diff --git a/tools/virsh.pod b/tools/virsh.pod index 0e03d68..b4c6ff7 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -568,13 +568,16 @@ XEN_CREDIT scheduler and are now I<DEPRECATED>.
=item B<setmem> I<domain-id> B<kilobytes>
-Change the current memory allocation in the guest domain. This should take -effect immediately. The memory limit is specified in -kilobytes. +Change the current memory allocation in an B<active> guest domain. This +should take effect immediately. The memory limit is specified in kilobytes.
Do we need extra text talking about rounding and/or rejection if the hypervisor can't support a memory limit with that small of a granularity (for example, Matthias recently posted patches regarding esx only having megabyte granularity).
For Xen, you can only adjust the memory of a running domain if the domain is paravirtualized or running the PV balloon driver.
+B<Note>, this command only works on active guest domains. To change the +number of virtual CPUs in a inactive guest domain, use the virsh B<edit> +command to update the XML <memory> element.
Oops - don't you mean "change the memory allocation of an inactive" rather than "change the number of virtual CPUs in a inactive"?
@@ -593,24 +596,29 @@ QEMU/KVM supports I<--hard-limit>, I<--soft-limit>, and I<--swap-hard-limit>. =item B<setvcpus> I<domain-id> I<count> optional I<--maximum> I<--config> I<--live>
+B<Note>, this command only works on active guest domains. To change the +number of virtual CPUs in a inactive guest domain, use the virsh B<edit> +command to update the XML <vcpu> element.
When I did the setvcpus work, my intention was that the --config option was to allow changing vcpu allocation without requiring a running domain, insofar as things are implemented by the hypervisor. If we have cases where the behavior still doesn't match those intentions, we probably ought to fix the bugs, rather than documenting that this command is live-only. So I'm thinking this paragraph doesn't belong. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 13/01/2011, at 8:54 AM, Eric Blake wrote:
On 01/12/2011 02:24 PM, Justin Clift wrote:
Addresses BZ # 622534:
https://bugzilla.redhat.com/show_bug.cgi?id=622534 --- tools/virsh.pod | 28 ++++++++++++++++++---------- 1 files changed, 18 insertions(+), 10 deletions(-)
diff --git a/tools/virsh.pod b/tools/virsh.pod index 0e03d68..b4c6ff7 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -568,13 +568,16 @@ XEN_CREDIT scheduler and are now I<DEPRECATED>.
=item B<setmem> I<domain-id> B<kilobytes>
-Change the current memory allocation in the guest domain. This should take -effect immediately. The memory limit is specified in -kilobytes. +Change the current memory allocation in an B<active> guest domain. This +should take effect immediately. The memory limit is specified in kilobytes.
Do we need extra text talking about rounding and/or rejection if the hypervisor can't support a memory limit with that small of a granularity (for example, Matthias recently posted patches regarding esx only having megabyte granularity).
That's not a bad idea. I have no idea of the text to add about it though. Is it something you know, or should we ask Matthias, or ?
For Xen, you can only adjust the memory of a running domain if the domain is paravirtualized or running the PV balloon driver.
+B<Note>, this command only works on active guest domains. To change the +number of virtual CPUs in a inactive guest domain, use the virsh B<edit> +command to update the XML <memory> element.
Oops - don't you mean "change the memory allocation of an inactive" rather than "change the number of virtual CPUs in a inactive"?
Oh wow. I even read that more than once, and still mentally missed it. Will v2 it after we figure out the rounding/rejection you mention above. :)
@@ -593,24 +596,29 @@ QEMU/KVM supports I<--hard-limit>, I<--soft-limit>, and I<--swap-hard-limit>. =item B<setvcpus> I<domain-id> I<count> optional I<--maximum> I<--config> I<--live>
+B<Note>, this command only works on active guest domains. To change the +number of virtual CPUs in a inactive guest domain, use the virsh B<edit> +command to update the XML <vcpu> element.
When I did the setvcpus work, my intention was that the --config option was to allow changing vcpu allocation without requiring a running domain, insofar as things are implemented by the hypervisor. If we have cases where the behavior still doesn't match those intentions, we probably ought to fix the bugs, rather than documenting that this command is live-only. So I'm thinking this paragraph doesn't belong.
Ahhh. With the BZ, it's main intention is that people have tried running setvcpus on an inactive domain, and it barfs. I haven't actually tried the command to see if modern libvirt behaves this way.
On 13/01/2011, at 9:06 AM, Justin Clift wrote:
On 13/01/2011, at 8:54 AM, Eric Blake wrote:
On 01/12/2011 02:24 PM, Justin Clift wrote:
Addresses BZ # 622534:
https://bugzilla.redhat.com/show_bug.cgi?id=622534 --- tools/virsh.pod | 28 ++++++++++++++++++---------- 1 files changed, 18 insertions(+), 10 deletions(-)
diff --git a/tools/virsh.pod b/tools/virsh.pod index 0e03d68..b4c6ff7 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod
How's this for new virsh text for the setvcpus bit? setvcpus domain-id count optional --maximum --config --live Change the number of virtual CPUs active in a guest domain. By default, this command works on active guest domains. To change the settings for an inactive guest domain, use the --config flag. The count value may be limited by host, hypervisor, or a limit coming from the original description of the guest domain. For Xen, you can only adjust the virtual CPUs of a running domain if the domain is paravirtualized. If the --config flag is specified, the change is made to the stored XML configuration for the guest domain, and will only take effect when the guest domain is next started. If --live is specified, the domain must be active, and the change takes place immediately. Both the --config and --live flags may be specified together if supported by the hypervisor. When neither the --config nor --live flags are given, the --live flag is assumed and the guest domain must be active. In this situation it is up to the hypervisor whether the --config flag is also assumed, and therefore whether the XML configuration is adjusted to make the change persistent. The --maximum flag controls the maximum number of virtual cpus that can be hot-plugged the next time the domain is booted. As such, it must only be used with the --config flag, and not with the --live option. + Justin
On 01/13/2011 09:36 AM, Justin Clift wrote:
How's this for new virsh text for the setvcpus bit?
setvcpus domain-id count optional --maximum --config --live Change the number of virtual CPUs active in a guest domain. By default, this command works on active guest domains. To change the settings for an inactive guest domain, use the --config flag.
The count value may be limited by host, hypervisor, or a limit coming from the original description of the guest domain.
For Xen, you can only adjust the virtual CPUs of a running domain if the domain is paravirtualized.
Since both of these paragraphs talk about limitations on using the command, I could see merging them if you wanted, but that's up to you.
If the --config flag is specified, the change is made to the stored XML configuration for the guest domain, and will only take effect when the guest domain is next started.
If --live is specified, the domain must be active, and the change takes place immediately. Both the --config and --live flags may be specified together if supported by the hypervisor.
When neither the --config nor --live flags are given, the --live flag is assumed and the guest domain must be active. In this situation it is up to the hypervisor whether the --config flag is also assumed, and therefore whether the XML configuration is adjusted to make the change persistent.
The --maximum flag controls the maximum number of virtual cpus that can be hot-plugged the next time the domain is booted. As such, it must only be used with the --config flag, and not with the --live option.
That reads well to me. Thanks for persisting on this. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 13/01/2011, at 8:54 AM, Eric Blake wrote: <snip>
+B<Note>, this command only works on active guest domains. To change the +number of virtual CPUs in a inactive guest domain, use the virsh B<edit> +command to update the XML <vcpu> element.
When I did the setvcpus work, my intention was that the --config option was to allow changing vcpu allocation without requiring a running domain, insofar as things are implemented by the hypervisor. If we have cases where the behavior still doesn't match those intentions, we probably ought to fix the bugs, rather than documenting that this command is live-only. So I'm thinking this paragraph doesn't belong.
Think I've found a bug here. With an inactive domain "Fedora_14_x64", attempting without the --config option gives the expected error message: virsh # setvcpus Fedora_14_x64 4 error: Requested operation is not valid: domain is not running But trying other flags (such as --maximum) don't: virsh # setvcpus Fedora_14_x64 4 --maximum error: invalid argument in virDomainSetVcpusFlags Should that be giving the "domain is not running" error as well? Note, using the --config option with the --maximum option works: virsh # setvcpus Fedora_14_x64 4 --maximum --config So the "invalid argument" error seems bogus.
On Fri, Jan 14, 2011 at 03:12:13AM +1100, Justin Clift wrote:
On 13/01/2011, at 8:54 AM, Eric Blake wrote: <snip>
+B<Note>, this command only works on active guest domains. To change the +number of virtual CPUs in a inactive guest domain, use the virsh B<edit> +command to update the XML <vcpu> element.
When I did the setvcpus work, my intention was that the --config option was to allow changing vcpu allocation without requiring a running domain, insofar as things are implemented by the hypervisor. If we have cases where the behavior still doesn't match those intentions, we probably ought to fix the bugs, rather than documenting that this command is live-only. So I'm thinking this paragraph doesn't belong.
Think I've found a bug here. With an inactive domain "Fedora_14_x64", attempting without the --config option gives the expected error message:
virsh # setvcpus Fedora_14_x64 4 error: Requested operation is not valid: domain is not running
But trying other flags (such as --maximum) don't:
virsh # setvcpus Fedora_14_x64 4 --maximum error: invalid argument in virDomainSetVcpusFlags
Should that be giving the "domain is not running" error as well?
The 'invalid argument' error is because you can't mix 'MAXIMUM' and 'LIVE' flags together. virsh should have reported that error, before even trying to invoke virDomainSetVcpusFlags. Daniel
--- tools/virsh.c | 21 +++++++++++++++++++++ 1 files changed, 21 insertions(+), 0 deletions(-) diff --git a/tools/virsh.c b/tools/virsh.c index 018e363..f14144d 100644 --- a/tools/virsh.c +++ b/tools/virsh.c @@ -2765,11 +2765,32 @@ cmdSetvcpus(vshControl *ctl, const vshCmd *cmd) ret = FALSE; } } else { + /* If the --maximum flag was given, we need to ensure only the + --config flag is in effect as well */ + if (VIR_DOMAIN_VCPU_MAXIMUM & flags) { + vshDebug(ctl, 5, "--maximum flag was given\n"); + + /* If neither the --config nor --live flags were given, OR + if just the --live flag was given, we need to error out + warning the user that the --maximum flag can only be used + with the --config flag */ + if ((VIR_DOMAIN_VCPU_LIVE & flags) | + (VIR_DOMAIN_VCPU_MAXIMUM == flags)) { + + /* Warn the user about the invalid flag combination */ + vshError(ctl, _("--maximum must be used with --config only")); + ret = FALSE; + goto cleanup; + } + } + + /* Apply the virtual cpu changes */ if (virDomainSetVcpusFlags(dom, count, flags) < 0) { ret = FALSE; } } + cleanup: virDomainFree(dom); return ret; } -- 1.7.3.5
On 01/13/2011 10:42 AM, Justin Clift wrote:
--- tools/virsh.c | 21 +++++++++++++++++++++ 1 files changed, 21 insertions(+), 0 deletions(-)
diff --git a/tools/virsh.c b/tools/virsh.c index 018e363..f14144d 100644 --- a/tools/virsh.c +++ b/tools/virsh.c @@ -2765,11 +2765,32 @@ cmdSetvcpus(vshControl *ctl, const vshCmd *cmd) ret = FALSE; } } else { + /* If the --maximum flag was given, we need to ensure only the + --config flag is in effect as well */ + if (VIR_DOMAIN_VCPU_MAXIMUM & flags) { + vshDebug(ctl, 5, "--maximum flag was given\n"); + + /* If neither the --config nor --live flags were given, OR + if just the --live flag was given, we need to error out + warning the user that the --maximum flag can only be used + with the --config flag */ + if ((VIR_DOMAIN_VCPU_LIVE & flags) | + (VIR_DOMAIN_VCPU_MAXIMUM == flags)) {
Idiomatically, I would use || instead of | (although the result is the same in this case). Also, rather than checking flags, you can check the bool variables that fed flags. I'm squashing this in, then pushing. diff --git i/tools/virsh.c w/tools/virsh.c index 4c3d965..4f103ae 100644 --- i/tools/virsh.c +++ w/tools/virsh.c @@ -1,7 +1,7 @@ /* * virsh.c: a shell to exercise the libvirt API * - * Copyright (C) 2005, 2007-2010 Red Hat, Inc. + * Copyright (C) 2005, 2007-2011 Red Hat, Inc. * * See COPYING.LIB for the License of this software * @@ -2767,15 +2767,14 @@ cmdSetvcpus(vshControl *ctl, const vshCmd *cmd) } else { /* If the --maximum flag was given, we need to ensure only the --config flag is in effect as well */ - if (VIR_DOMAIN_VCPU_MAXIMUM & flags) { + if (maximum) { vshDebug(ctl, 5, "--maximum flag was given\n"); /* If neither the --config nor --live flags were given, OR if just the --live flag was given, we need to error out warning the user that the --maximum flag can only be used with the --config flag */ - if ((VIR_DOMAIN_VCPU_LIVE & flags) | - (VIR_DOMAIN_VCPU_MAXIMUM == flags)) { + if (live || !config) { /* Warn the user about the invalid flag combination */ vshError(ctl, _("--maximum must be used with --config only")); -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 14/01/2011, at 5:00 AM, Eric Blake wrote:
Idiomatically, I would use || instead of | (although the result is the same in this case).
Also, rather than checking flags, you can check the bool variables that fed flags. I'm squashing this in, then pushing.
Thanks Eric. :)
On 13/01/2011, at 8:54 AM, Eric Blake wrote:
On 01/12/2011 02:24 PM, Justin Clift wrote:
Addresses BZ # 622534:
https://bugzilla.redhat.com/show_bug.cgi?id=622534 --- tools/virsh.pod | 28 ++++++++++++++++++---------- 1 files changed, 18 insertions(+), 10 deletions(-) <snip> Do we need extra text talking about rounding and/or rejection if the hypervisor can't support a memory limit with that small of a granularity (for example, Matthias recently posted patches regarding esx only having megabyte granularity).
Hows this for the setmem virsh text? setmem domain-id new-allocation Immediately change the current memory allocation for an active guest domain. The new-allocation value is in kilobytes, and will be rejected if the hypervisor can't support the given memory allocation. For vSphere/ESX, the new-allocation value must be a multiple of megabytes (ie. 2048 for 2GB), otherwise the hypervisor will reject it. For Xen, you can only adjust the memory of a running domain if the domain is paravirtualized or running the PV balloon driver. Note, this command only works on active guest domains. To change the memory allocation for an inactive guest domain, use the virsh edit command to update the XML <memory> element.
On 01/13/2011 11:27 AM, Justin Clift wrote:
On 13/01/2011, at 8:54 AM, Eric Blake wrote:
On 01/12/2011 02:24 PM, Justin Clift wrote:
Addresses BZ # 622534:
https://bugzilla.redhat.com/show_bug.cgi?id=622534 --- tools/virsh.pod | 28 ++++++++++++++++++---------- 1 files changed, 18 insertions(+), 10 deletions(-) <snip> Do we need extra text talking about rounding and/or rejection if the hypervisor can't support a memory limit with that small of a granularity (for example, Matthias recently posted patches regarding esx only having megabyte granularity).
Hows this for the setmem virsh text?
setmem domain-id new-allocation Immediately change the current memory allocation for an active guest domain. The new-allocation value is in kilobytes, and will be rejected if the hypervisor can't support the given memory allocation.
For vSphere/ESX, the new-allocation value must be a multiple of megabytes (ie. 2048 for 2GB), otherwise the hypervisor will reject it.
Not quite. The virsh command always takes kB, but vSphere rejects the parameter unless the kB argument is evenly divisible by 1024 (that is, the kB argument happens to represent megabytes). Maybe more like: Some hypervisors require a larger granularity than kilobytes, and requests that are not an even multiple will either be rounded down or rejected. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 14/01/2011, at 5:30 AM, Eric Blake wrote:
Not quite. The virsh command always takes kB, but vSphere rejects the parameter unless the kB argument is evenly divisible by 1024 (that is, the kB argument happens to represent megabytes).
Maybe more like:
Some hypervisors require a larger granularity than kilobytes, and requests that are not an even multiple will either be rounded down or rejected.
Heh, nice text. Combining both of your above sounds even better though I reckon: setmem domain-id kilobytes Immediately change the current memory allocation for an active guest domain. Some hypervisors require a larger granularity than kilobytes, and requests that are not an even multiple will either be rounded down or rejected. For example, vSphere/ESX rejects the parameter unless the kB argument is evenly divisible by 1024 (that is, the kB argument happens to represent megabytes). For Xen, you can only adjust the memory of a running domain if the domain is paravirtualized or running the PV balloon driver. Note, this command only works on active guest domains. To change the memory allocation for an inactive guest domain, use the virsh edit command to update the XML <memory> element. Workable?
On 01/13/2011 11:39 AM, Justin Clift wrote:
setmem domain-id kilobytes Immediately change the current memory allocation for an active guest domain.
Some hypervisors require a larger granularity than kilobytes, and requests that are not an even multiple will either be rounded down or rejected. For example, vSphere/ESX rejects the parameter unless the kB argument is evenly divisible by 1024 (that is, the kB argument happens to represent megabytes).
For Xen, you can only adjust the memory of a running domain if the domain is paravirtualized or running the PV balloon driver.
Note, this command only works on active guest domains. To change the memory allocation for an inactive guest domain, use the virsh edit command to update the XML <memory> element.
Workable?
Sounds good to me. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
Addresses BZ # 622534: https://bugzilla.redhat.com/show_bug.cgi?id=622534 --- Pushed this, as the text has already been agreed on-list. tools/virsh.pod | 53 ++++++++++++++++++++++++++++++++++------------------- 1 files changed, 34 insertions(+), 19 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 0e03d68..1f15fef 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -568,12 +568,19 @@ XEN_CREDIT scheduler and are now I<DEPRECATED>. =item B<setmem> I<domain-id> B<kilobytes> -Change the current memory allocation in the guest domain. This should take -effect immediately. The memory limit is specified in -kilobytes. +Immediately change the current memory allocation for an active guest domain. + +Some hypervisors require a larger granularity than kilobytes, and requests +that are not an even multiple will either be rounded down or rejected. For +example, vSphere/ESX rejects the parameter unless the kB argument is evenly +divisible by 1024 (that is, the kB argument happens to represent megabytes). + +For Xen, you can only adjust the memory of a running domain if the domain is +paravirtualized or running the PV balloon driver. -For Xen, you can only adjust the memory of a running domain if the -domain is paravirtualized or running the PV balloon driver. +Note, this command only works on active guest domains. To change the memory +allocation for an inactive guest domain, use the virsh B<edit> command to +update the XML <memory> element. =item B<setmaxmem> I<domain-id> B<kilobytes> @@ -593,23 +600,31 @@ QEMU/KVM supports I<--hard-limit>, I<--soft-limit>, and I<--swap-hard-limit>. =item B<setvcpus> I<domain-id> I<count> optional I<--maximum> I<--config> I<--live> -Change the number of virtual CPUs active in the guest domain. Note that -I<count> may be limited by host, hypervisor or limit coming from the -original description of domain. +Change the number of virtual CPUs active in a guest domain. By default, +this command works on active guest domains. To change the settings for an +inactive guest domain, use the I<--config> flag. + +The I<count> value may be limited by host, hypervisor, or a limit coming +from the original description of the guest domain. For Xen, you can only +adjust the virtual CPUs of a running domain if the domain is paravirtualized. + +If the I<--config> flag is specified, the change is made to the stored XML +configuration for the guest domain, and will only take effect when the guest +domain is next started. -For Xen, you can only adjust the virtual CPUs of a running domain if -the domain is paravirtualized. +If I<--live> is specified, the guest domain must be active, and the change +takes place immediately. Both the I<--config> and I<--live> flags may be +specified together if supported by the hypervisor. -If I<--config> is specified, the change will only affect the next -boot of a domain. If I<--live> is specified, the domain must be -running, and the change takes place immediately. Both flags may be -specified, if supported by the hypervisor. If neither flag is given, -then I<--live> is implied and it is up to the hypervisor whether -I<--config> is also implied. +When neither the I<--config> nor I<--live> flags are given, the I<--live> +flag is assumed and the guest domain must be active. In this situation it +is up to the hypervisor whether the I<--config> flag is also assumed, and +therefore whether the XML configuration is adjusted to make the change +persistent. -If I<--maximum> is specified, then you must use I<--config> and -avoid I<--live>; this flag controls the maximum limit of vcpus that -can be hot-plugged the next time the domain is booted. +The I<--maximum> flag controls the maximum number of virtual cpus that can +be hot-plugged the next time the domain is booted. As such, it must only be +used with the I<--config> flag, and not with the I<--live> flag. =item B<shutdown> I<domain-id> -- 1.7.3.5
participants (3)
-
Daniel P. Berrange -
Eric Blake -
Justin Clift