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@xxxxxxxxxx> > --- > - 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
