From fa3eaba680f417ab560f60cef5fb57c11b8d61fa Mon Sep 17 00:00:00 2001 From: Jonathon Jongsma Date: Tue, 27 Aug 2019 15:35:56 -0500 Subject: [PATCH] virsh: alphabetize domain commands in man page It appears that all commands were originally fully in alphabetical order but as new commands were added, they were sometimes inserted out of order. Fix up all domain commands so that they're in alphabetical order again. Signed-off-by: Jonathon Jongsma Reviewed-by: Michal Privoznik --- tools/virsh.pod | 1543 +++++++++++++++++++++++------------------------ 1 file changed, 771 insertions(+), 772 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index d9b3290cb8..0dc3216bc2 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -713,6 +713,333 @@ Configure a domain to be automatically started at boot. The option I<--disable> disables autostarting. +=item B I I +[[I<--config>] [I<--live>] | [I<--current>]] +[[I] | [I] [I]] +[[I] | [I] [I]] +[[I] | [I] [I]] +[[I] | [I] [I]] +[[I] | +[I] [I]] +[[I] | +[I] [I]] +[I] [I] + +Set or query the block disk io parameters for a block device of I. +I specifies a unique target name () or source +file () for one of the disk devices attached to +I (see also B for listing these names). + +If no limit is specified, it will query current I/O limits setting. +Otherwise, alter the limits with these flags: +I<--total-bytes-sec> specifies total throughput limit as a scaled integer, the +default being bytes per second if no suffix is specified. +I<--read-bytes-sec> specifies read throughput limit as a scaled integer, the +default being bytes per second if no suffix is specified. +I<--write-bytes-sec> specifies write throughput limit as a scaled integer, the +default being bytes per second if no suffix is specified. +I<--total-iops-sec> specifies total I/O operations limit per second. +I<--read-iops-sec> specifies read I/O operations limit per second. +I<--write-iops-sec> specifies write I/O operations limit per second. +I<--total-bytes-sec-max> specifies maximum total throughput limit as a scaled +integer, the default being bytes per second if no suffix is specified +I<--read-bytes-sec-max> specifies maximum read throughput limit as a scaled +integer, the default being bytes per second if no suffix is specified. +I<--write-bytes-sec-max> specifies maximum write throughput limit as a scaled +integer, the default being bytes per second if no suffix is specified. +I<--total-iops-sec-max> specifies maximum total I/O operations limit per second. +I<--read-iops-sec-max> specifies maximum read I/O operations limit per second. +I<--write-iops-sec-max> specifies maximum write I/O operations limit per second. +I<--total-bytes-sec-max-length> specifies duration in seconds to allow maximum +total throughput limit. +I<--read-bytes-sec-max-length> specifies duration in seconds to allow maximum +read throughput limit. +I<--write-bytes-sec-max-length> specifies duration in seconds to allow maximum +write throughput limit. +I<--total-iops-sec-max-length> specifies duration in seconds to allow maximum +total I/O operations limit. +I<--read-iops-sec-max-length> specifies duration in seconds to allow maximum +read I/O operations limit. +I<--write-iops-sec-max-length> specifies duration in seconds to allow maximum +write I/O operations limit. +I<--size-iops-sec> specifies size I/O operations limit per second. +I<--group-name> specifies group name to share I/O quota between multiple drives. +For a qemu domain, if no name is provided, then the default is to have a single +group for each I. + +Older versions of virsh only accepted these options with underscore +instead of dash, as in I<--total_bytes_sec>. + +Bytes and iops values are independent, but setting only one value (such +as --read-bytes-sec) resets the other two in that category to unlimited. +An explicit 0 also clears any limit. A non-zero value for a given total +cannot be mixed with non-zero values for read or write. + +It is up to the hypervisor to determine how to handle the length values. +For the qemu hypervisor, if an I/O limit value or maximum value is set, +then the default value of 1 second will be displayed. Supplying a 0 will +reset the value back to the default. + +If I<--live> is specified, affect a running guest. +If I<--config> is specified, affect the next boot of a persistent guest. +If I<--current> is specified, affect the current guest state. +When setting the disk io parameters both I<--live> and I<--config> flags may be +given, but I<--current> is exclusive. For querying only one of I<--live>, +I<--config> or I<--current> can be specified. If no flag is specified, behavior +is different depending on hypervisor. + +=item B I [I<--weight> B] +[I<--device-weights> B] +[I<--device-read-iops-sec> B] +[I<--device-write-iops-sec> B] +[I<--device-read-bytes-sec> B] +[I<--device-write-bytes-sec> B] +[[I<--config>] [I<--live>] | [I<--current>]] + +Display or set the blkio parameters. QEMU/KVM supports I<--weight>. +I<--weight> is in range [100, 1000]. After kernel 2.6.39, the value +could be in the range [10, 1000]. + +B is a single string listing one or more device/weight +pairs, in the format of /path/to/device,weight,/path/to/device,weight. +Each weight is in the range [100, 1000], [10, 1000] after kernel 2.6.39, +or the value 0 to remove that device from per-device listings. +Only the devices listed in the string are modified; +any existing per-device weights for other devices remain unchanged. + +B is a single string listing one or more device/read_iops_sec +pairs, int the format of /path/to/device,read_iops_sec,/path/to/device,read_iops_sec. +Each read_iops_sec is a number which type is unsigned int, value 0 to remove that +device from per-device listing. +Only the devices listed in the string are modified; +any existing per-device read_iops_sec for other devices remain unchanged. + +B is a single string listing one or more device/write_iops_sec +pairs, int the format of /path/to/device,write_iops_sec,/path/to/device,write_iops_sec. +Each write_iops_sec is a number which type is unsigned int, value 0 to remove that +device from per-device listing. +Only the devices listed in the string are modified; +any existing per-device write_iops_sec for other devices remain unchanged. + +B is a single string listing one or more device/read_bytes_sec +pairs, int the format of /path/to/device,read_bytes_sec,/path/to/device,read_bytes_sec. +Each read_bytes_sec is a number which type is unsigned long long, value 0 to remove +that device from per-device listing. +Only the devices listed in the string are modified; +any existing per-device read_bytes_sec for other devices remain unchanged. + +B is a single string listing one or more device/write_bytes_sec +pairs, int the format of /path/to/device,write_bytes_sec,/path/to/device,write_bytes_sec. +Each write_bytes_sec is a number which type is unsigned long long, value 0 to remove +that device from per-device listing. +Only the devices listed in the string are modified; +any existing per-device write_bytes_sec for other devices remain unchanged. + +If I<--live> is specified, affect a running guest. +If I<--config> is specified, affect the next boot of a persistent guest. +If I<--current> is specified, affect the current guest state. +Both I<--live> and I<--config> flags may be given, but I<--current> is +exclusive. If no flag is specified, behavior is different depending +on hypervisor. + +=item B I I [I] [I<--bytes>] +[I] [I<--shallow>] [I] [I<--delete>] [I<--keep-relative>] +[I<--wait> [I<--async>] [I<--verbose>]] [I<--timeout> B] +[I<--active>] [{I<--pivot> | I<--keep-overlay>}] + +Reduce the length of a backing image chain, by committing changes at the +top of the chain (snapshot or delta files) into backing images. By +default, this command attempts to flatten the entire chain. If I +and/or I are specified as files within the backing chain, then the +operation is constrained to committing just that portion of the chain; +I<--shallow> can be used instead of I to specify the immediate +backing file of the resulting top image to be committed. The files +being committed are rendered invalid, possibly as soon as the operation +starts; using the I<--delete> flag will attempt to remove these invalidated +files at the successful completion of the commit operation. When the +I<--keep-relative> flag is used, the backing file paths will be kept relative. + +When I is omitted or specified as the active image, it is also +possible to specify I<--active> to trigger a two-phase active commit. In +the first phase, I is copied into I and the job can only be +canceled, with top still containing data not yet in base. In the second +phase, I and I remain identical until a call to B +with the I<--abort> flag (keeping top as the active image that tracks +changes from that point in time) or the I<--pivot> flag (making base +the new active image and invalidating top). + +By default, this command returns as soon as possible, and data for +the entire disk is committed in the background; the progress of the +operation can be checked with B. However, if I<--wait> is +specified, then this command will block until the operation completes +(or for I<--active>, enters the second phase), or until the operation +is canceled because the optional I in seconds elapses +or SIGINT is sent (usually with C). Using I<--verbose> along +with I<--wait> will produce periodic status updates. If job cancellation +is triggered, I<--async> will return control to the user as fast as +possible, otherwise the command may continue to block a little while +longer until the job is done cleaning up. Using I<--pivot> is shorthand +for combining I<--active> I<--wait> with an automatic B +I<--pivot>; and using I<--keep-overlay> is shorthand for combining +I<--active> I<--wait> with an automatic B I<--abort>. + +I specifies fully-qualified path of the disk; it corresponds +to a unique target name () or source file () for one of the disk devices attached to I (see +also B for listing these names). +I specifies copying bandwidth limit in MiB/s, although for +qemu, it may be non-zero only for an online domain. For further information +on the I argument see the corresponding section for the B +command. + +=item B I I { I [I] [I<--blockdev>] +| I<--xml> B } [I<--shallow>] [I<--reuse-external>] [I] +[I<--wait> [I<--async>] [I<--verbose>]] [{I<--pivot> | I<--finish>}] +[I<--timeout> B] [I] [I] [I<--bytes>] +[I<--transient-job>] + +Copy a disk backing image chain to a destination. Either I as +the destination file name, or I<--xml> with the name of an XML file containing +a top-level element describing the destination, must be present. +Additionally, if I is given, I should be specified to declare +the format of the destination (if I is omitted, then libvirt +will reuse the format of the source, or with I<--reuse-external> will +be forced to probe the destination format, which could be a potential +security hole). The command supports I<--raw> as a boolean flag synonym for +I<--format=raw>. When using I, the destination is treated as a regular +file unless I<--blockdev> is used to signal that it is a block device. By +default, this command flattens the entire chain; but if I<--shallow> is +specified, the copy shares the backing chain. + +If I<--reuse-external> is specified, then the destination must exist and have +sufficient space to hold the copy. If I<--shallow> is used in +conjunction with I<--reuse-external> then the pre-created image must have +guest visible contents identical to guest visible contents of the backing +file of the original image. This may be used to modify the backing file +names on the destination. + +By default, the copy job runs in the background, and consists of two +phases. Initially, the job must copy all data from the source, and +during this phase, the job can only be canceled to revert back to the +source disk, with no guarantees about the destination. After this phase +completes, both the source and the destination remain mirrored until a +call to B with the I<--abort> and I<--pivot> flags pivots over +to the copy, or a call without I<--pivot> leaves the destination as a +faithful copy of that point in time. However, if I<--wait> is specified, +then this command will block until the mirroring phase begins, or cancel +the operation if the optional I in seconds elapses or SIGINT is +sent (usually with C). Using I<--verbose> along with I<--wait> +will produce periodic status updates. Using I<--pivot> (similar to +B I<--pivot>) or I<--finish> (similar to B I<--abort>) +implies I<--wait>, and will additionally end the job cleanly rather than +leaving things in the mirroring phase. If job cancellation is triggered +by timeout or by I<--finish>, I<--async> will return control to the user +as fast as possible, otherwise the command may continue to block a little +while longer until the job has actually cancelled. + +I specifies fully-qualified path of the disk. +I specifies copying bandwidth limit in MiB/s. Specifying a negative +value is interpreted as an unsigned long long value that might be essentially +unlimited, but more likely would overflow; it is safer to use 0 for that +purpose. For further information on the I argument see the +corresponding section for the B command. +Specifying I allows fine-tuning of the granularity that will be +copied when a dirty region is detected; larger values trigger less +I/O overhead but may end up copying more data overall (the default value is +usually correct); hypervisors may restrict this to be a power of two or fall +within a certain range. Specifying I will control how much data can +be simultaneously in-flight during the copy; larger values use more memory but +may allow faster completion (the default value is usually correct). + +I<--transient-job> allows specifying that the user does not require the job to +be recovered if the VM crashes or is turned off before the job completes. This +flag removes the restriction of copy jobs to transient domains if that +restriction is applied by the hypervisor. + +=item B I I { [I<--abort>] [I<--async>] [I<--pivot>] | +[I<--info>] [I<--raw>] [I<--bytes>] | [I] } + +Manage active block operations. There are three mutually-exclusive modes: +I<--info>, I, and I<--abort>. I<--async> and I<--pivot> imply +abort mode; I<--raw> implies info mode; and if no mode was given, I<--info> +mode is assumed. + +I specifies fully-qualified path of the disk; it corresponds +to a unique target name () or source file () for one of the disk devices attached to I (see +also B for listing these names). + +In I<--abort> mode, the active job on the specified disk will +be aborted. If I<--async> is also specified, this command will return +immediately, rather than waiting for the cancellation to complete. If +I<--pivot> is specified, this requests that an active copy or active +commit job be pivoted over to the new image. + +In I<--info> mode, the active job information on the specified +disk will be printed. By default, the output is a single human-readable +summary line; this format may change in future versions. Adding +I<--raw> lists each field of the struct, in a stable format. If the +I<--bytes> flag is set, then the command errors out if the server could +not supply bytes/s resolution; when omitting the flag, raw output is +listed in MiB/s and human-readable output automatically selects the +best resolution supported by the server. + +I can be used to set bandwidth limit for the active job in MiB/s. +If I<--bytes> is specified then the bandwidth value is interpreted in +bytes/s. Specifying a negative value is interpreted as an unsigned long +value or essentially unlimited. The hypervisor can choose whether to +reject the value or convert it to the maximum value allowed. Optionally a +scaled positive number may be used as bandwidth (see B above). Using +I<--bytes> with a scaled value permits a finer granularity to be selected. +A scaled value used without I<--bytes> will be rounded down to MiB/s. Note +that the I<--bytes> may be unsupported by the hypervisor. + +=item B I I [I] [I<--bytes>] [I] +[I<--wait> [I<--verbose>] [I<--timeout> B] [I<--async>]] +[I<--keep-relative>] + +Populate a disk from its backing image chain. By default, this command +flattens the entire chain; but if I is specified, containing the +name of one of the backing files in the chain, then that file becomes +the new backing file and only the intermediate portion of the chain is +pulled. Once all requested data from the backing image chain has been +pulled, the disk no longer depends on that portion of the backing chain. + +By default, this command returns as soon as possible, and data for +the entire disk is pulled in the background; the progress of the +operation can be checked with B. However, if I<--wait> is +specified, then this command will block until the operation completes, +or cancel the operation if the optional I in seconds elapses +or SIGINT is sent (usually with C). Using I<--verbose> along +with I<--wait> will produce periodic status updates. If job cancellation +is triggered, I<--async> will return control to the user as fast as +possible, otherwise the command may continue to block a little while +longer until the job is done cleaning up. + +Using the I<--keep-relative> flag will keep the backing chain names +relative. + +I specifies fully-qualified path of the disk; it corresponds +to a unique target name () or source file () for one of the disk devices attached to I (see +also B for listing these names). +I specifies copying bandwidth limit in MiB/s. For further information +on the I argument see the corresponding section for the B +command. + +=item B I I I + +Resize a block device of domain while the domain is running, I +specifies the absolute path of the block device; it corresponds +to a unique target name () or source file () for one of the disk devices attached to I (see +also B for listing these names). + +I is a scaled integer (see B above) which defaults to KiB +(blocks of 1024 bytes) if there is no suffix. You must use a suffix of +"B" to get bytes (note that for historical reasons, this differs from +B which defaults to bytes without a suffix). + =item B I [I] [I<--safe>] [I<--force>] Connect the virtual serial console for the guest. The optional @@ -726,6 +1053,14 @@ the server has to ensure exclusive access to console devices. Optionally the I<--force> flag may be specified, requesting to disconnect any existing sessions, such as in a case of a broken connection. +=item B I [I<--total>] [I] [I] + +Provide cpu statistics information of a domain. The domain should +be running. Default it shows stats for all CPUs, and a total. Use +I<--total> for only the total stats, I for only the per-cpu +stats of the CPUs from I, I for only I CPUs' +stats. + =item B I [I<--console>] [I<--paused>] [I<--autodestroy>] [I<--pass-fds N,M,...>] [I<--validate>] @@ -822,6 +1157,35 @@ If I<--graceful> is specified, don't resort to extreme measures (e.g. SIGKILL) when the guest doesn't stop after a reasonable timeout; return an error instead. +=item B I + +Show errors on block devices. This command usually comes handy when +B command says that a domain was paused due to I/O error. +The B command lists all block devices in error state and +the error seen on each of them. + +=item B I [I I<--all>] [I<--human>] + +Get block device size info for a domain. A I corresponds +to a unique target name () or source file () for one of the disk devices attached to I (see +also B for listing these names). If I<--human> is set, the +output will have a human readable output. +If I<--all> is set, the output will be a table showing all block devices +size info associated with I. +The I<--all> option takes precedence of the others. + +=item B I [I<--inactive>] [I<--details>] + +Print a table showing the brief information of all block devices +associated with I. If I<--inactive> is specified, query the +block devices that will be used on the next boot, rather than those +currently in use by a running domain. If I<--details> is specified, +disk type and device value will also be printed. Other contexts +that require a block device name (such as I or +I for disk snapshots) will accept either target +or unique source names printed by this command. + =item B I [I] [I<--human>] Get device block stats for a running domain. A I corresponds @@ -850,6 +1214,99 @@ B (fields appear in the following order): <-- other fields provided by hypervisor --> +=item B I I I + +Set the threshold value for delivering the block-threshold event. I +specifies the disk device target or backing chain element of given device using +the 'target[1]' syntax. I is a scaled value of the offset. If the +block device should write beyond that offset the event will be delivered. + +=item B I + +Returns state of an interface to VMM used to control a domain. For +states other than "ok" or "error" the command also prints number of +seconds elapsed since the control interface entered its current state. + +=item B I [I<--include-password>] +[[I<--type>] B] [I<--all>] + +Output a URI which can be used to connect to the graphical display of the +domain via VNC, SPICE or RDP. The particular graphical display type can +be selected using the B parameter (e.g. "vnc", "spice", "rdp"). If +I<--include-password> is specified, the SPICE channel password will be +included in the URI. If I<--all> is specified, then all show all possible +graphical displays, for a VM could have more than one graphical displays. + +=item B I [[I<--mountpoint>] B...] + +Freeze mounted filesystems within a running domain to prepare for consistent +snapshots. + +The I<--mountpoint> option takes a parameter B, which is a +mount point path of the filesystem to be frozen. This option can occur +multiple times. If this is not specified, every mounted filesystem is frozen. + +Note: B command has a I<--quiesce> option to freeze +and thaw the filesystems automatically to keep snapshots consistent. +B command is only needed when a user wants to utilize the +native snapshot features of storage devices not supported by libvirt. + +=item B I + +Show a list of mounted filesystems within the running domain. The list contains +mountpoints, names of a mounted device in the guest, filesystem types, and +unique target names used in the domain XML (). + +Note that this command requires a guest agent configured and running in the +domain's guest OS. + +=item B I [[I<--mountpoint>] B...] + +Thaw mounted filesystems within a running domain, which have been frozen by +domfsfreeze command. + +The I<--mountpoint> option takes a parameter B, which is a +mount point path of the filesystem to be thawed. This option can occur +multiple times. If this is not specified, every mounted filesystem is thawed. + +=item B I [I<--minimum> B] +[I<--mountpoint mountPoint>] + +Issue a fstrim command on all mounted filesystems within a running +domain. It discards blocks which are not in use by the filesystem. +If I<--minimum> B is specified, it tells guest kernel length +of contiguous free range. Smaller than this may be ignored (this is +a hint and the guest may not respect it). By increasing this value, +the fstrim operation will complete more quickly for filesystems +with badly fragmented free space, although not all blocks will +be discarded. The default value is zero, meaning "discard +every free block". Moreover, if a user wants to trim only one mount +point, it can be specified via optional I<--mountpoint> parameter. + +=item B I + +Returns the hostname of a domain, if the hypervisor makes it available. + +=item B I + +Convert a domain name (or UUID) to a domain id + +=item B I I [I<--config>] + +Query link state of the domain's virtual interface. If I<--config> +is specified, query the persistent configuration, for compatibility +purposes, I<--persistent> is alias of I<--config>. + +I can be the interface's target name or the MAC address. + +=item B I I I [I<--config>] + +Modify link state of the domain's virtual interface. Possible values for +state are "up" and "down". If I<--config> is specified, only the persistent +configuration of the domain is modified, for compatibility purposes, +I<--persistent> is alias of I<--config>. +I can be the interface's target name or the MAC address. + =item B I [I] [I<--full>] [I<--source lease|agent|arp>] @@ -870,6 +1327,15 @@ addresses, currently 'lease' to read DHCP leases, 'agent' to query the guest OS via an agent, or 'arp' to get IP from host's arp tables. If unspecified, 'lease' is the default. +=item B I [I<--inactive>] + +Print a table showing the brief information of all virtual interfaces +associated with I. If I<--inactive> is specified, query the +virtual interfaces that will be used on the next boot, rather than those +currently in use by a running domain. Other contexts that require a MAC +address of virtual interface (such as I or +I) will accept the MAC address printed by this command. + =item B I I Get network interface stats for a running domain. The network @@ -879,22 +1345,6 @@ physical source interface. This does not include, for example, a outside world. I can be the interface target by name or MAC address. -=item B I I I [I<--config>] - -Modify link state of the domain's virtual interface. Possible values for -state are "up" and "down". If I<--config> is specified, only the persistent -configuration of the domain is modified, for compatibility purposes, -I<--persistent> is alias of I<--config>. -I can be the interface's target name or the MAC address. - -=item B I I [I<--config>] - -Query link state of the domain's virtual interface. If I<--config> -is specified, query the persistent configuration, for compatibility -purposes, I<--persistent> is alias of I<--config>. - -I can be the interface's target name or the MAC address. - =item B I I [[I<--config>] [I<--live>] | [I<--current>]] [I<--inbound average,peak,burst,floor>] @@ -922,6 +1372,24 @@ Both I<--live> and I<--config> flags may be given, but I<--current> is exclusive. If no flag is specified, behavior is different depending on hypervisor. +=item B I + +Returns basic information about the domain. + +=item B I + +Abort the currently running domain job. + +=item B I [I<--completed>] + +Returns information about jobs running on a domain. I<--completed> tells +virsh to return information about a recently finished job. Statistics of +a completed job are automatically destroyed once read or when libvirtd +is restarted. Note that time information returned for completed +migrations may be completely irrelevant unless both source and +destination hosts have synchronized time (i.e., NTP daemon is running +on both of them). + =item B I [I<--period> B] [[I<--config>] [I<--live>] | [I<--current>]] @@ -967,34 +1435,51 @@ Both I<--live> and I<--config> flags may be given, but I<--current> is exclusive. If no flag is specified, behavior is different depending on the guest state. -=item B I +=item B I -Show errors on block devices. This command usually comes handy when -B command says that a domain was paused due to I/O error. -The B command lists all block devices in error state and -the error seen on each of them. +Convert a domain Id (or UUID) to domain name -=item B I [I I<--all>] [I<--human>] +=item B I I [I<--duration>] -Get block device size info for a domain. A I corresponds -to a unique target name () or source file () for one of the disk devices attached to I (see -also B for listing these names). If I<--human> is set, the -output will have a human readable output. -If I<--all> is set, the output will be a table showing all block devices -size info associated with I. -The I<--all> option takes precedence of the others. +Suspend a running domain into one of these states (possible I +values): + mem equivalent of S3 ACPI state + disk equivalent of S4 ACPI state + hybrid RAM is saved to disk but not powered off -=item B I [I<--inactive>] [I<--details>] +The I<--duration> argument specifies number of seconds before the domain is +woken up after it was suspended (see also B). Default is 0 for +unlimited suspend time. (This feature isn't currently supported by any +hypervisor driver and 0 should be used.). -Print a table showing the brief information of all block devices -associated with I. If I<--inactive> is specified, query the -block devices that will be used on the next boot, rather than those -currently in use by a running domain. If I<--details> is specified, -disk type and device value will also be printed. Other contexts -that require a block device name (such as I or -I for disk snapshots) will accept either target -or unique source names printed by this command. +Note that this command requires a guest agent configured and running in the +domain's guest OS. + +Beware that at least for QEMU, the domain's process will be terminated when +target disk is used and a new process will be launched when libvirt is asked +to wake up the domain. As a result of this, any runtime changes, such as +device hotplug or memory settings, are lost unless such changes were made +with I<--config> flag. + + +=item B I + +Wakeup a domain from pmsuspended state (either suspended by dompmsuspend or +from the guest itself). Injects a wakeup into the guest that is in pmsuspended +state, rather than waiting for the previously requested duration (if any) to +elapse. This operation doesn't not necessarily fail if the domain is running. + +=item B I I + +Rename a domain. This command changes current domain name to the new name +specified in the second argument. + +B: Domain must be inactive and without snapshots or checkpoints. + +=item B I [I<--reason>] + +Returns state about a domain. I<--reason> tells virsh to also print +reason for the state. =item B [I<--raw>] [I<--enforce>] [I<--backing>] [I<--nowait>] [I<--state>] [I<--cpu-total>] [I<--balloon>] [I<--vcpu>] [I<--interface>] @@ -1196,404 +1681,6 @@ This may cause unnecessary delay in delivering stats. Using I<--nowait> suppresses this behaviour. On the other hand some statistics might be missing for such domain. -=item B I [I<--inactive>] - -Print a table showing the brief information of all virtual interfaces -associated with I. If I<--inactive> is specified, query the -virtual interfaces that will be used on the next boot, rather than those -currently in use by a running domain. Other contexts that require a MAC -address of virtual interface (such as I or -I) will accept the MAC address printed by this command. - -=item B I I [I] [I<--bytes>] -[I] [I<--shallow>] [I] [I<--delete>] [I<--keep-relative>] -[I<--wait> [I<--async>] [I<--verbose>]] [I<--timeout> B] -[I<--active>] [{I<--pivot> | I<--keep-overlay>}] - -Reduce the length of a backing image chain, by committing changes at the -top of the chain (snapshot or delta files) into backing images. By -default, this command attempts to flatten the entire chain. If I -and/or I are specified as files within the backing chain, then the -operation is constrained to committing just that portion of the chain; -I<--shallow> can be used instead of I to specify the immediate -backing file of the resulting top image to be committed. The files -being committed are rendered invalid, possibly as soon as the operation -starts; using the I<--delete> flag will attempt to remove these invalidated -files at the successful completion of the commit operation. When the -I<--keep-relative> flag is used, the backing file paths will be kept relative. - -When I is omitted or specified as the active image, it is also -possible to specify I<--active> to trigger a two-phase active commit. In -the first phase, I is copied into I and the job can only be -canceled, with top still containing data not yet in base. In the second -phase, I and I remain identical until a call to B -with the I<--abort> flag (keeping top as the active image that tracks -changes from that point in time) or the I<--pivot> flag (making base -the new active image and invalidating top). - -By default, this command returns as soon as possible, and data for -the entire disk is committed in the background; the progress of the -operation can be checked with B. However, if I<--wait> is -specified, then this command will block until the operation completes -(or for I<--active>, enters the second phase), or until the operation -is canceled because the optional I in seconds elapses -or SIGINT is sent (usually with C). Using I<--verbose> along -with I<--wait> will produce periodic status updates. If job cancellation -is triggered, I<--async> will return control to the user as fast as -possible, otherwise the command may continue to block a little while -longer until the job is done cleaning up. Using I<--pivot> is shorthand -for combining I<--active> I<--wait> with an automatic B -I<--pivot>; and using I<--keep-overlay> is shorthand for combining -I<--active> I<--wait> with an automatic B I<--abort>. - -I specifies fully-qualified path of the disk; it corresponds -to a unique target name () or source file () for one of the disk devices attached to I (see -also B for listing these names). -I specifies copying bandwidth limit in MiB/s, although for -qemu, it may be non-zero only for an online domain. For further information -on the I argument see the corresponding section for the B -command. - -=item B I I { I [I] [I<--blockdev>] -| I<--xml> B } [I<--shallow>] [I<--reuse-external>] [I] -[I<--wait> [I<--async>] [I<--verbose>]] [{I<--pivot> | I<--finish>}] -[I<--timeout> B] [I] [I] [I<--bytes>] -[I<--transient-job>] - -Copy a disk backing image chain to a destination. Either I as -the destination file name, or I<--xml> with the name of an XML file containing -a top-level element describing the destination, must be present. -Additionally, if I is given, I should be specified to declare -the format of the destination (if I is omitted, then libvirt -will reuse the format of the source, or with I<--reuse-external> will -be forced to probe the destination format, which could be a potential -security hole). The command supports I<--raw> as a boolean flag synonym for -I<--format=raw>. When using I, the destination is treated as a regular -file unless I<--blockdev> is used to signal that it is a block device. By -default, this command flattens the entire chain; but if I<--shallow> is -specified, the copy shares the backing chain. - -If I<--reuse-external> is specified, then the destination must exist and have -sufficient space to hold the copy. If I<--shallow> is used in -conjunction with I<--reuse-external> then the pre-created image must have -guest visible contents identical to guest visible contents of the backing -file of the original image. This may be used to modify the backing file -names on the destination. - -By default, the copy job runs in the background, and consists of two -phases. Initially, the job must copy all data from the source, and -during this phase, the job can only be canceled to revert back to the -source disk, with no guarantees about the destination. After this phase -completes, both the source and the destination remain mirrored until a -call to B with the I<--abort> and I<--pivot> flags pivots over -to the copy, or a call without I<--pivot> leaves the destination as a -faithful copy of that point in time. However, if I<--wait> is specified, -then this command will block until the mirroring phase begins, or cancel -the operation if the optional I in seconds elapses or SIGINT is -sent (usually with C). Using I<--verbose> along with I<--wait> -will produce periodic status updates. Using I<--pivot> (similar to -B I<--pivot>) or I<--finish> (similar to B I<--abort>) -implies I<--wait>, and will additionally end the job cleanly rather than -leaving things in the mirroring phase. If job cancellation is triggered -by timeout or by I<--finish>, I<--async> will return control to the user -as fast as possible, otherwise the command may continue to block a little -while longer until the job has actually cancelled. - -I specifies fully-qualified path of the disk. -I specifies copying bandwidth limit in MiB/s. Specifying a negative -value is interpreted as an unsigned long long value that might be essentially -unlimited, but more likely would overflow; it is safer to use 0 for that -purpose. For further information on the I argument see the -corresponding section for the B command. -Specifying I allows fine-tuning of the granularity that will be -copied when a dirty region is detected; larger values trigger less -I/O overhead but may end up copying more data overall (the default value is -usually correct); hypervisors may restrict this to be a power of two or fall -within a certain range. Specifying I will control how much data can -be simultaneously in-flight during the copy; larger values use more memory but -may allow faster completion (the default value is usually correct). - -I<--transient-job> allows specifying that the user does not require the job to -be recovered if the VM crashes or is turned off before the job completes. This -flag removes the restriction of copy jobs to transient domains if that -restriction is applied by the hypervisor. - -=item B I I [I] [I<--bytes>] [I] -[I<--wait> [I<--verbose>] [I<--timeout> B] [I<--async>]] -[I<--keep-relative>] - -Populate a disk from its backing image chain. By default, this command -flattens the entire chain; but if I is specified, containing the -name of one of the backing files in the chain, then that file becomes -the new backing file and only the intermediate portion of the chain is -pulled. Once all requested data from the backing image chain has been -pulled, the disk no longer depends on that portion of the backing chain. - -By default, this command returns as soon as possible, and data for -the entire disk is pulled in the background; the progress of the -operation can be checked with B. However, if I<--wait> is -specified, then this command will block until the operation completes, -or cancel the operation if the optional I in seconds elapses -or SIGINT is sent (usually with C). Using I<--verbose> along -with I<--wait> will produce periodic status updates. If job cancellation -is triggered, I<--async> will return control to the user as fast as -possible, otherwise the command may continue to block a little while -longer until the job is done cleaning up. - -Using the I<--keep-relative> flag will keep the backing chain names -relative. - -I specifies fully-qualified path of the disk; it corresponds -to a unique target name () or source file () for one of the disk devices attached to I (see -also B for listing these names). -I specifies copying bandwidth limit in MiB/s. For further information -on the I argument see the corresponding section for the B -command. - -=item B I I -[[I<--config>] [I<--live>] | [I<--current>]] -[[I] | [I] [I]] -[[I] | [I] [I]] -[[I] | [I] [I]] -[[I] | [I] [I]] -[[I] | -[I] [I]] -[[I] | -[I] [I]] -[I] [I] - -Set or query the block disk io parameters for a block device of I. -I specifies a unique target name () or source -file () for one of the disk devices attached to -I (see also B for listing these names). - -If no limit is specified, it will query current I/O limits setting. -Otherwise, alter the limits with these flags: -I<--total-bytes-sec> specifies total throughput limit as a scaled integer, the -default being bytes per second if no suffix is specified. -I<--read-bytes-sec> specifies read throughput limit as a scaled integer, the -default being bytes per second if no suffix is specified. -I<--write-bytes-sec> specifies write throughput limit as a scaled integer, the -default being bytes per second if no suffix is specified. -I<--total-iops-sec> specifies total I/O operations limit per second. -I<--read-iops-sec> specifies read I/O operations limit per second. -I<--write-iops-sec> specifies write I/O operations limit per second. -I<--total-bytes-sec-max> specifies maximum total throughput limit as a scaled -integer, the default being bytes per second if no suffix is specified -I<--read-bytes-sec-max> specifies maximum read throughput limit as a scaled -integer, the default being bytes per second if no suffix is specified. -I<--write-bytes-sec-max> specifies maximum write throughput limit as a scaled -integer, the default being bytes per second if no suffix is specified. -I<--total-iops-sec-max> specifies maximum total I/O operations limit per second. -I<--read-iops-sec-max> specifies maximum read I/O operations limit per second. -I<--write-iops-sec-max> specifies maximum write I/O operations limit per second. -I<--total-bytes-sec-max-length> specifies duration in seconds to allow maximum -total throughput limit. -I<--read-bytes-sec-max-length> specifies duration in seconds to allow maximum -read throughput limit. -I<--write-bytes-sec-max-length> specifies duration in seconds to allow maximum -write throughput limit. -I<--total-iops-sec-max-length> specifies duration in seconds to allow maximum -total I/O operations limit. -I<--read-iops-sec-max-length> specifies duration in seconds to allow maximum -read I/O operations limit. -I<--write-iops-sec-max-length> specifies duration in seconds to allow maximum -write I/O operations limit. -I<--size-iops-sec> specifies size I/O operations limit per second. -I<--group-name> specifies group name to share I/O quota between multiple drives. -For a qemu domain, if no name is provided, then the default is to have a single -group for each I. - -Older versions of virsh only accepted these options with underscore -instead of dash, as in I<--total_bytes_sec>. - -Bytes and iops values are independent, but setting only one value (such -as --read-bytes-sec) resets the other two in that category to unlimited. -An explicit 0 also clears any limit. A non-zero value for a given total -cannot be mixed with non-zero values for read or write. - -It is up to the hypervisor to determine how to handle the length values. -For the qemu hypervisor, if an I/O limit value or maximum value is set, -then the default value of 1 second will be displayed. Supplying a 0 will -reset the value back to the default. - -If I<--live> is specified, affect a running guest. -If I<--config> is specified, affect the next boot of a persistent guest. -If I<--current> is specified, affect the current guest state. -When setting the disk io parameters both I<--live> and I<--config> flags may be -given, but I<--current> is exclusive. For querying only one of I<--live>, -I<--config> or I<--current> can be specified. If no flag is specified, behavior -is different depending on hypervisor. - -=item B I I { [I<--abort>] [I<--async>] [I<--pivot>] | -[I<--info>] [I<--raw>] [I<--bytes>] | [I] } - -Manage active block operations. There are three mutually-exclusive modes: -I<--info>, I, and I<--abort>. I<--async> and I<--pivot> imply -abort mode; I<--raw> implies info mode; and if no mode was given, I<--info> -mode is assumed. - -I specifies fully-qualified path of the disk; it corresponds -to a unique target name () or source file () for one of the disk devices attached to I (see -also B for listing these names). - -In I<--abort> mode, the active job on the specified disk will -be aborted. If I<--async> is also specified, this command will return -immediately, rather than waiting for the cancellation to complete. If -I<--pivot> is specified, this requests that an active copy or active -commit job be pivoted over to the new image. - -In I<--info> mode, the active job information on the specified -disk will be printed. By default, the output is a single human-readable -summary line; this format may change in future versions. Adding -I<--raw> lists each field of the struct, in a stable format. If the -I<--bytes> flag is set, then the command errors out if the server could -not supply bytes/s resolution; when omitting the flag, raw output is -listed in MiB/s and human-readable output automatically selects the -best resolution supported by the server. - -I can be used to set bandwidth limit for the active job in MiB/s. -If I<--bytes> is specified then the bandwidth value is interpreted in -bytes/s. Specifying a negative value is interpreted as an unsigned long -value or essentially unlimited. The hypervisor can choose whether to -reject the value or convert it to the maximum value allowed. Optionally a -scaled positive number may be used as bandwidth (see B above). Using -I<--bytes> with a scaled value permits a finer granularity to be selected. -A scaled value used without I<--bytes> will be rounded down to MiB/s. Note -that the I<--bytes> may be unsupported by the hypervisor. - - -=item B I I I - -Set the threshold value for delivering the block-threshold event. I -specifies the disk device target or backing chain element of given device using -the 'target[1]' syntax. I is a scaled value of the offset. If the -block device should write beyond that offset the event will be delivered. - -=item B I I I - -Resize a block device of domain while the domain is running, I -specifies the absolute path of the block device; it corresponds -to a unique target name () or source file () for one of the disk devices attached to I (see -also B for listing these names). - -I is a scaled integer (see B above) which defaults to KiB -(blocks of 1024 bytes) if there is no suffix. You must use a suffix of -"B" to get bytes (note that for historical reasons, this differs from -B which defaults to bytes without a suffix). - -=item B I [I<--include-password>] -[[I<--type>] B] [I<--all>] - -Output a URI which can be used to connect to the graphical display of the -domain via VNC, SPICE or RDP. The particular graphical display type can -be selected using the B parameter (e.g. "vnc", "spice", "rdp"). If -I<--include-password> is specified, the SPICE channel password will be -included in the URI. If I<--all> is specified, then all show all possible -graphical displays, for a VM could have more than one graphical displays. - -=item B I - -Show a list of mounted filesystems within the running domain. The list contains -mountpoints, names of a mounted device in the guest, filesystem types, and -unique target names used in the domain XML (). - -Note that this command requires a guest agent configured and running in the -domain's guest OS. - -=item B I [[I<--mountpoint>] B...] - -Freeze mounted filesystems within a running domain to prepare for consistent -snapshots. - -The I<--mountpoint> option takes a parameter B, which is a -mount point path of the filesystem to be frozen. This option can occur -multiple times. If this is not specified, every mounted filesystem is frozen. - -Note: B command has a I<--quiesce> option to freeze -and thaw the filesystems automatically to keep snapshots consistent. -B command is only needed when a user wants to utilize the -native snapshot features of storage devices not supported by libvirt. - -=item B I [[I<--mountpoint>] B...] - -Thaw mounted filesystems within a running domain, which have been frozen by -domfsfreeze command. - -The I<--mountpoint> option takes a parameter B, which is a -mount point path of the filesystem to be thawed. This option can occur -multiple times. If this is not specified, every mounted filesystem is thawed. - -=item B I [I<--minimum> B] -[I<--mountpoint mountPoint>] - -Issue a fstrim command on all mounted filesystems within a running -domain. It discards blocks which are not in use by the filesystem. -If I<--minimum> B is specified, it tells guest kernel length -of contiguous free range. Smaller than this may be ignored (this is -a hint and the guest may not respect it). By increasing this value, -the fstrim operation will complete more quickly for filesystems -with badly fragmented free space, although not all blocks will -be discarded. The default value is zero, meaning "discard -every free block". Moreover, if a user wants to trim only one mount -point, it can be specified via optional I<--mountpoint> parameter. - -=item B I - -Returns the hostname of a domain, if the hypervisor makes it available. - -=item B I - -Returns basic information about the domain. - -=item B I - -Convert a domain name or id to domain UUID - -=item B I - -Convert a domain name (or UUID) to a domain id - -=item B I - -Abort the currently running domain job. - -=item B I [I<--completed>] - -Returns information about jobs running on a domain. I<--completed> tells -virsh to return information about a recently finished job. Statistics of -a completed job are automatically destroyed once read or when libvirtd -is restarted. Note that time information returned for completed -migrations may be completely irrelevant unless both source and -destination hosts have synchronized time (i.e., NTP daemon is running -on both of them). - -=item B I - -Convert a domain Id (or UUID) to domain name - -=item B I I - -Rename a domain. This command changes current domain name to the new name -specified in the second argument. - -B: Domain must be inactive and without snapshots or checkpoints. - -=item B I [I<--reason>] - -Returns state about a domain. I<--reason> tells virsh to also print -reason for the state. - -=item B I - -Returns state of an interface to VMM used to control a domain. For -states other than "ok" or "error" the command also prints number of -seconds elapsed since the control interface entered its current state. - =item B I { [I<--now>] [I<--pretty>] [I<--sync>] [I<--time> B