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