[libvirt PATCH v2] manpages/virsh: A couple of small clarifications
Kashyap Chamarthy
kchamart at redhat.com
Mon Aug 24 14:40:59 UTC 2020
A gentle 'ping' :-)
On Tue, Aug 04, 2020 at 04:04:03PM +0200, Kashyap Chamarthy wrote:
> Changes:
>
> - Update the descriptions of --current & --config flags.
>
> For --config, the reason to rephrase "next boot" to "next start"
> is: "Next boot may still imply somebody selecting "reboot" in the
> guest OS and fully expecting the changes to be applied." (per Peter
> Krempa)
>
> For --current, existing documentation says:
>
> "If *--current* is specified, affect the current guest state."
>
> It's not entirely clear what states can "current" mean or imply. So
> rephrase it in context of the other two related flags --live and
> --config.
>
> - While at it, I also took the liberty to replace the few occurrences
> of "peristent domain[s]" with "persistent guest[s]"
>
> Fix all occurrences (i.e. as many as I could spot) of this.
>
> (Thanks: Dan Berrangé on IRC.)
>
> Signed-off-by: Kashyap Chamarthy <kchamart at redhat.com>
> ---
> - v2: Address Peter Krempa's feedback
> (https://www.redhat.com/archives/libvir-list/2020-July/msg01274.html)
> ---
> docs/manpages/virsh.rst | 163 +++++++++++++++++++++++-----------------
> 1 file changed, 95 insertions(+), 68 deletions(-)
>
> diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
> index 1a2cf09fb7..561b1f038e 100644
> --- a/docs/manpages/virsh.rst
> +++ b/docs/manpages/virsh.rst
> @@ -710,7 +710,7 @@ groups:
> Persistence
> ...........
>
> -Flag *--persistent* is used to include persistent domains in the returned
> +Flag *--persistent* is used to include persistent guests in the returned
> list. To include transient domains specify *--transient*.
>
> Existence of managed save image
> @@ -1089,8 +1089,9 @@ then the default value of 1 second will be displayed. Supplying a 0 will
> reset the value back to the default.
>
> If *--live* is specified, affect a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> When setting the disk io parameters both *--live* and *--config* flags may be
> given, but *--current* is exclusive. For querying only one of *--live*,
> *--config* or *--current* can be specified. If no flag is specified, behavior
> @@ -1151,8 +1152,9 @@ Only the devices listed in the string are modified;
> any existing per-device write_bytes_sec for other devices remain unchanged.
>
> If *--live* is specified, affect a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. If no flag is specified, behavior is different depending
> on hypervisor.
> @@ -1451,7 +1453,7 @@ Create a domain from an XML <file>. Optionally, *--validate* option can be
> passed to validate the format of the input XML file against an internal RNG
> schema (identical to using virt-xml-validate(1) tool). Domains created using
> this command are going to be either transient (temporary ones that will vanish
> -once destroyed) or existing persistent domains that will run with one-time use
> +once destroyed) or existing persistent guests that will run with one-time use
> configuration, leaving the persistent XML untouched (this can come handy during
> an automated testing of various configurations all based on the original XML).
> See the example below for usage demonstration.
> @@ -1490,7 +1492,7 @@ is only supported with container based virtualization.
> respectively:
>
> a. the domain is going to be transient
> - b. an existing persistent domain will run with a modified one-time
> + b. an existing persistent guest will run with a modified one-time
> configuration
>
> .. code-block::
> @@ -1985,8 +1987,9 @@ To clear inbound or outbound settings, use *--inbound* or *--outbound*
> respectfully with average value of zero.
>
> If *--live* is specified, affect a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. If no flag is specified, behavior is different depending
> on hypervisor.
> @@ -2088,8 +2091,10 @@ QEMU/KVM 1.5 to be running on the host.
> The *--live*, *--config*, and *--current* flags are only valid when using
> the *--period* option in order to set the collection period for the balloon
> driver. If *--live* is specified, only the running guest collection period
> -is affected. If *--config* is specified, affect the next boot of a persistent
> -guest. If *--current* is specified, affect the current guest state.
> +is affected. If *--config* is specified, affect the next start of a persistent
> +guest. If *--current* is specified, it is equivalent to either *--live*
> +or *--config*, depending on the current state of the guest.
> +
>
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. If no flag is specified, behavior is different depending
> @@ -2581,8 +2586,9 @@ CPUs.
> See ``vcpupin`` for *cpulist*.
>
> If *--live* is specified, affect a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given if *cpulist* is present,
> but *--current* is exclusive.
> If no flag is specified, behavior is different depending on hypervisor.
> @@ -2744,9 +2750,9 @@ If the *iothread_id* already exists, the command will fail. The
>
> If *--live* is specified, affect a running guest. If the guest is not
> running an error is returned.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified or *--live* and *--config* are not specified,
> -affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
>
>
> iothreaddel
> @@ -2765,9 +2771,10 @@ If the *iothread_id* does not exist an error will occur.
>
> If *--live* is specified, affect a running guest. If the guest is not
> running an error is returned.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified or *--live* and *--config* are not specified,
> -affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> +
>
>
> iothreadinfo
> @@ -2784,10 +2791,11 @@ the CPU Affinity for each IOThread.
>
> If *--live* is specified, get the IOThreads data from the running guest. If
> the guest is not running, an error is returned.
> -If *--config* is specified, get the IOThreads data from the next boot of
> +If *--config* is specified, get the IOThreads data from the next start of
> a persistent guest.
> If *--current* is specified or *--live* and *--config* are not specified,
> -then get the IOThread data based on the current guest state.
> +then get the IOThread data based on the current guest state, which can
> +either be live or offline.
>
>
> iothreadpin
> @@ -2812,9 +2820,9 @@ to all physical cpus, simply specify 'r' as a *cpulist*.
>
> If *--live* is specified, affect a running guest. If the guest is not running,
> an error is returned.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified or *--live* and *--config* are not specified,
> -affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given if *cpulist* is present,
> but *--current* is exclusive.
> If no flag is specified, behavior is different depending on hypervisor.
> @@ -2851,7 +2859,8 @@ next start, restore, etc.
> If *--live* is specified, affect a running guest. If the guest is not
> running an error is returned.
> If *--current* is specified or *--live* is not specified, then handle
> -as if *--live* was specified.
> +as if *--live* was specified. (Where "current" here means whatever the
> +present guest state is: live or offline.)
>
>
> managedsave
> @@ -2997,8 +3006,9 @@ than KiB, and requests that are not an even multiple will be rounded up.
> For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
>
> If *--live* is specified, affect a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. If no flag is specified, behavior is different depending
> on hypervisor.
> @@ -3160,7 +3170,7 @@ the destination to supply a larger set of changes to any host-specific
> portions of the domain XML, such as accounting for naming differences
> between source and destination in accessing underlying storage.
> If *--persistent* is enabled, *--persistent-xml* ``file`` can be used to
> -supply an alternative XML file which will be used as the persistent domain
> +supply an alternative XML file which will be used as the persistent guest
> definition on the destination host.
>
> *--timeout* ``seconds`` tells virsh to run a specified action when live
> @@ -3392,8 +3402,9 @@ Its syntax is a comma separated list, with '-' for ranges and '^' for
> excluding a node.
>
> If *--live* is specified, set scheduler information of a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
>
> For running guests in Linux hosts, the changes made in the domain's
> numa parameters does not imply that the guest memory will be moved to a
> @@ -3485,8 +3496,9 @@ separated by commas. Valid event names are as follows:
> the *--perf* flag.
>
> If *--live* is specified, affect a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. If no flag is specified, behavior is different depending
> on hypervisor.
> @@ -3714,8 +3726,9 @@ Xen (credit scheduler): weight, cap
> ESX (allocation scheduler): reservation, limit, shares
>
> If *--live* is specified, set scheduler information of a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
>
> ``Note``: The cpu_shares parameter has a valid value range of 0-262144; Negative
> values are wrapped to positive, and larger values are capped at the maximum.
> @@ -3956,8 +3969,9 @@ setmaxmem
>
> Change the maximum memory allocation limit for a guest domain.
> If *--live* is specified, affect a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. If no flag is specified, behavior is different depending
> on hypervisor.
> @@ -3987,8 +4001,9 @@ setmem
>
> Change the memory allocation for a guest domain.
> If *--live* is specified, perform a memory balloon of a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. If no flag is specified, behavior is different depending
> on hypervisor.
> @@ -4038,7 +4053,8 @@ specified together if supported by the hypervisor. If this command is run
> before the guest has finished booting, the guest may fail to process
> the change.
>
> -If *--current* is specified, affect the current guest state.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
>
> When no flags are given, the *--live*
> flag is assumed and the guest domain must be active. In this situation it
> @@ -4083,10 +4099,11 @@ Note that hypervisors may refuse to disable certain vcpus such as vcpu 0 or
> others.
>
> If *--live* is specified, affect a running domain.
> -If *--config* is specified, affect the next startup of a persistent domain.
> -If *--current* is specified, affect the current domain state. This is the
> -default. Both *--live* and *--config* flags may be given, but *--current* is
> -exclusive.
> +If *--config* is specified, affect the next startup of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest. This is the
> +default. Both *--live* and *--config* flags may be given, but
> +*--current* is exclusive.
>
>
> shutdown
> @@ -4262,7 +4279,7 @@ via the *--active* flag, rather than relating to the *--current* flag.
> *--maximum* requests information on the maximum cap of vcpus that a
> domain can add via ``setvcpus``, while *--active* shows the current
> usage; these two flags cannot both be specified. *--config*
> -requires a persistent domain and requests information regarding the next
> +requires a persistent guest and requests information regarding the next
> time the domain will be booted, *--live* requires a running domain and
> lists current values, and *--current* queries according to the current
> state of the domain (corresponding to *--live* if running, or
> @@ -4355,8 +4372,9 @@ separated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2') can
> also be allowed. The '-' denotes the range and the '^' denotes exclusive.
> For pinning the *vcpu* to all physical cpus specify 'r' as a *cpulist*.
> If *--live* is specified, affect a running guest.
> -If *--config* is specified, affect the next boot of a persistent guest.
> -If *--current* is specified, affect the current guest state.
> +If *--config* is specified, affect the next start of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given if *cpulist* is present,
> but *--current* is exclusive.
> If no flag is specified, behavior is different depending on hypervisor.
> @@ -4402,7 +4420,7 @@ file using a device definition element such as <disk> or <interface>
> as the top-level element. See the documentation at
> `https://libvirt.org/formatdomain.html#elementsDevices <https://libvirt.org/formatdomain.html#elementsDevices>`__ to learn about
> libvirt XML format for a device. If *--config* is specified the
> -command alters the persistent domain configuration with the device
> +command alters the persistent guest configuration with the device
> attach taking effect the next time libvirt starts the domain.
> For cdrom and floppy devices, this command only replaces the media
> within an existing device; consider using ``update-device`` for this
> @@ -4410,8 +4428,9 @@ usage. For passthrough host devices, see also ``nodedev-detach``,
> needed if the PCI device does not use managed mode.
>
> If *--live* is specified, affect a running domain.
> -If *--config* is specified, affect the next startup of a persistent domain.
> -If *--current* is specified, affect the current domain state.
> +If *--config* is specified, affect the next startup of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. When no flag is specified legacy API is used whose behavior depends
> on the hypervisor driver.
> @@ -4479,8 +4498,9 @@ If *--print-xml* is specified, then the XML of the disk that would be attached
> is printed instead.
>
> If *--live* is specified, affect a running domain.
> -If *--config* is specified, affect the next startup of a persistent domain.
> -If *--current* is specified, affect the current domain state.
> +If *--config* is specified, affect the next startup of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. When no flag is specified legacy API is used whose behavior depends
> on the hypervisor driver.
> @@ -4567,8 +4587,9 @@ If ``--print-xml`` is specified, then the XML of the interface that would be
> attached is printed instead.
>
> If ``--live`` is specified, affect a running domain.
> -If ``--config`` is specified, affect the next startup of a persistent domain.
> -If ``--current`` is specified, affect the current domain state.
> +If ``--config`` is specified, affect the next startup of a persistent guest.
> +If ``--current`` is specified, affect the current domain state, which
> +can either be live or offline.
> Both ``--live`` and ``--config`` flags may be given, but ``--current`` is
> exclusive. When no flag is specified legacy API is used whose behavior
> depends on the hypervisor driver.
> @@ -4614,8 +4635,9 @@ when the device is removed. Note that the event may arrive before the command
> returns.
>
> If *--live* is specified, affect a running domain.
> -If *--config* is specified, affect the next startup of a persistent domain.
> -If *--current* is specified, affect the current domain state.
> +If *--config* is specified, affect the next startup of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. When no flag is specified legacy API is used whose behavior depends
> on the hypervisor driver.
> @@ -4642,8 +4664,9 @@ removal of the device is notified asynchronously via libvirt events
> (see virsh event).
>
> If *--live* is specified, affect a running domain.
> -If *--config* is specified, affect the next startup of a persistent domain.
> -If *--current* is specified, affect the current domain state.
> +If *--config* is specified, affect the next startup of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive.
>
> @@ -4662,8 +4685,9 @@ Detach a disk device from a domain. The *target* is the device as seen
> from the domain.
>
> If *--live* is specified, affect a running domain.
> -If *--config* is specified, affect the next startup of a persistent domain.
> -If *--current* is specified, affect the current domain state.
> +If *--config* is specified, affect the next startup of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. When no flag is specified legacy API is used whose behavior depends
> on the hypervisor driver.
> @@ -4698,8 +4722,9 @@ Detach a network interface from a domain.
> present on the domain.
>
> If *--live* is specified, affect a running domain.
> -If *--config* is specified, affect the next startup of a persistent domain.
> -If *--current* is specified, affect the current domain state.
> +If *--config* is specified, affect the next startup of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. When no flag is specified legacy API is used whose behavior depends
> on the hypervisor driver.
> @@ -4731,8 +4756,9 @@ locked/mounted in the domain. See the documentation at
> libvirt XML format for a device.
>
> If *--live* is specified, affect a running domain.
> -If *--config* is specified, affect the next startup of a persistent domain.
> -If *--current* is specified, affect the current domain state.
> +If *--config* is specified, affect the next startup of a persistent guest.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. Not specifying any flag is the same as specifying *--current*.
>
> @@ -4776,7 +4802,7 @@ is used by default.
> The *--force* option can be used to force media changing.
> If *--live* is specified, alter live configuration of running guest.
> If *--config* is specified, alter persistent configuration, effect observed
> -on next boot.
> +on next startup of the guest.
> *--current* can be either or both of *live* and *config*, depends on
> the hypervisor's implementation.
> Both *--live* and *--config* flags may be given, but *--current* is
> @@ -5223,7 +5249,8 @@ instance of <ip> will get the modification.
>
> If *--live* is specified, affect a running network.
> If *--config* is specified, affect the next startup of a persistent network.
> -If *--current* is specified, affect the current network state.
> +If *--current* is specified, it is equivalent to either *--live* or
> +*--config*, depending on the current state of the guest.
> Both *--live* and *--config* flags may be given, but *--current* is
> exclusive. Not specifying any flag is the same as specifying *--current*.
>
> @@ -6717,7 +6744,7 @@ taken. This increases the size of the memory image of the external
> snapshot. This is currently supported only for full system external snapshots.
>
> Existence of snapshot metadata will prevent attempts to ``undefine``
> -a persistent domain. However, for transient domains, snapshot
> +a persistent guest. However, for transient domains, snapshot
> metadata is silently lost when the domain quits running (whether
> by command such as ``destroy`` or by internal guest action).
>
> @@ -6926,7 +6953,7 @@ Filtering options are not compatible with *--tree*.
>
> If *--metadata* is specified, the list will be filtered to just
> snapshots that involve libvirt metadata, and thus would prevent
> -``undefine`` of a persistent domain, or be lost on ``destroy`` of
> +``undefine`` of a persistent guest, or be lost on ``destroy`` of
> a transient domain. Likewise, if *--no-metadata* is specified,
> the list will be filtered to just snapshots that exist without
> the need for libvirt metadata.
> @@ -7087,7 +7114,7 @@ to freeze and unfreeze domain's mounted file systems. However,
> if domain has no guest agent, checkpoint creation will fail.
>
> Existence of checkpoint metadata will prevent attempts to ``undefine``
> -a persistent domain. However, for transient domains, checkpoint
> +a persistent guest. However, for transient domains, checkpoint
> metadata is silently lost when the domain quits running (whether
> by command such as ``destroy`` or by internal guest action).
>
> --
> 2.26.2
>
--
/kashyap
More information about the libvir-list
mailing list