Re: [libvirt PATCH v2] manpages/virsh: A couple of small clarifications

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(a)redhat.com&gt; --- - 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