[libvirt] [PATCH 15/17] docs: convert virsh man page from pod to rst

This was a semi-automated conversion. First it was run through pod2rst, and then it was manually editted to use a rst structure that matches expectations of rst2man. Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com&gt; --- docs/Makefile.am | 1 + docs/manpages/index.rst | 1 + docs/manpages/virsh.rst | 7096 +++++++++++++++++++++++++++++++++++++++ tools/Makefile.am | 5 +- tools/virsh.pod | 5526 ------------------------------ 5 files changed, 7099 insertions(+), 5530 deletions(-) create mode 100644 docs/manpages/virsh.rst delete mode 100644 tools/virsh.pod diff --git a/docs/Makefile.am b/docs/Makefile.am index 1f42afedb6..fad506539b 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -204,6 +204,7 @@ manpages1_rst = \ manpages/virt-pki-validate.rst \ manpages/virt-xml-validate.rst \ manpages/virt-admin.rst \ + manpages/virsh.rst \ $(NULL) manpages7_rst = \ $(NULL) diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index d7e4bcf1d1..1041dbf8b4 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -18,3 +18,4 @@ Tools * `virt-sanlock-cleanup(8) <virt-sanlock-cleanup.html>`__ - remove stale sanlock resource lease files * `virt-login-shell(1) <virt-login-shell.html>`__ - tool to execute a shell within a container * `virt-admin(1) <virt-admin.html>`__ - daemon administration interface +* `virsh(1) <virsh.html>`__ - management user interface diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst new file mode 100644 index 0000000000..d639509fec --- /dev/null +++ b/docs/manpages/virsh.rst @@ -0,0 +1,7096 @@ +===== +virsh +===== + +------------------------- +management user interface +------------------------- + +:Manual section: 1 +:Manual group: Virtualization Support + +.. contents:: :depth: 2 + +SYNOPSIS +======== + + +``virsh`` [*OPTION*]... [*COMMAND_STRING*] + +``virsh`` [*OPTION*]... *COMMAND* [*ARG*]... + + +DESCRIPTION +=========== + +The ``virsh`` program is the main interface for managing virsh guest +domains. The program can be used to create, pause, and shutdown +domains. It can also be used to list current domains. Libvirt is a C +toolkit to interact with the virtualization capabilities of recent +versions of Linux (and other OSes). It is free software available +under the GNU Lesser General Public License. Virtualization of the +Linux Operating System means the ability to run multiple instances of +Operating Systems concurrently on a single hardware system where the +basic resources are driven by a Linux instance. The library aims at +providing a long term stable C API. It currently supports Xen, QEMU, +KVM, LXC, OpenVZ, VirtualBox and VMware ESX. + +The basic structure of most virsh usage is: + + +.. code-block:: shell + + virsh [OPTION]... <command> <domain> [ARG]... + + +Where *command* is one of the commands listed below; *domain* is the +numeric domain id, or the domain name, or the domain UUID; and *ARGS* +are command specific options. There are a few exceptions to this rule +in the cases where the command in question acts on all domains, the +entire machine, or directly on the xen hypervisor. Those exceptions +will be clear for each of those commands. Note: it is permissible to +give numeric names to domains, however, doing so will result in a +domain that can only be identified by domain id. In other words, if a +numeric value is supplied it will be interpreted as a domain id, not +as a name. Any *command* starting with ``#`` is treated as a comment +and silently ignored, all other unrecognized *commands* are diagnosed. + +The ``virsh`` program can be used either to run one *COMMAND* by giving the +command and its arguments on the shell command line, or a *COMMAND_STRING* +which is a single shell argument consisting of multiple *COMMAND* actions +and their arguments joined with whitespace and separated by semicolons or +newlines between commands, where unquoted backslash-newline pairs are +elided. Within *COMMAND_STRING*, virsh understands the +same single, double, and backslash escapes as the shell, although you must +add another layer of shell escaping in creating the single shell argument, +and any word starting with unquoted *#* begins a comment that ends at newline. +If no command is given in the command line, ``virsh`` will then start a minimal +interpreter waiting for your commands, and the ``quit`` command will then exit +the program. + +The ``virsh`` program understands the following *OPTIONS*. + + +``-c``, ``--connect`` *URI* + +Connect to the specified *URI*, as if by the ``connect`` command, +instead of the default connection. + +``-d``, ``--debug`` *LEVEL* + +Enable debug messages at integer *LEVEL* and above. *LEVEL* can +range from 0 to 4 (default). See the documentation of ``VIRSH_DEBUG`` +environment variable below for the description of each *LEVEL*. + + + +- ``-e``, ``--escape`` *string* + +Set alternative escape sequence for *console* command. By default, +telnet's ``^]`` is used. Allowed characters when using hat notation are: +alphabetic character, @, [, ], \, ^, _. + + + +- ``-h``, ``--help`` + +Ignore all other arguments, and behave as if the ``help`` command were +given instead. + + + +- ``-k``, ``--keepalive-interval`` *INTERVAL* + +Set an *INTERVAL* (in seconds) for sending keepalive messages to +check whether connection to the server is still alive. Setting the +interval to 0 disables client keepalive mechanism. + + + +- ``-K``, ``--keepalive-count`` *COUNT* + +Set a number of times keepalive message can be sent without getting an +answer from the server without marking the connection dead. There is +no effect to this setting in case the *INTERVAL* is set to 0. + + + +- ``-l``, ``--log`` *FILE* + +Output logging details to *FILE*. + + + +- ``-q``, ``--quiet`` + +Avoid extra informational messages. + + + +- ``-r``, ``--readonly`` + +Make the initial connection read-only, as if by the *--readonly* +option of the ``connect`` command. + + + +- ``-t``, ``--timing`` + +Output elapsed time information for each command. + + + +- ``-v``, ``--version[=short]`` + +Ignore all other arguments, and prints the version of the libvirt library +virsh is coming from + + + +- ``-V``, ``--version=long`` + +Ignore all other arguments, and prints the version of the libvirt library +virsh is coming from and which options and driver are compiled in. + + + + +NOTES +===== + + +Most ``virsh`` operations rely upon the libvirt library being able to +connect to an already running libvirtd service. This can usually be +done using the command ``service libvirtd start``. + +Most ``virsh`` commands require root privileges to run due to the +communications channels used to talk to the hypervisor. Running as +non root will return an error. + +Most ``virsh`` commands act synchronously, except maybe shutdown, +setvcpus and setmem. In those cases the fact that the ``virsh`` +program returned, may not mean the action is complete and you +must poll periodically to detect that the guest completed the +operation. + +``virsh`` strives for backward compatibility. Although the ``help`` +command only lists the preferred usage of a command, if an older +version of ``virsh`` supported an alternate spelling of a command or +option (such as *--tunnelled* instead of *--tunneled*), then +scripts using that older spelling will continue to work. + +Several ``virsh`` commands take an optionally scaled integer; if no +scale is provided, then the default is listed in the command (for +historical reasons, some commands default to bytes, while other +commands default to kibibytes). The following case-insensitive +suffixes can be used to select a specific scale: + +.. code-block:: + + b, byte byte 1 + KB kilobyte 1,000 + k, KiB kibibyte 1,024 + MB megabyte 1,000,000 + M, MiB mebibyte 1,048,576 + GB gigabyte 1,000,000,000 + G, GiB gibibyte 1,073,741,824 + TB terabyte 1,000,000,000,000 + T, TiB tebibyte 1,099,511,627,776 + PB petabyte 1,000,000,000,000,000 + P, PiB pebibyte 1,125,899,906,842,624 + EB exabyte 1,000,000,000,000,000,000 + E, EiB exbibyte 1,152,921,504,606,846,976 + + +GENERIC COMMANDS +================ + + +The following commands are generic i.e. not specific to a domain. + + +help +---- + +.. code-block:: shell + + help [command-or-group] + + +This lists each of the virsh commands. When used without options, all +commands are listed, one per line, grouped into related categories, +displaying the keyword for each group. + +To display only commands for a specific group, give the keyword for that +group as an option. For example: + +Example 1 +~~~~~~~~~ + +.. code-block:: shell + + virsh # help host + + Host and Hypervisor (help keyword 'host'): + capabilities capabilities + cpu-models show the CPU models for an architecture + connect (re)connect to hypervisor + freecell NUMA free memory + hostname print the hypervisor hostname + qemu-attach Attach to existing QEMU process + qemu-monitor-command QEMU Monitor Command + qemu-agent-command QEMU Guest Agent Command + sysinfo print the hypervisor sysinfo + uri print the hypervisor canonical URI + + +To display detailed information for a specific command, give its name as the +option instead. For example: + +Example 2 +~~~~~~~~~ + +.. code-block:: shell + + virsh # help list + NAME + list - list domains + + SYNOPSIS + list [--inactive] [--all] + + DESCRIPTION + Returns list of domains. + + OPTIONS + --inactive list inactive domains + --all list inactive & active domains + + +quit, exit +---------- + +.. code-block:: shell + + quit + exit + + +quit this interactive terminal + + + +version +------- + +.. code-block:: shell + + version [--daemon] + + +Will print out the major version info about what this built from. +If *--daemon* is specified then the version of the libvirt daemon +is included in the output. + + +Example +~~~~~~~ + +.. code-block:: shell + + $ virsh version + Compiled against library: libvirt 1.2.3 + Using library: libvirt 1.2.3 + Using API: QEMU 1.2.3 + Running hypervisor: QEMU 2.0.50 + + $ virsh version --daemon + Compiled against library: libvirt 1.2.3 + Using library: libvirt 1.2.3 + Using API: QEMU 1.2.3 + Running hypervisor: QEMU 2.0.50 + Running against daemon: 1.2.6 + + +cd +-- + +.. code-block:: shell + + cd [directory] + + +Will change current directory to *directory*. The default directory +for the ``cd`` command is the home directory or, if there is no *HOME* +variable in the environment, the root directory. + +This command is only available in interactive mode. + + +pwd +--- + +.. code-block:: shell + + pwd + + +Will print the current directory. + + +connect +------- + +.. code-block:: shell + + connect [URI] [--readonly] + + +(Re)-Connect to the hypervisor. When the shell is first started, this +is automatically run with the *URI* parameter requested by the ``-c`` +option on the command line. The *URI* parameter specifies how to +connect to the hypervisor. The URI docs +`https://libvirt.org/uri.html <https://libvirt.org/uri.html>`_ list the +values supported, but the most common are: + + +- xen:///system + + this is used to connect to the local Xen hypervisor + +- qemu:///system + + connect locally as root to the daemon supervising QEMU and KVM domains + +- qemu:///session + + connect locally as a normal user to his own set of QEMU and KVM domains + +- lxc:///system + + connect to a local linux container + +To find the currently used URI, check the *uri* command documented below. + +For remote access see the URI docs +`https://libvirt.org/uri.html <https://libvirt.org/uri.html>`_ on how +to make URIs. The *--readonly* option allows for read-only connection + + +uri +--- + +.. code-block:: shell + + uri + +Prints the hypervisor canonical URI, can be useful in shell mode. + + +hostname +-------- + +.. code-block:: shell + + hostname + +Print the hypervisor hostname. + + +sysinfo +------- + +.. code-block:: shell + + sysinfo + +Print the XML representation of the hypervisor sysinfo, if available. + + +nodeinfo +-------- + +.. code-block:: shell + + nodeinfo + +Returns basic information about the node, like number and type of CPU, +and size of the physical memory. The output corresponds to virNodeInfo +structure. Specifically, the "CPU socket(s)" field means number of CPU +sockets per NUMA cell. The information libvirt displays is dependent +upon what each architecture may provide. + + +nodecpumap +---------- + +.. code-block:: shell + + nodecpumap [--pretty] + + +Displays the node's total number of CPUs, the number of online CPUs +and the list of online CPUs. + +With *--pretty* the online CPUs are printed as a range instead of a list. + + +nodecpustats +------------ + +.. code-block:: shell + + nodecpustats [cpu] [--percent] + +Returns cpu stats of the node. +If *cpu* is specified, this will print the specified cpu statistics only. +If *--percent* is specified, this will print the percentage of each kind +of cpu statistics during 1 second. + + +nodememstats +------------ + +.. code-block:: shell + + nodememstats [cell] + +Returns memory stats of the node. +If *cell* is specified, this will print the specified cell statistics only. + + +nodesuspend +----------- + +.. code-block:: shell + + nodesuspend [target] [duration] + +Puts the node (host machine) into a system-wide sleep state and schedule +the node's Real-Time-Clock interrupt to resume the node after the time +duration specified by *duration* is out. +*target* specifies the state to which the host will be suspended to, it +can be "mem" (suspend to RAM), "disk" (suspend to disk), or "hybrid" +(suspend to both RAM and disk). *duration* specifies the time duration +in seconds for which the host has to be suspended, it should be at least +60 seconds. + + +node +---- + +.. code-block:: shell + + node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs] [shm-merge-across-nodes] + +Allows you to display or set the node memory parameters. +*shm-pages-to-scan* can be used to set the number of pages to scan +before the shared memory service goes to sleep; *shm-sleep-millisecs* +can be used to set the number of millisecs the shared memory service should +sleep before next scan; *shm-merge-across-nodes* specifies if pages from +different numa nodes can be merged. When set to 0, only pages which physically +reside in the memory area of same NUMA node can be merged. When set to 1, +pages from all nodes can be merged. Default to 1. + +``Note``: Currently the "shared memory service" only means KSM (Kernel Samepage +Merging). + + +capabilities +------------ + +.. code-block:: shell + + capabilities + +Print an XML document describing the capabilities of the hypervisor +we are currently connected to. This includes a section on the host +capabilities in terms of CPU and features, and a set of description +for each kind of guest which can be virtualized. For a more complete +description see: + +`https://libvirt.org/formatcaps.html <https://libvirt.org/formatcaps.html>`_ + +The XML also show the NUMA topology information if available. + + +domcapabilities +--------------- + +.. code-block:: shell + + domcapabilities [virttype] [emulatorbin] [arch] [machine] + + +Print an XML document describing the domain capabilities for the +hypervisor we are connected to using information either sourced from an +existing domain or taken from the ``virsh capabilities`` output. This may +be useful if you intend to create a new domain and are curious if for +instance it could make use of VFIO by creating a domain for the +hypervisor with a specific emulator and architecture. + +Each hypervisor will have different requirements regarding which options +are required and which are optional. A hypervisor can support providing +a default value for any of the options. + +The *virttype* option specifies the virtualization type used. The value +to be used is either from the 'type' attribute of the <domain/> top +level element from the domain XML or the 'type' attribute found within +each <guest/> element from the ``virsh capabilities`` output. The +*emulatorbin* option specifies the path to the emulator. The value to +be used is either the <emulator> element in the domain XML or the +``virsh capabilities`` output. The *arch* option specifies the +architecture to be used for the domain. The value to be used is either +the "arch" attribute from the domain's XML <os/> element and <type/> +subelement or the "name" attribute of an <arch/> element from the +``virsh capabililites`` output. The *machine* specifies the machine type +for the emulator. The value to be used is either the "machine" attribute +from the domain's XML <os/> element and <type/> subelement or one from a +list of machines from the ``virsh capabilities`` output for a specific +architecture and domain type. + +For the qemu hypervisor, a *virttype* of either 'qemu' or 'kvm' must be +supplied along with either the *emulatorbin* or *arch* in order to +generate output for the default *machine*. Supplying a *machine* +value will generate output for the specific machine. + + +pool-capabilities +----------------- + +.. code-block:: shell + + pool-capabilities + +Print an XML document describing the storage pool capabilities for the +connected storage driver. This may be useful if you intend to create a +new storage pool and need to know the available pool types and supported +storage pool source and target volume formats as well as the required +source elements to create the pool. + + + +inject +------ + +.. code-block:: shell + + inject-nmi domain + +Inject NMI to the guest. + + +list +---- + +.. code-block:: shell + + list [--inactive | --all] + [--managed-save] [--title] + { [--table] | --name | --uuid } + [--persistent] [--transient] + [--with-managed-save] [--without-managed-save] + [--autostart] [--no-autostart] + [--with-snapshot] [--without-snapshot] + [--with-checkpoint] [--without-checkpoint] + [--state-running] [--state-paused] + [--state-shutoff] [--state-other] + +Prints information about existing domains. If no options are +specified it prints out information about running domains. + +Example 1 +~~~~~~~~~ + +An example format for the list is as follows: + +.. code-block:: shell + + ``virsh`` list + Id Name State + ---------------------------------------------------- + 0 Domain-0 running + 2 fedora paused + +Name is the name of the domain. ID the domain numeric id. +State is the run state (see below). + +STATES +~~~~~~ + +The State field lists what state each domain is currently in. A domain +can be in one of the following possible states: + + +- ``running`` + + The domain is currently running on a CPU + +- ``idle`` + + The domain is idle, and not running or runnable. This can be caused + because the domain is waiting on IO (a traditional wait state) or has + gone to sleep because there was nothing else for it to do. + +- ``paused`` + + The domain has been paused, usually occurring through the administrator + running ``virsh suspend``. When in a paused state the domain will still + consume allocated resources like memory, but will not be eligible for + scheduling by the hypervisor. + +- ``in shutdown`` + + The domain is in the process of shutting down, i.e. the guest operating system + has been notified and should be in the process of stopping its operations + gracefully. + +- ``shut off`` + + The domain is not running. Usually this indicates the domain has been + shut down completely, or has not been started. + +- ``crashed`` + + The domain has crashed, which is always a violent ending. Usually + this state can only occur if the domain has been configured not to + restart on crash. + +- ``pmsuspended`` + + The domain has been suspended by guest power management, e.g. entered + into s3 state. + + + +Normally only active domains are listed. To list inactive domains specify +*--inactive* or *--all* to list both active and inactive domains. + +Filtering +~~~~~~~~~ + +To further filter the list of domains you may specify one or more of filtering +flags supported by the ``list`` command. These flags are grouped by function. +Specifying one or more flags from a group enables the filter group. Note that +some combinations of flags may yield no results. Supported filtering flags and +groups: + + +Persistence +........... + +Flag *--persistent* is used to include persistent domains in the returned +list. To include transient domains specify *--transient*. + +Existence of managed save image +............................... + +To list domains having a managed save image specify flag +*--with-managed-save*. For domains that don't have a managed save image +specify *--without-managed-save*. + +Domain state +............ + +The following filter flags select a domain by its state: +*--state-running* for running domains, *--state-paused* for paused domains, +*--state-shutoff* for turned off domains and *--state-other* for all +other states as a fallback. + +Autostarting domains +.................... + +To list autostarting domains use the flag *--autostart*. To list domains with +this feature disabled use *--no-autostart*. + +Snapshot existence +.................. + +Domains that have snapshot images can be listed using flag *--with-snapshot*, +domains without a snapshot *--without-snapshot*. + +Checkpoint existence +.................... + +Domains that have checkpoints can be listed using flag *--with-checkpoint*, +domains without a checkpoint *--without-checkpoint*. + + +When talking to older servers, this command is forced to use a series of API +calls with an inherent race, where a domain might not be listed or might appear +more than once if it changed state between calls while the list was being +collected. Newer servers do not have this problem. + +If *--managed-save* is specified, then domains that have managed save state +(only possible if they are in the ``shut off`` state, so you need to specify +*--inactive* or *--all* to actually list them) will instead show as ``saved`` +in the listing. This flag is usable only with the default *--table* output. +Note that this flag does not filter the list of domains. + +If *--name* is specified, domain names are printed instead of the table +formatted one per line. If *--uuid* is specified domain's UUID's are printed +instead of names. Flag *--table* specifies that the legacy table-formatted +output should be used. This is the default. + +If both *--name* and *--uuid* are specified, domain UUID's and names +are printed side by side without any header. Flag *--table* specifies +that the legacy table-formatted output should be used. This is the +default if neither *--name* nor *--uuid* are specified. Option +*--table* is mutually exclusive with options *--uuid* and *--name*. + +If *--title* is specified, then the short domain description (title) is +printed in an extra column. This flag is usable only with the default +*--table* output. + +Example 2 +~~~~~~~~~ + +.. code-block:: shell + + $ virsh list --title + Id Name State Title + ------------------------------------------- + 0 Domain-0 running Mailserver 1 + 2 fedora paused + + + +freecell +-------- + +.. code-block:: shell + + freecell [{ [--cellno] cellno | --all }] + +Prints the available amount of memory on the machine or within a NUMA +cell. The freecell command can provide one of three different +displays of available memory on the machine depending on the options +specified. With no options, it displays the total free memory on the +machine. With the --all option, it displays the free memory in each +cell and the total free memory on the machine. Finally, with a +numeric argument or with --cellno plus a cell number it will display +the free memory for the specified cell only. + + +freepages +--------- + +.. code-block:: shell + + freepages [{ [--cellno] cellno [--pagesize] pagesize | --all }] + +Prints the available amount of pages within a NUMA cell. *cellno* refers +to the NUMA cell you're interested in. *pagesize* is a scaled integer (see +``NOTES`` above). Alternatively, if *--all* is used, info on each possible +combination of NUMA cell and page size is printed out. + + +allocpages +---------- + +.. code-block:: shell + + allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno] cellno] [--add] [--all] + +Change the size of pages pool of *pagesize* on the host. If +*--add* is specified, then *pagecount* pages are added into the +pool. However, if *--add* wasn't specified, then the +*pagecount* is taken as the new absolute size of the pool (this +may be used to free some pages and size the pool down). The +*cellno* modifier can be used to narrow the modification down to +a single host NUMA cell. On the other end of spectrum lies +*--all* which executes the modification on all NUMA cells. + + +cpu-baseline +------------ + +.. code-block:: shell + + cpu-baseline FILE [--features] [--migratable] + +Compute baseline CPU which will be supported by all host CPUs given in <file>. +(See ``hypervisor-cpu-baseline`` command to get a CPU which can be provided by a +specific hypervisor.) The list of host CPUs is built by extracting all <cpu> +elements from the <file>. Thus, the <file> can contain either a set of <cpu> +elements separated by new lines or even a set of complete <capabilities> +elements printed by ``capabilities`` command. If *--features* is specified, +then the resulting XML description will explicitly include all features that +make up the CPU, without this option features that are part of the CPU model +will not be listed in the XML description. If *--migratable* is specified, +features that block migration will not be included in the resulting CPU. + + +cpu-compare +----------- + +.. code-block:: shell + + cpu-compare FILE [--error] + +Compare CPU definition from XML <file> with host CPU. (See +``hypervisor-cpu-compare`` command for comparing the CPU definition with the CPU +which a specific hypervisor is able to provide on the host.) The XML <file> may +contain either host or guest CPU definition. The host CPU definition is the +<cpu> element and its contents as printed by ``capabilities`` command. The +guest CPU definition is the <cpu> element and its contents from domain XML +definition or the CPU definition created from the host CPU model found in +domain capabilities XML (printed by ``domcapabilities`` command). In +addition to the <cpu> element itself, this command accepts +full domain XML, capabilities XML, or domain capabilities XML containing +the CPU definition. For more information on guest CPU definition see: +`https://libvirt.org/formatdomain.html#elementsCPU <https://libvirt.org/formatdomain.html#elementsCPU>`_. If *--error* is +specified, the command will return an error when the given CPU is +incompatible with host CPU and a message providing more details about the +incompatibility will be printed out. + + +cpu-models +---------- + +.. code-block:: shell + + cpu-models arch + +Print the list of CPU models known by libvirt for the specified architecture. +Whether a specific hypervisor is able to create a domain which uses any of +the printed CPU models is a separate question which can be answered by +looking at the domain capabilities XML returned by ``domcapabilities`` command. +Moreover, for some architectures libvirt does not know any CPU models and +the usable CPU models are only limited by the hypervisor. This command will +print that all CPU models are accepted for these architectures and the actual +list of supported CPU models can be checked in the domain capabilities XML. + + +echo +---- + +.. code-block:: shell + + echo [--shell] [--xml] [err...] [arg...] + +Echo back each *arg*, separated by space. If *--shell* is +specified, then the output will be single-quoted where needed, so that +it is suitable for reuse in a shell context. If *--xml* is +specified, then the output will be escaped for use in XML. +If *--err* is specified, prefix ``"error: "`` and output to stderr +instead of stdout. + + +hypervisor-cpu-compare +---------------------- + +.. code-block:: shell + + hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine] [--error] + +Compare CPU definition from XML <file> with the CPU the hypervisor is able to +provide on the host. (This is different from ``cpu-compare`` which compares the +CPU definition with the host CPU without considering any specific hypervisor +and its abilities.) + +The XML *FILE* may contain either a host or guest CPU definition. The host CPU +definition is the <cpu> element and its contents as printed by the +``capabilities`` command. The guest CPU definition is the <cpu> element and its +contents from the domain XML definition or the CPU definition created from the +host CPU model found in the domain capabilities XML (printed by the +``domcapabilities`` command). In addition to the <cpu> element itself, this +command accepts full domain XML, capabilities XML, or domain capabilities XML +containing the CPU definition. For more information on guest CPU definition +see: `https://libvirt.org/formatdomain.html#elementsCPU <https://libvirt.org/formatdomain.html#elementsCPU>`_. + +The *virttype* option specifies the virtualization type (usable in the 'type' +attribute of the <domain> top level element from the domain XML). *emulator* +specifies the path to the emulator, *arch* specifies the CPU architecture, and +*machine* specifies the machine type. If *--error* is specified, the command +will return an error when the given CPU is incompatible with the host CPU and a +message providing more details about the incompatibility will be printed out. + + +hypervisor-cpu-baseline +----------------------- + +.. code-block:: shell + + hypervisor-cpu-baseline FILE [virttype] [emulator] [arch] [machine] [--features] [--migratable] + +Compute a baseline CPU which will be compatible with all CPUs defined in an XML +*file* and with the CPU the hypervisor is able to provide on the host. (This +is different from ``cpu-baseline`` which does not consider any hypervisor +abilities when computing the baseline CPU.) + +The XML *FILE* may contain either host or guest CPU definitions describing the +host CPU model. The host CPU definition is the <cpu> element and its contents +as printed by ``capabilities`` command. The guest CPU definition may be created +from the host CPU model found in domain capabilities XML (printed by +``domcapabilities`` command). In addition to the <cpu> elements, this command +accepts full capabilities XMLs, or domain capabilities XMLs containing the CPU +definitions. For best results, use only the CPU definitions from domain +capabilities. + +When *FILE* contains only a single CPU definition, the command will print the +same CPU with restrictions imposed by the capabilities of the hypervisor. +Specifically, running th ``virsh hypervisor-cpu-baseline`` command with no +additional options on the result of ``virsh domcapabilities`` will transform the +host CPU model from domain capabilities XML to a form directly usable in domain +XML. + +The *virttype* option specifies the virtualization type (usable in the 'type' +attribute of the <domain> top level element from the domain XML). *emulator* +specifies the path to the emulator, *arch* specifies the CPU architecture, and +*machine* specifies the machine type. If *--features* is specified, then the +resulting XML description will explicitly include all features that make up the +CPU, without this option features that are part of the CPU model will not be +listed in the XML description. If *--migratable* is specified, features that +block migration will not be included in the resulting CPU. + + +DOMAIN COMMANDS +=============== + +The following commands manipulate domains directly, as stated +previously most commands take domain as the first parameter. The +*domain* can be specified as a short integer, a name or a full UUID. + +autostart +--------- + +.. code-block:: shell + + autostart [--disable] domain + + +Configure a domain to be automatically started at boot. + +The option *--disable* disables autostarting. + + +blkdeviotune +------------ + +.. code-block:: shell + + blkdeviotune domain device [[--config] [--live] | [--current]] + [[total-bytes-sec] | [read-bytes-sec] [write-bytes-sec]] + [[total-iops-sec] | [read-iops-sec] [write-iops-sec]] + [[total-bytes-sec-max] | [read-bytes-sec-max] [write-bytes-sec-max]] + [[total-iops-sec-max] | [read-iops-sec-max] [write-iops-sec-max]] + [[total-bytes-sec-max-length] | + [read-bytes-sec-max-length] [write-bytes-sec-max-length]] + [[total-iops-sec-max-length] | + [read-iops-sec-max-length] [write-iops-sec-max-length]] + [size-iops-sec] [group-name] + +Set or query the block disk io parameters for a block device of *domain*. +*device* specifies a unique target name (<target dev='name'/>) or source +file (<source file='name'/>) for one of the disk devices attached to +*domain* (see also ``domblklist`` for listing these names). + +If no limit is specified, it will query current I/O limits setting. +Otherwise, alter the limits with these flags: +*--total-bytes-sec* specifies total throughput limit as a scaled integer, the +default being bytes per second if no suffix is specified. +*--read-bytes-sec* specifies read throughput limit as a scaled integer, the +default being bytes per second if no suffix is specified. +*--write-bytes-sec* specifies write throughput limit as a scaled integer, the +default being bytes per second if no suffix is specified. +*--total-iops-sec* specifies total I/O operations limit per second. +*--read-iops-sec* specifies read I/O operations limit per second. +*--write-iops-sec* specifies write I/O operations limit per second. +*--total-bytes-sec-max* specifies maximum total throughput limit as a scaled +integer, the default being bytes per second if no suffix is specified +*--read-bytes-sec-max* specifies maximum read throughput limit as a scaled +integer, the default being bytes per second if no suffix is specified. +*--write-bytes-sec-max* specifies maximum write throughput limit as a scaled +integer, the default being bytes per second if no suffix is specified. +*--total-iops-sec-max* specifies maximum total I/O operations limit per second. +*--read-iops-sec-max* specifies maximum read I/O operations limit per second. +*--write-iops-sec-max* specifies maximum write I/O operations limit per second. +*--total-bytes-sec-max-length* specifies duration in seconds to allow maximum +total throughput limit. +*--read-bytes-sec-max-length* specifies duration in seconds to allow maximum +read throughput limit. +*--write-bytes-sec-max-length* specifies duration in seconds to allow maximum +write throughput limit. +*--total-iops-sec-max-length* specifies duration in seconds to allow maximum +total I/O operations limit. +*--read-iops-sec-max-length* specifies duration in seconds to allow maximum +read I/O operations limit. +*--write-iops-sec-max-length* specifies duration in seconds to allow maximum +write I/O operations limit. +*--size-iops-sec* specifies size I/O operations limit per second. +*--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 *device*. + +Older versions of virsh only accepted these options with underscore +instead of dash, as in *--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 *--live* is specified, affect a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. +When setting the disk io parameters both *--live* and *--config* flags may be +given, but *--current* is exclusive. For querying only one of *--live*, +*--config* or *--current* can be specified. If no flag is specified, behavior +is different depending on hypervisor. + + +blkiotune +--------- + +.. code-block:: shell + + blkiotune domain [--weight weight] [--device-weights device-weights] + [--device-read-iops-sec device-read-iops-sec] + [--device-write-iops-sec device-write-iops-sec] + [--device-read-bytes-sec device-read-bytes-sec] + [--device-write-bytes-sec device-write-bytes-sec] + [[--config] [--live] | [--current]] + +Display or set the blkio parameters. QEMU/KVM supports *--weight*. +*--weight* is in range [100, 1000]. After kernel 2.6.39, the value +could be in the range [10, 1000]. + +``device-weights`` 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. + +``device-read-iops-sec`` 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. + +``device-write-iops-sec`` 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. + +``device-read-bytes-sec`` 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. + +``device-write-bytes-sec`` 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 *--live* is specified, affect a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. If no flag is specified, behavior is different depending +on hypervisor. + + +blockcommit +----------- + +.. code-block:: shell + + blockcommit domain path [bandwidth] [--bytes] [base] + [--shallow] [top] [--delete] [--keep-relative] + [--wait [--async] [--verbose]] [--timeout seconds] + [--active] [{--pivot | --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 *base* +and/or *top* are specified as files within the backing chain, then the +operation is constrained to committing just that portion of the chain; +*--shallow* can be used instead of *base* 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 *--delete* flag will attempt to remove these invalidated +files at the successful completion of the commit operation. When the +*--keep-relative* flag is used, the backing file paths will be kept relative. + +When *top* is omitted or specified as the active image, it is also +possible to specify *--active* to trigger a two-phase active commit. In +the first phase, *top* is copied into *base* and the job can only be +canceled, with top still containing data not yet in base. In the second +phase, *top* and *base* remain identical until a call to ``blockjob`` +with the *--abort* flag (keeping top as the active image that tracks +changes from that point in time) or the *--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 ``blockjob``. However, if *--wait* is +specified, then this command will block until the operation completes +(or for *--active*, enters the second phase), or until the operation +is canceled because the optional *timeout* in seconds elapses +or SIGINT is sent (usually with ``Ctrl-C``). Using *--verbose* along +with *--wait* will produce periodic status updates. If job cancellation +is triggered, *--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 *--pivot* is shorthand +for combining *--active* *--wait* with an automatic ``blockjob`` +*--pivot*; and using *--keep-overlay* is shorthand for combining +*--active* *--wait* with an automatic ``blockjob`` *--abort*. + +*path* specifies fully-qualified path of the disk; it corresponds +to a unique target name (<target dev='name'/>) or source file (<source +file='name'/>) for one of the disk devices attached to *domain* (see +also ``domblklist`` for listing these names). +*bandwidth* 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 *bandwidth* argument see the corresponding section for the ``blockjob`` +command. + + +blockcopy +--------- + +.. code-block:: shell + + blockcopy domain path { dest [format] [--blockdev] | --xml file } + [--shallow] [--reuse-external] [bandwidth] + [--wait [--async] [--verbose]] [{--pivot | --finish}] + [--timeout seconds] [granularity] [buf-size] [--bytes] + [--transient-job] + +Copy a disk backing image chain to a destination. Either *dest* as +the destination file name, or *--xml* with the name of an XML file containing +a top-level <disk> element describing the destination, must be present. +Additionally, if *dest* is given, *format* should be specified to declare +the format of the destination (if *format* is omitted, then libvirt +will reuse the format of the source, or with *--reuse-external* will +be forced to probe the destination format, which could be a potential +security hole). The command supports *--raw* as a boolean flag synonym for +*--format=raw*. When using *dest*, the destination is treated as a regular +file unless *--blockdev* is used to signal that it is a block device. By +default, this command flattens the entire chain; but if *--shallow* is +specified, the copy shares the backing chain. + +If *--reuse-external* is specified, then the destination must exist and have +sufficient space to hold the copy. If *--shallow* is used in +conjunction with *--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 ``blockjob`` with the *--abort* and *--pivot* flags pivots over +to the copy, or a call without *--pivot* leaves the destination as a +faithful copy of that point in time. However, if *--wait* is specified, +then this command will block until the mirroring phase begins, or cancel +the operation if the optional *timeout* in seconds elapses or SIGINT is +sent (usually with ``Ctrl-C``). Using *--verbose* along with *--wait* +will produce periodic status updates. Using *--pivot* (similar to +``blockjob`` *--pivot*) or *--finish* (similar to ``blockjob`` *--abort*) +implies *--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 *--finish*, *--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. + +*path* specifies fully-qualified path of the disk. +*bandwidth* 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 *bandwidth* argument see the +corresponding section for the ``blockjob`` command. +Specifying *granularity* 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 *buf-size* 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). + +*--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. + + +blockjob +-------- + +.. code-block:: shell + + blockjob domain path { [--abort] [--async] [--pivot] | + [--info] [--raw] [--bytes] | [bandwidth] } + +Manage active block operations. There are three mutually-exclusive modes: +*--info*, *bandwidth*, and *--abort*. *--async* and *--pivot* imply +abort mode; *--raw* implies info mode; and if no mode was given, *--info* +mode is assumed. + +*path* specifies fully-qualified path of the disk; it corresponds +to a unique target name (<target dev='name'/>) or source file (<source +file='name'/>) for one of the disk devices attached to *domain* (see +also ``domblklist`` for listing these names). + +In *--abort* mode, the active job on the specified disk will +be aborted. If *--async* is also specified, this command will return +immediately, rather than waiting for the cancellation to complete. If +*--pivot* is specified, this requests that an active copy or active +commit job be pivoted over to the new image. + +In *--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 +*--raw* lists each field of the struct, in a stable format. If the +*--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. + +*bandwidth* can be used to set bandwidth limit for the active job in MiB/s. +If *--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 ``NOTES`` above). Using +*--bytes* with a scaled value permits a finer granularity to be selected. +A scaled value used without *--bytes* will be rounded down to MiB/s. Note +that the *--bytes* may be unsupported by the hypervisor. + + +blockpull +--------- + +.. code-block:: shell + + blockpull domain path [bandwidth] [--bytes] [base] + [--wait [--verbose] [--timeout seconds] [--async]] + [--keep-relative] + +Populate a disk from its backing image chain. By default, this command +flattens the entire chain; but if *base* 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 ``blockjob``. However, if *--wait* is +specified, then this command will block until the operation completes, +or cancel the operation if the optional *timeout* in seconds elapses +or SIGINT is sent (usually with ``Ctrl-C``). Using *--verbose* along +with *--wait* will produce periodic status updates. If job cancellation +is triggered, *--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 *--keep-relative* flag will keep the backing chain names +relative. + +*path* specifies fully-qualified path of the disk; it corresponds +to a unique target name (<target dev='name'/>) or source file (<source +file='name'/>) for one of the disk devices attached to *domain* (see +also ``domblklist`` for listing these names). +*bandwidth* specifies copying bandwidth limit in MiB/s. For further information +on the *bandwidth* argument see the corresponding section for the ``blockjob`` +command. + + +blockresize +----------- + +.. code-block:: shell + + blockresize domain path size + +Resize a block device of domain while the domain is running, *path* +specifies the absolute path of the block device; it corresponds +to a unique target name (<target dev='name'/>) or source file (<source +file='name'/>) for one of the disk devices attached to *domain* (see +also ``domblklist`` for listing these names). + +*size* is a scaled integer (see ``NOTES`` 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 +``vol-resize`` which defaults to bytes without a suffix). + + +console +------- + +.. code-block:: shell + + console domain [devname] [--safe] [--force] + +Connect the virtual serial console for the guest. The optional +*devname* parameter refers to the device alias of an alternate +console, serial or parallel device configured for the guest. +If omitted, the primary console will be opened. + +If the flag *--safe* is specified, the connection is only attempted +if the driver supports safe console handling. This flag specifies that +the server has to ensure exclusive access to console devices. Optionally +the *--force* flag may be specified, requesting to disconnect any existing +sessions, such as in a case of a broken connection. + + +cpu-stats +--------- + +.. code-block:: shell + + cpu-stats domain [--total] [start] [count] + +Provide cpu statistics information of a domain. The domain should +be running. Default it shows stats for all CPUs, and a total. Use +*--total* for only the total stats, *start* for only the per-cpu +stats of the CPUs from *start*, *count* for only *count* CPUs' +stats. + + +create +------ + +.. code-block:: shell + + create FILE [--console] [--paused] [--autodestroy] + [--pass-fds N,M,...] [--validate] + +Create a domain from an XML <file>. Optionally, *--validate* option can be +passed to validate the format of the input XML file against an internal RNG +schema (identical to using virt-xml-validate(1) tool). Domains created using +this command are going to be either transient (temporary ones that will vanish +once destroyed) or existing persistent domains that will run with one-time use +configuration, leaving the persistent XML untouched (this can come handy during +an automated testing of various configurations all based on the original XML). +See the ``Example`` section for usage demonstration. + +The domain will be paused if the *--paused* option is used +and supported by the driver; otherwise it will be running. If *--console* is +requested, attach to the console after creation. +If *--autodestroy* is requested, then the guest will be automatically +destroyed when virsh closes its connection to libvirt, or otherwise +exits. + +If *--pass-fds* is specified, the argument is a comma separated list +of open file descriptors which should be pass on into the guest. The +file descriptors will be re-numbered in the guest, starting from 3. This +is only supported with container based virtualization. + +Example +~~~~~~~ + +#. prepare a template from an existing domain (skip directly to 3a if writing + one from scratch) + + .. code-block:: shell + + # virsh dumpxml <domain> > domain.xml + +#. edit the template using an editor of your choice and: + + a. DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or + b. DON'T CHANGE! either <name> or <uuid> + + .. code-block:: shell + + # $EDITOR domain.xml + +#. create a domain from domain.xml, depending on whether following 2a or 2b + respectively: + + a. the domain is going to be transient + b. an existing persistent domain will run with a modified one-time + configuration + + .. code-block:: shell + + # virsh create domain.xml + + +define +------ + +.. code-block:: shell + + define FILE [--validate] + +Define a domain from an XML <file>. Optionally, the format of the input XML +file can be validated against an internal RNG schema with *--validate* +(identical to using virt-xml-validate(1) tool). The domain definition is +registered but not started. If domain is already running, the changes will take +effect on the next boot. + + +desc +---- + +.. code-block:: shell + + desc domain [[--live] [--config] | + [--current]] [--title] [--edit] [--new-desc + New description or title message] + +Show or modify description and title of a domain. These values are user +fields that allow storing arbitrary textual data to allow easy +identification of domains. Title should be short, although it's not enforced. +(See also ``metadata`` that works with XML based domain metadata.) + +Flags *--live* or *--config* select whether this command works on live +or persistent definitions of the domain. If both *--live* and *--config* +are specified, the *--config* option takes precedence on getting the current +description and both live configuration and config are updated while setting +the description. *--current* is exclusive and implied if none of these was +specified. + +Flag *--edit* specifies that an editor with the contents of current +description or title should be opened and the contents saved back afterwards. + +Flag *--title* selects operation on the title field instead of description. + +If neither of *--edit* and *--new-desc* are specified the note or description +is displayed instead of being modified. + + +destroy +------- + +.. code-block:: shell + + destroy domain [--graceful] + +Immediately terminate the domain *domain*. This doesn't give the domain +OS any chance to react, and it's the equivalent of ripping the power +cord out on a physical machine. In most cases you will want to use +the ``shutdown`` command instead. However, this does not delete any +storage volumes used by the guest, and if the domain is persistent, it +can be restarted later. + +If *domain* is transient, then the metadata of any snapshots will +be lost once the guest stops running, but the snapshot contents still +exist, and a new domain with the same name and UUID can restore the +snapshot metadata with ``snapshot-create``. Similarly, the metadata of +any checkpoints will be lost, but can be restored with ``checkpoint-create``. + +If *--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. + + + +domblkerror +----------- + +.. code-block:: shell + + domblkerror domain + +Show errors on block devices. This command usually comes handy when +``domstate`` command says that a domain was paused due to I/O error. +The ``domblkerror`` command lists all block devices in error state and +the error seen on each of them. + + + +domblkinfo +---------- + +.. code-block:: shell + + domblkinfo domain [block-device --all] [--human] + +Get block device size info for a domain. A *block-device* corresponds +to a unique target name (<target dev='name'/>) or source file (<source +file='name'/>) for one of the disk devices attached to *domain* (see +also ``domblklist`` for listing these names). If *--human* is set, the +output will have a human readable output. +If *--all* is set, the output will be a table showing all block devices +size info associated with *domain*. +The *--all* option takes precedence of the others. + + + +domblklist +---------- + +.. code-block:: shell + + domblklist domain [--inactive] [--details] + +Print a table showing the brief information of all block devices +associated with *domain*. If *--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 *--details* is specified, +disk type and device value will also be printed. Other contexts +that require a block device name (such as *domblkinfo* or +*snapshot-create* for disk snapshots) will accept either target +or unique source names printed by this command. + + + +domblkstat +---------- + +.. code-block:: shell + + domblkstat domain [block-device] [--human] + +Get device block stats for a running domain. A *block-device* corresponds +to a unique target name (<target dev='name'/>) or source file (<source +file='name'/>) for one of the disk devices attached to *domain* (see +also ``domblklist`` for listing these names). On a lxc or qemu domain, +omitting the *block-device* yields device block stats summarily for the +entire domain. + +Use *--human* for a more human readable output. + +Availability of these fields depends on hypervisor. Unsupported fields are +missing from the output. Other fields may appear if communicating with a newer +version of libvirtd. + +Explanation of fields (fields appear in the following order): + +* rd_req - count of read operations +* rd_bytes - count of read bytes +* wr_req - count of write operations +* wr_bytes - count of written bytes +* errs - error count +* flush_operations - count of flush operations +* rd_total_times - total time read operations took (ns) +* wr_total_times - total time write operations took (ns) +* flush_total_times - total time flush operations took (ns) +* <-- other fields provided by hypervisor --> + + + +domblkthreshold +--------------- + +.. code-block:: shell + + domblkthreshold domain dev threshold + +Set the threshold value for delivering the block-threshold event. *dev* +specifies the disk device target or backing chain element of given device using +the 'target[1]' syntax. *threshold* is a scaled value of the offset. If the +block device should write beyond that offset the event will be delivered. + + +domcontrol +---------- + +.. code-block:: shell + + domcontrol domain + +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. + + +domdisplay +---------- + +.. code-block:: shell + + domdisplay domain [--include-password] [[--type] type] [--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 ``type`` parameter (e.g. "vnc", "spice", "rdp"). If +*--include-password* is specified, the SPICE channel password will be +included in the URI. If *--all* is specified, then all show all possible +graphical displays, for a VM could have more than one graphical displays. + + +domfsfreeze +----------- + +.. code-block:: shell + + domfsfreeze domain [[--mountpoint] mountpoint...] + +Freeze mounted filesystems within a running domain to prepare for consistent +snapshots. + +The *--mountpoint* option takes a parameter ``mountpoint``, 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: ``snapshot-create`` command has a *--quiesce* option to freeze +and thaw the filesystems automatically to keep snapshots consistent. +``domfsfreeze`` command is only needed when a user wants to utilize the +native snapshot features of storage devices not supported by libvirt. + + +domfsinfo +--------- + +.. code-block:: shell + + domfsinfo domain + +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 (<target dev='name'/>). + +Note that this command requires a guest agent configured and running in the +domain's guest OS. + + +domfsthaw +--------- + +.. code-block:: shell + + domfsthaw domain [[--mountpoint] mountpoint...] + +Thaw mounted filesystems within a running domain, which have been frozen by +domfsfreeze command. + +The *--mountpoint* option takes a parameter ``mountpoint``, 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. + + +domfstrim +--------- + +.. code-block:: shell + + domfstrim domain [--minimum bytes] [--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 *--minimum* ``bytes`` 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 *--mountpoint* parameter. + + +domhostname +----------- + +.. code-block:: shell + + domhostname domain + +Returns the hostname of a domain, if the hypervisor makes it available. + + +domid +----- + +.. code-block:: shell + + domid domain-name-or-uuid + +Convert a domain name (or UUID) to a domain id + + +domif +----- + +.. code-block:: shell + + domif-getlink domain interface-device [--config] + +Query link state of the domain's virtual interface. If *--config* +is specified, query the persistent configuration, for compatibility +purposes, *--persistent* is alias of *--config*. + +*interface-device* can be the interface's target name or the MAC address. + + +domif +----- + +.. code-block:: shell + + domif-setlink domain interface-device state [--config] + +Modify link state of the domain's virtual interface. Possible values for +state are "up" and "down". If *--config* is specified, only the persistent +configuration of the domain is modified, for compatibility purposes, +*--persistent* is alias of *--config*. +*interface-device* can be the interface's target name or the MAC address. + + +domifaddr +--------- + +.. code-block:: shell + + domifaddr domain [interface] [--full] + [--source lease|agent|arp] + +Get a list of interfaces of a running domain along with their IP and MAC +addresses, or limited output just for one interface if *interface* is +specified. Note that *interface* can be driver dependent, it can be the name +within guest OS or the name you would see in domain XML. Moreover, the whole +command may require a guest agent to be configured for the queried domain under +some hypervisors, notably QEMU. + +If *--full* is specified, the interface name and MAC address is always +displayed when the interface has multiple IP addresses or aliases; otherwise, +only the interface name and MAC address is displayed for the first name and +MAC address with "-" for the others using the same name and MAC address. + +The *--source* argument specifies what data source to use for the +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. + + +domiflist +--------- + +.. code-block:: shell + + domiflist domain [--inactive] + +Print a table showing the brief information of all virtual interfaces +associated with *domain*. If *--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 *detach-interface* or +*domif-setlink*) will accept the MAC address printed by this command. + + +domifstat +--------- + +.. code-block:: shell + + domifstat domain interface-device + +Get network interface stats for a running domain. The network +interface stats are only available for interfaces that have a +physical source interface. This does not include, for example, a +'user' interface type since it is a virtual LAN with NAT to the +outside world. *interface-device* can be the interface target by +name or MAC address. + + +domiftune +--------- + +.. code-block:: shell + + domiftune domain interface-device [[--config] [--live] | [--current]] + [*--inbound average,peak,burst,floor*] + [*--outbound average,peak,burst*] + +Set or query the domain's network interface's bandwidth parameters. +*interface-device* can be the interface's target name (<target dev='name'/>), +or the MAC address. + +If no *--inbound* or *--outbound* is specified, this command will +query and show the bandwidth settings. Otherwise, it will set the +inbound or outbound bandwidth. *average,peak,burst,floor* is the same as +in command *attach-interface*. Values for *average*, *peak* and *floor* +are expressed in kilobytes per second, while *burst* is expressed in kilobytes +in a single burst at *peak* speed as described in the Network XML +documentation at `https://libvirt.org/formatnetwork.html#elementQoS <https://libvirt.org/formatnetwork.html#elementQoS>`_. + +To clear inbound or outbound settings, use *--inbound* or *--outbound* +respectfully with average value of zero. + +If *--live* is specified, affect a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. If no flag is specified, behavior is different depending +on hypervisor. + + +dominfo +------- + +.. code-block:: shell + + dominfo domain + +Returns basic information about the domain. + + +domjobabort +----------- + +.. code-block:: shell + + domjobabort domain + +Abort the currently running domain job. + + +domjobinfo +---------- + +.. code-block:: shell + + domjobinfo domain [--completed [--keep-completed]] [--anystats] [--rawstats] + +Returns information about jobs running on a domain. *--completed* tells +virsh to return information about a recently finished job. Statistics of +a completed job are automatically destroyed once read (unless +*--keep-completed* is used) or when libvirtd is restarted. + +Normally only statistics for running and successful completed jobs are printed. +*--anystats* can be used to also display statistics for failed jobs. + +In case *--rawstats* is used, all fields are printed as received from the +server without any attempts to interpret the data. The "Job type:" field is +special, since it's reported by the API and not part of stats. + +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). + + +dommemstat +---------- + +.. code-block:: shell + + dommemstat domain [--period seconds] [[--config] [--live] | [--current]] + +Get memory stats for a running domain. + +Availability of these fields depends on hypervisor. Unsupported fields are +missing from the output. Other fields may appear if communicating with a newer +version of libvirtd. + +Explanation of fields: + +* ``swap_in`` - The amount of data read from swap space (in KiB) +* ``swap_out`` - The amount of memory written out to swap space (in KiB) +* ``major_fault`` - The number of page faults where disk IO was required +* ``minor_fault`` - The number of other page faults +* ``unused`` - The amount of memory left unused by the system (in KiB) +* ``available`` - The amount of usable memory as seen by the domain (in KiB) +* ``actual`` - Current balloon value (in KiB) +* ``rss`` - Resident Set Size of the running domain's process (in KiB) +* ``usable`` - The amount of memory which can be reclaimed by balloon + without causing host swapping (in KiB) +* ``last-update`` - Timestamp of the last update of statistics (in seconds) +* ``disk_caches`` - The amount of memory that can be reclaimed without + additional I/O, typically disk caches (in KiB) +* ``hugetlb_pgalloc`` - The number of successful huge page allocations initiated + from within the domain +* ``hugetlb_pgfail`` - The number of failed huge page allocations initiated from + within the domain + +For QEMU/KVM with a memory balloon, setting the optional *--period* to a +value larger than 0 in seconds will allow the balloon driver to return +additional statistics which will be displayed by subsequent ``dommemstat`` +commands. Setting the *--period* to 0 will stop the balloon driver collection, +but does not clear the statistics in the balloon driver. Requires at least +QEMU/KVM 1.5 to be running on the host. + +The *--live*, *--config*, and *--current* flags are only valid when using +the *--period* option in order to set the collection period for the balloon +driver. If *--live* is specified, only the running guest collection period +is affected. If *--config* is specified, affect the next boot of a persistent +guest. If *--current* is specified, affect the current guest state. + +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. If no flag is specified, behavior is different depending +on the guest state. + + +domname +------- + +.. code-block:: shell + + domname domain-id-or-uuid + +Convert a domain Id (or UUID) to domain name + + +dompmsuspend +------------ + +.. code-block:: shell + + dompmsuspend domain target [--duration] + +Suspend a running domain into one of these states (possible *target* +values): + +* ``mem`` - equivalent of S3 ACPI state +* ``disk`` - equivalent of S4 ACPI state +* ``hybrid`` - RAM is saved to disk but not powered off + +The *--duration* argument specifies number of seconds before the domain is +woken up after it was suspended (see also ``dompmwakeup``). Default is 0 for +unlimited suspend time. (This feature isn't currently supported by any +hypervisor driver and 0 should be used.). + +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 *--config* flag. + + +dompmwakeup +----------- + +.. code-block:: shell + + dompmwakeup domain + +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. + + +domrename +--------- + +.. code-block:: shell + + domrename domain new-name + +Rename a domain. This command changes current domain name to the new name +specified in the second argument. + +``Note``: Domain must be inactive and without snapshots or checkpoints. + + +domstate +-------- + +.. code-block:: shell + + domstate domain [--reason] + +Returns state about a domain. *--reason* tells virsh to also print +reason for the state. + + +domstats +-------- + +.. code-block:: shell + + domstats [--raw] [--enforce] [--backing] [--nowait] [--state] + [--cpu-total] [--balloon] [--vcpu] [--interface] + [--block] [--perf] [--iothread] + [[--list-active] [--list-inactive] + [--list-persistent] [--list-transient] [--list-running]y + [--list-paused] [--list-shutoff] [--list-other]] | [domain ...] + +Get statistics for multiple or all domains. Without any argument this +command prints all available statistics for all domains. + +The list of domains to gather stats for can be either limited by listing +the domains as a space separated list, or by specifying one of the +filtering flags *--list-NNN*. (The approaches can't be combined.) + +By default some of the returned fields may be converted to more +human friendly values by a set of pretty-printers. To suppress this +behavior use the *--raw* flag. + +The individual statistics groups are selectable via specific flags. By +default all supported statistics groups are returned. Supported +statistics groups flags are: *--state*, *--cpu-total*, *--balloon*, +*--vcpu*, *--interface*, *--block*, *--perf*, *--iothread*. + +Note that - depending on the hypervisor type and version or the domain state +- not all of the following statistics may be returned. + +When selecting the *--state* group the following fields are returned: + + +* ``state.state`` - state of the VM, returned as number from + virDomainState enum +* ``state.reason`` - reason for entering given state, returned + as int from virDomain*Reason enum corresponding + to given state + + +*--cpu-total* returns: + + +* ``cpu.time`` - total cpu time spent for this domain in nanoseconds +* ``cpu.user`` - user cpu time spent in nanoseconds +* ``cpu.system`` - system cpu time spent in nanoseconds +* ``cpu.cache.monitor.count`` - the number of cache monitors for this + domain +* ``cpu.cache.monitor.<num>.name`` - the name of cache monitor <num> +* ``cpu.cache.monitor.<num>.vcpus`` - vcpu list of cache monitor <num> +* ``cpu.cache.monitor.<num>.bank.count`` - the number of cache banks + in cache monitor <num> +* ``cpu.cache.monitor.<num>.bank.<index>.id`` - host allocated cache id + for bank <index> in cache monitor <num> +* ``cpu.cache.monitor.<num>.bank.<index>.bytes`` - the number of bytes + of last level cache that the domain is using on cache bank <index> + + +*--balloon* returns: + +* ``balloon.current`` - the memory in KiB currently used +* ``balloon.maximum`` - the maximum memory in KiB allowed +* ``balloon.swap_in`` - the amount of data read from swap space (in KiB) +* ``balloon.swap_out`` - the amount of memory written out to swap + space (in KiB) +* ``balloon.major_fault`` - the number of page faults then disk IO + was required +* ``balloon.minor_fault`` - the number of other page faults +* ``balloon.unused`` - the amount of memory left unused by the + system (in KiB) +* ``balloon.available`` - the amount of usable memory as seen by + the domain (in KiB) +* ``balloon.rss`` - Resident Set Size of running domain's process + (in KiB) +* ``balloon.usable`` - the amount of memory which can be reclaimed by + balloon without causing host swapping (in KiB) +* ``balloon.last-update`` - timestamp of the last update of statistics + (in seconds) +* ``balloon.disk_caches`` - the amount of memory that can be reclaimed + without additional I/O, typically disk (in KiB) + + +*--vcpu* returns: + +* ``vcpu.current`` - current number of online virtual CPUs +* ``vcpu.maximum`` - maximum number of online virtual CPUs +* ``vcpu.<num>.state`` - state of the virtual CPU <num>, as + number from virVcpuState enum +* ``vcpu.<num>.time`` - virtual cpu time spent by virtual + CPU <num> (in microseconds) +* ``vcpu.<num>.wait`` - virtual cpu time spent by virtual + CPU <num> waiting on I/O (in microseconds) +* ``vcpu.<num>.halted`` - virtual CPU <num> is halted: yes or + no (may indicate the processor is idle or even disabled, + depending on the architecture) + + +*--interface* returns: + +* ``net.count`` - number of network interfaces on this domain +* ``net.<num>.name`` - name of the interface <num> +* ``net.<num>.rx.bytes`` - number of bytes received +* ``net.<num>.rx.pkts`` - number of packets received +* ``net.<num>.rx.errs`` - number of receive errors +* ``net.<num>.rx.drop`` - number of receive packets dropped +* ``net.<num>.tx.bytes`` - number of bytes transmitted +* ``net.<num>.tx.pkts`` - number of packets transmitted +* ``net.<num>.tx.errs`` - number of transmission errors +* ``net.<num>.tx.drop`` - number of transmit packets dropped + + +*--perf* returns the statistics of all enabled perf events: + +* ``perf.cmt`` - the cache usage in Byte currently used +* ``perf.mbmt`` - total system bandwidth from one level of cache +* ``perf.mbml`` - bandwidth of memory traffic for a memory controller +* ``perf.cpu_cycles`` - the count of cpu cycles (total/elapsed) +* ``perf.instructions`` - the count of instructions +* ``perf.cache_references`` - the count of cache hits +* ``perf.cache_misses`` - the count of caches misses +* ``perf.branch_instructions`` - the count of branch instructions +* ``perf.branch_misses`` - the count of branch misses +* ``perf.bus_cycles`` - the count of bus cycles +* ``perf.stalled_cycles_frontend`` - the count of stalled frontend + cpu cycles +* ``perf.stalled_cycles_backend`` - the count of stalled backend + cpu cycles +* ``perf.ref_cpu_cycles`` - the count of ref cpu cycles +* ``perf.cpu_clock`` - the count of cpu clock time +* ``perf.task_clock`` - the count of task clock time +* ``perf.page_faults`` - the count of page faults +* ``perf.context_switches`` - the count of context switches +* ``perf.cpu_migrations`` - the count of cpu migrations +* ``perf.page_faults_min`` - the count of minor page faults +* ``perf.page_faults_maj`` - the count of major page faults +* ``perf.alignment_faults`` - the count of alignment faults +* ``perf.emulation_faults`` - the count of emulation faults + + +See the ``perf`` command for more details about each event. + +*--block* returns information about disks associated with each +domain. Using the *--backing* flag extends this information to +cover all resources in the backing chain, rather than the default +of limiting information to the active layer for each guest disk. +Information listed includes: + + +* ``block.count`` - number of block devices being listed +* ``block.<num>.name`` - name of the target of the block + device <num> (the same name for multiple entries if I<--backing> + is present) +* ``block.<num>.backingIndex`` - when I<--backing> is present, + matches up with the <backingStore> index listed in domain XML for + backing files +* ``block.<num>.path`` - file source of block device <num>, if + it is a local file or block device +* ``block.<num>.rd.reqs`` - number of read requests +* ``block.<num>.rd.bytes`` - number of read bytes +* ``block.<num>.rd.times`` - total time (ns) spent on reads +* ``block.<num>.wr.reqs`` - number of write requests +* ``block.<num>.wr.bytes`` - number of written bytes +* ``block.<num>.wr.times`` - total time (ns) spent on writes +* ``block.<num>.fl.reqs`` - total flush requests +* ``block.<num>.fl.times`` - total time (ns) spent on cache flushing +* ``block.<num>.errors`` - Xen only: the 'oo_req' value +* ``block.<num>.allocation`` - offset of highest written sector in bytes +* ``block.<num>.capacity`` - logical size of source file in bytes +* ``block.<num>.physical`` - physical size of source file in bytes +* ``block.<num>.threshold`` - threshold (in bytes) for delivering the + VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event. See domblkthreshold. + + +*--iothread* returns information about IOThreads on the running guest +if supported by the hypervisor. + +The "poll-max-ns" for each thread is the maximum nanoseconds to allow +each polling interval to occur. A polling interval is a period of time +allowed for a thread to process data before being the guest gives up +its CPU quantum back to the host. A value set too small will not allow +the IOThread to run long enough on a CPU to process data. A value set +too high will consume too much CPU time per IOThread failing to allow +other threads running on the CPU to get time. The polling interval is +not available for statistical purposes. + +* ``iothread.<id>.poll-max-ns`` - maximum polling time in nanoseconds used + by the <id> IOThread. A value of 0 (zero) indicates polling is disabled. +* ``iothread.<id>.poll-grow`` - polling time grow value. A value of 0 (zero) + growth is managed by the hypervisor. +* ``iothread.<id>.poll-shrink`` - polling time shrink value. A value of + (zero) indicates shrink is managed by hypervisor. + +Selecting a specific statistics groups doesn't guarantee that the +daemon supports the selected group of stats. Flag *--enforce* +forces the command to fail if the daemon doesn't support the +selected group. + +When collecting stats libvirtd may wait for some time if there's +already another job running on given domain for it to finish. +This may cause unnecessary delay in delivering stats. Using +*--nowait* suppresses this behaviour. On the other hand +some statistics might be missing for such domain. + + +domtime +------- + +.. code-block:: shell + + domtime domain { [--now] [--pretty] [--sync] [--time time] } + +Gets or sets the domain's system time. When run without any arguments +(but *domain*), the current domain's system time is printed out. The +*--pretty* modifier can be used to print the time in more human +readable form. + +When *--time* ``time`` is specified, the domain's time is +not gotten but set instead. The *--now* modifier acts like if it was +an alias for *--time* ``$now``, which means it sets the time that is +currently on the host virsh is running at. In both cases (setting and +getting), time is in seconds relative to Epoch of 1970-01-01 in UTC. +The *--sync* modifies the set behavior a bit: The time passed is +ignored, but the time to set is read from domain's RTC instead. Please +note, that some hypervisors may require a guest agent to be configured +in order to get or set the guest time. + + +domuuid +------- + +.. code-block:: shell + + domuuid domain-name-or-id + +Convert a domain name or id to domain UUID + + +domxml +------ + +.. code-block:: shell + + domxml-from-native format config + +Convert the file *config* in the native guest configuration format +named by *format* to a domain XML format. For QEMU/KVM hypervisor, +the *format* argument must be ``qemu-argv``. For Xen hypervisor, the +*format* argument may be ``xen-xm``, ``xen-xl``, or ``xen-sxpr``. For +LXC hypervisor, the *format* argument must be ``lxc-tools``. For +VMware/ESX hypervisor, the *format* argument must be ``vmware-vmx``. +For the Bhyve hypervisor, the *format* argument must be ``bhyve-argv``. + + +domxml +------ + +.. code-block:: shell + + domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-uuid } + +Convert the file *xml* into domain XML format or convert an existing +*--domain* to the native guest configuration format named by *format*. +The *xml* and *--domain* arguments are mutually exclusive. For the types +of *format* argument, refer to ``domxml-from-native``. + + +dump +---- + +.. code-block:: shell + + dump domain corefilepath [--bypass-cache] + { [--live] | [--crash] | [--reset] } + [--verbose] [--memory-only] [--format string] + +Dumps the core of a domain to a file for analysis. +If *--live* is specified, the domain continues to run until the core +dump is complete, rather than pausing up front. +If *--crash* is specified, the domain is halted with a crashed status, +rather than merely left in a paused state. +If *--reset* is specified, the domain is reset after successful dump. +Note, these three switches are mutually exclusive. +If *--bypass-cache* is specified, the save will avoid the file system +cache, although this may slow down the operation. +If *--memory-only* is specified, the file is elf file, and will only +include domain's memory and cpu common register value. It is very +useful if the domain uses host devices directly. +*--format* *string* is used to specify the format of 'memory-only' +dump, and *string* can be one of them: elf, kdump-zlib(kdump-compressed +format with zlib-compressed), kdump-lzo(kdump-compressed format with +lzo-compressed), kdump-snappy(kdump-compressed format with snappy-compressed). + +The progress may be monitored using ``domjobinfo`` virsh command and canceled +with ``domjobabort`` command (sent by another virsh instance). Another option +is to send SIGINT (usually with ``Ctrl-C``) to the virsh process running +``dump`` command. *--verbose* displays the progress of dump. + +NOTE: Some hypervisors may require the user to manually ensure proper +permissions on file and path specified by argument *corefilepath*. + +NOTE: Crash dump in a old kvmdump format is being obsolete and cannot be loaded +and processed by crash utility since its version 6.1.0. A --memory-only option +is required in order to produce valid ELF file which can be later processed by +the crash utility. + + +dumpxml +------- + +.. code-block:: shell + + dumpxml domain [--inactive] [--security-info] [--update-cpu] [--migratable] + +Output the domain information as an XML dump to stdout, this format can be used +by the ``create`` command. Additional options affecting the XML dump may be +used. *--inactive* tells virsh to dump domain configuration that will be used +on next start of the domain as opposed to the current domain configuration. +Using *--security-info* will also include security sensitive information +in the XML dump. *--update-cpu* updates domain CPU requirements according to +host CPU. With *--migratable* one can request an XML that is suitable for +migrations, i.e., compatible with older libvirt releases and possibly amended +with internal run-time options. This option may automatically enable other +options (*--update-cpu*, *--security-info*, ...) as necessary. + + +edit +---- + +.. code-block:: shell + + edit domain + +Edit the XML configuration file for a domain, which will affect the +next boot of the guest. + +This is equivalent to: + +.. code-block:: shell + + virsh dumpxml --inactive --security-info domain > domain.xml + vi domain.xml (or make changes with your other text editor) + virsh define domain.xml + +except that it does some error checking. + +The editor used can be supplied by the ``$VISUAL`` or ``$EDITOR`` environment +variables, and defaults to ``vi``. + + +emulatorpin +----------- + +.. code-block:: shell + + emulatorpin domain [cpulist] [[--live] [--config] | [--current]] + +Query or change the pinning of domain's emulator threads to host physical +CPUs. + +See ``vcpupin`` for *cpulist*. + +If *--live* is specified, affect a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. +Both *--live* and *--config* flags may be given if *cpulist* is present, +but *--current* is exclusive. +If no flag is specified, behavior is different depending on hypervisor. + + +event +----- + +.. code-block:: shell + + event {[domain] { event | --all } [--loop] [--timeout seconds] [--timestamp] | --list} + +Wait for a class of domain events to occur, and print appropriate details +of events as they happen. The events can optionally be filtered by +*domain*. Using *--list* as the only argument will provide a list +of possible *event* values known by this client, although the connection +might not allow registering for all these events. It is also possible +to use *--all* instead of *event* to register for all possible event +types at once. + +By default, this command is one-shot, and returns success once an event +occurs; you can send SIGINT (usually via ``Ctrl-C``) to quit immediately. +If *--timeout* is specified, the command gives up waiting for events +after *seconds* have elapsed. With *--loop*, the command prints all +events until a timeout or interrupt key. + +When *--timestamp* is used, a human-readable timestamp will be printed +before the event. + + +guest +----- + +.. code-block:: shell + + guest-agent-timeout domain --timeout value + +Set how long to wait for a response from guest agent commands. By default, +agent commands block forever waiting for a response. ``value`` must be a +positive value (wait for given amount of seconds) or one of the following +values: + +* -2 - block forever waiting for a result, +* -1 - reset timeout to the default value, +* 0 - do not wait at all, + + +guestinfo +--------- + +.. code-block:: shell + + guestinfo domain [--user] [--os] [--timezone] [--hostname] [--filesystem] + +Print information about the guest from the point of view of the guest agent. +Note that this command requires a guest agent to be configured and running in +the domain's guest OS. + +When run without any arguments, this command prints all information types that +are supported by the guest agent. You can limit the types of information that +are returned by specifying one or more flags. If a requested information +type is not supported, the processes will provide an exit code of 1. +Available information types flags are *--user*, *--os*, +*--timezone*, *--hostname*, and *--filesystem*. + +Note that depending on the hypervisor type and the version of the guest agent +running within the domain, not all of the following information may be +returned. + +When selecting the *--user* information type, the following fields may be +returned: + + +* ``user.count`` - the number of active users on this domain +* ``user.<num>.name`` - username of user <num> +* ``user.<num>.domain`` - domain of the user <num> (may only be present on certain + guets types) +* ``user.<num>.login-time`` - the login time of user <num> in milliseconds since + the epoch + + +*--os* returns: + +* ``os.id`` - a string identifying the operating system +* ``os.name`` - the name of the operating system +* ``os.pretty-name`` - a pretty name for the operating system +* ``os.version`` - the version of the operating system +* ``os.version-id`` - the version id of the operating system +* ``os.kernel-release`` - the release of the operating system kernel +* ``os.kernel-version`` - the version of the operating system kernel +* ``os.machine`` - the machine hardware name +* ``os.variant`` - a specific variant or edition of the operating system +* ``os.variant-id`` - the id for a specific variant or edition of the operating + system + + +*--timezone* returns: + +* ``timezone.name`` - the name of the timezone +* ``timezone.offset`` - the offset to UTC in seconds + + +*--hostname* returns: + +* ``hostname`` - the hostname of the domain + + +*--filesystem* returns: + +* ``fs.count`` - the number of filesystems defined on this domain +* ``fs.<num>.mountpoint`` - the path to the mount point for filesystem <num> +* ``fs.<num>.name`` - device name in the guest (e.g. ``sda1``) for filesystem <num> +* ``fs.<num>.fstype`` - the type of filesystem <num> +* ``fs.<num>.total-bytes`` - the total size of filesystem <num> +* ``fs.<num>.used-bytes`` - the number of bytes used in filesystem <num> +* ``fs.<num>.disk.count`` - the number of disks targeted by filesystem <num> +* ``fs.<num>.disk.<num>.alias`` - the device alias of disk <num> (e.g. sda) +* ``fs.<num>.disk.<num>.serial`` - the serial number of disk <num> +* ``fs.<num>.disk.<num>.device`` - the device node of disk <num> + + +guestvcpus +---------- + +.. code-block:: shell + + guestvcpus domain [[--enable] | [--disable]] [cpulist] + +Query or change state of vCPUs from guest's point of view using the guest agent. +When invoked without *cpulist* the guest is queried for available guest vCPUs, +their state and possibility to be offlined. + +If *cpulist* is provided then one of *--enable* or *--disable* must be +provided too. The desired operation is then executed on the domain. + +See ``vcpupin`` for information on *cpulist*. + + +iothreadadd +----------- + +.. code-block:: shell + + iothreadadd domain iothread_id [[--config] [--live] | [--current]] + +Add a new IOThread to the domain using the specified *iothread_id*. +If the *iothread_id* already exists, the command will fail. The +*iothread_id* must be greater than zero. + +If *--live* is specified, affect a running guest. If the guest is not +running an error is returned. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified or *--live* and *--config* are not specified, +affect the current guest state. + + +iothreaddel +----------- + +.. code-block:: shell + + iothreaddel domain iothread_id [[--config] [--live] | [--current]] + +Delete an IOThread from the domain using the specified *iothread_id*. +If an IOThread is currently assigned to a disk resource such as via the +``attach-disk`` command, then the attempt to remove the IOThread will fail. +If the *iothread_id* does not exist an error will occur. + +If *--live* is specified, affect a running guest. If the guest is not +running an error is returned. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified or *--live* and *--config* are not specified, +affect the current guest state. + + +iothreadinfo +------------ + +.. code-block:: shell + + iothreadinfo domain [[--live] [--config] | [--current]] + +Display basic domain IOThreads information including the IOThread ID and +the CPU Affinity for each IOThread. + +If *--live* is specified, get the IOThreads data from the running guest. If +the guest is not running, an error is returned. +If *--config* is specified, get the IOThreads data from the next boot of +a persistent guest. +If *--current* is specified or *--live* and *--config* are not specified, +then get the IOThread data based on the current guest state. + + +iothreadpin +----------- + +.. code-block:: shell + + iothreadpin domain iothread cpulist [[--live] [--config] | [--current]] + +Change the pinning of a domain IOThread to host physical CPUs. In order +to retrieve a list of all IOThreads, use ``iothreadinfo``. To pin an +*iothread* specify the *cpulist* desired for the IOThread ID as listed +in the ``iothreadinfo`` output. + +*cpulist* is a list of physical CPU numbers. Its syntax is a comma +separated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2') can +also be allowed. The '-' denotes the range and the '^' denotes exclusive. +If you want to reset iothreadpin setting, that is, to pin an *iothread* +to all physical cpus, simply specify 'r' as a *cpulist*. + +If *--live* is specified, affect a running guest. If the guest is not running, +an error is returned. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified or *--live* and *--config* are not specified, +affect the current guest state. +Both *--live* and *--config* flags may be given if *cpulist* is present, +but *--current* is exclusive. +If no flag is specified, behavior is different depending on hypervisor. + +``Note``: The expression is sequentially evaluated, so "0-15,^8" is +identical to "9-14,0-7,15" but not identical to "^8,0-15". + + +iothreadset +----------- + +.. code-block:: shell + + iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor] + [--poll-shrink divisor]] + [[--config] [--live] | [--current]] + +Modifies an existing iothread of the domain using the specified +*iothread_id*. The *--poll-max-ns* provides the maximum polling +interval to be allowed for an IOThread in ns. If a 0 (zero) is provided, +then polling for the IOThread is disabled. The *--poll-grow* is the +factor by which the current polling time will be adjusted in order to +reach the maximum polling time. If a 0 (zero) is provided, then the +default factor will be used. The *--poll-shrink* is the quotient +by which the current polling time will be reduced in order to get +below the maximum polling interval. If a 0 (zero) is provided, then +the default quotient will be used. The polling values are purely dynamic +for a running guest. Saving, destroying, stopping, etc. the guest will +result in the polling values returning to hypervisor defaults at the +next start, restore, etc. + +If *--live* is specified, affect a running guest. If the guest is not +running an error is returned. +If *--current* is specified or *--live* is not specified, then handle +as if *--live* was specified. + + +managedsave +----------- + +.. code-block:: shell + + managedsave domain [--bypass-cache] [{--running | --paused}] [--verbose] + +Save and destroy (stop) a running domain, so it can be restarted from the same +state at a later time. When the virsh ``start`` command is next run for +the domain, it will automatically be started from this saved state. +If *--bypass-cache* is specified, the save will avoid the file system +cache, although this may slow down the operation. + +The progress may be monitored using ``domjobinfo`` virsh command and canceled +with ``domjobabort`` command (sent by another virsh instance). Another option +is to send SIGINT (usually with ``Ctrl-C``) to the virsh process running +``managedsave`` command. *--verbose* displays the progress of save. + +Normally, starting a managed save will decide between running or paused +based on the state the domain was in when the save was done; passing +either the *--running* or *--paused* flag will allow overriding which +state the ``start`` should use. + +The ``dominfo`` command can be used to query whether a domain currently +has any managed save image. + + +managedsave-define +------------------ + +.. code-block:: shell + + managedsave-define domain xml [{--running | --paused}] + +Update the domain XML that will be used when *domain* is later +started. The *xml* argument must be a file name containing +the alternative XML, with changes only in the host-specific portions of +the domain XML. For example, it can be used to change disk file paths. + +The managed save image records whether the domain should be started to a +running or paused state. Normally, this command does not alter the +recorded state; passing either the *--running* or *--paused* flag +will allow overriding which state the ``start`` should use. + + +managedsave-dumpxml +------------------- + +.. code-block:: shell + + managedsave-dumpxml domain [--security-info] + +Extract the domain XML that was in effect at the time the saved state +file *file* was created with the ``managedsave`` command. Using +*--security-info* will also include security sensitive information. + + +managedsave-edit +---------------- + +.. code-block:: shell + + managedsave-edit domain [{--running | --paused}] + +Edit the XML configuration associated with a saved state file of a +*domain* was created by the ``managedsave`` command. + +The managed save image records whether the domain should be started to a +running or paused state. Normally, this command does not alter the +recorded state; passing either the *--running* or *--paused* flag +will allow overriding which state the ``restore`` should use. + +This is equivalent to: + +.. code-block:: shell + + virsh managedsave-dumpxml domain-name > state-file.xml + vi state-file.xml (or make changes with your other text editor) + virsh managedsave-define domain-name state-file-xml + +except that it does some error checking. + +The editor used can be supplied by the ``$VISUAL`` or ``$EDITOR`` environment +variables, and defaults to ``vi``. + + +managedsave-remove +------------------ + +.. code-block:: shell + + managedsave-remove domain + +Remove the ``managedsave`` state file for a domain, if it exists. This +ensures the domain will do a full boot the next time it is started. + + +maxvcpus +-------- + +.. code-block:: shell + + maxvcpus [type] + +Provide the maximum number of virtual CPUs supported for a guest VM on +this connection. If provided, the *type* parameter must be a valid +type attribute for the <domain> element of XML. + + +memtune +------- + +.. code-block:: shell + + memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-limit size] + [--min-guarantee size] [[--config] [--live] | [--current]] + +Allows you to display or set the domain memory parameters. Without +flags, the current settings are displayed; with a flag, the +appropriate limit is adjusted if supported by the hypervisor. LXC and +QEMU/KVM support *--hard-limit*, *--soft-limit*, and *--swap-hard-limit*. +*--min-guarantee* is supported only by ESX hypervisor. Each of these +limits are scaled integers (see ``NOTES`` above), with a default of +kibibytes (blocks of 1024 bytes) if no suffix is present. Libvirt rounds +up to the nearest kibibyte. Some hypervisors require a larger granularity +than KiB, and requests that are not an even multiple will be rounded up. +For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes). + +If *--live* is specified, affect a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. If no flag is specified, behavior is different depending +on hypervisor. + +For QEMU/KVM, the parameters are applied to the QEMU process as a whole. +Thus, when counting them, one needs to add up guest RAM, guest video RAM, and +some memory overhead of QEMU itself. The last piece is hard to determine so +one needs guess and try. + +For LXC, the displayed hard_limit value is the current memory setting +from the XML or the results from a ``virsh setmem`` command. + + +- *--hard-limit* + + The maximum memory the guest can use. + +- *--soft-limit* + + The memory limit to enforce during memory contention. + +- *--swap-hard-limit* + + The maximum memory plus swap the guest can use. This has to be more + than hard-limit value provided. + +- *--min-guarantee* + + The guaranteed minimum memory allocation for the guest. + + +Specifying -1 as a value for these limits is interpreted as unlimited. + + +metadata +-------- + +.. code-block:: shell + + metadata domain [[--live] [--config] | [--current]] + [--edit] [uri] [key] [set] [--remove] + +Show or modify custom XML metadata of a domain. The metadata is a user +defined XML that allows storing arbitrary XML data in the domain definition. +Multiple separate custom metadata pieces can be stored in the domain XML. +The pieces are identified by a private XML namespace provided via the +*uri* argument. (See also ``desc`` that works with textual metadata of +a domain.) + +Flags *--live* or *--config* select whether this command works on live +or persistent definitions of the domain. If both *--live* and *--config* +are specified, the *--config* option takes precedence on getting the current +description and both live configuration and config are updated while setting +the description. *--current* is exclusive and implied if none of these was +specified. + +Flag *--remove* specifies that the metadata element specified by the *uri* +argument should be removed rather than updated. + +Flag *--edit* specifies that an editor with the metadata identified by the +*uri* argument should be opened and the contents saved back afterwards. +Otherwise the new contents can be provided via the *set* argument. + +When setting metadata via *--edit* or *set* the *key* argument must be +specified and is used to prefix the custom elements to bind them +to the private namespace. + +If neither of *--edit* and *set* are specified the XML metadata corresponding +to the *uri* namespace is displayed instead of being modified. + + +migrate +------- + +.. code-block:: shell + + migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]] + [--persistent] [--undefinesource] [--suspend] [--copy-storage-all] + [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose] + [--rdma-pin-all] [--abort-on-error] [--postcopy] [--postcopy-after-precopy] + domain desturi [migrateuri] [graphicsuri] [listen-address] [dname] + [--timeout seconds [--timeout-suspend | --timeout-postcopy]] + [--xml file] [--migrate-disks disk-list] [--disks-port port] + [--compressed] [--comp-methods method-list] + [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads] + [--comp-xbzrle-cache] [--auto-converge] [auto-converge-initial] + [auto-converge-increment] [--persistent-xml file] [--tls] + [--postcopy-bandwidth bandwidth] + [--parallel [--parallel-connections connections]] + [--bandwidth bandwidth] + +Migrate domain to another host. Add *--live* for live migration; <--p2p> +for peer-2-peer migration; *--direct* for direct migration; or *--tunnelled* +for tunnelled migration. *--offline* migrates domain definition without +starting the domain on destination and without stopping it on source host. +Offline migration may be used with inactive domains and it must be used with +*--persistent* option. *--persistent* leaves the domain persistent on +destination host, *--undefinesource* undefines the domain on the source host, +and *--suspend* leaves the domain paused on the destination host. +*--copy-storage-all* indicates migration with non-shared storage with full +disk copy, *--copy-storage-inc* indicates migration with non-shared storage +with incremental copy (same base image shared between source and destination). +In both cases the disk images have to exist on destination host, the +*--copy-storage-...* options only tell libvirt to transfer data from the +images on source host to the images found at the same place on the destination +host. By default only non-shared non-readonly images are transferred. Use +*--migrate-disks* to explicitly specify a list of disk targets to +transfer via the comma separated ``disk-list`` argument. *--change-protection* +enforces that no incompatible configuration changes will be made to the domain +while the migration is underway; this flag is implicitly enabled when supported +by the hypervisor, but can be explicitly used to reject the migration if the +hypervisor lacks change protection support. *--verbose* displays the progress +of migration. *--abort-on-error* cancels +the migration if a soft error (for example I/O error) happens during the +migration. *--postcopy* enables post-copy logic in migration, but does not +actually start post-copy, i.e., migration is started in pre-copy mode. +Once migration is running, the user may switch to post-copy using the +``migrate-postcopy`` command sent from another virsh instance or use +*--postcopy-after-precopy* along with *--postcopy* to let libvirt +automatically switch to post-copy after the first pass of pre-copy is finished. +The maximum bandwidth consumed during the post-copy phase may be limited using +*--postcopy-bandwidth*. The maximum bandwidth consumed during the pre-copy phase +may be limited using *--bandwidth*. + +*--auto-converge* forces convergence during live migration. The initial +guest CPU throttling rate can be set with *auto-converge-initial*. If the +initial throttling rate is not enough to ensure convergence, the rate is +periodically increased by *auto-converge-increment*. + +*--rdma-pin-all* can be used with RDMA migration (i.e., when *migrateuri* +starts with rdma://) to tell the hypervisor to pin all domain's memory at once +before migration starts rather than letting it pin memory pages as needed. For +QEMU/KVM this requires hard_limit memory tuning element (in the domain XML) to +be used and set to the maximum memory configured for the domain plus any memory +consumed by the QEMU process itself. Beware of setting the memory limit too +high (and thus allowing the domain to lock most of the host's memory). Doing so +may be dangerous to both the domain and the host itself since the host's kernel +may run out of memory. + +``Note``: Individual hypervisors usually do not support all possible types of +migration. For example, QEMU does not support direct migration. + +In some cases libvirt may refuse to migrate the domain because doing so may +lead to potential problems such as data corruption, and thus the migration is +considered unsafe. For QEMU domain, this may happen if the domain uses disks +without explicitly setting cache mode to "none". Migrating such domains is +unsafe unless the disk images are stored on coherent clustered filesystem, +such as GFS2 or GPFS. If you are sure the migration is safe or you just do not +care, use *--unsafe* to force the migration. + +*dname* is used for renaming the domain to new name during migration, which +also usually can be omitted. Likewise, *--xml* ``file`` is usually +omitted, but can be used to supply an alternative XML file for use on +the destination to supply a larger set of changes to any host-specific +portions of the domain XML, such as accounting for naming differences +between source and destination in accessing underlying storage. +If *--persistent* is enabled, *--persistent-xml* ``file`` can be used to +supply an alternative XML file which will be used as the persistent domain +definition on the destination host. + +*--timeout* ``seconds`` tells virsh to run a specified action when live +migration exceeds that many seconds. It can only be used with *--live*. +If *--timeout-suspend* is specified, the domain will be suspended after +the timeout and the migration will complete offline; this is the default +if no *--timeout-\\`` option is specified on the command line. When +*--timeout-postcopy* is used, virsh will switch migration from pre-copy +to post-copy upon timeout; migration has to be started with *--postcopy* +option for this to work. + +*--compressed* activates compression, the compression method is chosen +with *--comp-methods*. Supported methods are "mt" and "xbzrle" and +can be used in any combination. When no methods are specified, a hypervisor +default methods will be used. QEMU defaults to "xbzrle". Compression methods +can be tuned further. *--comp-mt-level* sets compression level. +Values are in range from 0 to 9, where 1 is maximum speed and 9 is maximum +compression. *--comp-mt-threads* and *--comp-mt-dthreads* set the number +of compress threads on source and the number of decompress threads on target +respectively. *--comp-xbzrle-cache* sets size of page cache in bytes. + +Providing *--tls* causes the migration to use the host configured TLS setup +(see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in order to perform +the migration of the domain. Usage requires proper TLS setup for both source +and target. + +*--parallel* option will cause migration data to be sent over multiple +parallel connections. The number of such connections can be set using +*--parallel-connections*. Parallel connections may help with saturating the +network link between the source and the target and thus speeding up the +migration. + +Running migration can be canceled by interrupting virsh (usually using +``Ctrl-C``) or by ``domjobabort`` command sent from another virsh instance. + +The *desturi* and *migrateuri* parameters can be used to control which +destination the migration uses. *desturi* is important for managed +migration, but unused for direct migration; *migrateuri* is required +for direct migration, but can usually be automatically determined for +managed migration. + +``Note``: The *desturi* parameter for normal migration and peer2peer migration +has different semantics: + +* normal migration: the *desturi* is an address of the target host as seen from the client machine. + +* peer2peer migration: the *desturi* is an address of the target host as seen from the source machine. + +When *migrateuri* is not specified, libvirt will automatically determine the +hypervisor specific URI. Some hypervisors, including QEMU, have an optional +"migration_host" configuration parameter (useful when the host has multiple +network interfaces). If this is unspecified, libvirt determines a name +by looking up the target host's configured hostname. + +There are a few scenarios where specifying *migrateuri* may help: + +* The configured hostname is incorrect, or DNS is broken. + If a host has a hostname which will not resolve to match one of its public IP addresses, then + libvirt will generate an incorrect URI. In this case *migrateuri* should be + explicitly specified, using an IP address, or a correct hostname. + +* The host has multiple network interfaces. If a host has multiple network + interfaces, it might be desirable for the migration data stream to be sent over + a specific interface for either security or performance reasons. In this case + *migrateuri* should be explicitly specified, using an IP address associated + with the network to be used. + +* The firewall restricts what ports are available. When libvirt generates a + migration URI, it will pick a port number using hypervisor specific rules. + Some hypervisors only require a single port to be open in the firewalls, while + others require a whole range of port numbers. In the latter case *migrateuri* + might be specified to choose a specific port number outside the default range in + order to comply with local firewall policies. + +See `https://libvirt.org/migration.html#uris <https://libvirt.org/migration.html#uris>`_ for more details on +migration URIs. + +Optional *graphicsuri* overrides connection parameters used for automatically +reconnecting a graphical clients at the end of migration. If omitted, libvirt +will compute the parameters based on target host IP address. In case the +client does not have a direct access to the network virtualization hosts are +connected to and needs to connect through a proxy, *graphicsuri* may be used +to specify the address the client should connect to. The URI is formed as +follows: + +.. code-block:: shell + + protocol://hostname[:port]/[?parameters] + +where protocol is either "spice" or "vnc" and parameters is a list of protocol +specific parameters separated by '&'. Currently recognized parameters are +"tlsPort" and "tlsSubject". For example, + +.. code-block:: shell + + spice://target.host.com:1234/?tlsPort=4567 + +Optional *listen-address* sets the listen address that hypervisor on the +destination side should bind to for incoming migration. Both IPv4 and IPv6 +addresses are accepted as well as hostnames (the resolving is done on +destination). Some hypervisors do not support this feature and will return an +error if this parameter is used. + +Optional *disks-port* sets the port that hypervisor on destination side should +bind to for incoming disks traffic. Currently it is supported only by qemu. + + +migrate-compcache +----------------- + +.. code-block:: shell + + migrate-compcache domain [--size bytes] + +Sets and/or gets size of the cache (in bytes) used for compressing repeatedly +transferred memory pages during live migration. When called without *size*, +the command just prints current size of the compression cache. When *size* +is specified, the hypervisor is asked to change compression cache to *size* +bytes and then the current size is printed (the result may differ from the +requested size due to rounding done by the hypervisor). The *size* option +is supposed to be used while the domain is being live-migrated as a reaction +to migration progress and increasing number of compression cache misses +obtained from domjobinfo. + + +migrate-getmaxdowntime +---------------------- + +.. code-block:: shell + + migrate-getmaxdowntime domain + + +Get the maximum tolerable downtime for a domain which is being live-migrated to +another host. This is the number of milliseconds the guest is allowed +to be down at the end of live migration. + + +migrate-getspeed +---------------- + +.. code-block:: shell + + migrate-getspeed domain [--postcopy] + +Get the maximum migration bandwidth (in MiB/s) for a domain. If the +*--postcopy* option is specified, the command will get the maximum bandwidth +allowed during a post-copy migration phase. + + +migrate-postcopy +---------------- + +.. code-block:: shell + + migrate-postcopy domain + +Switch the current migration from pre-copy to post-copy. This is only +supported for a migration started with *--postcopy* option. + + +migrate-setmaxdowntime +---------------------- + +.. code-block:: shell + + migrate-setmaxdowntime domain downtime + +Set maximum tolerable downtime for a domain which is being live-migrated to +another host. The *downtime* is a number of milliseconds the guest is allowed +to be down at the end of live migration. + + +migrate-setspeed +---------------- + +.. code-block:: shell + + migrate-setspeed domain bandwidth [--postcopy] + +Set the maximum migration bandwidth (in MiB/s) for a domain which is being +migrated to another host. *bandwidth* is interpreted as an unsigned long +long value. Specifying a negative value results in an essentially unlimited +value being provided to the hypervisor. The hypervisor can choose whether to +reject the value or convert it to the maximum value allowed. If the +*--postcopy* option is specified, the command will set the maximum bandwidth +allowed during a post-copy migration phase. + + +numatune +-------- + +.. code-block:: shell + + numatune domain [--mode mode] [--nodeset nodeset] + [[--config] [--live] | [--current]] + +Set or get a domain's numa parameters, corresponding to the <numatune> +element of domain XML. Without flags, the current settings are +displayed. + +*mode* can be one of \`strict', \`interleave' and \`preferred' or any +valid number from the virDomainNumatuneMemMode enum in case the daemon +supports it. For a running domain, the mode can't be changed, and the +nodeset can be changed only if the domain was started with a mode of +\`strict'. + +*nodeset* is a list of numa nodes used by the host for running the domain. +Its syntax is a comma separated list, with '-' for ranges and '^' for +excluding a node. + +If *--live* is specified, set scheduler information of a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. + + +perf +---- + +.. code-block:: shell + + perf domain [--enable eventSpec] [--disable eventSpec] + [[--config] [--live] | [--current]] + +Get the current perf events setting or enable/disable specific perf +events for a guest domain. + +Perf is a performance analyzing tool in Linux, and it can instrument +CPU performance counters, tracepoints, kprobes, and uprobes (dynamic +tracing). Perf supports a list of measurable events, and can measure +events coming from different sources. For instance, some event are +pure kernel counters, in this case they are called software events, +including context-switches, minor-faults, etc.. Now dozens of events +from different sources can be supported by perf. + +Currently only QEMU/KVM supports this command. The *--enable* and *--disable* +option combined with ``eventSpec`` can be used to enable or disable specific +performance event. ``eventSpec`` is a string list of one or more events +separated by commas. Valid event names are as follows: + +Valid perf event names +~~~~~~~~~~~~~~~~~~~~~~ + +* ``cmt`` - A PQos (Platform Qos) feature to monitor the + usage of cache by applications running on the platform. +* ``mbmt`` - Provides a way to monitor the total system + memory bandwidth between one level of cache and another. +* ``mbml`` - Provides a way to limit the amount of data + (bytes/s) send through the memory controller on the socket. +* ``cache_misses`` - Provides the count of cache misses by + applications running on the platform. +* ``cache_references`` - Provides the count of cache hits by + applications running on th e platform. +* ``instructions`` - Provides the count of instructions executed + by applications running on the platform. +* ``cpu_cycles`` - Provides the count of cpu cycles + (total/elapsed). May be used with instructions in order to get + a cycles per instruction. +* ``branch_instructions`` - Provides the count of branch instructions + executed by applications running on the platform. +* ``branch_misses`` - Provides the count of branch misses executed + by applications running on the platform. +* ``bus_cycles`` - Provides the count of bus cycles executed + by applications running on the platform. +* ``stalled_cycles_frontend`` - Provides the count of stalled cpu + cycles in the frontend of the instruction processor pipeline by + applications running on the platform. +* ``stalled_cycles_backend`` - Provides the count of stalled cpu + cycles in the backend of the instruction processor pipeline by + applications running on the platform. +* ``ref_cpu_cycles`` - Provides the count of total cpu cycles + not affected by CPU frequency scaling by applications running + on the platform. +* ``cpu_clock`` - Provides the cpu clock time consumed by + applications running on the platform. +* ``task_clock`` - Provides the task clock time consumed by + applications running on the platform. +* ``page_faults`` - Provides the count of page faults by + applications running on the platform. +* ``context_switches`` - Provides the count of context switches + by applications running on the platform. +* ``cpu_migrations`` - Provides the count cpu migrations by + applications running on the platform. +* ``page_faults_min`` - Provides the count minor page faults + by applications running on the platform. +* ``page_faults_maj`` - Provides the count major page faults + by applications running on the platform. +* ``alignment_faults`` - Provides the count alignment faults + by applications running on the platform. +* ``emulation_faults`` - Provides the count emulation faults + by applications running on the platform. + +``Note``: The statistics can be retrieved using the ``domstats`` command using +the *--perf* flag. + +If *--live* is specified, affect a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. If no flag is specified, behavior is different depending +on hypervisor. + + +reboot +------ + +.. code-block:: shell + + reboot domain [--mode MODE-LIST] + +Reboot a domain. This acts just as if the domain had the ``reboot`` +command run from the console. The command returns as soon as it has +executed the reboot action, which may be significantly before the +domain actually reboots. + +The exact behavior of a domain when it reboots is set by the +*on_reboot* parameter in the domain's XML definition. + +By default the hypervisor will try to pick a suitable shutdown +method. To specify an alternative method, the *--mode* parameter +can specify a comma separated list which includes ``acpi``, ``agent``, +``initctl``, ``signal`` and ``paravirt``. The order in which drivers will +try each mode is undefined, and not related to the order specified to virsh. +For strict control over ordering, use a single mode at a time and +repeat the command. + + +reset +----- + +.. code-block:: shell + + reset domain + +Reset a domain immediately without any guest shutdown. ``reset`` +emulates the power reset button on a machine, where all guest +hardware sees the RST line set and reinitializes internal state. + +``Note``: Reset without any guest OS shutdown risks data loss. + + +restore +------- + +.. code-block:: shell + + restore state-file [--bypass-cache] [--xml file] + [{--running | --paused}] + +Restores a domain from a ``virsh save`` state file. See *save* for more info. + +If *--bypass-cache* is specified, the restore will avoid the file system +cache, although this may slow down the operation. + +*--xml* ``file`` is usually omitted, but can be used to supply an +alternative XML file for use on the restored guest with changes only +in the host-specific portions of the domain XML. For example, it can +be used to account for file naming differences in underlying storage +due to disk snapshots taken after the guest was saved. + +Normally, restoring a saved image will use the state recorded in the +save image to decide between running or paused; passing either the +*--running* or *--paused* flag will allow overriding which state the +domain should be started in. + +``Note``: To avoid corrupting file system contents within the domain, you +should not reuse the saved state file for a second ``restore`` unless you +have also reverted all storage volumes back to the same contents as when +the state file was created. + + +resume +------ + +.. code-block:: shell + + resume domain + +Moves a domain out of the suspended state. This will allow a previously +suspended domain to now be eligible for scheduling by the underlying +hypervisor. + + +save +---- + +.. code-block:: shell + + save domain state-file [--bypass-cache] [--xml file] + [{--running | --paused}] [--verbose] + +Saves a running domain (RAM, but not disk state) to a state file so that +it can be restored +later. Once saved, the domain will no longer be running on the +system, thus the memory allocated for the domain will be free for +other domains to use. ``virsh restore`` restores from this state file. +If *--bypass-cache* is specified, the save will avoid the file system +cache, although this may slow down the operation. + +The progress may be monitored using ``domjobinfo`` virsh command and canceled +with ``domjobabort`` command (sent by another virsh instance). Another option +is to send SIGINT (usually with ``Ctrl-C``) to the virsh process running +``save`` command. *--verbose* displays the progress of save. + +This is roughly equivalent to doing a hibernate on a running computer, +with all the same limitations. Open network connections may be +severed upon restore, as TCP timeouts may have expired. + +*--xml* ``file`` is usually omitted, but can be used to supply an +alternative XML file for use on the restored guest with changes only +in the host-specific portions of the domain XML. For example, it can +be used to account for file naming differences that are planned to +be made via disk snapshots of underlying storage after the guest is saved. + +Normally, restoring a saved image will decide between running or paused +based on the state the domain was in when the save was done; passing +either the *--running* or *--paused* flag will allow overriding which +state the ``restore`` should use. + +Domain saved state files assume that disk images will be unchanged +between the creation and restore point. For a more complete system +restore point, where the disk state is saved alongside the memory +state, see the ``snapshot`` family of commands. + + +save-image-define +----------------- + +.. code-block:: shell + + save-image-define file xml [{--running | --paused}] + +Update the domain XML that will be used when *file* is later +used in the ``restore`` command. The *xml* argument must be a file +name containing the alternative XML, with changes only in the +host-specific portions of the domain XML. For example, it can +be used to account for file naming differences resulting from creating +disk snapshots of underlying storage after the guest was saved. + +The save image records whether the domain should be restored to a +running or paused state. Normally, this command does not alter the +recorded state; passing either the *--running* or *--paused* flag +will allow overriding which state the ``restore`` should use. + + +save-image-dumpxml +------------------ + +.. code-block:: shell + + save-image-dumpxml file [--security-info] + +Extract the domain XML that was in effect at the time the saved state +file *file* was created with the ``save`` command. Using +*--security-info* will also include security sensitive information. + + +save-image-edit +--------------- + +.. code-block:: shell + + save-image-edit file [{--running | --paused}] + +Edit the XML configuration associated with a saved state file *file* +created by the ``save`` command. + +The save image records whether the domain should be restored to a +running or paused state. Normally, this command does not alter the +recorded state; passing either the *--running* or *--paused* flag +will allow overriding which state the ``restore`` should use. + +This is equivalent to: + +.. code-block:: shell + + virsh save-image-dumpxml state-file > state-file.xml + vi state-file.xml (or make changes with your other text editor) + virsh save-image-define state-file state-file-xml + +except that it does some error checking. + +The editor used can be supplied by the ``$VISUAL`` or ``$EDITOR`` environment +variables, and defaults to ``vi``. + + +schedinfo +--------- + +.. code-block:: shell + + schedinfo domain [[--config] [--live] | [--current]] [[--set] parameter=value]... + schedinfo [--weight number] [--cap number] domain + +Allows you to show (and set) the domain scheduler parameters. The parameters +available for each hypervisor are: + +LXC (posix scheduler) : cpu_shares, vcpu_period, vcpu_quota + +QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota, +emulator_period, emulator_quota, iothread_quota, iothread_period + +Xen (credit scheduler): weight, cap + +ESX (allocation scheduler): reservation, limit, shares + +If *--live* is specified, set scheduler information of a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. + +``Note``: The cpu_shares parameter has a valid value range of 0-262144; Negative +values are wrapped to positive, and larger values are capped at the maximum. +Therefore, -1 is a useful shorthand for 262144. On the Linux kernel, the +values 0 and 1 are automatically converted to a minimal value of 2. + +``Note``: The weight and cap parameters are defined only for the +XEN_CREDIT scheduler. + +``Note``: The vcpu_period, emulator_period, and iothread_period parameters +have a valid value range of 1000-1000000 or 0, and the vcpu_quota, +emulator_quota, and iothread_quota parameters have a valid value range of +1000-18446744073709551 or less than 0. The value 0 for +either parameter is the same as not specifying that parameter. + + +screenshot +---------- + +.. code-block:: shell + + screenshot domain [imagefilepath] [--screen screenID] + +Takes a screenshot of a current domain console and stores it into a file. +Optionally, if the hypervisor supports more displays for a domain, *screenID* +allows specifying which screen will be captured. It is the sequential number +of screen. In case of multiple graphics cards, heads are enumerated before +devices, e.g. having two graphics cards, both with four heads, screen ID 5 +addresses the second head on the second card. + + +send-key +-------- + +.. code-block:: shell + + send-key domain [--codeset codeset] [--holdtime holdtime] keycode... + +Parse the *keycode* sequence as keystrokes to send to *domain*. +Each *keycode* can either be a numeric value or a symbolic name from +the corresponding codeset. If *--holdtime* is given, each keystroke +will be held for that many milliseconds. The default codeset is +``linux``, but use of the *--codeset* option allows other codesets to +be chosen. + +If multiple keycodes are specified, they are all sent simultaneously +to the guest, and they may be received in random order. If you need +distinct keypresses, you must use multiple send-key invocations. + +- ``linux`` + + The numeric values are those defined by the Linux generic input + event subsystem. The symbolic names match the corresponding + Linux key constant macro names. + + See virkeycode-linux(7) and virkeyname-linux(7) + +- ``xt`` + + The numeric values are those defined by the original XT keyboard + controller. No symbolic names are provided + + See virkeycode-xt(7) + +- ``atset1`` + + The numeric values are those defined by the AT keyboard controller, + set 1 (aka XT compatible set). Extended keycoes from ``atset1`` + may differ from extended keycodes in the ``xt`` codeset. No symbolic + names are provided + + See virkeycode-atset1(7) + +- ``atset2`` + + The numeric values are those defined by the AT keyboard controller, + set 2. No symbolic names are provided + + See virkeycode-atset2(7) + +- ``atset3`` + + The numeric values are those defined by the AT keyboard controller, + set 3 (aka PS/2 compatible set). No symbolic names are provided + + See virkeycode-atset3(7) + +- ``os_x`` + + The numeric values are those defined by the macOS keyboard input + subsystem. The symbolic names match the corresponding macOS key + constant macro names + + See virkeycode-osx(7) and virkeyname-osx(7) + +- ``xt_kbd`` + + The numeric values are those defined by the Linux KBD device. + These are a variant on the original XT codeset, but often with + different encoding for extended keycodes. No symbolic names are + provided. + + See virkeycode-xtkbd(7) + +- ``win32`` + + The numeric values are those defined by the Win32 keyboard input + subsystem. The symbolic names match the corresponding Win32 key + constant macro names + + See virkeycode-win32(7) and virkeyname-win32(7) + +- ``usb`` + + The numeric values are those defined by the USB HID specification + for keyboard input. No symbolic names are provided + + See virkeycode-usb(7) + +- ``qnum`` + + The numeric values are those defined by the QNUM extension for sending + raw keycodes. These are a variant on the XT codeset, but extended + keycodes have the low bit of the second byte set, instead of the high + bit of the first byte. No symbolic names are provided. + + See virkeycode-qnum(7) + + +Examples +~~~~~~~~ + +.. code-block:: shell + + # send three strokes 'k', 'e', 'y', using xt codeset. these + # are all pressed simultaneously and may be received by the guest + # in random order + virsh send-key dom --codeset xt 37 18 21 + + # send one stroke 'right-ctrl+C' + virsh send-key dom KEY_RIGHTCTRL KEY_C + + # send a tab, held for 1 second + virsh send-key --holdtime 1000 0xf + + + +send-process-signal +------------------- + +.. code-block:: shell + + send-process-signal domain-id pid signame + +Send a signal *signame* to the process identified by *pid* running in +the virtual domain *domain-id*. The *pid* is a process ID in the virtual +domain namespace. + +The *signame* argument may be either an integer signal constant number, +or one of the symbolic names: + +.. code-block:: shell + + "nop", "hup", "int", "quit", "ill", + "trap", "abrt", "bus", "fpe", "kill", + "usr1", "segv", "usr2", "pipe", "alrm", + "term", "stkflt", "chld", "cont", "stop", + "tstp", "ttin", "ttou", "urg", "xcpu", + "xfsz", "vtalrm", "prof", "winch", "poll", + "pwr", "sys", "rt0", "rt1", "rt2", "rt3", + "rt4", "rt5", "rt6", "rt7", "rt8", "rt9", + "rt10", "rt11", "rt12", "rt13", "rt14", "rt15", + "rt16", "rt17", "rt18", "rt19", "rt20", "rt21", + "rt22", "rt23", "rt24", "rt25", "rt26", "rt27", + "rt28", "rt29", "rt30", "rt31", "rt32" + +The symbol name may optionally be prefixed with ``sig`` or ``sig_`` and +may be in uppercase or lowercase. + +Examples +~~~~~~~~ + +.. code-block:: shell + + virsh send-process-signal myguest 1 15 + virsh send-process-signal myguest 1 term + virsh send-process-signal myguest 1 sigterm + virsh send-process-signal myguest 1 SIG_HUP + + +set-lifecycle-action +-------------------- + +.. code-block:: shell + + set-lifecycle-action domain type action + [[--config] [--live] | [--current]] + +Set the lifecycle *action* for specified lifecycle *type*. +The valid types are "poweroff", "reboot" and "crash", and for each of +them valid *action* is one of "destroy", "restart", "rename-restart", +"preserve". For *type* "crash", additional actions "coredump-destroy" +and "coredump-restart" are supported. + + +set-user-password +----------------- + +.. code-block:: shell + + set-user-password domain user password [--encrypted] + +Set the password for the *user* account in the guest domain. + +If *--encrypted* is specified, the password is assumed to be already +encrypted by the method required by the guest OS. + +For QEMU/KVM, this requires the guest agent to be configured +and running. + + +setmaxmem +--------- + +.. code-block:: shell + + setmaxmem domain size [[--config] [--live] | [--current]] + +Change the maximum memory allocation limit for a guest domain. +If *--live* is specified, affect a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. If no flag is specified, behavior is different depending +on hypervisor. + +Some hypervisors such as QEMU/KVM don't support live changes (especially +increasing) of the maximum memory limit. Even persistent configuration changes +might not be performed with some hypervisors/configuration (e.g. on NUMA enabled +domains on QEMU). For complex configuration changes use command ``edit`` +instead). + +*size* is a scaled integer (see ``NOTES`` above); it defaults to kibibytes +(blocks of 1024 bytes) unless you provide a suffix (and the older option +name *--kilobytes* is available as a deprecated synonym) . Libvirt rounds +up to the nearest kibibyte. Some hypervisors require a larger granularity +than KiB, and requests that are not an even multiple will be rounded up. +For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes). + + +setmem +------ + +.. code-block:: shell + + setmem domain size [[--config] [--live] | [--current]] + +Change the memory allocation for a guest domain. +If *--live* is specified, perform a memory balloon of a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. If no flag is specified, behavior is different depending +on hypervisor. + +*size* is a scaled integer (see ``NOTES`` above); it defaults to kibibytes +(blocks of 1024 bytes) unless you provide a suffix (and the older option +name *--kilobytes* is available as a deprecated synonym) . Libvirt rounds +up to the nearest kibibyte. Some hypervisors require a larger granularity +than KiB, and requests that are not an even multiple will be rounded up. +For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes). + +For Xen, you can only adjust the memory of a running domain if the domain is +paravirtualized or running the PV balloon driver. + +For LXC, the value being set is the cgroups value for limit_in_bytes or the +maximum amount of user memory (including file cache). When viewing memory +inside the container, this is the /proc/meminfo "MemTotal" value. When viewing +the value from the host, use the ``virsh memtune`` command. In order to view +the current memory in use and the maximum value allowed to set memory, use +the ``virsh dominfo`` command. + + +setvcpus +-------- + +.. code-block:: shell + + setvcpus domain count [--maximum] [[--config] [--live] | [--current]] [--guest] [--hotpluggable] + +Change the number of virtual CPUs active in a guest domain. By default, +this command works on active guest domains. To change the settings for an +inactive guest domain, use the *--config* flag. + +The *count* value may be limited by host, hypervisor, or a limit coming +from the original description of the guest domain. For Xen, you can only +adjust the virtual CPUs of a running domain if the domain is paravirtualized. + +If the *--config* flag is specified, the change is made to the stored XML +configuration for the guest domain, and will only take effect when the guest +domain is next started. + +If *--live* is specified, the guest domain must be active, and the change +takes place immediately. Both the *--config* and *--live* flags may be +specified together if supported by the hypervisor. If this command is run +before the guest has finished booting, the guest may fail to process +the change. + +If *--current* is specified, affect the current guest state. + +When no flags are given, the *--live* +flag is assumed and the guest domain must be active. In this situation it +is up to the hypervisor whether the *--config* flag is also assumed, and +therefore whether the XML configuration is adjusted to make the change +persistent. + +If *--guest* is specified, then the count of cpus is modified in the guest +instead of the hypervisor. This flag is usable only for live domains +and may require guest agent to be configured in the guest. + +To allow adding vcpus to persistent definitions that can be later hotunplugged +after the domain is booted it is necessary to specify the *--hotpluggable* +flag. Vcpus added to live domains supporting vcpu unplug are automatically +marked as hotpluggable. + +The *--maximum* flag controls the maximum number of virtual cpus that can +be hot-plugged the next time the domain is booted. As such, it must only be +used with the *--config* flag, and not with the *--live* or the *--current* +flag. Note that it may not be possible to change the maximum vcpu count if +the processor topology is specified for the guest. + + +setvcpu +------- + +.. code-block:: shell + + setvcpu domain vcpulist [--enable] | [--disable] + [[--live] [--config] | [--current]] + +Change state of individual vCPUs using hot(un)plug mechanism. + +See ``vcpupin`` for information on format of *vcpulist*. Hypervisor drivers may +require that *vcpulist* contains exactly vCPUs belonging to one hotpluggable +entity. This is usually just a single vCPU but certain architectures such as +ppc64 require a full core to be specified at once. + +Note that hypervisors may refuse to disable certain vcpus such as vcpu 0 or +others. + +If *--live* is specified, affect a running domain. +If *--config* is specified, affect the next startup of a persistent domain. +If *--current* is specified, affect the current domain state. This is the +default. Both *--live* and *--config* flags may be given, but *--current* is +exclusive. + + +shutdown +-------- + +.. code-block:: shell + + shutdown domain [--mode MODE-LIST] + +Gracefully shuts down a domain. This coordinates with the domain OS +to perform graceful shutdown, so there is no guarantee that it will +succeed, and may take a variable length of time depending on what +services must be shutdown in the domain. + +The exact behavior of a domain when it shuts down is set by the +*on_poweroff* parameter in the domain's XML definition. + +If *domain* is transient, then the metadata of any snapshots and +checkpoints will be lost once the guest stops running, but the underlying +contents still exist, and a new domain with the same name and UUID can +restore the snapshot metadata with ``snapshot-create``, and the checkpoint +metadata with ``checkpoint-create``. + +By default the hypervisor will try to pick a suitable shutdown +method. To specify an alternative method, the *--mode* parameter +can specify a comma separated list which includes ``acpi``, ``agent``, +``initctl``, ``signal`` and ``paravirt``. The order in which drivers will +try each mode is undefined, and not related to the order specified to virsh. +For strict control over ordering, use a single mode at a time and +repeat the command. + + +start +----- + +.. code-block:: shell + + start domain-name-or-uuid [--console] [--paused] + [--autodestroy] [--bypass-cache] [--force-boot] + [--pass-fds N,M,...] + +Start a (previously defined) inactive domain, either from the last +``managedsave`` state, or via a fresh boot if no managedsave state is +present. The domain will be paused if the *--paused* option is +used and supported by the driver; otherwise it will be running. +If *--console* is requested, attach to the console after creation. +If *--autodestroy* is requested, then the guest will be automatically +destroyed when virsh closes its connection to libvirt, or otherwise +exits. If *--bypass-cache* is specified, and managedsave state exists, +the restore will avoid the file system cache, although this may slow +down the operation. If *--force-boot* is specified, then any +managedsave state is discarded and a fresh boot occurs. + +If *--pass-fds* is specified, the argument is a comma separated list +of open file descriptors which should be pass on into the guest. The +file descriptors will be re-numbered in the guest, starting from 3. This +is only supported with container based virtualization. + + +suspend +------- + +.. code-block:: shell + + suspend domain + +Suspend a running domain. It is kept in memory but won't be scheduled +anymore. + + +ttyconsole +---------- + +.. code-block:: shell + + ttyconsole domain + +Output the device used for the TTY console of the domain. If the information +is not available the processes will provide an exit code of 1. + + +undefine +-------- + +.. code-block:: shell + + undefine domain [--managed-save] [--snapshots-metadata] + [--checkpoints-metadata] [--nvram] [--keep-nvram] + [ {--storage volumes | --remove-all-storage + [--delete-storage-volume-snapshots]} --wipe-storage] + +Undefine a domain. If the domain is running, this converts it to a +transient domain, without stopping it. If the domain is inactive, +the domain configuration is removed. + +The *--managed-save* flag guarantees that any managed save image (see +the ``managedsave`` command) is also cleaned up. Without the flag, attempts +to undefine a domain with a managed save image will fail. + +The *--snapshots-metadata* flag guarantees that any snapshots (see the +``snapshot-list`` command) are also cleaned up when undefining an inactive +domain. Without the flag, attempts to undefine an inactive domain with +snapshot metadata will fail. If the domain is active, this flag is +ignored. + +The *--checkpoints-metadata* flag guarantees that any checkpoints (see the +``checkpoint-list`` command) are also cleaned up when undefining an inactive +domain. Without the flag, attempts to undefine an inactive domain with +checkpoint metadata will fail. If the domain is active, this flag is +ignored. + +*--nvram* and *--keep-nvram* specify accordingly to delete or keep nvram +(/domain/os/nvram/) file. If the domain has an nvram file and the flags are +omitted, the undefine will fail. + +The *--storage* flag takes a parameter ``volumes``, which is a comma separated +list of volume target names or source paths of storage volumes to be removed +along with the undefined domain. Volumes can be undefined and thus removed only +on inactive domains. Volume deletion is only attempted after the domain is +undefined; if not all of the requested volumes could be deleted, the +error message indicates what still remains behind. If a volume path is not +found in the domain definition, it's treated as if the volume was successfully +deleted. Only volumes managed by libvirt in storage pools can be removed this +way. +(See ``domblklist`` for list of target names associated to a domain). +Example: --storage vda,/path/to/storage.img + +The *--remove-all-storage* flag specifies that all of the domain's storage +volumes should be deleted. + +The *--delete-storage-volume-snapshots* (previously *--delete-snapshots*) +flag specifies that any snapshots associated with +the storage volume should be deleted as well. Requires the +*--remove-all-storage* flag to be provided. Not all storage drivers +support this option, presently only rbd. Using this when also removing volumes +handled by a storage driver which does not support the flag will result in +failure. + +The flag *--wipe-storage* specifies that the storage volumes should be +wiped before removal. + +NOTE: For an inactive domain, the domain name or UUID must be used as the +*domain*. + + +vcpucount +--------- + +.. code-block:: shell + + vcpucount domain [{--maximum | --active} + {--config | --live | --current}] [--guest] + +Print information about the virtual cpu counts of the given +*domain*. If no flags are specified, all possible counts are +listed in a table; otherwise, the output is limited to just the +numeric value requested. For historical reasons, the table +lists the label "current" on the rows that can be queried in isolation +via the *--active* flag, rather than relating to the *--current* flag. + +*--maximum* requests information on the maximum cap of vcpus that a +domain can add via ``setvcpus``, while *--active* shows the current +usage; these two flags cannot both be specified. *--config* +requires a persistent domain and requests information regarding the next +time the domain will be booted, *--live* requires a running domain and +lists current values, and *--current* queries according to the current +state of the domain (corresponding to *--live* if running, or +*--config* if inactive); these three flags are mutually exclusive. + +If *--guest* is specified, then the count of cpus is reported from +the perspective of the guest. This flag is usable only for live domains +and may require guest agent to be configured in the guest. + + +vcpuinfo +-------- + +.. code-block:: shell + + vcpuinfo domain [--pretty] + +Returns basic information about the domain virtual CPUs, like the number of +vCPUs, the running time, the affinity to physical processors. + +With *--pretty*, cpu affinities are shown as ranges. + +Example +~~~~~~~ + +.. code-block:: shell + + $ virsh vcpuinfo fedora + VCPU: 0 + CPU: 0 + State: running + CPU time: 7,0s + CPU Affinity: yyyy + + VCPU: 1 + CPU: 1 + State: running + CPU time: 0,7s + CPU Affinity: yyyy + + +``STATES`` + +The State field displays the current operating state of a virtual CPU + + +- ``offline`` + + The virtual CPU is offline and not usable by the domain. + This state is not supported by all hypervisors. + +- ``running`` + + The virtual CPU is available to the domain and is operating. + +- ``blocked`` + + The virtual CPU is available to the domain but is waiting for a resource. + This state is not supported by all hypervisors, in which case *running* + may be reported instead. + +- ``no state`` + + The virtual CPU state could not be determined. This could happen if + the hypervisor is newer than virsh. + +- ``N/A`` + + There's no information about the virtual CPU state available. This can + be the case if the domain is not running or the hypervisor does + not report the virtual CPU state. + + +vcpupin +------- + +.. code-block:: shell + + vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]] + +Query or change the pinning of domain VCPUs to host physical CPUs. To +pin a single *vcpu*, specify *cpulist*; otherwise, you can query one +*vcpu* or omit *vcpu* to list all at once. + +*cpulist* is a list of physical CPU numbers. Its syntax is a comma +separated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2') can +also be allowed. The '-' denotes the range and the '^' denotes exclusive. +For pinning the *vcpu* to all physical cpus specify 'r' as a *cpulist*. +If *--live* is specified, affect a running guest. +If *--config* is specified, affect the next boot of a persistent guest. +If *--current* is specified, affect the current guest state. +Both *--live* and *--config* flags may be given if *cpulist* is present, +but *--current* is exclusive. +If no flag is specified, behavior is different depending on hypervisor. + +``Note``: The expression is sequentially evaluated, so "0-15,^8" is +identical to "9-14,0-7,15" but not identical to "^8,0-15". + + +vncdisplay +---------- + +.. code-block:: shell + + vncdisplay domain + +Output the IP address and port number for the VNC display. If the information +is not available the processes will provide an exit code of 1. + + +DEVICE COMMANDS +=============== + +The following commands manipulate devices associated to domains. +The *domain* can be specified as a short integer, a name or a full UUID. +To better understand the values allowed as options for the command +reading the documentation at `https://libvirt.org/formatdomain.html <https://libvirt.org/formatdomain.html>`_ on the +format of the device sections to get the most accurate set of accepted values. + + +attach-device +------------- + +.. code-block:: shell + + attach-device domain FILE [[[--live] [--config] | [--current]] | [--persistent]] + +Attach a device to the domain, using a device definition in an XML +file using a device definition element such as <disk> or <interface> +as the top-level element. See the documentation at +`https://libvirt.org/formatdomain.html#elementsDevices <https://libvirt.org/formatdomain.html#elementsDevices>`_ to learn about +libvirt XML format for a device. If *--config* is specified the +command alters the persistent domain configuration with the device +attach taking effect the next time libvirt starts the domain. +For cdrom and floppy devices, this command only replaces the media +within an existing device; consider using ``update-device`` for this +usage. For passthrough host devices, see also ``nodedev-detach``, +needed if the PCI device does not use managed mode. + +If *--live* is specified, affect a running domain. +If *--config* is specified, affect the next startup of a persistent domain. +If *--current* is specified, affect the current domain state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. When no flag is specified legacy API is used whose behavior depends +on the hypervisor driver. + +For compatibility purposes, *--persistent* behaves like *--config* for +an offline domain, and like *--live* *--config* for a running domain. + +``Note``: using of partial device definition XML files may lead to unexpected +results as some fields may be autogenerated and thus match devices other than +expected. + + +attach-disk +----------- + +.. code-block:: shell + + attach-disk domain source target [[[--live] [--config] | + [--current]] | [--persistent]] [--targetbus bus] + [--driver driver] [--subdriver subdriver] [--iothread iothread] + [--cache cache] [--io io] [--type type] [--alias alias] + [--mode mode] [--sourcetype sourcetype] [--serial serial] + [--wwn wwn] [--rawio] [--address address] [--multifunction] + [--print-xml] + +Attach a new disk device to the domain. +*source* is path for the files and devices. *target* controls the bus or +device under which the disk is exposed to the guest OS. It indicates the +"logical" device name; the optional *targetbus* attribute specifies the type +of disk device to emulate; possible values are driver specific, with typical +values being *ide*, *scsi*, *virtio*, *xen*, *usb*, *sata*, or *sd*, if +omitted, the bus type is inferred from the style of the device name (e.g. a +device named 'sda' will typically be exported using a SCSI bus). *driver* can +be *file*, *tap* or *phy* for the Xen +hypervisor depending on the kind of access; or *qemu* for the QEMU emulator. +Further details to the driver can be passed using *subdriver*. For Xen +*subdriver* can be *aio*, while for QEMU subdriver should match the format +of the disk source, such as *raw* or *qcow2*. Hypervisor default will be +used if *subdriver* is not specified. However, the default may not be +correct, esp. for QEMU as for security reasons it is configured not to detect +disk formats. *type* can indicate *lun*, *cdrom* or *floppy* as +alternative to the disk default, although this use only replaces the media +within the existing virtual cdrom or floppy device; consider using +``update-device`` for this usage instead. +*alias* can set user supplied alias. +*mode* can specify the two specific mode *readonly* or *shareable*. +*sourcetype* can indicate the type of source (block|file) +*cache* can be one of "default", "none", "writethrough", "writeback", +"directsync" or "unsafe". +*io* controls specific policies on I/O; QEMU guests support "threads" and "native". +*iothread* is the number within the range of domain IOThreads to which +this disk may be attached (QEMU only). +*serial* is the serial of disk device. *wwn* is the wwn of disk device. +*rawio* indicates the disk needs rawio capability. +*address* is the address of disk device in the form of +pci:domain.bus.slot.function, scsi:controller.bus.unit, +ide:controller.bus.unit, usb:bus.port, sata:controller.bus.unit or +ccw:cssid.ssid.devno. Virtio-ccw devices must have their cssid set to 0xfe. +*multifunction* indicates specified pci address is a multifunction pci device +address. + +If *--print-xml* is specified, then the XML of the disk that would be attached +is printed instead. + +If *--live* is specified, affect a running domain. +If *--config* is specified, affect the next startup of a persistent domain. +If *--current* is specified, affect the current domain state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. When no flag is specified legacy API is used whose behavior depends +on the hypervisor driver. + +For compatibility purposes, *--persistent* behaves like *--config* for +an offline domain, and like *--live* *--config* for a running domain. +Likewise, *--shareable* is an alias for *--mode shareable*. + + +attach-interface +---------------- + +.. code-block:: shell + + attach-interface domain type source [[[--live] + [--config] | [--current]] | [--persistent]] + [--target target] [--mac mac] [--script script] [--model model] + [--inbound average,peak,burst,floor] [--outbound average,peak,burst] + [--alias alias] [--managed] [--print-xml] + +Attach a new network interface to the domain. + +``type`` can be one of the: + +*network* to indicate connection via a libvirt virtual network, + +*bridge* to indicate connection via a bridge device on the host, + +*direct* to indicate connection directly to one of the host's network +interfaces or bridges, + +*hostdev* to indicate connection using a passthrough of PCI device +on the host. + +``source`` indicates the source of the connection. The source depends +on the type of the interface: + +*network* name of the virtual network, + +*bridge* the name of the bridge device, + +*direct* the name of the host's interface or bridge, + +*hostdev* the PCI address of the host's interface formatted +as domain:bus:slot.function. + +``--target`` is used to specify the tap/macvtap device to be used to +connect the domain to the source. Names starting with 'vnet' are +considered as auto-generated and are blanked out/regenerated each +time the interface is attached. + +``--mac`` specifies the MAC address of the network interface; if a MAC +address is not given, a new address will be automatically generated +(and stored in the persistent configuration if "--config" is given on +the command line). + +``--script`` is used to specify a path to a custom script to be called +while attaching to a bridge - this will be called instead of the default +script not in addition to it. This is valid only for interfaces of +*bridge* type and only for Xen domains. + +``--model`` specifies the network device model to be presented to the +domain. + +``alias`` can set user supplied alias. + +``--inbound`` and ``--outbound`` control the bandwidth of the +interface. At least one from the *average*, *floor* pair must be +specified. The other two *peak* and *burst* are optional, so +"average,peak", "average,,burst", "average,,,floor", "average" and +",,,floor" are also legal. Values for *average*, *floor* and *peak* +are expressed in kilobytes per second, while *burst* is expressed in +kilobytes in a single burst at *peak* speed as described in the +Network XML documentation at +`https://libvirt.org/formatnetwork.html#elementQoS <https://libvirt.org/formatnetwork.html#elementQoS>`_. + +``--managed`` is usable only for *hostdev* type and tells libvirt +that the interface should be managed, which means detached and reattached +from/to the host by libvirt. + +If ``--print-xml`` is specified, then the XML of the interface that would be +attached is printed instead. + +If ``--live`` is specified, affect a running domain. +If ``--config`` is specified, affect the next startup of a persistent domain. +If ``--current`` is specified, affect the current domain state. +Both ``--live`` and ``--config`` flags may be given, but ``--current`` is +exclusive. When no flag is specified legacy API is used whose behavior +depends on the hypervisor driver. + +For compatibility purposes, ``--persistent`` behaves like ``--config`` for +an offline domain, and like ``--live`` ``--config`` for a running domain. + +``Note``: the optional target value is the name of a device to be created +as the back-end on the node. If not provided a device named "vnetN" or "vifN" +will be created automatically. + + +detach-device +------------- + +.. code-block:: shell + + detach-device domain FILE [[[--live] [--config] | + [--current]] | [--persistent]] + +Detach a device from the domain, takes the same kind of XML descriptions +as command ``attach-device``. +For passthrough host devices, see also ``nodedev-reattach``, needed if +the device does not use managed mode. + +``Note``: The supplied XML description of the device should be as specific +as its definition in the domain XML. The set of attributes used +to match the device are internal to the drivers. Using a partial definition, +or attempting to detach a device that is not present in the domain XML, +but shares some specific attributes with one that is present, +may lead to unexpected results. + +``Quirk``: Device unplug is asynchronous in most cases and requires guest +cooperation. This means that it's up to the discretion of the guest to disallow +or delay the unplug arbitrarily. As the libvirt API used in this command was +designed as synchronous it returns success after some timeout even if the device +was not unplugged yet to allow further interactions with the domain e.g. if the +guest is unresponsive. Callers which need to make sure that the +device was unplugged can use libvirt events (see virsh event) to be notified +when the device is removed. Note that the event may arrive before the command +returns. + +If *--live* is specified, affect a running domain. +If *--config* is specified, affect the next startup of a persistent domain. +If *--current* is specified, affect the current domain state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. When no flag is specified legacy API is used whose behavior depends +on the hypervisor driver. + +For compatibility purposes, *--persistent* behaves like *--config* for +an offline domain, and like *--live* *--config* for a running domain. + +Note that older versions of virsh used *--config* as an alias for +*--persistent*. + + +detach-device-alias +------------------- + +.. code-block:: shell + + detach-device-alias domain alias [[[--live] [--config] | [--current]]]] + +Detach a device with given *alias* from the *domain*. This command returns +successfully after the unplug request was sent to the hypervisor. The actual +removal of the device is notified asynchronously via libvirt events +(see virsh event). + +If *--live* is specified, affect a running domain. +If *--config* is specified, affect the next startup of a persistent domain. +If *--current* is specified, affect the current domain state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. + + +detach-disk +----------- + +.. code-block:: shell + + detach-disk domain target [[[--live] [--config] | + [--current]] | [--persistent]] [--print-xml] + +Detach a disk device from a domain. The *target* is the device as seen +from the domain. + +If *--live* is specified, affect a running domain. +If *--config* is specified, affect the next startup of a persistent domain. +If *--current* is specified, affect the current domain state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. When no flag is specified legacy API is used whose behavior depends +on the hypervisor driver. + +For compatibility purposes, *--persistent* behaves like *--config* for +an offline domain, and like *--live* *--config* for a running domain. + +Note that older versions of virsh used *--config* as an alias for +*--persistent*. + +If ``--print-xml`` is specified, then the XML which would be used to detach the +disk is printed instead. + +Please see documentation for ``detach-device`` for known quirks. + + + +detach-interface +---------------- + +.. code-block:: shell + + detach-interface domain type [--mac mac] + [[[--live] [--config] | [--current]] | [--persistent]] + +Detach a network interface from a domain. +*type* can be either *network* to indicate a physical network device or +*bridge* to indicate a bridge to a device. It is recommended to use the +*mac* option to distinguish between the interfaces if more than one are +present on the domain. + +If *--live* is specified, affect a running domain. +If *--config* is specified, affect the next startup of a persistent domain. +If *--current* is specified, affect the current domain state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. When no flag is specified legacy API is used whose behavior depends +on the hypervisor driver. + +For compatibility purposes, *--persistent* behaves like *--config* for +an offline domain, and like *--live* *--config* for a running domain. + +Note that older versions of virsh used *--config* as an alias for +*--persistent*. + +Please see documentation for ``detach-device`` for known quirks. + + +update-device +------------- + +.. code-block:: shell + + update-device domain file [--force] [[[--live] + [--config] | [--current]] | [--persistent]] + +Update the characteristics of a device associated with *domain*, +based on the device definition in an XML *file*. The *--force* option +can be used to force device update, e.g., to eject a CD-ROM even if it is +locked/mounted in the domain. See the documentation at +`https://libvirt.org/formatdomain.html#elementsDevices <https://libvirt.org/formatdomain.html#elementsDevices>`_ to learn about +libvirt XML format for a device. + +If *--live* is specified, affect a running domain. +If *--config* is specified, affect the next startup of a persistent domain. +If *--current* is specified, affect the current domain state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. Not specifying any flag is the same as specifying *--current*. + +For compatibility purposes, *--persistent* behaves like *--config* for +an offline domain, and like *--live* *--config* for a running domain. + +Note that older versions of virsh used *--config* as an alias for +*--persistent*. + +``Note``: using of partial device definition XML files may lead to unexpected +results as some fields may be autogenerated and thus match devices other than +expected. + + +change-media +------------ + +.. code-block:: shell + + change-media domain path [--eject] [--insert] + [--update] [source] [--force] [[--live] [--config] | + [--current]] [--print-xml] [--block] + +Change media of CDROM or floppy drive. *path* can be the fully-qualified path +or the unique target name (<target dev='hdc'>) of the disk device. *source* +specifies the path of the media to be inserted or updated. The *--block* flag +allows setting the backing type in case a block device is used as media for the +CDROM or floppy drive instead of a file. + +*--eject* indicates the media will be ejected. +*--insert* indicates the media will be inserted. *source* must be specified. +If the device has source (e.g. <source file='media'>), and *source* is not +specified, *--update* is equal to *--eject*. If the device has no source, +and *source* is specified, *--update* is equal to *--insert*. If the device +has source, and *source* is specified, *--update* behaves like combination +of *--eject* and *--insert*. +If none of *--eject*, *--insert*, and *--update* is specified, *--update* +is used by default. +The *--force* option can be used to force media changing. +If *--live* is specified, alter live configuration of running guest. +If *--config* is specified, alter persistent configuration, effect observed +on next boot. +*--current* can be either or both of *live* and *config*, depends on +the hypervisor's implementation. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. If no flag is specified, behavior is different depending +on hypervisor. +If *--print-xml* is specified, the XML that would be used to change media is +printed instead of changing the media. + + +NODEDEV COMMANDS +================ + +The following commands manipulate host devices that are intended to be +passed through to guest domains via <hostdev> elements in a domain's +<devices> section. A node device key is generally specified by the bus +name followed by its address, using underscores between all components, +such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00. +The ``nodedev-list`` gives the full list of host devices that are known +to libvirt, although this includes devices that cannot be assigned to +a guest (for example, attempting to detach the PCI device that controls +the host's hard disk controller where the guest's disk images live could +cause the host system to lock up or reboot). + +For more information on node device definition see: +`https://libvirt.org/formatnode.html <https://libvirt.org/formatnode.html>`_. + +Passthrough devices cannot be simultaneously used by the host and its +guest domains, nor by multiple active guests at once. If the +<hostdev> description of a PCI device includes the attribute ``managed='yes'``, +and the hypervisor driver supports it, then the device is in managed mode, and +attempts to use that passthrough device in an active guest will +automatically behave as if ``nodedev-detach`` (guest start, device +hot-plug) and ``nodedev-reattach`` (guest stop, device hot-unplug) were +called at the right points. If a PCI device is not marked as managed, +then it must manually be detached before guests can use it, and manually +reattached to be returned to the host. Also, if a device is manually detached, +then the host does not regain control of the device without a matching +reattach, even if the guests use the device in managed mode. + + +nodedev-create +-------------- + +.. code-block:: shell + + nodedev-create FILE + +Create a device on the host node that can then be assigned to virtual +machines. Normally, libvirt is able to automatically determine which +host nodes are available for use, but this allows registration of +host hardware that libvirt did not automatically detect. *file* +contains xml for a top-level <device> description of a node device. + + +nodedev-destroy +--------------- + +.. code-block:: shell + + nodedev-destroy device + +Destroy (stop) a device on the host. *device* can be either device +name or wwn pair in "wwnn,wwpn" format (only works for vHBA currently). +Note that this makes libvirt quit managing a host device, and may even +make that device unusable by the rest of the physical host until a reboot. + + +nodedev-detach +-------------- + +.. code-block:: shell + + nodedev-detach nodedev [--driver backend_driver] + +Detach *nodedev* from the host, so that it can safely be used by +guests via <hostdev> passthrough. This is reversed with +``nodedev-reattach``, and is done automatically for managed devices. + +Different backend drivers expect the device to be bound to different +dummy devices. For example, QEMU's "kvm" backend driver (the default) +expects the device to be bound to pci-stub, but its "vfio" backend +driver expects the device to be bound to vfio-pci. The *--driver* +parameter can be used to specify the desired backend driver. + + +nodedev-dumpxml +--------------- + +.. code-block:: shell + + nodedev-dumpxml device + +Dump a <device> XML representation for the given node device, including +such information as the device name, which bus owns the device, the +vendor and product id, and any capabilities of the device usable by +libvirt (such as whether device reset is supported). *device* can +be either device name or wwn pair in "wwnn,wwpn" format (only works +for HBA). + + +nodedev-list +------------ + +.. code-block:: shell + + nodedev-list cap --tree + +List all of the devices available on the node that are known by libvirt. +*cap* is used to filter the list by capability types, the types must be +separated by comma, e.g. --cap pci,scsi. Valid capability types include +'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host', 'scsi_target', +'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic', 'drm', 'mdev', +'mdev_types', 'ccw'. +If *--tree* is used, the output is formatted in a tree representing parents of each +node. *cap* and *--tree* are mutually exclusive. + + +nodedev-reattach +---------------- + +.. code-block:: shell + + nodedev-reattach nodedev + +Declare that *nodedev* is no longer in use by any guests, and that +the host can resume normal use of the device. This is done +automatically for PCI devices in managed mode and USB devices, but +must be done explicitly to match any explicit ``nodedev-detach``. + + +nodedev-reset +------------- + +.. code-block:: shell + + nodedev-reset nodedev + +Trigger a device reset for *nodedev*, useful prior to transferring +a node device between guest passthrough or the host. Libvirt will +often do this action implicitly when required, but this command +allows an explicit reset when needed. + + +nodedev-event +------------- + +.. code-block:: shell + + nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list} + +Wait for a class of node device events to occur, and print appropriate +details of events as they happen. The events can optionally be filtered +by *nodedev*. Using *--list* as the only argument will provide a list +of possible *event* values known by this client, although the connection +might not allow registering for all these events. + +By default, this command is one-shot, and returns success once an event +occurs; you can send SIGINT (usually via ``Ctrl-C``) to quit immediately. +If *--timeout* is specified, the command gives up waiting for events +after *seconds* have elapsed. With *--loop*, the command prints all +events until a timeout or interrupt key. + +When *--timestamp* is used, a human-readable timestamp will be printed +before the event. + + +VIRTUAL NETWORK COMMANDS +======================== + +The following commands manipulate networks. Libvirt has the capability to +define virtual networks which can then be used by domains and linked to +actual network devices. For more detailed information about this feature +see the documentation at `https://libvirt.org/formatnetwork.html <https://libvirt.org/formatnetwork.html>`_ . Many +of the commands for virtual networks are similar to the ones used for domains, +but the way to name a virtual network is either by its name or UUID. + + +net-autostart +------------- + +.. code-block:: shell + + net-autostart network [--disable] + +Configure a virtual network to be automatically started at boot. +The *--disable* option disable autostarting. + + +net-create +---------- + +.. code-block:: shell + + net-create file + +Create a transient (temporary) virtual network from an +XML *file* and instantiate (start) the network. +See the documentation at `https://libvirt.org/formatnetwork.html <https://libvirt.org/formatnetwork.html>`_ +to get a description of the XML network format used by libvirt. + + +net-define +---------- + +.. code-block:: shell + + net-define file + +Define an inactive persistent virtual network or modify an existing persistent +one from the XML *file*. + + +net-destroy +----------- + +.. code-block:: shell + + net-destroy network + +Destroy (stop) a given transient or persistent virtual network +specified by its name or UUID. This takes effect immediately. + + +net-dumpxml +----------- + +.. code-block:: shell + + net-dumpxml network [--inactive] + + +Output the virtual network information as an XML dump to stdout. +If *--inactive* is specified, then physical functions are not +expanded into their associated virtual functions. + + +net-edit +-------- + +.. code-block:: shell + + net-edit network + +Edit the XML configuration file for a network. + +This is equivalent to: + +.. code-block:: shell + + virsh net-dumpxml --inactive network > network.xml + vi network.xml (or make changes with your other text editor) + virsh net-define network.xml + +except that it does some error checking. + +The editor used can be supplied by the ``$VISUAL`` or ``$EDITOR`` environment +variables, and defaults to ``vi``. + + +net-event +--------- + +.. code-block:: shell + + net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list} + +Wait for a class of network events to occur, and print appropriate details +of events as they happen. The events can optionally be filtered by +*network*. Using *--list* as the only argument will provide a list +of possible *event* values known by this client, although the connection +might not allow registering for all these events. + +By default, this command is one-shot, and returns success once an event +occurs; you can send SIGINT (usually via ``Ctrl-C``) to quit immediately. +If *--timeout* is specified, the command gives up waiting for events +after *seconds* have elapsed. With *--loop*, the command prints all +events until a timeout or interrupt key. + +When *--timestamp* is used, a human-readable timestamp will be printed +before the event. + + +net-info +-------- + +.. code-block:: shell + + net-info network + +Returns basic information about the *network* object. + + +net-list +-------- + +.. code-block:: shell + + net-list [--inactive | --all] + { [--table] | --name | --uuid } + [--persistent] [<--transient>] + [--autostart] [<--no-autostart>] + +Returns the list of active networks, if *--all* is specified this will also +include defined but inactive networks, if *--inactive* is specified only the +inactive ones will be listed. You may also want to filter the returned networks +by *--persistent* to list the persistent ones, *--transient* to list the +transient ones, *--autostart* to list the ones with autostart enabled, and +*--no-autostart* to list the ones with autostart disabled. + +If *--name* is specified, network names are printed instead of the table +formatted one per line. If *--uuid* is specified network's UUID's are printed +instead of names. Flag *--table* specifies that the legacy table-formatted +output should be used. This is the default. All of these are mutually +exclusive. + +NOTE: When talking to older servers, this command is forced to use a series of +API calls with an inherent race, where a pool might not be listed or might appear +more than once if it changed state between calls while the list was being +collected. Newer servers do not have this problem. + + +net-name +-------- + +.. code-block:: shell + + net-name network-UUID + +Convert a network UUID to network name. + + +net-start +--------- + +.. code-block:: shell + + net-start network + +Start a (previously defined) inactive network. + + +net-undefine +------------ + +.. code-block:: shell + + net-undefine network + +Undefine the configuration for a persistent network. If the network is active, +make it transient. + + +net-uuid +-------- + +.. code-block:: shell + + net-uuid network-name + +Convert a network name to network UUID. + + +net-update +---------- + +.. code-block:: shell + + net-update network command section xml + [--parent-index index] [[--live] [--config] | [--current]] + +Update the given section of an existing network definition, with the +changes optionally taking effect immediately, without needing to +destroy and re-start the network. + +*command* is one of "add-first", "add-last", "add" (a synonym for +add-last), "delete", or "modify". + +*section* is one of "bridge", "domain", "ip", "ip-dhcp-host", +"ip-dhcp-range", "forward", "forward-interface", "forward-pf", +"portgroup", "dns-host", "dns-txt", or "dns-srv", each section being +named by a concatenation of the xml element hierarchy leading to the +element being changed. For example, "ip-dhcp-host" will change a +<host> element that is contained inside a <dhcp> element inside an +<ip> element of the network. + +*xml* is either the text of a complete xml element of the type being +changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the +name of a file that contains a complete xml element. Disambiguation is +done by looking at the first character of the provided text - if the +first character is "<", it is xml text, if the first character is not +"<", it is the name of a file that contains the xml text to be used. + +The *--parent-index* option is used to specify which of several +parent elements the requested element is in (0-based). For example, a +dhcp <host> element could be in any one of multiple <ip> elements in +the network; if a parent-index isn't provided, the "most appropriate" +<ip> element will be selected (usually the only one that already has a +<dhcp> element), but if *--parent-index* is given, that particular +instance of <ip> will get the modification. + +If *--live* is specified, affect a running network. +If *--config* is specified, affect the next startup of a persistent network. +If *--current* is specified, affect the current network state. +Both *--live* and *--config* flags may be given, but *--current* is +exclusive. Not specifying any flag is the same as specifying *--current*. + + +net-dhcp-leases +--------------- + +.. code-block:: shell + + net-dhcp-leases network [mac] + +Get a list of dhcp leases for all network interfaces connected to the given +virtual *network* or limited output just for one interface if *mac* is +specified. + + +NETWORK PORT COMMANDS +===================== + +The following commands manipulate network ports. Libvirt virtual networks +have ports created when a virtual machine has a virtual network interface +added. In general there should be no need to use any of the commands +here, since the hypervisor drivers run these commands are the right +point in a virtual machine's lifecycle. They can be useful for debugging +problems and / or recovering from bugs / stale state. + + +net-port-list +------------- + +.. code-block:: shell + + net-port-list { [--table] | --uuid } network + +List all network ports recorded against the network. + +If *--uuid* is specified network ports' UUID's are printed +instead of a table. Flag *--table* specifies that the legacy +table-formatted output should be used. This is the default. +All of these are mutually exclusive. + + +net-port-create +--------------- + +.. code-block:: shell + + net-port-create network file + +Allocate a new network port reserving resources based on the +port description. + + +net-port-dumpxml +---------------- + +.. code-block:: shell + + net-port-dumpxml network port + +Output the network port information as an XML dump to stdout. + + +net-port-delete +--------------- + +.. code-block:: shell + + net-port-delete network port + +Delete record of the network port and release its resources + + +INTERFACE COMMANDS +================== + +The following commands manipulate host interfaces. Often, these host +interfaces can then be used by name within domain <interface> elements +(such as a system-created bridge interface), but there is no +requirement that host interfaces be tied to any particular guest +configuration XML at all. + +Many of the commands for host interfaces are similar to the ones used +for domains, and the way to name an interface is either by its name or +its MAC address. However, using a MAC address for an *iface* +argument only works when that address is unique (if an interface and a +bridge share the same MAC address, which is often the case, then using +that MAC address results in an error due to ambiguity, and you must +resort to a name instead). + +iface-bridge +------------ + +.. code-block:: shell + + iface-bridge interface bridge [--no-stp] [delay] [--no-start] + +Create a bridge device named *bridge*, and attach the existing +network device *interface* to the new bridge. The new bridge +defaults to starting immediately, with STP enabled and a delay of 0; +these settings can be altered with *--no-stp*, *--no-start*, and an +integer number of seconds for *delay*. All IP address configuration +of *interface* will be moved to the new bridge device. + +See also ``iface-unbridge`` for undoing this operation. + + +iface-define +------------ + +.. code-block:: shell + + iface-define file + +Define an inactive persistent physical host interface or modify an existing +persistent one from the XML *file*. + + +iface-destroy +------------- + +.. code-block:: shell + + iface-destroy interface + +Destroy (stop) a given host interface, such as by running "if-down" to +disable that interface from active use. This takes effect immediately. + + +iface-dumpxml +------------- + +.. code-block:: shell + + iface-dumpxml interface [--inactive] + +Output the host interface information as an XML dump to stdout. If +*--inactive* is specified, then the output reflects the persistent +state of the interface that will be used the next time it is started. + + +iface-edit +---------- + +.. code-block:: shell + + iface-edit interface + +Edit the XML configuration file for a host interface. + +This is equivalent to: + +.. code-block:: shell + + virsh iface-dumpxml iface > iface.xml + vi iface.xml (or make changes with your other text editor) + virsh iface-define iface.xml + +except that it does some error checking. + +The editor used can be supplied by the ``$VISUAL`` or ``$EDITOR`` environment +variables, and defaults to ``vi``. + + +iface-list +---------- + +.. code-block:: shell + + iface-list [--inactive | --all] + +Returns the list of active host interfaces. If *--all* is specified +this will also include defined but inactive interfaces. If +*--inactive* is specified only the inactive ones will be listed. + + +iface-name +---------- + +.. code-block:: shell + + iface-name interface + +Convert a host interface MAC to interface name, if the MAC address is unique +among the host's interfaces. + +*interface* specifies the interface MAC address. + + +iface-mac +--------- + +.. code-block:: shell + + iface-mac interface + +Convert a host interface name to MAC address. + +*interface* specifies the interface name. + + +iface-start +----------- + +.. code-block:: shell + + iface-start interface + +Start a (previously defined) host interface, such as by running "if-up". + + +iface-unbridge +-------------- + +.. code-block:: shell + + iface-unbridge bridge [--no-start] + +Tear down a bridge device named *bridge*, releasing its underlying +interface back to normal usage, and moving all IP address +configuration from the bridge device to the underlying device. The +underlying interface is restarted unless *--no-start* is present; +this flag is present for symmetry, but generally not recommended. + +See also ``iface-bridge`` for creating a bridge. + + +iface-undefine +-------------- + +.. code-block:: shell + + iface-undefine interface + +Undefine the configuration for an inactive host interface. + + +iface-begin +----------- + +.. code-block:: shell + + iface-begin + +Create a snapshot of current host interface settings, which can later +be committed (*iface-commit*) or restored (*iface-rollback*). If a +snapshot already exists, then this command will fail until the +previous snapshot has been committed or restored. Undefined behavior +results if any external changes are made to host interfaces outside of +the libvirt API between the beginning of a snapshot and its eventual +commit or rollback. + + +iface-commit +------------ + +.. code-block:: shell + + iface-commit + +Declare all changes since the last *iface-begin* as working, and +delete the rollback point. If no interface snapshot has already been +started, then this command will fail. + + +iface-rollback +-------------- + +.. code-block:: shell + + iface-rollback + +Revert all host interface settings back to the state recorded in the +last *iface-begin*. If no interface snapshot has already been +started, then this command will fail. Rebooting the host also serves +as an implicit rollback point. + + +STORAGE POOL COMMANDS +===================== + +The following commands manipulate storage pools. Libvirt has the +capability to manage various storage solutions, including files, raw +partitions, and domain-specific formats, used to provide the storage +volumes visible as devices within virtual machines. For more detailed +information about this feature, see the documentation at +`https://libvirt.org/formatstorage.html <https://libvirt.org/formatstorage.html>`_ . Many of the commands for +pools are similar to the ones used for domains. + +find-storage-pool-sources +------------------------- + +.. code-block:: shell + + find-storage-pool-sources type [srcSpec] + +Returns XML describing all possible available storage pool sources that +could be used to create or define a storage pool of a given *type*. If +*srcSpec* is provided, it is a file that contains XML to further restrict +the query for pools. + +Not all storage pools support discovery in this manner. Furthermore, for +those that do support discovery, only specific XML elements are required +in order to return valid data, while other elements and even attributes +of some elements are ignored since they are not necessary to find the pool +based on the search criteria. The following lists the supported *type* +options and the expected minimal XML elements used to perform the search. + +For a "netfs" or "gluster" pool, the minimal expected XML required is the +<host> element with a "name" attribute describing the IP address or hostname +to be used to find the pool. The "port" attribute will be ignored as will +any other provided XML elements in *srcSpec*. + +For a "logical" pool, the contents of the *srcSpec* file are ignored, +although if provided the file must at least exist. + +For an "iscsi" pool, the minimal expect XML required is the <host> element +with a "name" attribute describing the IP address or hostname to be used to +find the pool (the iSCSI server address). Optionally, the "port" attribute +may be provided, although it will default to 3260. Optionally, an <initiator> +XML element with a "name" attribute may be provided to further restrict the +iSCSI target search to a specific initiator for multi-iqn iSCSI storage pools. + + +find-pool-sources-as +-------------------- + +.. code-block:: shell + + find-storage-pool-sources-as type [host] [port] [initiator] + +Rather than providing *srcSpec* XML file for ``find-storage-pool-sources`` +use this command option in order to have virsh generate the query XML file +using the optional arguments. The command will return the same output +XML as ``find-storage-pool-sources``. + +Use *host* to describe a specific host to use for networked storage, such +as netfs, gluster, and iscsi *type* pools. + +Use *port* to further restrict which networked port to utilize for the +connection if required by the specific storage backend, such as iscsi. + +Use *initiator* to further restrict the iscsi *type* pool searches to +specific target initiators. + + +pool-autostart +-------------- + +.. code-block:: shell + + pool-autostart pool-or-uuid [--disable] + +Configure whether *pool* should automatically start at boot. + + +pool-build +---------- + +.. code-block:: shell + + pool-build pool-or-uuid [--overwrite] [--no-overwrite] + +Build a given pool. + +Options *--overwrite* and *--no-overwrite* can only be used for +``pool-build`` a filesystem, disk, or logical pool. + +For a file system pool if neither flag is specified, then ``pool-build`` +just makes the target path directory and no attempt to run mkfs on the +target volume device. If *--no-overwrite* is specified, it probes to +determine if a filesystem already exists on the target device, returning +an error if one exists or using mkfs to format the target device if not. +If *--overwrite* is specified, mkfs is always executed and any existing +data on the target device is overwritten unconditionally. + +For a disk pool, if neither of them is specified or *--no-overwrite* +is specified, ``pool-build`` will check the target volume device for +existing filesystems or partitions before attempting to write a new +label on the target volume device. If the target volume device already +has a label, the command will fail. If *--overwrite* is specified, +then no check will be made on the target volume device prior to writing +a new label. Writing of the label uses the pool source format type +or "dos" if not specified. + +For a logical pool, if neither of them is specified or *--no-overwrite* +is specified, ``pool-build`` will check the target volume devices for +existing filesystems or partitions before attempting to initialize +and format each device for usage by the logical pool. If any target +volume device already has a label, the command will fail. If +*--overwrite* is specified, then no check will be made on the target +volume devices prior to initializing and formatting each device. Once +all the target volume devices are properly formatted via pvcreate, +the volume group will be created using all the devices. + + +pool-create +----------- + +.. code-block:: shell + + pool-create file [--build] [[--overwrite] | [--no-overwrite]] + +Create and start a pool object from the XML *file*. + +[*--build*] [[*--overwrite*] | [*--no-overwrite*]] perform a +``pool-build`` after creation in order to remove the need for a +follow-up command to build the pool. The *--overwrite* and +*--no-overwrite* flags follow the same rules as ``pool-build``. If +just *--build* is provided, then ``pool-build`` is called with no flags. + + +pool-create-as +-------------- + +.. code-block:: shell + + pool-create-as name type + [--source-host hostname] [--source-path path] [--source-dev path] + [--source-name name] [--target path] [--source-format format] + [--auth-type authtype --auth-username username + [--secret-usage usage | --secret-uuid uuid]] + [--source-protocol-ver ver] + [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn] + [--adapter-parent parent | + --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn | + --adapter-parent-fabric-wwn parent_fabric_wwn]] + [--build] [[--overwrite] | [--no-overwrite]] [--print-xml] + +Create and start a pool object *name* from the raw parameters. If +*--print-xml* is specified, then print the XML of the pool object +without creating the pool. Otherwise, the pool has the specified +*type*. When using ``pool-create-as`` for a pool of *type* "disk", +the existing partitions found on the *--source-dev path* will be used +to populate the disk pool. Therefore, it is suggested to use +``pool-define-as`` and ``pool-build`` with the *--overwrite* in order +to properly initialize the disk pool. + +[*--source-host hostname*] provides the source hostname for pools backed +by storage from a remote server (pool types netfs, iscsi, rbd, sheepdog, +gluster). + +[*--source-path path*] provides the source directory path for pools backed +by directories (pool type dir). + +[*--source-dev path*] provides the source path for pools backed by physical +devices (pool types fs, logical, disk, iscsi, zfs). + +[*--source-name name*] provides the source name for pools backed by storage +from a named element (pool types logical, rbd, sheepdog, gluster). + +[*--target path*] is the path for the mapping of the storage pool into +the host file system. + +[*--source-format format*] provides information about the format of the +pool (pool types fs, netfs, disk, logical). + +[*--auth-type authtype* *--auth-username username* +[*--secret-usage usage* | *--secret-uuid uuid*]] +provides the elements required to generate authentication credentials for +the storage pool. The *authtype* is either chap for iscsi *type* pools or +ceph for rbd *type* pools. Either the secret *usage* or *uuid* value may +be provided, but not both. + +[*--source-protocol-ver ver*] provides the NFS protocol version number used +to contact the server's NFS service via nfs mount option 'nfsvers=n'. It is +expect the *ver* value is an unsigned integer. + +[*--adapter-name name*] defines the scsi_hostN adapter name to be used for +the scsi_host adapter type pool. + +[*--adapter-wwnn wwnn* *--adapter-wwpn wwpn* [*--adapter-parent parent* | +*--adapter-parent-wwnn parent_wwnn* *adapter-parent-wwpn parent_wwpn* | +*--adapter-parent-fabric-wwn parent_fabric_wwn*]] +defines the wwnn and wwpn to be used for the fc_host adapter type pool. +Optionally provide the parent scsi_hostN node device to be used for the +vHBA either by parent name, parent_wwnn and parent_wwpn, or parent_fabric_wwn. +The parent name could change between reboots if the hardware environment +changes, so providing the parent_wwnn and parent_wwpn ensure usage of the +same physical HBA even if the scsi_hostN node device changes. Usage of the +parent_fabric_wwn allows a bit more flexibility to choose an HBA on the +same storage fabric in order to define the pool. + +[*--build*] [[*--overwrite*] | [*--no-overwrite*]] perform a +``pool-build`` after creation in order to remove the need for a +follow-up command to build the pool. The *--overwrite* and +*--no-overwrite* flags follow the same rules as ``pool-build``. If +just *--build* is provided, then ``pool-build`` is called with no flags. + +For a "logical" pool only [*--name*] needs to be provided. The +[*--source-name*] if provided must match the Volume Group name. +If not provided, one will be generated using the [*--name*]. If +provided the [*--target*] is ignored and a target source is generated +using the [*--source-name*] (or as generated from the [*--name*]). + + +pool-define +----------- + +.. code-block:: shell + + pool-define file + +Define an inactive persistent storage pool or modify an existing persistent one +from the XML *file*. + + +pool-define-as +-------------- + +.. code-block:: shell + + pool-define-as name type + [--source-host hostname] [--source-path path] [--source-dev path] + [*--source-name name*] [*--target path*] [*--source-format format*] + [*--auth-type authtype* *--auth-username username* + [*--secret-usage usage* | *--secret-uuid uuid*]] + [*--source-protocol-ver ver*] + [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*] + [*--adapter-parent parent*]] [*--print-xml*] + +Create, but do not start, a pool object *name* from the raw parameters. If +*--print-xml* is specified, then print the XML of the pool object +without defining the pool. Otherwise, the pool has the specified +*type*. + +Use the same arguments as ``pool-create-as``, except for the *--build*, +*--overwrite*, and *--no-overwrite* options. + + +pool-destroy +------------ + +.. code-block:: shell + + pool-destroy pool-or-uuid + +Destroy (stop) a given *pool* object. Libvirt will no longer manage the +storage described by the pool object, but the raw data contained in +the pool is not changed, and can be later recovered with +``pool-create``. + + +pool-delete +----------- + +.. code-block:: shell + + pool-delete pool-or-uuid + +Destroy the resources used by a given *pool* object. This operation +is non-recoverable. The *pool* object will still exist after this +command, ready for the creation of new storage volumes. + + +pool-dumpxml +------------ + +.. code-block:: shell + + pool-dumpxml [--inactive] pool-or-uuid + +Returns the XML information about the *pool* object. +*--inactive* tells virsh to dump pool configuration that will be used +on next start of the pool as opposed to the current pool configuration. + + +pool-edit +--------- + +.. code-block:: shell + + pool-edit pool-or-uuid + +Edit the XML configuration file for a storage pool. + +This is equivalent to: + +.. code-block:: shell + + virsh pool-dumpxml pool > pool.xml + vi pool.xml (or make changes with your other text editor) + virsh pool-define pool.xml + +except that it does some error checking. + +The editor used can be supplied by the ``$VISUAL`` or ``$EDITOR`` environment +variables, and defaults to ``vi``. + + +pool-info +--------- + +.. code-block:: shell + + pool-info [--bytes] pool-or-uuid + +Returns basic information about the *pool* object. If *--bytes* is specified the sizes +of basic info are not converted to human friendly units. + + +pool-list +--------- + +.. code-block:: shell + + pool-list [--inactive] [--all] + [--persistent] [--transient] + [--autostart] [--no-autostart] + [[--details] [--uuid] + [--name] [<type>] + +List pool objects known to libvirt. By default, only active pools +are listed; *--inactive* lists just the inactive pools, and *--all* +lists all pools. + +In addition, there are several sets of filtering flags. *--persistent* is to +list the persistent pools, *--transient* is to list the transient pools. +*--autostart* lists the autostarting pools, *--no-autostart* lists the pools +with autostarting disabled. If *--uuid* is specified only pool's UUIDs are printed. +If *--name* is specified only pool's names are printed. If both *--name* +and *--uuid* are specified, pool's UUID and names are printed side by side +without any header. Option *--details* is mutually exclusive with options +*--uuid* and *--name*. + +You may also want to list pools with specified types using *type*, the +pool types must be separated by comma, e.g. --type dir,disk. The valid pool +types include 'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi', 'scsi', +'mpath', 'rbd', 'sheepdog', 'gluster', 'zfs', 'vstorage' and 'iscsi-direct'. + +The *--details* option instructs virsh to additionally +display pool persistence and capacity related information where available. + +NOTE: When talking to older servers, this command is forced to use a series of +API calls with an inherent race, where a pool might not be listed or might appear +more than once if it changed state between calls while the list was being +collected. Newer servers do not have this problem. + + +pool-name +--------- + +.. code-block:: shell + + pool-name uuid + +Convert the *uuid* to a pool name. + + +pool-refresh +------------ + +.. code-block:: shell + + pool-refresh pool-or-uuid + +Refresh the list of volumes contained in *pool*. + + +pool-start +---------- + +.. code-block:: shell + + pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]] + +Start the storage *pool*, which is previously defined but inactive. + +[*--build*] [[*--overwrite*] | [*--no-overwrite*]] perform a +``pool-build`` prior to ``pool-start`` to ensure the pool environment is +in an expected state rather than needing to run the build command prior +to startup. The *--overwrite* and *--no-overwrite* flags follow the +same rules as ``pool-build``. If just *--build* is provided, then +``pool-build`` is called with no flags. + +``Note``: A storage pool that relies on remote resources such as an +"iscsi" or a (v)HBA backed "scsi" pool may need to be refreshed multiple +times in order to have all the volumes detected (see ``pool-refresh``). +This is because the corresponding volume devices may not be present in +the host's filesystem during the initial pool startup or the current +refresh attempt. The number of refresh retries is dependent upon the +network connection and the time the host takes to export the +corresponding devices. + + +pool-undefine +------------- + +.. code-block:: shell + + pool-undefine pool-or-uuid + +Undefine the configuration for an inactive *pool*. + + +pool-uuid +--------- + +.. code-block:: shell + + pool-uuid pool + +Returns the UUID of the named *pool*. + + +pool-event +---------- + +.. code-block:: shell + + pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list} + +Wait for a class of storage pool events to occur, and print appropriate +details of events as they happen. The events can optionally be filtered +by *pool*. Using *--list* as the only argument will provide a list +of possible *event* values known by this client, although the connection +might not allow registering for all these events. + +By default, this command is one-shot, and returns success once an event +occurs; you can send SIGINT (usually via ``Ctrl-C``) to quit immediately. +If *--timeout* is specified, the command gives up waiting for events +after *seconds* have elapsed. With *--loop*, the command prints all +events until a timeout or interrupt key. + +When *--timestamp* is used, a human-readable timestamp will be printed +before the event. + + +VOLUME COMMANDS +=============== + +vol-create +---------- + +.. code-block:: shell + + vol-create pool-or-uuid FILE [--prealloc-metadata] + +Create a volume from an XML <file>. + +*pool-or-uuid* is the name or UUID of the storage pool to create the volume in. + +*FILE* is the XML <file> with the volume definition. An easy way to create the +XML <file> is to use the ``vol-dumpxml`` command to obtain the definition of a +pre-existing volume. + +[*--prealloc-metadata*] preallocate metadata (for qcow2 images which don't +support full allocation). This option creates a sparse image file with metadata, +resulting in higher performance compared to images with no preallocation and +only slightly higher initial disk space usage. + +Example +~~~~~~~ + +.. code-block:: shell + + virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml + vi newvolume.xml (or make changes with your other text editor) + virsh vol-create differentstoragepool newvolume.xml + + +vol-create-from +--------------- + +.. code-block:: shell + + vol-create-from pool-or-uuid FILE vol-name-or-key-or-path + [--inputpool pool-or-uuid] [--prealloc-metadata] [--reflink] + +Create a volume, using another volume as input. + +*pool-or-uuid* is the name or UUID of the storage pool to create the volume in. + +*FILE* is the XML <file> with the volume definition. + +*vol-name-or-key-or-path* is the name or key or path of the source volume. + +*--inputpool* *pool-or-uuid* is the name or uuid of the storage pool the +source volume is in. + +[*--prealloc-metadata*] preallocate metadata (for qcow2 images which don't +support full allocation). This option creates a sparse image file with metadata, +resulting in higher performance compared to images with no preallocation and +only slightly higher initial disk space usage. + +When *--reflink* is specified, perform a COW lightweight copy, +where the data blocks are copied only when modified. +If this is not possible, the copy fails. + + +vol-create-as +------------- + +.. code-block:: shell + + vol-create-as pool-or-uuid name capacity [--allocation size] [--format string] + [--backing-vol vol-name-or-key-or-path] + [--backing-vol-format string] [--prealloc-metadata] [--print-xml] + +Create a volume from a set of arguments unless *--print-xml* is specified, in +which case just the XML of the volume object is printed out without any actual +object creation. + +*pool-or-uuid* is the name or UUID of the storage pool to create the volume +in. + +*name* is the name of the new volume. For a disk pool, this must match the +partition name as determined from the pool's source device path and the next +available partition. For example, a source device path of /dev/sdb and there +are no partitions on the disk, then the name must be sdb1 with the next +name being sdb2 and so on. + +*capacity* is the size of the volume to be created, as a scaled integer +(see ``NOTES`` above), defaulting to bytes if there is no suffix. + +*--allocation* *size* is the initial size to be allocated in the volume, +also as a scaled integer defaulting to bytes. + +*--format* *string* is used in file based storage pools to specify the volume +file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use extended for disk +storage pools in order to create an extended partition (other values are +validity checked but not preserved when libvirtd is restarted or the pool +is refreshed). + +*--backing-vol* *vol-name-or-key-or-path* is the source backing +volume to be used if taking a snapshot of an existing volume. + +*--backing-vol-format* *string* is the format of the snapshot backing volume; +raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, however, meant for +file based storage pools. + +[*--prealloc-metadata*] preallocate metadata (for qcow2 images which don't +support full allocation). This option creates a sparse image file with metadata, +resulting in higher performance compared to images with no preallocation and +only slightly higher initial disk space usage. + + +vol-clone +--------- + +.. code-block:: shell + + vol-clone vol-name-or-key-or-path name + [--pool pool-or-uuid] [--prealloc-metadata] [--reflink] + +Clone an existing volume within the parent pool. Less powerful, +but easier to type, version of ``vol-create-from``. + +*vol-name-or-key-or-path* is the name or key or path of the source volume. + +*name* is the name of the new volume. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool +that contains the source volume and will contain the new volume. +If the source volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be cloned; otherwise, +the first volume found by the key or path will be used. + +[*--prealloc-metadata*] preallocate metadata (for qcow2 images which don't +support full allocation). This option creates a sparse image file with metadata, +resulting in higher performance compared to images with no preallocation and +only slightly higher initial disk space usage. + +When *--reflink* is specified, perform a COW lightweight copy, +where the data blocks are copied only when modified. +If this is not possible, the copy fails. + + +vol-delete +---------- + +.. code-block:: shell + + vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots] + +Delete a given volume. + +*vol-name-or-key-or-path* is the volume name or key or path of the volume +to delete. + +[*--pool* *pool-or-uuid*] is the name or UUID of the storage pool the volume +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be deleted; otherwise, +the first volume found by the key or path will be used. + +The *--delete-snapshots* flag specifies that any snapshots associated with +the storage volume should be deleted as well. Not all storage drivers +support this option, presently only rbd. + + +vol-upload +---------- + +.. code-block:: shell + + vol-upload vol-name-or-key-or-path local-file + [--pool pool-or-uuid] [--offset bytes] + [--length bytes] [--sparse] + +Upload the contents of *local-file* to a storage volume. + +*vol-name-or-key-or-path* is the name or key or path of the volume where the +*local-file* will be uploaded. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool the volume +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be uploaded into; +otherwise, the first volume found by the key or path will be used. + +*--offset* is the position in the storage volume at which to start writing +the data. The value must be 0 or larger. + +*--length* is an upper bound of the amount of data to be uploaded. +A negative value is interpreted as an unsigned long long value to +essentially include everything from the offset to the end of the volume. + +If *--sparse* is specified, this command will preserve volume sparseness. + +An error will occur if the *local-file* is greater than the specified +*length*. + +See the description for the libvirt virStorageVolUpload API for details +regarding possible target volume and pool changes as a result of the +pool refresh when the upload is attempted. + + +vol-download +------------ + +.. code-block:: shell + + vol-download vol-name-or-key-or-path local-file + [--pool pool-or-uuid] [--offset bytes] [--length bytes] + [--sparse] + +Download the contents of a storage volume to *local-file*. + +*vol-name-or-key-or-path* is the name or key or path of the volume to +download into *local-file*. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool the volume +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be uploaded into; +otherwise, the first volume found by the key or path will be used. + +*--offset* is the position in the storage volume at which to start reading +the data. The value must be 0 or larger. + +*--length* is an upper bound of the amount of data to be downloaded. +A negative value is interpreted as an unsigned long long value to +essentially include everything from the offset to the end of the volume. + +If *--sparse* is specified, this command will preserve volume sparseness. + + +vol-wipe +-------- + +.. code-block:: shell + + vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm] + +Wipe a volume, ensure data previously on the volume is not accessible to +future reads. + +*vol-name-or-key-or-path* is the name or key or path of the volume to wipe. +It is possible to choose different wiping algorithms instead of re-writing +volume with zeroes. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool the +volume is in. If the volume name is provided instead of the key or path, +then providing the pool is necessary to find the volume to be wiped; +otherwise, the first volume found by the key or path will be used. + +Use the *--algorithm* switch choosing from the list of the following +algorithms in order to define which algorithm to use for the wipe. + +``Supported algorithms`` + +* zero - 1-pass all zeroes +* nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for + sanitizing removable and non-removable hard disks: + random x2, 0x00, verify. +* dod - 4-pass DoD 5220.22-M section 8-306 procedure for + sanitizing removable and non-removable rigid + disks: random, 0x00, 0xff, verify. +* bsi - 9-pass method recommended by the German Center of + Security in Information Technologies + (http://www.bsi.bund.de): 0xff, 0xfe, 0xfd, 0xfb, + 0xf7, 0xef, 0xdf, 0xbf, 0x7f. +* gutmann - The canonical 35-pass sequence described in + Gutmann's paper. +* schneier - 7-pass method described by Bruce Schneier in + "Applied Cryptography" (1996): 0x00, 0xff, random x5. +* pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7. +* pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33. +* random - 1-pass pattern: random. +* trim - 1-pass trimming the volume using TRIM or DISCARD + +``Note``: The ``scrub`` binary will be used to handle the 'nnsa', 'dod', +'bsi', 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33' algorithms. +The availability of the algorithms may be limited by the version of +the ``scrub`` binary installed on the host. The 'zero' algorithm will +write zeroes to the entire volume. For some volumes, such as sparse +or rbd volumes, this may result in completely filling the volume with +zeroes making it appear to be completely full. As an alternative, the +'trim' algorithm does not overwrite all the data in a volume, rather +it expects the storage driver to be able to discard all bytes in a +volume. It is up to the storage driver to handle how the discarding +occurs. Not all storage drivers or volume types can support 'trim'. + + +vol-dumpxml +----------- + +.. code-block:: shell + + vol-dumpxml vol-name-or-key-or-path [--pool pool-or-uuid] + +Output the volume information as an XML dump to stdout. + +*vol-name-or-key-or-path* is the name or key or path of the volume +to output the XML. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool the volume +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be uploaded into; +otherwise, the first volume found by the key or path will be used. + + +vol-info +-------- + +.. code-block:: shell + + vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical] + +Returns basic information about the given storage volume. + +*vol-name-or-key-or-path* is the name or key or path of the volume +to return information for. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool the volume +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be uploaded into; +otherwise, the first volume found by the key or path will be used. + +If *--bytes* is specified the sizes are not converted to human friendly +units. + +If *--physical* is specified, then the host physical size is returned +and displayed instead of the allocation value. The physical value for +some file types, such as qcow2 may have a different (larger) physical +value than is shown for allocation. Additionally sparse files will +have different physical and allocation values. + + +vol-list +-------- + +.. code-block:: shell + + vol-list [--pool pool-or-uuid] [--details] + +Return the list of volumes in the given storage pool. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool. + +The *--details* option instructs virsh to additionally display volume +type and capacity related information where available. + + +vol-pool +-------- + +.. code-block:: shell + + vol-pool vol-key-or-path [--uuid] + +Return the pool name or UUID for a given volume. By default, the pool name is +returned. + +*vol-key-or-path* is the key or path of the volume to return the pool +information. + +If the *--uuid* option is given, the pool UUID is returned instead. + + +vol-path +-------- + +.. code-block:: shell + + vol-path vol-name-or-key [--pool pool-or-uuid] + +Return the path for a given volume. + +*vol-name-or-key* is the name or key of the volume to return the path. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool the volume +is in. If the volume name is provided instead of the key, then providing +the pool is necessary to find the volume to be uploaded into; otherwise, +the first volume found by the key will be used. + + +vol-name +-------- + +.. code-block:: shell + + vol-name vol-key-or-path + +Return the name for a given volume. + +*vol-key-or-path* is the key or path of the volume to return the name. + + +vol-key +------- + +.. code-block:: shell + + vol-key vol-name-or-path [--pool pool-or-uuid] + +Return the volume key for a given volume. + +*vol-name-or-path* is the name or path of the volume to return the +volume key. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool the volume +is in. If the volume name is provided instead of the path, then providing +the pool is necessary to find the volume to be uploaded into; otherwise, +the first volume found by the path will be used. + + +vol-resize +---------- + +.. code-block:: shell + + vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink] + +Resize the capacity of the given volume, in bytes. + +*vol-name-or-key-or-path* is the name or key or path of the volume +to resize. + +*capacity* is a scaled integer (see ``NOTES`` above) for the volume, +which defaults to bytes if there is no suffix. + +*--pool* *pool-or-uuid* is the name or UUID of the storage pool the volume +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be uploaded into; +otherwise, the first volume found by the key or path will be used. + +The new *capacity* might be sparse unless *--allocate* is specified. + +Normally, *capacity* is the new size, but if *--delta* +is present, then it is added to the existing size. + +Attempts to shrink the volume will fail unless *--shrink* is present. +The *capacity* cannot be negative unless *--shrink* is provided, but +a negative sign is not necessary. + +This command is only safe for storage volumes not in use by an active +guest; see also ``blockresize`` for live resizing. + + +SECRET COMMANDS +=============== + +The following commands manipulate "secrets" (e.g. passwords, passphrases and +encryption keys). Libvirt can store secrets independently from their use, and +other objects (e.g. volumes or domains) can refer to the secrets for encryption +or possibly other uses. Secrets are identified using a UUID. See +`https://libvirt.org/formatsecret.html <https://libvirt.org/formatsecret.html>`_ for documentation of the XML format +used to represent properties of secrets. + +secret-define +------------- + +.. code-block:: shell + + secret-define file + +Create a secret with the properties specified in *file*, with no associated +secret value. If *file* does not specify a UUID, choose one automatically. +If *file* specifies a UUID of an existing secret, replace its properties by +properties defined in *file*, without affecting the secret value. + + +secret-dumpxml +-------------- + +.. code-block:: shell + + secret-dumpxml secret + +Output properties of *secret* (specified by its UUID) as an XML dump to stdout. + + +secret-event +------------ + +.. code-block:: shell + + secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list} + +Wait for a class of secret events to occur, and print appropriate details +of events as they happen. The events can optionally be filtered by +*secret*. Using *--list* as the only argument will provide a list +of possible *event* values known by this client, although the connection +might not allow registering for all these events. + +By default, this command is one-shot, and returns success once an event +occurs; you can send SIGINT (usually via ``Ctrl-C``) to quit immediately. +If *--timeout* is specified, the command gives up waiting for events +after *seconds* have elapsed. With *--loop*, the command prints all +events until a timeout or interrupt key. + +When *--timestamp* is used, a human-readable timestamp will be printed +before the event. + + +secret-set-value +---------------- + +.. code-block:: shell + + secret-set-value secret base64 + +Set the value associated with *secret* (specified by its UUID) to the value +Base64-encoded value *base64*. + + +secret-get-value +---------------- + +.. code-block:: shell + + secret-get-value secret + +Output the value associated with *secret* (specified by its UUID) to stdout, +encoded using Base64. + + +secret-undefine +--------------- + +.. code-block:: shell + + secret-undefine secret + + +Delete a *secret* (specified by its UUID), including the associated value, if +any. + + +secret-list +----------- + +.. code-block:: shell + + secret-list [--ephemeral] [--no-ephemeral] + [--private] [--no-private] + +Returns the list of secrets. You may also want to filter the returned secrets +by *--ephemeral* to list the ephemeral ones, *--no-ephemeral* to list the +non-ephemeral ones, *--private* to list the private ones, and +*--no-private* to list the non-private ones. + + +SNAPSHOT COMMANDS +================= + +The following commands manipulate domain snapshots. Snapshots take the +disk, memory, and device state of a domain at a point-of-time, and save it +for future use. They have many uses, from saving a "clean" copy of an OS +image to saving a domain's state before a potentially destructive operation. +Snapshots are identified with a unique name. See +`https://libvirt.org/formatsnapshot.html <https://libvirt.org/formatsnapshot.html>`_ for documentation of the XML format +used to represent properties of snapshots. + +snapshot-create +--------------- + +.. code-block:: shell + + snapshot-create domain [xmlfile] {[--redefine [--current]] | + [--no-metadata] [--halt] [--disk-only] [--reuse-external] + [--quiesce] [--atomic] [--live]} [--validate] + +Create a snapshot for domain *domain* with the properties specified in +*xmlfile*. Optionally, the *--validate* option can be passed to +validate the format of the input XML file against an internal RNG +schema (identical to using the virt-xml-validate(1) tool). Normally, +the only properties settable for a domain snapshot +are the <name> and <description> elements, as well as <disks> if +*--disk-only* is given; the rest of the fields are +ignored, and automatically filled in by libvirt. If *xmlfile* is +completely omitted, then libvirt will choose a value for all fields. +The new snapshot will become current, as listed by ``snapshot-current``. + +If *--halt* is specified, the domain will be left in an inactive state +after the snapshot is created. + +If *--disk-only* is specified, the snapshot will only include disk +content rather than the usual full system snapshot with vm state. Disk +snapshots are captured faster than full system snapshots, but reverting to a +disk snapshot may require fsck or journal replays, since it is like +the disk state at the point when the power cord is abruptly pulled; +and mixing *--halt* and *--disk-only* loses any data that was not +flushed to disk at the time. + +If *--redefine* is specified, then all XML elements produced by +``snapshot-dumpxml`` are valid; this can be used to migrate snapshot +hierarchy from one machine to another, to recreate hierarchy for the +case of a transient domain that goes away and is later recreated with +the same name and UUID, or to make slight alterations in the snapshot +metadata (such as host-specific aspects of the domain XML embedded in +the snapshot). When this flag is supplied, the *xmlfile* argument +is mandatory, and the domain's current snapshot will not be altered +unless the *--current* flag is also given. + +If *--no-metadata* is specified, then the snapshot data is created, +but any metadata is immediately discarded (that is, libvirt does not +treat the snapshot as current, and cannot revert to the snapshot +unless *--redefine* is later used to teach libvirt about the +metadata again). + +If *--reuse-external* is specified, and the snapshot XML requests an +external snapshot with a destination of an existing file, then the +destination must exist and be pre-created with correct format and +metadata. The file is then reused; otherwise, a snapshot is refused +to avoid losing contents of the existing files. + +If *--quiesce* is specified, libvirt will try to use guest agent +to freeze and unfreeze domain's mounted file systems. However, +if domain has no guest agent, snapshot creation will fail. +Currently, this requires *--disk-only* to be passed as well. + +If *--atomic* is specified, libvirt will guarantee that the snapshot +either succeeds, or fails with no changes; not all hypervisors support +this. If this flag is not specified, then some hypervisors may fail +after partially performing the action, and ``dumpxml`` must be used to +see whether any partial changes occurred. + +If *--live* is specified, libvirt takes the snapshot while +the guest is running. Both disk snapshot and domain memory snapshot are +taken. This increases the size of the memory image of the external +snapshot. This is currently supported only for full system external snapshots. + +Existence of snapshot metadata will prevent attempts to ``undefine`` +a persistent domain. However, for transient domains, snapshot +metadata is silently lost when the domain quits running (whether +by command such as ``destroy`` or by internal guest action). + +For now, it is not possible to create snapshots in a domain that has +checkpoints, although this restriction will be lifted in a future +release. + + +snapshot-create-as +------------------ + +.. code-block:: shell + + snapshot-create-as domain {[--print-xml] [--no-metadata] + [--halt] [--reuse-external]} [name] + [description] [--disk-only [--quiesce]] [--atomic] + [[--live] [--memspec memspec]] [--diskspec] diskspec]... + +Create a snapshot for domain *domain* with the given <name> and +<description>; if either value is omitted, libvirt will choose a +value. If *--print-xml* is specified, then XML appropriate for +*snapshot-create* is output, rather than actually creating a snapshot. +Otherwise, if *--halt* is specified, the domain will be left in an +inactive state after the snapshot is created, and if *--disk-only* +is specified, the snapshot will not include vm state. + +The *--memspec* option can be used to control whether a full system snapshot +is internal or external. The *--memspec* flag is mandatory, followed +by a ``memspec`` of the form ``[file=]name[,snapshot=type]``, where +type can be ``no``, ``internal``, or ``external``. To include a literal +comma in ``file=name``, escape it with a second comma. *--memspec* cannot +be used together with *--disk-only*. + +The *--diskspec* option can be used to control how *--disk-only* and +external full system snapshots create external files. This option can occur +multiple times, according to the number of <disk> elements in the domain +xml. Each <diskspec> is in the +form ``disk[,snapshot=type][,driver=type][,stype=type][,file=name]``. +A *diskspec* must be provided for disks backed by block devices as libvirt +doesn't auto-generate file names for those. The optional ``stype`` parameter +allows to control the type of the source file. Supported values are 'file' +(default) and 'block'. + +To include a literal comma in ``disk`` or in ``file=name``, escape it with a +second comma. A literal *--diskspec* must precede each ``diskspec`` unless +all three of *domain*, *name*, and *description* are also present. +For example, a diskspec of "vda,snapshot=external,file=/path/to,,new" +results in the following XML: + +.. code-block:: xml + + <disk name='vda' snapshot='external'> + <source file='/path/to,new'/> + </disk> + +If *--reuse-external* is specified, and the domain XML or *diskspec* +option requests an external snapshot with a destination of an existing +file, then the destination must exist and be pre-created with correct +format and metadata. The file is then reused; otherwise, a snapshot +is refused to avoid losing contents of the existing files. + +If *--quiesce* is specified, libvirt will try to use guest agent +to freeze and unfreeze domain's mounted file systems. However, +if domain has no guest agent, snapshot creation will fail. +Currently, this requires *--disk-only* to be passed as well. + +If *--no-metadata* is specified, then the snapshot data is created, +but any metadata is immediately discarded (that is, libvirt does not +treat the snapshot as current, and cannot revert to the snapshot +unless ``snapshot-create`` is later used to teach libvirt about the +metadata again). + +If *--atomic* is specified, libvirt will guarantee that the snapshot +either succeeds, or fails with no changes; not all hypervisors support +this. If this flag is not specified, then some hypervisors may fail +after partially performing the action, and ``dumpxml`` must be used to +see whether any partial changes occurred. + +If *--live* is specified, libvirt takes the snapshot while the guest is +running. This increases the size of the memory image of the external +snapshot. This is currently supported only for external full system snapshots. + +For now, it is not possible to create snapshots in a domain that has +checkpoints, although this restriction will be lifted in a future +release. + + +snapshot-current +---------------- + +.. code-block:: shell + + snapshot-current domain {[--name] | [--security-info] | [snapshotname]} + +Without *snapshotname*, this will output the snapshot XML for the domain's +current snapshot (if any). If *--name* is specified, just the +current snapshot name instead of the full xml. Otherwise, using +*--security-info* will also include security sensitive information in +the XML. + +With *snapshotname*, this is a request to make the existing named +snapshot become the current snapshot, without reverting the domain. + + +snapshot-edit +------------- + +.. code-block:: shell + + snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]} + +Edit the XML configuration file for *snapshotname* of a domain. If +both *snapshotname* and *--current* are specified, also force the +edited snapshot to become the current snapshot. If *snapshotname* +is omitted, then *--current* must be supplied, to edit the current +snapshot. + +This is equivalent to: + +.. code-block:: shell + + virsh snapshot-dumpxml dom name > snapshot.xml + vi snapshot.xml (or make changes with your other text editor) + virsh snapshot-create dom snapshot.xml --redefine [--current] + +except that it does some error checking. + +The editor used can be supplied by the ``$VISUAL`` or ``$EDITOR`` environment +variables, and defaults to ``vi``. + +If *--rename* is specified, then the edits can change the snapshot +name. If *--clone* is specified, then changing the snapshot name +will create a clone of the snapshot metadata. If neither is specified, +then the edits must not change the snapshot name. Note that changing +a snapshot name must be done with care, since the contents of some +snapshots, such as internal snapshots within a single qcow2 file, are +accessible only from the original name. + + +snapshot-info +------------- + +.. code-block:: shell + + snapshot-info domain {snapshot | --current} + +Output basic information about a named <snapshot>, or the current snapshot +with *--current*. + + +snapshot-list +------------- + +.. code-block:: shell + + snapshot-list domain [--metadata] [--no-metadata] + [{--parent | --roots | [{--tree | --name}]}] [--topological] + [{[--from] snapshot | --current} [--descendants]] + [--leaves] [--no-leaves] [--inactive] [--active] + [--disk-only] [--internal] [--external] + +List all of the available snapshots for the given domain, defaulting +to show columns for the snapshot name, creation time, and domain state. + +Normally, table form output is sorted by snapshot name; using +*--topological* instead sorts so that no child is listed before its +ancestors (although there may be more than one possible ordering with +this property). + +If *--parent* is specified, add a column to the output table giving +the name of the parent of each snapshot. If *--roots* is specified, +the list will be filtered to just snapshots that have no parents. +If *--tree* is specified, the output will be in a tree format, listing +just snapshot names. These three options are mutually exclusive. If +*--name* is specified only the snapshot name is printed. This option is +mutually exclusive with *--tree*. + +If *--from* is provided, filter the list to snapshots which are +children of the given ``snapshot``; or if *--current* is provided, +start at the current snapshot. When used in isolation or with +*--parent*, the list is limited to direct children unless +*--descendants* is also present. When used with *--tree*, the +use of *--descendants* is implied. This option is not compatible +with *--roots*. Note that the starting point of *--from* or +*--current* is not included in the list unless the *--tree* +option is also present. + +If *--leaves* is specified, the list will be filtered to just +snapshots that have no children. Likewise, if *--no-leaves* is +specified, the list will be filtered to just snapshots with +children. (Note that omitting both options does no filtering, +while providing both options will either produce the same list +or error out depending on whether the server recognizes the flags). +Filtering options are not compatible with *--tree*. + +If *--metadata* is specified, the list will be filtered to just +snapshots that involve libvirt metadata, and thus would prevent +``undefine`` of a persistent domain, or be lost on ``destroy`` of +a transient domain. Likewise, if *--no-metadata* is specified, +the list will be filtered to just snapshots that exist without +the need for libvirt metadata. + +If *--inactive* is specified, the list will be filtered to snapshots +that were taken when the domain was shut off. If *--active* is +specified, the list will be filtered to snapshots that were taken +when the domain was running, and where the snapshot includes the +memory state to revert to that running state. If *--disk-only* is +specified, the list will be filtered to snapshots that were taken +when the domain was running, but where the snapshot includes only +disk state. + +If *--internal* is specified, the list will be filtered to snapshots +that use internal storage of existing disk images. If *--external* +is specified, the list will be filtered to snapshots that use external +files for disk images or memory state. + + +snapshot-dumpxml +---------------- + +.. code-block:: shell + + snapshot-dumpxml domain snapshot [--security-info] + +Output the snapshot XML for the domain's snapshot named *snapshot*. +Using *--security-info* will also include security sensitive information. +Use ``snapshot-current`` to easily access the XML of the current snapshot. + + +snapshot-parent +--------------- + +.. code-block:: shell + + snapshot-parent domain {snapshot | --current} + +Output the name of the parent snapshot, if any, for the given +*snapshot*, or for the current snapshot with *--current*. + + +snapshot-revert +--------------- + +.. code-block:: shell + + snapshot-revert domain {snapshot | --current} [{--running | --paused}] [--force] + +Revert the given domain to the snapshot specified by *snapshot*, or to +the current snapshot with *--current*. Be aware +that this is a destructive action; any changes in the domain since the last +snapshot was taken will be lost. Also note that the state of the domain after +snapshot-revert is complete will be the state of the domain at the time +the original snapshot was taken. + +Normally, reverting to a snapshot leaves the domain in the state it was +at the time the snapshot was created, except that a disk snapshot with +no vm state leaves the domain in an inactive state. Passing either the +*--running* or *--paused* flag will perform additional state changes +(such as booting an inactive domain, or pausing a running domain). Since +transient domains cannot be inactive, it is required to use one of these +flags when reverting to a disk snapshot of a transient domain. + +There are two cases where a snapshot revert involves extra risk, which +requires the use of *--force* to proceed. One is the case of a +snapshot that lacks full domain information for reverting +configuration (such as snapshots created prior to libvirt 0.9.5); +since libvirt cannot prove that the current configuration matches what +was in use at the time of the snapshot, supplying *--force* assures +libvirt that the snapshot is compatible with the current configuration +(and if it is not, the domain will likely fail to run). The other is +the case of reverting from a running domain to an active state where a +new hypervisor has to be created rather than reusing the existing +hypervisor, because it implies drawbacks such as breaking any existing +VNC or Spice connections; this condition happens with an active +snapshot that uses a provably incompatible configuration, as well as +with an inactive snapshot that is combined with the *--start* or +*--pause* flag. + + +snapshot-delete +--------------- + +.. code-block:: shell + + snapshot-delete domain {snapshot | --current} + [--metadata] [{--children | --children-only}] + +Delete the snapshot for the domain named *snapshot*, or the current +snapshot with *--current*. If this snapshot +has child snapshots, changes from this snapshot will be merged into the +children. If *--children* is passed, then delete this snapshot and any +children of this snapshot. If *--children-only* is passed, then delete +any children of this snapshot, but leave this snapshot intact. These +two flags are mutually exclusive. + +If *--metadata* is specified, then only delete the snapshot metadata +maintained by libvirt, while leaving the snapshot contents intact for +access by external tools; otherwise deleting a snapshot also removes +the data contents from that point in time. + + +CHECKPOINT COMMANDS +=================== + +The following commands manipulate domain checkpoints. Checkpoints serve as +a point in time to identify which portions of a guest's disks have changed +after that time, making it possible to perform incremental and differential +backups. Checkpoints are identified with a unique name. See +`https://libvirt.org/formatcheckpoint.html <https://libvirt.org/formatcheckpoint.html>`_ for documentation of the XML +format used to represent properties of checkpoints. + +checkpoint-create +----------------- + +.. code-block:: shell + + checkpoint-create domain [xmlfile] { --redefine | [--quiesce]} + +Create a checkpoint for domain *domain* with the properties specified +in *xmlfile* describing a <domaincheckpoint> top-level element. The +format of the input XML file will be validated against an internal RNG +schema (idential to using the virt-xml-validate(1) tool). If +*xmlfile* is completely omitted, then libvirt will create a +checkpoint with a name based on the current time. + +If *--redefine* is specified, then all XML elements produced by +``checkpoint-dumpxml`` are valid; this can be used to migrate +checkpoint hierarchy from one machine to another, to recreate +hierarchy for the case of a transient domain that goes away and is +later recreated with the same name and UUID, or to make slight +alterations in the checkpoint metadata (such as host-specific aspects +of the domain XML embedded in the checkpoint). When this flag is +supplied, the *xmlfile* argument is mandatory. + +If *--quiesce* is specified, libvirt will try to use guest agent +to freeze and unfreeze domain's mounted file systems. However, +if domain has no guest agent, checkpoint creation will fail. + +Existence of checkpoint metadata will prevent attempts to ``undefine`` +a persistent domain. However, for transient domains, checkpoint +metadata is silently lost when the domain quits running (whether +by command such as ``destroy`` or by internal guest action). + +For now, it is not possible to create checkpoints in a domain that has +snapshots, although this restriction will be lifted in a future +release. + + +checkpoint-create-as +-------------------- + +.. code-block:: shell + + checkpoint-create-as domain [--print-xml] [name] + [description] [--quiesce] [--diskspec] diskspec]... + +Create a checkpoint for domain *domain* with the given <name> and +<description>; if either value is omitted, libvirt will choose a +value. If *--print-xml* is specified, then XML appropriate for +*checkpoint-create* is output, rather than actually creating a +checkpoint. + +The *--diskspec* option can be used to control which guest disks +participate in the checkpoint. This option can occur multiple times, +according to the number of <disk> elements in the domain xml. Each +<diskspec> is in the form ``disk[,checkpoint=type][,bitmap=name]``. A +literal *--diskspec* must precede each ``diskspec`` unless +all three of *domain*, *name*, and *description* are also present. +For example, a diskspec of "vda,checkpoint=bitmap,bitmap=map1" +results in the following XML: + +.. code-block:: xml + + <disk name='vda' checkpoint='bitmap' bitmap='map1'/> + +If *--quiesce* is specified, libvirt will try to use guest agent +to freeze and unfreeze domain's mounted file systems. However, +if domain has no guest agent, checkpoint creation will fail. + +For now, it is not possible to create checkpoints in a domain that has +snapshots, although this restriction will be lifted in a future +release. + + +checkpoint-edit +--------------- + +.. code-block:: shell + + checkpoint-edit domain checkpointname + +Edit the XML configuration file for *checkpointname* of a domain. + +This is equivalent to: + +.. code-block:: shell + + virsh checkpoint-dumpxml dom name > checkpoint.xml + vi checkpoint.xml (or make changes with your other text editor) + virsh checkpoint-create dom checkpoint.xml --redefine + +except that it does some error checking, including that the edits +should not attempt to change the checkpoint name. + +The editor used can be supplied by the ``$VISUAL`` or ``$EDITOR`` environment +variables, and defaults to ``vi``. + + +checkpoint-info +--------------- + +.. code-block:: shell + + checkpoint-info domain checkpoint + +Output basic information about a named <checkpoint>. + + +checkpoint-list +--------------- + +.. code-block:: shell + + checkpoint-list domain [{--parent | --roots | + [{--tree | --name}]}] [--topological] + [[--from] checkpoint | [--descendants]] + [--leaves] [--no-leaves] + +List all of the available checkpoints for the given domain, defaulting +to show columns for the checkpoint name and creation time. + +Normally, table form output is sorted by checkpoint name; using +*--topological* instead sorts so that no child is listed before its +ancestors (although there may be more than one possible ordering with +this property). + +If *--parent* is specified, add a column to the output table giving +the name of the parent of each checkpoint. If *--roots* is +specified, the list will be filtered to just checkpoints that have no +parents. If *--tree* is specified, the output will be in a tree +format, listing just checkpoint names. These three options are +mutually exclusive. If *--name* is specified only the checkpoint name +is printed. This option is mutually exclusive with *--tree*. + +If *--from* is provided, filter the list to checkpoints which are +children of the given ``checkpoint``. When used in isolation or with +*--parent*, the list is limited to direct children unless +*--descendants* is also present. When used with *--tree*, the use +of *--descendants* is implied. This option is not compatible with +*--roots*. Note that the starting point of *--from* +is not included in the list unless the *--tree* option is also +present. + +If *--leaves* is specified, the list will be filtered to just +checkpoints that have no children. Likewise, if *--no-leaves* is +specified, the list will be filtered to just checkpoints with +children. (Note that omitting both options does no filtering, while +providing both options will either produce the same list or error out +depending on whether the server recognizes the flags). Filtering +options are not compatible with *--tree*. + + +checkpoint-dumpxml +------------------ + +.. code-block:: shell + + checkpoint-dumpxml domain checkpoint [--security-info] [--no-domain] [--size] + +Output the checkpoint XML for the domain's checkpoint named +*checkpoint*. Using +*--security-info* will also include security sensitive information. +Using *--size* will add XML indicating the current size in bytes of +guest data that has changed since the checkpoint was created (although +remember that guest activity between a size check and actually +creating a backup can result in the backup needing slightly more +space). Using *--no-domain* will omit the <domain> element from the +output for a more compact view. + + +checkpoint-parent +----------------- + +.. code-block:: shell + + checkpoint-parent domain checkpoint + +Output the name of the parent checkpoint, if any, for the given +*checkpoint*. + +checkpoint +---------- + +.. code-block:: shell + + checkpoint-delete domain checkpoint + [--metadata] [{--children | --children-only}] + +Delete the checkpoint for the domain named *checkpoint*. The +record of which portions of +the disk changed since the checkpoint are merged into the parent +checkpoint (if any). If *--children* is passed, then delete this +checkpoint and any children of this checkpoint. If *--children-only* +is passed, then delete any children of this checkpoint, but leave this +checkpoint intact. These two flags are mutually exclusive. + +If *--metadata* is specified, then only delete the checkpoint +metadata maintained by libvirt, while leaving the checkpoint contents +intact for access by external tools; otherwise deleting a checkpoint +also removes the ability to perform an incremental backup from that +point in time. + + +NWFILTER COMMANDS +================= + +The following commands manipulate network filters. Network filters allow +filtering of the network traffic coming from and going to virtual machines. +Individual network traffic filters are written in XML and may contain +references to other network filters, describe traffic filtering rules, +or contain both. Network filters are referenced by virtual machines +from within their interface description. A network filter may be referenced +by multiple virtual machines' interfaces. + + +nwfilter-define +--------------- + +.. code-block:: shell + + nwfilter-define xmlfile + +Make a new network filter known to libvirt. If a network filter with +the same name already exists, it will be replaced with the new XML. +Any running virtual machine referencing this network filter will have +its network traffic rules adapted. If for any reason the network traffic +filtering rules cannot be instantiated by any of the running virtual +machines, then the new XML will be rejected. + + +nwfilter-undefine +----------------- + +.. code-block:: shell + + nwfilter-undefine nwfilter-name + +Delete a network filter. The deletion will fail if any running virtual +machine is currently using this network filter. + + +nwfilter-list +------------- + +.. code-block:: shell + + nwfilter-list + +List all of the available network filters. + + +nwfilter-dumpxml +---------------- + +.. code-block:: shell + + nwfilter-dumpxml nwfilter-name + +Output the network filter XML. + + +nwfilter-edit +------------- + +.. code-block:: shell + + nwfilter-edit nwfilter-name + +Edit the XML of a network filter. + +This is equivalent to: + +.. code-block:: shell + + virsh nwfilter-dumpxml myfilter > myfilter.xml + vi myfilter.xml (or make changes with your other text editor) + virsh nwfilter-define myfilter.xml + +except that it does some error checking. +The new network filter may be rejected due to the same reason as +mentioned in *nwfilter-define*. + +The editor used can be supplied by the ``$VISUAL`` or ``$EDITOR`` environment +variables, and defaults to ``vi``. + + +NWFILTER BINDING COMMANDS +========================= + +The following commands manipulate network filter bindings. Network filter +bindings track the association between a network port and a network +filter. Generally the bindings are managed automatically by the hypervisor +drivers when adding/removing NICs on a guest. + +If an admin is creating/deleting TAP devices for non-guest usage, +however, the network filter binding commands provide a way to make use +of the network filters directly. + +nwfilter-binding-create +----------------------- + +.. code-block:: shell + + nwfilter-binding-create xmlfile + +Associate a network port with a network filter. The network filter backend +will immediately attempt to instantiate the filter rules on the port. This +command may be used to associate a filter with a currently running guest +that does not have a filter defined for a specific network port. Since the +bindings are generally automatically managed by the hypervisor, using this +command to define a filter for a network port and then starting the guest +afterwards may prevent the guest from starting if it attempts to use the +network port and finds a filter already defined. + + +nwfilter-binding-delete +----------------------- + +.. code-block:: shell + + nwfilter-binding-delete port-name + +Disassociate a network port from a network filter. The network filter +backend will immediately tear down the filter rules that exist on the +port. This command may be used to remove the network port binding for +a filter currently in use for the guest while the guest is running +without needing to restart the guest. Restoring the network port binding +filter for the running guest would be accomplished by using +*nwfilter-binding-create*. + + +nwfilter-binding-list +--------------------- + +.. code-block:: shell + + nwfilter-binding-list + +List all of the network ports which have filters associated with them. + + +nwfilter-binding-dumpxml +------------------------ + +.. code-block:: shell + + nwfilter-binding-dumpxml port-name + +Output the network filter binding XML for the network device called +``port-name``. + + +HYPERVISOR-SPECIFIC COMMANDS +============================ + +NOTE: Use of the following commands is ``strongly`` discouraged. They +can cause libvirt to become confused and do the wrong thing on subsequent +operations. Once you have used these commands, please do not report +problems to the libvirt developers; the reports will be ignored. If +you find that these commands are the only way to accomplish something, +then it is better to request that the feature be added as a first-class +citizen in the regular libvirt library. + +qemu-attach +----------- + +.. code-block:: shell + + qemu-attach pid + +Attach an externally launched QEMU process to the libvirt QEMU driver. +The QEMU process must have been created with a monitor connection +using the UNIX driver. Ideally the process will also have had the +'-name' argument specified. + +.. code-block:: shell + + $ qemu-kvm -cdrom ~/demo.iso \ + -monitor unix:/tmp/demo,server,nowait \ + -name foo \ + -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea & + $ QEMUPID=$! + $ virsh qemu-attach $QEMUPID + +Not all functions of libvirt are expected to work reliably after +attaching to an externally launched QEMU process. There may be +issues with the guest ABI changing upon migration and device hotplug +or hotunplug may not work. The attached environment should be considered +primarily read-only. + + +qemu-monitor-command +-------------------- + +.. code-block:: shell + + qemu-monitor-command domain { [--hmp] | [--pretty] } command... + +Send an arbitrary monitor command *command* to domain *domain* through the +qemu monitor. The results of the command will be printed on stdout. If +*--hmp* is passed, the command is considered to be a human monitor command +and libvirt will automatically convert it into QMP if needed. In that case +the result will also be converted back from QMP. If *--pretty* is given, +and the monitor uses QMP, then the output will be pretty-printed. If more +than one argument is provided for *command*, they are concatenated with a +space in between before passing the single command to the monitor. + + +qemu-agent-command +------------------ + +.. code-block:: shell + + qemu-agent-command domain [--timeout seconds | --async | --block] command... + +Send an arbitrary guest agent command *command* to domain *domain* through +qemu agent. +*--timeout*, *--async* and *--block* options are exclusive. +*--timeout* requires timeout seconds *seconds* and it must be positive. +When *--aysnc* is given, the command waits for timeout whether success or +failed. And when *--block* is given, the command waits forever with blocking +timeout. + + +qemu-monitor-event +------------------ + +.. code-block:: shell + + qemu-monitor-event [domain] [--event event-name] + [--loop] [--timeout seconds] [--pretty] [--regex] [--no-case] + [--timestamp] + +Wait for arbitrary QEMU monitor events to occur, and print out the +details of events as they happen. The events can optionally be filtered +by *domain* or *event-name*. The 'query-events' QMP command can be +used via *qemu-monitor-command* to learn what events are supported. +If *--regex* is used, *event-name* is a basic regular expression +instead of a literal string. If *--no-case* is used, *event-name* +will match case-insensitively. + +By default, this command is one-shot, and returns success once an event +occurs; you can send SIGINT (usually via ``Ctrl-C``) to quit immediately. +If *--timeout* is specified, the command gives up waiting for events +after *seconds* have elapsed. With *--loop*, the command prints all +events until a timeout or interrupt key. If *--pretty* is specified, +any JSON event details are pretty-printed for better legibility. + +When *--timestamp* is used, a human-readable timestamp will be printed +before the event, and the timing information provided by QEMU will be +omitted. + + +lxc +--- + +.. code-block:: shell + + lxc-enter-namespace domain [--noseclabel] -- + /path/to/binary [arg1, [arg2, ...]] + +Enter the namespace of *domain* and execute the command ``/path/to/binary`` +passing the requested args. The binary path is relative to the container +root filesystem, not the host root filesystem. The binary will inherit the +environment variables / console visible to virsh. The command will be run +with the same sVirt context and cgroups placement as processes within the +container. This command only works when connected to the LXC hypervisor +driver. This command succeeds only if ``/path/to/binary`` has 0 exit status. + +By default the new process will run with the security label of the new +parent container. Use the *--noseclabel* option to instead have the +process keep the same security label as ``virsh``. + + +ENVIRONMENT +=========== + +The following environment variables can be set to alter the behaviour +of ``virsh`` + +- VIRSH_DEBUG=<0 to 4> + + Turn on verbose debugging of virsh commands. Valid levels are + + * VIRSH_DEBUG=0 + + DEBUG - Messages at ALL levels get logged + + * VIRSH_DEBUG=1 + + INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR + + * VIRSH_DEBUG=2 + + NOTICE - Logs messages at levels NOTICE, WARNING and ERROR + + * VIRSH_DEBUG=3 + + WARNING - Logs messages at levels WARNING and ERROR + + * VIRSH_DEBUG=4 + + ERROR - Messages at only ERROR level gets logged. + +- VIRSH_LOG_FILE=``LOGFILE`` + + The file to log virsh debug messages. + +- VIRSH_DEFAULT_CONNECT_URI + + The hypervisor to connect to by default. Set this to a URI, in the same + format as accepted by the ``connect`` option. This environment variable + is deprecated in favour of the global ``LIBVIRT_DEFAULT_URI`` variable + which serves the same purpose. + +- LIBVIRT_DEFAULT_URI + + The hypervisor to connect to by default. Set this to a URI, in the + same format as accepted by the ``connect`` option. This overrides + the default URI set in any client config file and prevents libvirt + from probing for drivers. + +- VISUAL + + The editor to use by the ``edit`` and related options. + +- EDITOR + + The editor to use by the ``edit`` and related options, if ``VISUAL`` + is not set. + +- VIRSH_HISTSIZE + + The number of commands to remember in the command history. The + default value is 500. + +- LIBVIRT_DEBUG=LEVEL + + Turn on verbose debugging of all libvirt API calls. Valid levels are + + * LIBVIRT_DEBUG=1 + + Messages at level DEBUG or above + + * LIBVIRT_DEBUG=2 + + Messages at level INFO or above + + * LIBVIRT_DEBUG=3 + + Messages at level WARNING or above + + * LIBVIRT_DEBUG=4 + + Messages at level ERROR + + +For further information about debugging options consult +`https://libvirt.org/logging.html <https://libvirt.org/logging.html>`_ + + +BUGS +==== + +Please report all bugs you discover. This should be done via either: + +#. the mailing list + + `https://libvirt.org/contact.html <https://libvirt.org/contact.html>`_ + +#. the bug tracker + + `https://libvirt.org/bugs.html <https://libvirt.org/bugs.html>`_ + +Alternatively, you may report bugs to your software distributor / vendor. + + +AUTHORS +======= + +Please refer to the AUTHORS file distributed with libvirt. + + +COPYRIGHT +========= + +Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +======= + +``virsh`` is distributed under the terms of the GNU LGPL v2+. +This is free software; see the source for copying conditions. There +is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE + + +SEE ALSO +======== + +virt-install(1), virt-xml-validate(1), virt-top(1), virt-df(1), +`https://libvirt.org/ <https://libvirt.org/>`_ diff --git a/tools/Makefile.am b/tools/Makefile.am index f490a61348..9565c6026f 100644 --- a/tools/Makefile.am +++ b/tools/Makefile.am @@ -53,11 +53,9 @@ ICON_FILES = \ virsh_win_icon.rc PODFILES = \ - virsh.pod \ $(NULL) MANINFILES = \ - virsh.1.in \ $(NULL) EXTRA_DIST = \ @@ -85,8 +83,7 @@ conf_DATA = bin_SCRIPTS = virt-xml-validate virt-pki-validate bin_PROGRAMS = virsh virt-admin libexec_SCRIPTS = libvirt-guests.sh -man1_MANS = \ - virsh.1 +man1_MANS = if WITH_SANLOCK sbin_SCRIPTS = virt-sanlock-cleanup diff --git a/tools/virsh.pod b/tools/virsh.pod deleted file mode 100644 index a8331154e1..0000000000 --- a/tools/virsh.pod +++ /dev/null @@ -1,5526 +0,0 @@ -=head1 NAME - -virsh - management user interface - -=head1 SYNOPSIS - -B<virsh> [I<OPTION>]... [I<COMMAND_STRING>] - -B<virsh> [I<OPTION>]... I<COMMAND> [I<ARG>]... - -=head1 DESCRIPTION - -The B<virsh> program is the main interface for managing virsh guest -domains. The program can be used to create, pause, and shutdown -domains. It can also be used to list current domains. Libvirt is a C -toolkit to interact with the virtualization capabilities of recent -versions of Linux (and other OSes). It is free software available -under the GNU Lesser General Public License. Virtualization of the -Linux Operating System means the ability to run multiple instances of -Operating Systems concurrently on a single hardware system where the -basic resources are driven by a Linux instance. The library aims at -providing a long term stable C API. It currently supports Xen, QEMU, -KVM, LXC, OpenVZ, VirtualBox and VMware ESX. - -The basic structure of most virsh usage is: - - virsh [OPTION]... <command> <domain> [ARG]... - -Where I<command> is one of the commands listed below; I<domain> is the -numeric domain id, or the domain name, or the domain UUID; and I<ARGS> -are command specific options. There are a few exceptions to this rule -in the cases where the command in question acts on all domains, the -entire machine, or directly on the xen hypervisor. Those exceptions -will be clear for each of those commands. Note: it is permissible to -give numeric names to domains, however, doing so will result in a -domain that can only be identified by domain id. In other words, if a -numeric value is supplied it will be interpreted as a domain id, not -as a name. Any I<command> starting with B<#> is treated as a comment -and silently ignored, all other unrecognized I<command>s are diagnosed. - -The B<virsh> program can be used either to run one I<COMMAND> by giving the -command and its arguments on the shell command line, or a I<COMMAND_STRING> -which is a single shell argument consisting of multiple I<COMMAND> actions -and their arguments joined with whitespace and separated by semicolons or -newlines between commands, where unquoted backslash-newline pairs are -elided. Within I<COMMAND_STRING>, virsh understands the -same single, double, and backslash escapes as the shell, although you must -add another layer of shell escaping in creating the single shell argument, -and any word starting with unquoted I<#> begins a comment that ends at newline. -If no command is given in the command line, B<virsh> will then start a minimal -interpreter waiting for your commands, and the B<quit> command will then exit -the program. - -The B<virsh> program understands the following I<OPTIONS>. - -=over 4 - -=item B<-c>, B<--connect> I<URI> - -Connect to the specified I<URI>, as if by the B<connect> command, -instead of the default connection. - -=item B<-d>, B<--debug> I<LEVEL> - -Enable debug messages at integer I<LEVEL> and above. I<LEVEL> can -range from 0 to 4 (default). See the documentation of B<VIRSH_DEBUG> -environment variable below for the description of each I<LEVEL>. - -=item B<-e>, B<--escape> I<string> - -Set alternative escape sequence for I<console> command. By default, -telnet's B<^]> is used. Allowed characters when using hat notation are: -alphabetic character, @, [, ], \, ^, _. - -=item B<-h>, B<--help> - -Ignore all other arguments, and behave as if the B<help> command were -given instead. - -=item B<-k>, B<--keepalive-interval> I<INTERVAL> - -Set an I<INTERVAL> (in seconds) for sending keepalive messages to -check whether connection to the server is still alive. Setting the -interval to 0 disables client keepalive mechanism. - -=item B<-K>, B<--keepalive-count> I<COUNT> - -Set a number of times keepalive message can be sent without getting an -answer from the server without marking the connection dead. There is -no effect to this setting in case the I<INTERVAL> is set to 0. - -=item B<-l>, B<--log> I<FILE> - -Output logging details to I<FILE>. - -=item B<-q>, B<--quiet> - -Avoid extra informational messages. - -=item B<-r>, B<--readonly> - -Make the initial connection read-only, as if by the I<--readonly> -option of the B<connect> command. - -=item B<-t>, B<--timing> - -Output elapsed time information for each command. - -=item B<-v>, B<--version[=short]> - -Ignore all other arguments, and prints the version of the libvirt library -virsh is coming from - -=item B<-V>, B<--version=long> - -Ignore all other arguments, and prints the version of the libvirt library -virsh is coming from and which options and driver are compiled in. - -=back - -=head1 NOTES - -Most B<virsh> operations rely upon the libvirt library being able to -connect to an already running libvirtd service. This can usually be -done using the command B<service libvirtd start>. - -Most B<virsh> commands require root privileges to run due to the -communications channels used to talk to the hypervisor. Running as -non root will return an error. - -Most B<virsh> commands act synchronously, except maybe shutdown, -setvcpus and setmem. In those cases the fact that the B<virsh> -program returned, may not mean the action is complete and you -must poll periodically to detect that the guest completed the -operation. - -B<virsh> strives for backward compatibility. Although the B<help> -command only lists the preferred usage of a command, if an older -version of B<virsh> supported an alternate spelling of a command or -option (such as I<--tunnelled> instead of I<--tunneled>), then -scripts using that older spelling will continue to work. - -Several B<virsh> commands take an optionally scaled integer; if no -scale is provided, then the default is listed in the command (for -historical reasons, some commands default to bytes, while other -commands default to kibibytes). The following case-insensitive -suffixes can be used to select a specific scale: - b, byte byte 1 - KB kilobyte 1,000 - k, KiB kibibyte 1,024 - MB megabyte 1,000,000 - M, MiB mebibyte 1,048,576 - GB gigabyte 1,000,000,000 - G, GiB gibibyte 1,073,741,824 - TB terabyte 1,000,000,000,000 - T, TiB tebibyte 1,099,511,627,776 - PB petabyte 1,000,000,000,000,000 - P, PiB pebibyte 1,125,899,906,842,624 - EB exabyte 1,000,000,000,000,000,000 - E, EiB exbibyte 1,152,921,504,606,846,976 - -=head1 GENERIC COMMANDS - -The following commands are generic i.e. not specific to a domain. - -=over 4 - -=item B<help> [I<command-or-group>] - -This lists each of the virsh commands. When used without options, all -commands are listed, one per line, grouped into related categories, -displaying the keyword for each group. - -To display only commands for a specific group, give the keyword for that -group as an option. For example: - - virsh # help host - - Host and Hypervisor (help keyword 'host'): - capabilities capabilities - cpu-models show the CPU models for an architecture - connect (re)connect to hypervisor - freecell NUMA free memory - hostname print the hypervisor hostname - qemu-attach Attach to existing QEMU process - qemu-monitor-command QEMU Monitor Command - qemu-agent-command QEMU Guest Agent Command - sysinfo print the hypervisor sysinfo - uri print the hypervisor canonical URI - -To display detailed information for a specific command, give its name as the -option instead. For example: - - virsh # help list - NAME - list - list domains - - SYNOPSIS - list [--inactive] [--all] - - DESCRIPTION - Returns list of domains. - - OPTIONS - --inactive list inactive domains - --all list inactive & active domains - -=item B<quit>, B<exit> - -quit this interactive terminal - -=item B<version> [I<--daemon>] - -Will print out the major version info about what this built from. -If I<--daemon> is specified then the version of the libvirt daemon -is included in the output. - -=over 4 - -B<Example> - - $ virsh version - Compiled against library: libvirt 1.2.3 - Using library: libvirt 1.2.3 - Using API: QEMU 1.2.3 - Running hypervisor: QEMU 2.0.50 - - $ virsh version --daemon - Compiled against library: libvirt 1.2.3 - Using library: libvirt 1.2.3 - Using API: QEMU 1.2.3 - Running hypervisor: QEMU 2.0.50 - Running against daemon: 1.2.6 - -=back - -=item B<cd> [I<directory>] - -Will change current directory to I<directory>. The default directory -for the B<cd> command is the home directory or, if there is no I<HOME> -variable in the environment, the root directory. - -This command is only available in interactive mode. - -=item B<pwd> - -Will print the current directory. - -=item B<connect> [I<URI>] [I<--readonly>] - -(Re)-Connect to the hypervisor. When the shell is first started, this -is automatically run with the I<URI> parameter requested by the C<-c> -option on the command line. The I<URI> parameter specifies how to -connect to the hypervisor. The documentation page at -L<https://libvirt.org/uri.html> list the values supported, but the most -common are: - -=over 4 - -=item xen:///system - -this is used to connect to the local Xen hypervisor - -=item qemu:///system - -connect locally as root to the daemon supervising QEMU and KVM domains - -=item qemu:///session - -connect locally as a normal user to his own set of QEMU and KVM domains - -=item lxc:///system - -connect to a local linux container - -=back - -To find the currently used URI, check the I<uri> command documented below. - -For remote access see the documentation page at -L<https://libvirt.org/uri.html> on how to make URIs. -The I<--readonly> option allows for read-only connection - -=item B<uri> - -Prints the hypervisor canonical URI, can be useful in shell mode. - -=item B<hostname> - -Print the hypervisor hostname. - -=item B<sysinfo> - -Print the XML representation of the hypervisor sysinfo, if available. - -=item B<nodeinfo> - -Returns basic information about the node, like number and type of CPU, -and size of the physical memory. The output corresponds to virNodeInfo -structure. Specifically, the "CPU socket(s)" field means number of CPU -sockets per NUMA cell. The information libvirt displays is dependent -upon what each architecture may provide. - -=item B<nodecpumap> [I<--pretty>] - -Displays the node's total number of CPUs, the number of online CPUs -and the list of online CPUs. - -With I<--pretty> the online CPUs are printed as a range instead of a list. - -=item B<nodecpustats> [I<cpu>] [I<--percent>] - -Returns cpu stats of the node. -If I<cpu> is specified, this will print the specified cpu statistics only. -If I<--percent> is specified, this will print the percentage of each kind -of cpu statistics during 1 second. - -=item B<nodememstats> [I<cell>] - -Returns memory stats of the node. -If I<cell> is specified, this will print the specified cell statistics only. - -=item B<nodesuspend> [I<target>] [I<duration>] - -Puts the node (host machine) into a system-wide sleep state and schedule -the node's Real-Time-Clock interrupt to resume the node after the time -duration specified by I<duration> is out. -I<target> specifies the state to which the host will be suspended to, it -can be "mem" (suspend to RAM), "disk" (suspend to disk), or "hybrid" -(suspend to both RAM and disk). I<duration> specifies the time duration -in seconds for which the host has to be suspended, it should be at least -60 seconds. - -=item B<node-memory-tune> [I<shm-pages-to-scan>] [I<shm-sleep-millisecs>] -[I<shm-merge-across-nodes>] - -Allows you to display or set the node memory parameters. -I<shm-pages-to-scan> can be used to set the number of pages to scan -before the shared memory service goes to sleep; I<shm-sleep-millisecs> -can be used to set the number of millisecs the shared memory service should -sleep before next scan; I<shm-merge-across-nodes> specifies if pages from -different numa nodes can be merged. When set to 0, only pages which physically -reside in the memory area of same NUMA node can be merged. When set to 1, -pages from all nodes can be merged. Default to 1. - -B<Note>: Currently the "shared memory service" only means KSM (Kernel Samepage -Merging). - -=item B<capabilities> - -Print an XML document describing the capabilities of the hypervisor -we are currently connected to. This includes a section on the host -capabilities in terms of CPU and features, and a set of description -for each kind of guest which can be virtualized. For a more complete -description see: - L<https://libvirt.org/formatcaps.html> -The XML also show the NUMA topology information if available. - -=item B<domcapabilities> [I<virttype>] [I<emulatorbin>] -[I<arch>] [I<machine>] - -Print an XML document describing the domain capabilities for the -hypervisor we are connected to using information either sourced from an -existing domain or taken from the B<virsh capabilities> output. This may -be useful if you intend to create a new domain and are curious if for -instance it could make use of VFIO by creating a domain for the -hypervisor with a specific emulator and architecture. - -Each hypervisor will have different requirements regarding which options -are required and which are optional. A hypervisor can support providing -a default value for any of the options. - -The I<virttype> option specifies the virtualization type used. The value -to be used is either from the 'type' attribute of the <domain/> top -level element from the domain XML or the 'type' attribute found within -each <guest/> element from the B<virsh capabilities> output. The -I<emulatorbin> option specifies the path to the emulator. The value to -be used is either the <emulator> element in the domain XML or the -B<virsh capabilities> output. The I<arch> option specifies the -architecture to be used for the domain. The value to be used is either -the "arch" attribute from the domain's XML <os/> element and <type/> -subelement or the "name" attribute of an <arch/> element from the -B<virsh capabililites> output. The I<machine> specifies the machine type -for the emulator. The value to be used is either the "machine" attribute -from the domain's XML <os/> element and <type/> subelement or one from a -list of machines from the B<virsh capabilities> output for a specific -architecture and domain type. - -For the qemu hypervisor, a I<virttype> of either 'qemu' or 'kvm' must be -supplied along with either the I<emulatorbin> or I<arch> in order to -generate output for the default I<machine>. Supplying a I<machine> -value will generate output for the specific machine. - -=item B<pool-capabilities> -Print an XML document describing the storage pool capabilities for the -connected storage driver. This may be useful if you intend to create a -new storage pool and need to know the available pool types and supported -storage pool source and target volume formats as well as the required -source elements to create the pool. - -=item B<inject-nmi> I<domain> - -Inject NMI to the guest. - -=item B<list> [I<--inactive> | I<--all>] - [I<--managed-save>] [I<--title>] - { [I<--table>] | I<--name> | I<--uuid> } - [I<--persistent>] [I<--transient>] - [I<--with-managed-save>] [I<--without-managed-save>] - [I<--autostart>] [I<--no-autostart>] - [I<--with-snapshot>] [I<--without-snapshot>] - [I<--with-checkpoint>] [I<--without-checkpoint>] - [I<--state-running>] [I<--state-paused>] - [I<--state-shutoff>] [I<--state-other>] - -Prints information about existing domains. If no options are -specified it prints out information about running domains. - -An example format for the list is as follows: - -B<virsh> list - Id Name State - ---------------------------------------------------- - 0 Domain-0 running - 2 fedora paused - -Name is the name of the domain. ID the domain numeric id. -State is the run state (see below). - -B<STATES> - -The State field lists what state each domain is currently in. A domain -can be in one of the following possible states: - - -=over 4 - -=item B<running> - -The domain is currently running on a CPU - -=item B<idle> - -The domain is idle, and not running or runnable. This can be caused -because the domain is waiting on IO (a traditional wait state) or has -gone to sleep because there was nothing else for it to do. - -=item B<paused> - -The domain has been paused, usually occurring through the administrator -running B<virsh suspend>. When in a paused state the domain will still -consume allocated resources like memory, but will not be eligible for -scheduling by the hypervisor. - -=item B<in shutdown> - -The domain is in the process of shutting down, i.e. the guest operating system -has been notified and should be in the process of stopping its operations -gracefully. - -=item B<shut off> - -The domain is not running. Usually this indicates the domain has been -shut down completely, or has not been started. - -=item B<crashed> - -The domain has crashed, which is always a violent ending. Usually -this state can only occur if the domain has been configured not to -restart on crash. - -=item B<pmsuspended> - -The domain has been suspended by guest power management, e.g. entered -into s3 state. - -=back - -Normally only active domains are listed. To list inactive domains specify -I<--inactive> or I<--all> to list both active and inactive domains. - -To further filter the list of domains you may specify one or more of filtering -flags supported by the B<list> command. These flags are grouped by function. -Specifying one or more flags from a group enables the filter group. Note that -some combinations of flags may yield no results. Supported filtering flags and -groups: - -=over 4 - -=item B<Persistence> - -Flag I<--persistent> is used to include persistent domains in the returned -list. To include transient domains specify I<--transient>. - -=item B<Existence of managed save image> - -To list domains having a managed save image specify flag -I<--with-managed-save>. For domains that don't have a managed save image -specify I<--without-managed-save>. - -=item B<Domain state> - -The following filter flags select a domain by its state: -I<--state-running> for running domains, I<--state-paused> for paused domains, -I<--state-shutoff> for turned off domains and I<--state-other> for all -other states as a fallback. - -=item B<Autostarting domains> - -To list autostarting domains use the flag I<--autostart>. To list domains with -this feature disabled use I<--no-autostart>. - -=item B<Snapshot existence> - -Domains that have snapshot images can be listed using flag I<--with-snapshot>, -domains without a snapshot I<--without-snapshot>. - -=item B<Checkpoint existence> - -Domains that have checkpoints can be listed using flag I<--with-checkpoint>, -domains without a checkpoint I<--without-checkpoint>. - -=back - -When talking to older servers, this command is forced to use a series of API -calls with an inherent race, where a domain might not be listed or might appear -more than once if it changed state between calls while the list was being -collected. Newer servers do not have this problem. - -If I<--managed-save> is specified, then domains that have managed save state -(only possible if they are in the B<shut off> state, so you need to specify -I<--inactive> or I<--all> to actually list them) will instead show as B<saved> -in the listing. This flag is usable only with the default I<--table> output. -Note that this flag does not filter the list of domains. - -If I<--name> is specified, domain names are printed instead of the table -formatted one per line. If I<--uuid> is specified domain's UUID's are printed -instead of names. Flag I<--table> specifies that the legacy table-formatted -output should be used. This is the default. - -If both I<--name> and I<--uuid> are specified, domain UUID's and names -are printed side by side without any header. Flag I<--table> specifies -that the legacy table-formatted output should be used. This is the -default if neither I<--name> nor I<--uuid> are specified. Option -I<--table> is mutually exclusive with options I<--uuid> and I<--name>. - -If I<--title> is specified, then the short domain description (title) is -printed in an extra column. This flag is usable only with the default -I<--table> output. - -Example: - -B<virsh> list --title - Id Name State Title - ------------------------------------------- - 0 Domain-0 running Mailserver 1 - 2 fedora paused - -=item B<freecell> [{ [I<--cellno>] B<cellno> | I<--all> }] - -Prints the available amount of memory on the machine or within a NUMA -cell. The freecell command can provide one of three different -displays of available memory on the machine depending on the options -specified. With no options, it displays the total free memory on the -machine. With the --all option, it displays the free memory in each -cell and the total free memory on the machine. Finally, with a -numeric argument or with --cellno plus a cell number it will display -the free memory for the specified cell only. - -=item B<freepages> [{ [I<--cellno>] I<cellno> [I<--pagesize>] I<pagesize> | - I<--all> }] - -Prints the available amount of pages within a NUMA cell. I<cellno> refers -to the NUMA cell you're interested in. I<pagesize> is a scaled integer (see -B<NOTES> above). Alternatively, if I<--all> is used, info on each possible -combination of NUMA cell and page size is printed out. - -=item B<allocpages> [I<--pagesize>] I<pagesize> [I<--pagecount>] I<pagecount> -[[I<--cellno>] I<cellno>] [I<--add>] [I<--all>] - -Change the size of pages pool of I<pagesize> on the host. If -I<--add> is specified, then I<pagecount> pages are added into the -pool. However, if I<--add> wasn't specified, then the -I<pagecount> is taken as the new absolute size of the pool (this -may be used to free some pages and size the pool down). The -I<cellno> modifier can be used to narrow the modification down to -a single host NUMA cell. On the other end of spectrum lies -I<--all> which executes the modification on all NUMA cells. - -=item B<cpu-baseline> I<FILE> [I<--features>] [I<--migratable>] - -Compute baseline CPU which will be supported by all host CPUs given in <file>. -(See B<hypervisor-cpu-baseline> command to get a CPU which can be provided by a -specific hypervisor.) The list of host CPUs is built by extracting all <cpu> -elements from the <file>. Thus, the <file> can contain either a set of <cpu> -elements separated by new lines or even a set of complete <capabilities> -elements printed by B<capabilities> command. If I<--features> is specified, -then the resulting XML description will explicitly include all features that -make up the CPU, without this option features that are part of the CPU model -will not be listed in the XML description. If I<--migratable> is specified, -features that block migration will not be included in the resulting CPU. - -=item B<cpu-compare> I<FILE> [I<--error>] - -Compare CPU definition from XML <file> with host CPU. (See -B<hypervisor-cpu-compare> command for comparing the CPU definition with the CPU -which a specific hypervisor is able to provide on the host.) The XML <file> may -contain either host or guest CPU definition. The host CPU definition is the -<cpu> element and its contents as printed by B<capabilities> command. The -guest CPU definition is the <cpu> element and its contents from domain XML -definition or the CPU definition created from the host CPU model found in -domain capabilities XML (printed by B<domcapabilities> command). In -addition to the <cpu> element itself, this command accepts -full domain XML, capabilities XML, or domain capabilities XML containing -the CPU definition. For more information on guest CPU definition see: -L<https://libvirt.org/formatdomain.html#elementsCPU>. If I<--error> is -specified, the command will return an error when the given CPU is -incompatible with host CPU and a message providing more details about the -incompatibility will be printed out. - -=item B<cpu-models> I<arch> - -Print the list of CPU models known by libvirt for the specified architecture. -Whether a specific hypervisor is able to create a domain which uses any of -the printed CPU models is a separate question which can be answered by -looking at the domain capabilities XML returned by B<domcapabilities> command. -Moreover, for some architectures libvirt does not know any CPU models and -the usable CPU models are only limited by the hypervisor. This command will -print that all CPU models are accepted for these architectures and the actual -list of supported CPU models can be checked in the domain capabilities XML. - -=item B<echo> [I<--shell>] [I<--xml>] [I<err>...] [I<arg>...] - -Echo back each I<arg>, separated by space. If I<--shell> is -specified, then the output will be single-quoted where needed, so that -it is suitable for reuse in a shell context. If I<--xml> is -specified, then the output will be escaped for use in XML. -If I<--err> is specified, prefix B<"error: "> and output to stderr -instead of stdout. - -=item B<hypervisor-cpu-compare> I<FILE> [I<virttype>] [I<emulator>] [I<arch>] -[I<machine>] [I<--error>] - -Compare CPU definition from XML <file> with the CPU the hypervisor is able to -provide on the host. (This is different from B<cpu-compare> which compares the -CPU definition with the host CPU without considering any specific hypervisor -and its abilities.) - -The XML I<FILE> may contain either a host or guest CPU definition. The host CPU -definition is the <cpu> element and its contents as printed by the -B<capabilities> command. The guest CPU definition is the <cpu> element and its -contents from the domain XML definition or the CPU definition created from the -host CPU model found in the domain capabilities XML (printed by the -B<domcapabilities> command). In addition to the <cpu> element itself, this -command accepts full domain XML, capabilities XML, or domain capabilities XML -containing the CPU definition. For more information on guest CPU definition -see: L<https://libvirt.org/formatdomain.html#elementsCPU>;. - -The I<virttype> option specifies the virtualization type (usable in the 'type' -attribute of the <domain> top level element from the domain XML). I<emulator> -specifies the path to the emulator, I<arch> specifies the CPU architecture, and -I<machine> specifies the machine type. If I<--error> is specified, the command -will return an error when the given CPU is incompatible with the host CPU and a -message providing more details about the incompatibility will be printed out. - -=item B<hypervisor-cpu-baseline> I<FILE> [I<virttype>] [I<emulator>] [I<arch>] -[I<machine>] [I<--features>] [I<--migratable>] - -Compute a baseline CPU which will be compatible with all CPUs defined in an XML -I<file> and with the CPU the hypervisor is able to provide on the host. (This -is different from B<cpu-baseline> which does not consider any hypervisor -abilities when computing the baseline CPU.) - -The XML I<FILE> may contain either host or guest CPU definitions describing the -host CPU model. The host CPU definition is the <cpu> element and its contents -as printed by B<capabilities> command. The guest CPU definition may be created -from the host CPU model found in domain capabilities XML (printed by -B<domcapabilities> command). In addition to the <cpu> elements, this command -accepts full capabilities XMLs, or domain capabilities XMLs containing the CPU -definitions. For best results, use only the CPU definitions from domain -capabilities. - -When I<FILE> contains only a single CPU definition, the command will print the -same CPU with restrictions imposed by the capabilities of the hypervisor. -Specifically, running th B<virsh hypervisor-cpu-baseline> command with no -additional options on the result of B<virsh domcapabilities> will transform the -host CPU model from domain capabilities XML to a form directly usable in domain -XML. - -The I<virttype> option specifies the virtualization type (usable in the 'type' -attribute of the <domain> top level element from the domain XML). I<emulator> -specifies the path to the emulator, I<arch> specifies the CPU architecture, and -I<machine> specifies the machine type. If I<--features> is specified, then the -resulting XML description will explicitly include all features that make up the -CPU, without this option features that are part of the CPU model will not be -listed in the XML description. If I<--migratable> is specified, features that -block migration will not be included in the resulting CPU. - - -=back - -=head1 DOMAIN COMMANDS - -The following commands manipulate domains directly, as stated -previously most commands take domain as the first parameter. The -I<domain> can be specified as a short integer, a name or a full UUID. - -=over 4 - -=item B<autostart> [I<--disable>] I<domain> - -Configure a domain to be automatically started at boot. - -The option I<--disable> disables autostarting. - -=item B<blkdeviotune> I<domain> I<device> -[[I<--config>] [I<--live>] | [I<--current>]] -[[I<total-bytes-sec>] | [I<read-bytes-sec>] [I<write-bytes-sec>]] -[[I<total-iops-sec>] | [I<read-iops-sec>] [I<write-iops-sec>]] -[[I<total-bytes-sec-max>] | [I<read-bytes-sec-max>] [I<write-bytes-sec-max>]] -[[I<total-iops-sec-max>] | [I<read-iops-sec-max>] [I<write-iops-sec-max>]] -[[I<total-bytes-sec-max-length>] | -[I<read-bytes-sec-max-length>] [I<write-bytes-sec-max-length>]] -[[I<total-iops-sec-max-length>] | -[I<read-iops-sec-max-length>] [I<write-iops-sec-max-length>]] -[I<size-iops-sec>] [I<group-name>] - -Set or query the block disk io parameters for a block device of I<domain>. -I<device> specifies a unique target name (<target dev='name'/>) or source -file (<source file='name'/>) for one of the disk devices attached to -I<domain> (see also B<domblklist> 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<device>. - -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<blkiotune> I<domain> [I<--weight> B<weight>] -[I<--device-weights> B<device-weights>] -[I<--device-read-iops-sec> B<device-read-iops-sec>] -[I<--device-write-iops-sec> B<device-write-iops-sec>] -[I<--device-read-bytes-sec> B<device-read-bytes-sec>] -[I<--device-write-bytes-sec> B<device-write-bytes-sec>] -[[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<device-weights> 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<device-read-iops-sec> 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<device-write-iops-sec> 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<device-read-bytes-sec> 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<device-write-bytes-sec> 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<blockcommit> I<domain> I<path> [I<bandwidth>] [I<--bytes>] -[I<base>] [I<--shallow>] [I<top>] [I<--delete>] [I<--keep-relative>] -[I<--wait> [I<--async>] [I<--verbose>]] [I<--timeout> B<seconds>] -[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<base> -and/or I<top> 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<base> 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<top> 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<top> is copied into I<base> and the job can only be -canceled, with top still containing data not yet in base. In the second -phase, I<top> and I<base> remain identical until a call to B<blockjob> -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<blockjob>. 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<timeout> in seconds elapses -or SIGINT is sent (usually with C<Ctrl-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<blockjob> -I<--pivot>; and using I<--keep-overlay> is shorthand for combining -I<--active> I<--wait> with an automatic B<blockjob> I<--abort>. - -I<path> specifies fully-qualified path of the disk; it corresponds -to a unique target name (<target dev='name'/>) or source file (<source -file='name'/>) for one of the disk devices attached to I<domain> (see -also B<domblklist> for listing these names). -I<bandwidth> 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<bandwidth> argument see the corresponding section for the B<blockjob> -command. - -=item B<blockcopy> I<domain> I<path> { I<dest> [I<format>] [I<--blockdev>] -| I<--xml> B<file> } [I<--shallow>] [I<--reuse-external>] [I<bandwidth>] -[I<--wait> [I<--async>] [I<--verbose>]] [{I<--pivot> | I<--finish>}] -[I<--timeout> B<seconds>] [I<granularity>] [I<buf-size>] [I<--bytes>] -[I<--transient-job>] - -Copy a disk backing image chain to a destination. Either I<dest> as -the destination file name, or I<--xml> with the name of an XML file containing -a top-level <disk> element describing the destination, must be present. -Additionally, if I<dest> is given, I<format> should be specified to declare -the format of the destination (if I<format> 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<dest>, 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<blockjob> 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<timeout> in seconds elapses or SIGINT is -sent (usually with C<Ctrl-C>). Using I<--verbose> along with I<--wait> -will produce periodic status updates. Using I<--pivot> (similar to -B<blockjob> I<--pivot>) or I<--finish> (similar to B<blockjob> 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<path> specifies fully-qualified path of the disk. -I<bandwidth> 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<bandwidth> argument see the -corresponding section for the B<blockjob> command. -Specifying I<granularity> 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<buf-size> 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<blockjob> I<domain> I<path> { [I<--abort>] [I<--async>] [I<--pivot>] | -[I<--info>] [I<--raw>] [I<--bytes>] | [I<bandwidth>] } - -Manage active block operations. There are three mutually-exclusive modes: -I<--info>, I<bandwidth>, 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<path> specifies fully-qualified path of the disk; it corresponds -to a unique target name (<target dev='name'/>) or source file (<source -file='name'/>) for one of the disk devices attached to I<domain> (see -also B<domblklist> 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<bandwidth> 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<NOTES> 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<blockpull> I<domain> I<path> [I<bandwidth>] [I<--bytes>] [I<base>] -[I<--wait> [I<--verbose>] [I<--timeout> B<seconds>] [I<--async>]] -[I<--keep-relative>] - -Populate a disk from its backing image chain. By default, this command -flattens the entire chain; but if I<base> 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<blockjob>. However, if I<--wait> is -specified, then this command will block until the operation completes, -or cancel the operation if the optional I<timeout> in seconds elapses -or SIGINT is sent (usually with C<Ctrl-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<path> specifies fully-qualified path of the disk; it corresponds -to a unique target name (<target dev='name'/>) or source file (<source -file='name'/>) for one of the disk devices attached to I<domain> (see -also B<domblklist> for listing these names). -I<bandwidth> specifies copying bandwidth limit in MiB/s. For further information -on the I<bandwidth> argument see the corresponding section for the B<blockjob> -command. - -=item B<blockresize> I<domain> I<path> I<size> - -Resize a block device of domain while the domain is running, I<path> -specifies the absolute path of the block device; it corresponds -to a unique target name (<target dev='name'/>) or source file (<source -file='name'/>) for one of the disk devices attached to I<domain> (see -also B<domblklist> for listing these names). - -I<size> is a scaled integer (see B<NOTES> 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<vol-resize> which defaults to bytes without a suffix). - -=item B<console> I<domain> [I<devname>] [I<--safe>] [I<--force>] - -Connect the virtual serial console for the guest. The optional -I<devname> parameter refers to the device alias of an alternate -console, serial or parallel device configured for the guest. -If omitted, the primary console will be opened. - -If the flag I<--safe> is specified, the connection is only attempted -if the driver supports safe console handling. This flag specifies that -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<cpu-stats> I<domain> [I<--total>] [I<start>] [I<count>] - -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<start> for only the per-cpu -stats of the CPUs from I<start>, I<count> for only I<count> CPUs' -stats. - -=item B<create> I<FILE> [I<--console>] [I<--paused>] [I<--autodestroy>] -[I<--pass-fds N,M,...>] [I<--validate>] - -Create a domain from an XML <file>. Optionally, I<--validate> option can be -passed to validate the format of the input XML file against an internal RNG -schema (identical to using L<virt-xml-validate(1)> tool). Domains created using -this command are going to be either transient (temporary ones that will vanish -once destroyed) or existing persistent domains that will run with one-time use -configuration, leaving the persistent XML untouched (this can come handy during -an automated testing of various configurations all based on the original XML). -See the B<Example> section for usage demonstration. - -The domain will be paused if the I<--paused> option is used -and supported by the driver; otherwise it will be running. If I<--console> is -requested, attach to the console after creation. -If I<--autodestroy> is requested, then the guest will be automatically -destroyed when virsh closes its connection to libvirt, or otherwise -exits. - -If I<--pass-fds> is specified, the argument is a comma separated list -of open file descriptors which should be pass on into the guest. The -file descriptors will be re-numbered in the guest, starting from 3. This -is only supported with container based virtualization. - -B<Example> - - 1) prepare a template from an existing domain (skip directly to 3a if writing - one from scratch) - - # virsh dumpxml <domain> > domain.xml - - 2) edit the template using an editor of your choice and: - a) DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or - b) DON'T CHANGE! either <name> or <uuid> - - # $EDITOR domain.xml - - 3) create a domain from domain.xml, depending on whether following 2a or 2b - respectively: - a) the domain is going to be transient - b) an existing persistent domain will run with a modified one-time - configuration - - # virsh create domain.xml - -=item B<define> I<FILE> [I<--validate>] - -Define a domain from an XML <file>. Optionally, the format of the input XML -file can be validated against an internal RNG schema with I<--validate> -(identical to using L<virt-xml-validate(1)> tool). The domain definition is -registered but not started. If domain is already running, the changes will take -effect on the next boot. - -=item B<desc> I<domain> [[I<--live>] [I<--config>] | - [I<--current>]] [I<--title>] [I<--edit>] [I<--new-desc> - New description or title message] - -Show or modify description and title of a domain. These values are user -fields that allow storing arbitrary textual data to allow easy -identification of domains. Title should be short, although it's not enforced. -(See also B<metadata> that works with XML based domain metadata.) - -Flags I<--live> or I<--config> select whether this command works on live -or persistent definitions of the domain. If both I<--live> and I<--config> -are specified, the I<--config> option takes precedence on getting the current -description and both live configuration and config are updated while setting -the description. I<--current> is exclusive and implied if none of these was -specified. - -Flag I<--edit> specifies that an editor with the contents of current -description or title should be opened and the contents saved back afterwards. - -Flag I<--title> selects operation on the title field instead of description. - -If neither of I<--edit> and I<--new-desc> are specified the note or description -is displayed instead of being modified. - -=item B<destroy> I<domain> [I<--graceful>] - -Immediately terminate the domain I<domain>. This doesn't give the domain -OS any chance to react, and it's the equivalent of ripping the power -cord out on a physical machine. In most cases you will want to use -the B<shutdown> command instead. However, this does not delete any -storage volumes used by the guest, and if the domain is persistent, it -can be restarted later. - -If I<domain> is transient, then the metadata of any snapshots will -be lost once the guest stops running, but the snapshot contents still -exist, and a new domain with the same name and UUID can restore the -snapshot metadata with B<snapshot-create>. Similarly, the metadata of -any checkpoints will be lost, but can be restored with B<checkpoint-create>. - -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<domblkerror> I<domain> - -Show errors on block devices. This command usually comes handy when -B<domstate> command says that a domain was paused due to I/O error. -The B<domblkerror> command lists all block devices in error state and -the error seen on each of them. - -=item B<domblkinfo> I<domain> [I<block-device> I<--all>] [I<--human>] - -Get block device size info for a domain. A I<block-device> corresponds -to a unique target name (<target dev='name'/>) or source file (<source -file='name'/>) for one of the disk devices attached to I<domain> (see -also B<domblklist> 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<domain>. -The I<--all> option takes precedence of the others. - -=item B<domblklist> I<domain> [I<--inactive>] [I<--details>] - -Print a table showing the brief information of all block devices -associated with I<domain>. 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<domblkinfo> or -I<snapshot-create> for disk snapshots) will accept either target -or unique source names printed by this command. - -=item B<domblkstat> I<domain> [I<block-device>] [I<--human>] - -Get device block stats for a running domain. A I<block-device> corresponds -to a unique target name (<target dev='name'/>) or source file (<source -file='name'/>) for one of the disk devices attached to I<domain> (see -also B<domblklist> for listing these names). On a lxc or qemu domain, -omitting the I<block-device> yields device block stats summarily for the -entire domain. - -Use I<--human> for a more human readable output. - -Availability of these fields depends on hypervisor. Unsupported fields are -missing from the output. Other fields may appear if communicating with a newer -version of libvirtd. - -B<Explanation of fields> (fields appear in the following order): - rd_req - count of read operations - rd_bytes - count of read bytes - wr_req - count of write operations - wr_bytes - count of written bytes - errs - error count - flush_operations - count of flush operations - rd_total_times - total time read operations took (ns) - wr_total_times - total time write operations took (ns) - flush_total_times - total time flush operations took (ns) - <-- other fields provided by hypervisor --> - - -=item B<domblkthreshold> I<domain> I<dev> I<threshold> - -Set the threshold value for delivering the block-threshold event. I<dev> -specifies the disk device target or backing chain element of given device using -the 'target[1]' syntax. I<threshold> is a scaled value of the offset. If the -block device should write beyond that offset the event will be delivered. - -=item B<domcontrol> I<domain> - -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<domdisplay> I<domain> [I<--include-password>] -[[I<--type>] B<type>] [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<type> 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<domfsfreeze> I<domain> [[I<--mountpoint>] B<mountpoint>...] - -Freeze mounted filesystems within a running domain to prepare for consistent -snapshots. - -The I<--mountpoint> option takes a parameter B<mountpoint>, 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<snapshot-create> command has a I<--quiesce> option to freeze -and thaw the filesystems automatically to keep snapshots consistent. -B<domfsfreeze> command is only needed when a user wants to utilize the -native snapshot features of storage devices not supported by libvirt. - -=item B<domfsinfo> I<domain> - -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 (<target dev='name'/>). - -Note that this command requires a guest agent configured and running in the -domain's guest OS. - -=item B<domfsthaw> I<domain> [[I<--mountpoint>] B<mountpoint>...] - -Thaw mounted filesystems within a running domain, which have been frozen by -domfsfreeze command. - -The I<--mountpoint> option takes a parameter B<mountpoint>, 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<domfstrim> I<domain> [I<--minimum> B<bytes>] -[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<bytes> 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<domhostname> I<domain> - -Returns the hostname of a domain, if the hypervisor makes it available. - -=item B<domid> I<domain-name-or-uuid> - -Convert a domain name (or UUID) to a domain id - -=item B<domif-getlink> I<domain> I<interface-device> [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<interface-device> can be the interface's target name or the MAC address. - -=item B<domif-setlink> I<domain> I<interface-device> I<state> [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<interface-device> can be the interface's target name or the MAC address. - -=item B<domifaddr> I<domain> [I<interface>] [I<--full>] - [I<--source lease|agent|arp>] - -Get a list of interfaces of a running domain along with their IP and MAC -addresses, or limited output just for one interface if I<interface> is -specified. Note that I<interface> can be driver dependent, it can be the name -within guest OS or the name you would see in domain XML. Moreover, the whole -command may require a guest agent to be configured for the queried domain under -some hypervisors, notably QEMU. - -If I<--full> is specified, the interface name and MAC address is always -displayed when the interface has multiple IP addresses or aliases; otherwise, -only the interface name and MAC address is displayed for the first name and -MAC address with "-" for the others using the same name and MAC address. - -The I<--source> argument specifies what data source to use for the -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<domiflist> I<domain> [I<--inactive>] - -Print a table showing the brief information of all virtual interfaces -associated with I<domain>. 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<detach-interface> or -I<domif-setlink>) will accept the MAC address printed by this command. - -=item B<domifstat> I<domain> I<interface-device> - -Get network interface stats for a running domain. The network -interface stats are only available for interfaces that have a -physical source interface. This does not include, for example, a -'user' interface type since it is a virtual LAN with NAT to the -outside world. I<interface-device> can be the interface target by -name or MAC address. - -=item B<domiftune> I<domain> I<interface-device> -[[I<--config>] [I<--live>] | [I<--current>]] -[I<--inbound average,peak,burst,floor>] -[I<--outbound average,peak,burst>] - -Set or query the domain's network interface's bandwidth parameters. -I<interface-device> can be the interface's target name (<target dev='name'/>), -or the MAC address. - -If no I<--inbound> or I<--outbound> is specified, this command will -query and show the bandwidth settings. Otherwise, it will set the -inbound or outbound bandwidth. I<average,peak,burst,floor> is the same as -in command I<attach-interface>. Values for I<average>, I<peak> and I<floor> -are expressed in kilobytes per second, while I<burst> is expressed in kilobytes -in a single burst at I<peak> speed as described in the Network XML -documentation at L<https://libvirt.org/formatnetwork.html#elementQoS>;. - -To clear inbound or outbound settings, use I<--inbound> or I<--outbound> -respectfully with average value of zero. - -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<dominfo> I<domain> - -Returns basic information about the domain. - -=item B<domjobabort> I<domain> - -Abort the currently running domain job. - -=item B<domjobinfo> I<domain> [I<--completed> [I<--keep-completed>]] -[I<--anystats>] [I<--rawstats>] - -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 (unless -I<--keep-completed> is used) or when libvirtd is restarted. - -Normally only statistics for running and successful completed jobs are printed. -I<--anystats> can be used to also display statistics for failed jobs. - -In case I<--rawstats> is used, all fields are printed as received from the -server without any attempts to interpret the data. The "Job type:" field is -special, since it's reported by the API and not part of stats. - -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<dommemstat> I<domain> [I<--period> B<seconds>] -[[I<--config>] [I<--live>] | [I<--current>]] - -Get memory stats for a running domain. - -Availability of these fields depends on hypervisor. Unsupported fields are -missing from the output. Other fields may appear if communicating with a newer -version of libvirtd. - -B<Explanation of fields>: - swap_in - The amount of data read from swap space (in KiB) - swap_out - The amount of memory written out to swap space (in KiB) - major_fault - The number of page faults where disk IO was required - minor_fault - The number of other page faults - unused - The amount of memory left unused by the system (in KiB) - available - The amount of usable memory as seen by the domain (in KiB) - actual - Current balloon value (in KiB) - rss - Resident Set Size of the running domain's process (in KiB) - usable - The amount of memory which can be reclaimed by balloon -without causing host swapping (in KiB) - last-update - Timestamp of the last update of statistics (in seconds) - disk_caches - The amount of memory that can be reclaimed without -additional I/O, typically disk caches (in KiB) - hugetlb_pgalloc - The number of successful huge page allocations initiated -from within the domain - hugetlb_pgfail - The number of failed huge page allocations initiated from -within the domain - -For QEMU/KVM with a memory balloon, setting the optional I<--period> to a -value larger than 0 in seconds will allow the balloon driver to return -additional statistics which will be displayed by subsequent B<dommemstat> -commands. Setting the I<--period> to 0 will stop the balloon driver collection, -but does not clear the statistics in the balloon driver. Requires at least -QEMU/KVM 1.5 to be running on the host. - -The I<--live>, I<--config>, and I<--current> flags are only valid when using -the I<--period> option in order to set the collection period for the balloon -driver. If I<--live> is specified, only the running guest collection period -is affected. 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 the guest state. - -=item B<domname> I<domain-id-or-uuid> - -Convert a domain Id (or UUID) to domain name - -=item B<dompmsuspend> I<domain> I<target> [I<--duration>] - -Suspend a running domain into one of these states (possible I<target> -values): - mem equivalent of S3 ACPI state - disk equivalent of S4 ACPI state - hybrid RAM is saved to disk but not powered off - -The I<--duration> argument specifies number of seconds before the domain is -woken up after it was suspended (see also B<dompmwakeup>). Default is 0 for -unlimited suspend time. (This feature isn't currently supported by any -hypervisor driver and 0 should be used.). - -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<dompmwakeup> I<domain> - -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<domrename> I<domain> I<new-name> - -Rename a domain. This command changes current domain name to the new name -specified in the second argument. - -B<Note>: Domain must be inactive and without snapshots or checkpoints. - -=item B<domstate> I<domain> [I<--reason>] - -Returns state about a domain. I<--reason> tells virsh to also print -reason for the state. - -=item B<domstats> [I<--raw>] [I<--enforce>] [I<--backing>] [I<--nowait>] -[I<--state>] [I<--cpu-total>] [I<--balloon>] [I<--vcpu>] [I<--interface>] -[I<--block>] [I<--perf>] [I<--iothread>] -[[I<--list-active>] [I<--list-inactive>] -[I<--list-persistent>] [I<--list-transient>] [I<--list-running>] -[I<--list-paused>] [I<--list-shutoff>] [I<--list-other>]] | [I<domain> ...] - -Get statistics for multiple or all domains. Without any argument this -command prints all available statistics for all domains. - -The list of domains to gather stats for can be either limited by listing -the domains as a space separated list, or by specifying one of the -filtering flags I<--list-*>. (The approaches can't be combined.) - -By default some of the returned fields may be converted to more -human friendly values by a set of pretty-printers. To suppress this -behavior use the I<--raw> flag. - -The individual statistics groups are selectable via specific flags. By -default all supported statistics groups are returned. Supported -statistics groups flags are: I<--state>, I<--cpu-total>, I<--balloon>, -I<--vcpu>, I<--interface>, I<--block>, I<--perf>, I<--iothread>. - -Note that - depending on the hypervisor type and version or the domain state -- not all of the following statistics may be returned. - -When selecting the I<--state> group the following fields are returned: - - "state.state" - state of the VM, returned as number from - virDomainState enum - "state.reason" - reason for entering given state, returned - as int from virDomain*Reason enum corresponding - to given state - -I<--cpu-total> returns: - - "cpu.time" - total cpu time spent for this domain in nanoseconds - "cpu.user" - user cpu time spent in nanoseconds - "cpu.system" - system cpu time spent in nanoseconds - "cpu.cache.monitor.count" - the number of cache monitors for this - domain - "cpu.cache.monitor.<num>.name" - the name of cache monitor <num> - "cpu.cache.monitor.<num>.vcpus" - vcpu list of cache monitor <num> - "cpu.cache.monitor.<num>.bank.count" - the number of cache banks - in cache monitor <num> - "cpu.cache.monitor.<num>.bank.<index>.id" - host allocated cache id - for bank <index> in - cache monitor <num> - "cpu.cache.monitor.<num>.bank.<index>.bytes" - the number of bytes - of last level cache - that the domain is - using on cache bank - <index> - -I<--balloon> returns: - - "balloon.current" - the memory in KiB currently used - "balloon.maximum" - the maximum memory in KiB allowed - "balloon.swap_in" - the amount of data read from swap space (in KiB) - "balloon.swap_out" - the amount of memory written out to swap - space (in KiB) - "balloon.major_fault" - the number of page faults then disk IO - was required - "balloon.minor_fault" - the number of other page faults - "balloon.unused" - the amount of memory left unused by the - system (in KiB) - "balloon.available" - the amount of usable memory as seen by - the domain (in KiB) - "balloon.rss" - Resident Set Size of running domain's process - (in KiB) - "balloon.usable" - the amount of memory which can be reclaimed by - balloon without causing host swapping (in KiB) - "balloon.last-update" - timestamp of the last update of statistics - (in seconds) - "balloon.disk_caches " - the amount of memory that can be reclaimed - without additional I/O, typically disk - caches (in KiB) - -I<--vcpu> returns: - - "vcpu.current" - current number of online virtual CPUs - "vcpu.maximum" - maximum number of online virtual CPUs - "vcpu.<num>.state" - state of the virtual CPU <num>, as - number from virVcpuState enum - "vcpu.<num>.time" - virtual cpu time spent by virtual - CPU <num> (in microseconds) - "vcpu.<num>.wait" - virtual cpu time spent by virtual - CPU <num> waiting on I/O (in microseconds) - "vcpu.<num>.halted" - virtual CPU <num> is halted: yes or - no (may indicate the processor is idle - or even disabled, depending on the - architecture) - -I<--interface> returns: - - "net.count" - number of network interfaces on this domain - "net.<num>.name" - name of the interface <num> - "net.<num>.rx.bytes" - number of bytes received - "net.<num>.rx.pkts" - number of packets received - "net.<num>.rx.errs" - number of receive errors - "net.<num>.rx.drop" - number of receive packets dropped - "net.<num>.tx.bytes" - number of bytes transmitted - "net.<num>.tx.pkts" - number of packets transmitted - "net.<num>.tx.errs" - number of transmission errors - "net.<num>.tx.drop" - number of transmit packets dropped - -I<--perf> returns the statistics of all enabled perf events: - - "perf.cmt" - the cache usage in Byte currently used - "perf.mbmt" - total system bandwidth from one level of cache - "perf.mbml" - bandwidth of memory traffic for a memory controller - "perf.cpu_cycles" - the count of cpu cycles (total/elapsed) - "perf.instructions" - the count of instructions - "perf.cache_references" - the count of cache hits - "perf.cache_misses" - the count of caches misses - "perf.branch_instructions" - the count of branch instructions - "perf.branch_misses" - the count of branch misses - "perf.bus_cycles" - the count of bus cycles - "perf.stalled_cycles_frontend" - the count of stalled frontend - cpu cycles - "perf.stalled_cycles_backend" - the count of stalled backend - cpu cycles - "perf.ref_cpu_cycles" - the count of ref cpu cycles - "perf.cpu_clock" - the count of cpu clock time - "perf.task_clock" - the count of task clock time - "perf.page_faults" - the count of page faults - "perf.context_switches" - the count of context switches - "perf.cpu_migrations" - the count of cpu migrations - "perf.page_faults_min" - the count of minor page faults - "perf.page_faults_maj" - the count of major page faults - "perf.alignment_faults" - the count of alignment faults - "perf.emulation_faults" - the count of emulation faults - -See the B<perf> command for more details about each event. - -I<--block> returns information about disks associated with each -domain. Using the I<--backing> flag extends this information to -cover all resources in the backing chain, rather than the default -of limiting information to the active layer for each guest disk. -Information listed includes: - - "block.count" - number of block devices being listed - "block.<num>.name" - name of the target of the block - device <num> (the same name for - multiple entries if I<--backing> - is present) - "block.<num>.backingIndex" - when I<--backing> is present, - matches up with the <backingStore> - index listed in domain XML for - backing files - "block.<num>.path" - file source of block device <num>, if - it is a local file or block device - "block.<num>.rd.reqs" - number of read requests - "block.<num>.rd.bytes" - number of read bytes - "block.<num>.rd.times" - total time (ns) spent on reads - "block.<num>.wr.reqs" - number of write requests - "block.<num>.wr.bytes" - number of written bytes - "block.<num>.wr.times" - total time (ns) spent on writes - "block.<num>.fl.reqs" - total flush requests - "block.<num>.fl.times" - total time (ns) spent on cache flushing - "block.<num>.errors" - Xen only: the 'oo_req' value - "block.<num>.allocation" - offset of highest written sector in bytes - "block.<num>.capacity" - logical size of source file in bytes - "block.<num>.physical" - physical size of source file in bytes - "block.<num>.threshold" - threshold (in bytes) for delivering the - VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event - See domblkthreshold. - -I<--iothread> returns information about IOThreads on the running guest -if supported by the hypervisor. - -The "poll-max-ns" for each thread is the maximum nanoseconds to allow -each polling interval to occur. A polling interval is a period of time -allowed for a thread to process data before being the guest gives up -its CPU quantum back to the host. A value set too small will not allow -the IOThread to run long enough on a CPU to process data. A value set -too high will consume too much CPU time per IOThread failing to allow -other threads running on the CPU to get time. The polling interval is -not available for statistical purposes. - - "iothread.<id>.poll-max-ns" - maximum polling time in nanoseconds used - by the <id> IOThread. A value of 0 (zero) - indicates polling is disabled. - "iothread.<id>.poll-grow" - polling time grow value. A value of 0 (zero) - indicates growth is managed by the hypervisor. - "iothread.<id>.poll-shrink" - polling time shrink value. A value of - 0 (zero) indicates shrink is managed by - the hypervisor. - -Selecting a specific statistics groups doesn't guarantee that the -daemon supports the selected group of stats. Flag I<--enforce> -forces the command to fail if the daemon doesn't support the -selected group. - -When collecting stats libvirtd may wait for some time if there's -already another job running on given domain for it to finish. -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<domtime> I<domain> { [I<--now>] [I<--pretty>] [I<--sync>] -[I<--time> B<time>] } - -Gets or sets the domain's system time. When run without any arguments -(but I<domain>), the current domain's system time is printed out. The -I<--pretty> modifier can be used to print the time in more human -readable form. - -When I<--time> B<time> is specified, the domain's time is -not gotten but set instead. The I<--now> modifier acts like if it was -an alias for I<--time> B<$now>, which means it sets the time that is -currently on the host virsh is running at. In both cases (setting and -getting), time is in seconds relative to Epoch of 1970-01-01 in UTC. -The I<--sync> modifies the set behavior a bit: The time passed is -ignored, but the time to set is read from domain's RTC instead. Please -note, that some hypervisors may require a guest agent to be configured -in order to get or set the guest time. - -=item B<domuuid> I<domain-name-or-id> - -Convert a domain name or id to domain UUID - -=item B<domxml-from-native> I<format> I<config> - -Convert the file I<config> in the native guest configuration format -named by I<format> to a domain XML format. For QEMU/KVM hypervisor, -the I<format> argument must be B<qemu-argv>. For Xen hypervisor, the -I<format> argument may be B<xen-xm>, B<xen-xl>, or B<xen-sxpr>. For -LXC hypervisor, the I<format> argument must be B<lxc-tools>. For -VMware/ESX hypervisor, the I<format> argument must be B<vmware-vmx>. -For the Bhyve hypervisor, the I<format> argument must be B<bhyve-argv>. - -=item B<domxml-to-native> I<format> -{ [I<--xml>] I<xml> | I<--domain> I<domain-name-or-id-or-uuid> } - -Convert the file I<xml> into domain XML format or convert an existing -I<--domain> to the native guest configuration format named by I<format>. -The I<xml> and I<--domain> arguments are mutually exclusive. For the types -of I<format> argument, refer to B<domxml-from-native>. - -=item B<dump> I<domain> I<corefilepath> [I<--bypass-cache>] -{ [I<--live>] | [I<--crash>] | [I<--reset>] } [I<--verbose>] [I<--memory-only>] -[I<--format> I<string>] - -Dumps the core of a domain to a file for analysis. -If I<--live> is specified, the domain continues to run until the core -dump is complete, rather than pausing up front. -If I<--crash> is specified, the domain is halted with a crashed status, -rather than merely left in a paused state. -If I<--reset> is specified, the domain is reset after successful dump. -Note, these three switches are mutually exclusive. -If I<--bypass-cache> is specified, the save will avoid the file system -cache, although this may slow down the operation. -If I<--memory-only> is specified, the file is elf file, and will only -include domain's memory and cpu common register value. It is very -useful if the domain uses host devices directly. -I<--format> I<string> is used to specify the format of 'memory-only' -dump, and I<string> can be one of them: elf, kdump-zlib(kdump-compressed -format with zlib-compressed), kdump-lzo(kdump-compressed format with -lzo-compressed), kdump-snappy(kdump-compressed format with snappy-compressed). - -The progress may be monitored using B<domjobinfo> virsh command and canceled -with B<domjobabort> command (sent by another virsh instance). Another option -is to send SIGINT (usually with C<Ctrl-C>) to the virsh process running -B<dump> command. I<--verbose> displays the progress of dump. - -NOTE: Some hypervisors may require the user to manually ensure proper -permissions on file and path specified by argument I<corefilepath>. - -NOTE: Crash dump in a old kvmdump format is being obsolete and cannot be loaded -and processed by crash utility since its version 6.1.0. A --memory-only option -is required in order to produce valid ELF file which can be later processed by -the crash utility. - -=item B<dumpxml> I<domain> [I<--inactive>] [I<--security-info>] -[I<--update-cpu>] [I<--migratable>] - -Output the domain information as an XML dump to stdout, this format can be used -by the B<create> command. Additional options affecting the XML dump may be -used. I<--inactive> tells virsh to dump domain configuration that will be used -on next start of the domain as opposed to the current domain configuration. -Using I<--security-info> will also include security sensitive information -in the XML dump. I<--update-cpu> updates domain CPU requirements according to -host CPU. With I<--migratable> one can request an XML that is suitable for -migrations, i.e., compatible with older libvirt releases and possibly amended -with internal run-time options. This option may automatically enable other -options (I<--update-cpu>, I<--security-info>, ...) as necessary. - -=item B<edit> I<domain> - -Edit the XML configuration file for a domain, which will affect the -next boot of the guest. - -This is equivalent to: - - virsh dumpxml --inactive --security-info domain > domain.xml - vi domain.xml (or make changes with your other text editor) - virsh define domain.xml - -except that it does some error checking. - -The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment -variables, and defaults to C<vi>. - -=item B<emulatorpin> I<domain> [I<cpulist>] [[I<--live>] [I<--config>] - | [I<--current>]] - -Query or change the pinning of domain's emulator threads to host physical -CPUs. - -See B<vcpupin> for I<cpulist>. - -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 if I<cpulist> is present, -but I<--current> is exclusive. -If no flag is specified, behavior is different depending on hypervisor. - -=item B<event> {[I<domain>] { I<event> | I<--all> } [I<--loop>] -[I<--timeout> I<seconds>] [I<--timestamp>] | I<--list>} - -Wait for a class of domain events to occur, and print appropriate details -of events as they happen. The events can optionally be filtered by -I<domain>. Using I<--list> as the only argument will provide a list -of possible I<event> values known by this client, although the connection -might not allow registering for all these events. It is also possible -to use I<--all> instead of I<event> to register for all possible event -types at once. - -By default, this command is one-shot, and returns success once an event -occurs; you can send SIGINT (usually via C<Ctrl-C>) to quit immediately. -If I<--timeout> is specified, the command gives up waiting for events -after I<seconds> have elapsed. With I<--loop>, the command prints all -events until a timeout or interrupt key. - -When I<--timestamp> is used, a human-readable timestamp will be printed -before the event. - -=item B<guest-agent-timeout> I<domain> I<--timeout> B<value> - -Set how long to wait for a response from guest agent commands. By default, -agent commands block forever waiting for a response. B<value> must be a -positive value (wait for given amount of seconds) or one of the following -values: - - -2 - block forever waiting for a result, - -1 - reset timeout to the default value, - 0 - do not wait at all, - -=item B<guestinfo> I<domain> [I<--user>] [I<--os>] [I<--timezone>] -[I<--hostname>] [I<--filesystem>] - -Print information about the guest from the point of view of the guest agent. -Note that this command requires a guest agent to be configured and running in -the domain's guest OS. - -When run without any arguments, this command prints all information types that -are supported by the guest agent. You can limit the types of information that -are returned by specifying one or more flags. If a requested information -type is not supported, the processes will provide an exit code of 1. -Available information types flags are I<--user>, I<--os>, -I<--timezone>, I<--hostname>, and I<--filesystem>. - -Note that depending on the hypervisor type and the version of the guest agent -running within the domain, not all of the following information may be -returned. - -When selecting the I<--user> information type, the following fields may be -returned: - - "user.count" - the number of active users on this domain - "user.<num>.name" - username of user <num> - "user.<num>.domain" - domain of the user <num> (may only be present on certain - guest types) - "user.<num>.login-time" - the login time of user <num> in milliseconds since - the epoch - -I<--os> returns: - - "os.id" - a string identifying the operating system - "os.name" - the name of the operating system - "os.pretty-name" - a pretty name for the operating system - "os.version" - the version of the operating system - "os.version-id" - the version id of the operating system - "os.kernel-release" - the release of the operating system kernel - "os.kernel-version" - the version of the operating system kernel - "os.machine" - the machine hardware name - "os.variant" - a specific variant or edition of the operating system - "os.variant-id" - the id for a specific variant or edition of the operating - system - -I<--timezone> returns: - - "timezone.name" - the name of the timezone - "timezone.offset" - the offset to UTC in seconds - -I<--hostname> returns: - - "hostname" - the hostname of the domain - -I<--filesystem> returns: - - "fs.count" - the number of filesystems defined on this domain - "fs.<num>.mountpoint" - the path to the mount point for filesystem <num> - "fs.<num>.name" - device name in the guest (e.g. "sda1") for filesystem <num> - "fs.<num>.fstype" - the type of filesystem <num> - "fs.<num>.total-bytes" - the total size of filesystem <num> - "fs.<num>.used-bytes" - the number of bytes used in filesystem <num> - "fs.<num>.disk.count" - the number of disks targeted by filesystem <num> - "fs.<num>.disk.<num>.alias" - the device alias of disk <num> (e.g. sda) - "fs.<num>.disk.<num>.serial" - the serial number of disk <num> - "fs.<num>.disk.<num>.device" - the device node of disk <num> - -=item B<guestvcpus> I<domain> [[I<--enable>] | [I<--disable>]] [I<cpulist>] - -Query or change state of vCPUs from guest's point of view using the guest agent. -When invoked without I<cpulist> the guest is queried for available guest vCPUs, -their state and possibility to be offlined. - -If I<cpulist> is provided then one of I<--enable> or I<--disable> must be -provided too. The desired operation is then executed on the domain. - -See B<vcpupin> for information on I<cpulist>. - -=item B<iothreadadd> I<domain> I<iothread_id> -[[I<--config>] [I<--live>] | [I<--current>]] - -Add a new IOThread to the domain using the specified I<iothread_id>. -If the I<iothread_id> already exists, the command will fail. The -I<iothread_id> must be greater than zero. - -If I<--live> is specified, affect a running guest. If the guest is not -running an error is returned. -If I<--config> is specified, affect the next boot of a persistent guest. -If I<--current> is specified or I<--live> and I<--config> are not specified, -affect the current guest state. - -=item B<iothreaddel> I<domain> I<iothread_id> -[[I<--config>] [I<--live>] | [I<--current>]] - -Delete an IOThread from the domain using the specified I<iothread_id>. -If an IOThread is currently assigned to a disk resource such as via the -B<attach-disk> command, then the attempt to remove the IOThread will fail. -If the I<iothread_id> does not exist an error will occur. - -If I<--live> is specified, affect a running guest. If the guest is not -running an error is returned. -If I<--config> is specified, affect the next boot of a persistent guest. -If I<--current> is specified or I<--live> and I<--config> are not specified, -affect the current guest state. - -=item B<iothreadinfo> I<domain> [[I<--live>] [I<--config>] | [I<--current>]] - -Display basic domain IOThreads information including the IOThread ID and -the CPU Affinity for each IOThread. - -If I<--live> is specified, get the IOThreads data from the running guest. If -the guest is not running, an error is returned. -If I<--config> is specified, get the IOThreads data from the next boot of -a persistent guest. -If I<--current> is specified or I<--live> and I<--config> are not specified, -then get the IOThread data based on the current guest state. - -=item B<iothreadpin> I<domain> I<iothread> I<cpulist> -[[I<--live>] [I<--config>] | [I<--current>]] - -Change the pinning of a domain IOThread to host physical CPUs. In order -to retrieve a list of all IOThreads, use B<iothreadinfo>. To pin an -I<iothread> specify the I<cpulist> desired for the IOThread ID as listed -in the B<iothreadinfo> output. - -I<cpulist> is a list of physical CPU numbers. Its syntax is a comma -separated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2') can -also be allowed. The '-' denotes the range and the '^' denotes exclusive. -If you want to reset iothreadpin setting, that is, to pin an I<iothread> -to all physical cpus, simply specify 'r' as a I<cpulist>. - -If I<--live> is specified, affect a running guest. If the guest is not running, -an error is returned. -If I<--config> is specified, affect the next boot of a persistent guest. -If I<--current> is specified or I<--live> and I<--config> are not specified, -affect the current guest state. -Both I<--live> and I<--config> flags may be given if I<cpulist> is present, -but I<--current> is exclusive. -If no flag is specified, behavior is different depending on hypervisor. - -B<Note>: The expression is sequentially evaluated, so "0-15,^8" is -identical to "9-14,0-7,15" but not identical to "^8,0-15". - -=item B<iothreadset> I<domain> I<iothread_id> -[[I<--poll-max-ns> B<ns>] [I<--poll-grow> B<factor>] -[I<--poll-shrink> B<divisor>]] -[[I<--config>] [I<--live>] | [I<--current>]] - -Modifies an existing iothread of the domain using the specified -I<iothread_id>. The I<--poll-max-ns> provides the maximum polling -interval to be allowed for an IOThread in ns. If a 0 (zero) is provided, -then polling for the IOThread is disabled. The I<--poll-grow> is the -factor by which the current polling time will be adjusted in order to -reach the maximum polling time. If a 0 (zero) is provided, then the -default factor will be used. The I<--poll-shrink> is the quotient -by which the current polling time will be reduced in order to get -below the maximum polling interval. If a 0 (zero) is provided, then -the default quotient will be used. The polling values are purely dynamic -for a running guest. Saving, destroying, stopping, etc. the guest will -result in the polling values returning to hypervisor defaults at the -next start, restore, etc. - -If I<--live> is specified, affect a running guest. If the guest is not -running an error is returned. -If I<--current> is specified or I<--live> is not specified, then handle -as if I<--live> was specified. - -=item B<managedsave> I<domain> [I<--bypass-cache>] -[{I<--running> | I<--paused>}] [I<--verbose>] - -Save and destroy (stop) a running domain, so it can be restarted from the same -state at a later time. When the virsh B<start> command is next run for -the domain, it will automatically be started from this saved state. -If I<--bypass-cache> is specified, the save will avoid the file system -cache, although this may slow down the operation. - -The progress may be monitored using B<domjobinfo> virsh command and canceled -with B<domjobabort> command (sent by another virsh instance). Another option -is to send SIGINT (usually with C<Ctrl-C>) to the virsh process running -B<managedsave> command. I<--verbose> displays the progress of save. - -Normally, starting a managed save will decide between running or paused -based on the state the domain was in when the save was done; passing -either the I<--running> or I<--paused> flag will allow overriding which -state the B<start> should use. - -The B<dominfo> command can be used to query whether a domain currently -has any managed save image. - -=item B<managedsave-define> I<domain> I<xml> [{I<--running> | I<--paused>}] - -Update the domain XML that will be used when I<domain> is later -started. The I<xml> argument must be a file name containing -the alternative XML, with changes only in the host-specific portions of -the domain XML. For example, it can be used to change disk file paths. - -The managed save image records whether the domain should be started to a -running or paused state. Normally, this command does not alter the -recorded state; passing either the I<--running> or I<--paused> flag -will allow overriding which state the B<start> should use. - -=item B<managedsave-dumpxml> I<domain> [I<--security-info>] - -Extract the domain XML that was in effect at the time the saved state -file I<file> was created with the B<managedsave> command. Using -I<--security-info> will also include security sensitive information. - -=item B<managedsave-edit> I<domain> [{I<--running> | I<--paused>}] - -Edit the XML configuration associated with a saved state file of a -I<domain> was created by the B<managedsave> command. - -The managed save image records whether the domain should be started to a -running or paused state. Normally, this command does not alter the -recorded state; passing either the I<--running> or I<--paused> flag -will allow overriding which state the B<restore> should use. - -This is equivalent to: - - virsh managedsave-dumpxml domain-name > state-file.xml - vi state-file.xml (or make changes with your other text editor) - virsh managedsave-define domain-name state-file-xml - -except that it does some error checking. - -The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment -variables, and defaults to C<vi>. - -=item B<managedsave-remove> I<domain> - -Remove the B<managedsave> state file for a domain, if it exists. This -ensures the domain will do a full boot the next time it is started. - -=item B<maxvcpus> [I<type>] - -Provide the maximum number of virtual CPUs supported for a guest VM on -this connection. If provided, the I<type> parameter must be a valid -type attribute for the <domain> element of XML. - -=item B<memtune> I<domain> [I<--hard-limit> B<size>] -[I<--soft-limit> B<size>] [I<--swap-hard-limit> B<size>] -[I<--min-guarantee> B<size>] [[I<--config>] [I<--live>] | [I<--current>]] - -Allows you to display or set the domain memory parameters. Without -flags, the current settings are displayed; with a flag, the -appropriate limit is adjusted if supported by the hypervisor. LXC and -QEMU/KVM support I<--hard-limit>, I<--soft-limit>, and I<--swap-hard-limit>. -I<--min-guarantee> is supported only by ESX hypervisor. Each of these -limits are scaled integers (see B<NOTES> above), with a default of -kibibytes (blocks of 1024 bytes) if no suffix is present. Libvirt rounds -up to the nearest kibibyte. Some hypervisors require a larger granularity -than KiB, and requests that are not an even multiple will be rounded up. -For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes). - -If 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. - -For QEMU/KVM, the parameters are applied to the QEMU process as a whole. -Thus, when counting them, one needs to add up guest RAM, guest video RAM, and -some memory overhead of QEMU itself. The last piece is hard to determine so -one needs guess and try. - -For LXC, the displayed hard_limit value is the current memory setting -from the XML or the results from a B<virsh setmem> command. - -=over 4 - -=item I<--hard-limit> - -The maximum memory the guest can use. - -=item I<--soft-limit> - -The memory limit to enforce during memory contention. - -=item I<--swap-hard-limit> - -The maximum memory plus swap the guest can use. This has to be more -than hard-limit value provided. - -=item I<--min-guarantee> - -The guaranteed minimum memory allocation for the guest. - -=back - -Specifying -1 as a value for these limits is interpreted as unlimited. - -=item B<metadata> I<domain> [[I<--live>] [I<--config>] | [I<--current>]] -[I<--edit>] [I<uri>] [I<key>] [I<set>] [I<--remove>] - -Show or modify custom XML metadata of a domain. The metadata is a user -defined XML that allows storing arbitrary XML data in the domain definition. -Multiple separate custom metadata pieces can be stored in the domain XML. -The pieces are identified by a private XML namespace provided via the -I<uri> argument. (See also B<desc> that works with textual metadata of -a domain.) - -Flags I<--live> or I<--config> select whether this command works on live -or persistent definitions of the domain. If both I<--live> and I<--config> -are specified, the I<--config> option takes precedence on getting the current -description and both live configuration and config are updated while setting -the description. I<--current> is exclusive and implied if none of these was -specified. - -Flag I<--remove> specifies that the metadata element specified by the I<uri> -argument should be removed rather than updated. - -Flag I<--edit> specifies that an editor with the metadata identified by the -I<uri> argument should be opened and the contents saved back afterwards. -Otherwise the new contents can be provided via the I<set> argument. - -When setting metadata via I<--edit> or I<set> the I<key> argument must be -specified and is used to prefix the custom elements to bind them -to the private namespace. - -If neither of I<--edit> and I<set> are specified the XML metadata corresponding -to the I<uri> namespace is displayed instead of being modified. - -=item B<migrate> [I<--live>] [I<--offline>] [I<--direct>] [I<--p2p> [I<--tunnelled>]] -[I<--persistent>] [I<--undefinesource>] [I<--suspend>] [I<--copy-storage-all>] -[I<--copy-storage-inc>] [I<--change-protection>] [I<--unsafe>] [I<--verbose>] -[I<--rdma-pin-all>] [I<--abort-on-error>] [I<--postcopy>] [I<--postcopy-after-precopy>] -I<domain> I<desturi> [I<migrateuri>] [I<graphicsuri>] [I<listen-address>] [I<dname>] -[I<--timeout> B<seconds> [I<--timeout-suspend> | I<--timeout-postcopy>]] -[I<--xml> B<file>] [I<--migrate-disks> B<disk-list>] [I<--disks-port> B<port>] -[I<--compressed>] [I<--comp-methods> B<method-list>] -[I<--comp-mt-level>] [I<--comp-mt-threads>] [I<--comp-mt-dthreads>] -[I<--comp-xbzrle-cache>] [I<--auto-converge>] [I<auto-converge-initial>] -[I<auto-converge-increment>] [I<--persistent-xml> B<file>] [I<--tls>] -[I<--postcopy-bandwidth> B<bandwidth>] -[I<--parallel> [I<--parallel-connections> B<connections>]] -[I<--bandwidth> B<bandwidth>] - -Migrate domain to another host. Add I<--live> for live migration; <--p2p> -for peer-2-peer migration; I<--direct> for direct migration; or I<--tunnelled> -for tunnelled migration. I<--offline> migrates domain definition without -starting the domain on destination and without stopping it on source host. -Offline migration may be used with inactive domains and it must be used with -I<--persistent> option. I<--persistent> leaves the domain persistent on -destination host, I<--undefinesource> undefines the domain on the source host, -and I<--suspend> leaves the domain paused on the destination host. -I<--copy-storage-all> indicates migration with non-shared storage with full -disk copy, I<--copy-storage-inc> indicates migration with non-shared storage -with incremental copy (same base image shared between source and destination). -In both cases the disk images have to exist on destination host, the -I<--copy-storage-...> options only tell libvirt to transfer data from the -images on source host to the images found at the same place on the destination -host. By default only non-shared non-readonly images are transferred. Use -I<--migrate-disks> to explicitly specify a list of disk targets to -transfer via the comma separated B<disk-list> argument. I<--change-protection> -enforces that no incompatible configuration changes will be made to the domain -while the migration is underway; this flag is implicitly enabled when supported -by the hypervisor, but can be explicitly used to reject the migration if the -hypervisor lacks change protection support. I<--verbose> displays the progress -of migration. I<--abort-on-error> cancels -the migration if a soft error (for example I/O error) happens during the -migration. I<--postcopy> enables post-copy logic in migration, but does not -actually start post-copy, i.e., migration is started in pre-copy mode. -Once migration is running, the user may switch to post-copy using the -B<migrate-postcopy> command sent from another virsh instance or use -I<--postcopy-after-precopy> along with I<--postcopy> to let libvirt -automatically switch to post-copy after the first pass of pre-copy is finished. -The maximum bandwidth consumed during the post-copy phase may be limited using -I<--postcopy-bandwidth>. The maximum bandwidth consumed during the pre-copy phase -may be limited using I<--bandwidth>. - -I<--auto-converge> forces convergence during live migration. The initial -guest CPU throttling rate can be set with I<auto-converge-initial>. If the -initial throttling rate is not enough to ensure convergence, the rate is -periodically increased by I<auto-converge-increment>. - -I<--rdma-pin-all> can be used with RDMA migration (i.e., when I<migrateuri> -starts with rdma://) to tell the hypervisor to pin all domain's memory at once -before migration starts rather than letting it pin memory pages as needed. For -QEMU/KVM this requires hard_limit memory tuning element (in the domain XML) to -be used and set to the maximum memory configured for the domain plus any memory -consumed by the QEMU process itself. Beware of setting the memory limit too -high (and thus allowing the domain to lock most of the host's memory). Doing so -may be dangerous to both the domain and the host itself since the host's kernel -may run out of memory. - -B<Note>: Individual hypervisors usually do not support all possible types of -migration. For example, QEMU does not support direct migration. - -In some cases libvirt may refuse to migrate the domain because doing so may -lead to potential problems such as data corruption, and thus the migration is -considered unsafe. For QEMU domain, this may happen if the domain uses disks -without explicitly setting cache mode to "none". Migrating such domains is -unsafe unless the disk images are stored on coherent clustered filesystem, -such as GFS2 or GPFS. If you are sure the migration is safe or you just do not -care, use I<--unsafe> to force the migration. - -I<dname> is used for renaming the domain to new name during migration, which -also usually can be omitted. Likewise, I<--xml> B<file> is usually -omitted, but can be used to supply an alternative XML file for use on -the destination to supply a larger set of changes to any host-specific -portions of the domain XML, such as accounting for naming differences -between source and destination in accessing underlying storage. -If I<--persistent> is enabled, I<--persistent-xml> B<file> can be used to -supply an alternative XML file which will be used as the persistent domain -definition on the destination host. - -I<--timeout> B<seconds> tells virsh to run a specified action when live -migration exceeds that many seconds. It can only be used with I<--live>. -If I<--timeout-suspend> is specified, the domain will be suspended after -the timeout and the migration will complete offline; this is the default -if no I<--timeout-*> option is specified on the command line. When -I<--timeout-postcopy> is used, virsh will switch migration from pre-copy -to post-copy upon timeout; migration has to be started with I<--postcopy> -option for this to work. - -I<--compressed> activates compression, the compression method is chosen -with I<--comp-methods>. Supported methods are "mt" and "xbzrle" and -can be used in any combination. When no methods are specified, a hypervisor -default methods will be used. QEMU defaults to "xbzrle". Compression methods -can be tuned further. I<--comp-mt-level> sets compression level. -Values are in range from 0 to 9, where 1 is maximum speed and 9 is maximum -compression. I<--comp-mt-threads> and I<--comp-mt-dthreads> set the number -of compress threads on source and the number of decompress threads on target -respectively. I<--comp-xbzrle-cache> sets size of page cache in bytes. - -Providing I<--tls> causes the migration to use the host configured TLS setup -(see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in order to perform -the migration of the domain. Usage requires proper TLS setup for both source -and target. - -I<--parallel> option will cause migration data to be sent over multiple -parallel connections. The number of such connections can be set using -I<--parallel-connections>. Parallel connections may help with saturating the -network link between the source and the target and thus speeding up the -migration. - -Running migration can be canceled by interrupting virsh (usually using -C<Ctrl-C>) or by B<domjobabort> command sent from another virsh instance. - -The I<desturi> and I<migrateuri> parameters can be used to control which -destination the migration uses. I<desturi> is important for managed -migration, but unused for direct migration; I<migrateuri> is required -for direct migration, but can usually be automatically determined for -managed migration. - -B<Note>: The I<desturi> parameter for normal migration and peer2peer migration -has different semantics: - -=over 4 - -=item * normal migration: the I<desturi> is an address of the target host as -seen from the client machine. - -=item * peer2peer migration: the I<desturi> is an address of the target host as -seen from the source machine. - -=back - -When I<migrateuri> is not specified, libvirt will automatically determine the -hypervisor specific URI. Some hypervisors, including QEMU, have an optional -"migration_host" configuration parameter (useful when the host has multiple -network interfaces). If this is unspecified, libvirt determines a name -by looking up the target host's configured hostname. - -There are a few scenarios where specifying I<migrateuri> may help: - -=over 4 - -=item * The configured hostname is incorrect, or DNS is broken. If a host has a -hostname which will not resolve to match one of its public IP addresses, then -libvirt will generate an incorrect URI. In this case I<migrateuri> should be -explicitly specified, using an IP address, or a correct hostname. - -=item * The host has multiple network interfaces. If a host has multiple network -interfaces, it might be desirable for the migration data stream to be sent over -a specific interface for either security or performance reasons. In this case -I<migrateuri> should be explicitly specified, using an IP address associated -with the network to be used. - -=item * The firewall restricts what ports are available. When libvirt generates -a migration URI, it will pick a port number using hypervisor specific rules. -Some hypervisors only require a single port to be open in the firewalls, while -others require a whole range of port numbers. In the latter case I<migrateuri> -might be specified to choose a specific port number outside the default range in -order to comply with local firewall policies. - -=back - -See L<https://libvirt.org/migration.html#uris> for more details on -migration URIs. - -Optional I<graphicsuri> overrides connection parameters used for automatically -reconnecting a graphical clients at the end of migration. If omitted, libvirt -will compute the parameters based on target host IP address. In case the -client does not have a direct access to the network virtualization hosts are -connected to and needs to connect through a proxy, I<graphicsuri> may be used -to specify the address the client should connect to. The URI is formed as -follows: - - protocol://hostname[:port]/[?parameters] - -where protocol is either "spice" or "vnc" and parameters is a list of protocol -specific parameters separated by '&'. Currently recognized parameters are -"tlsPort" and "tlsSubject". For example, - - spice://target.host.com:1234/?tlsPort=4567 - -Optional I<listen-address> sets the listen address that hypervisor on the -destination side should bind to for incoming migration. Both IPv4 and IPv6 -addresses are accepted as well as hostnames (the resolving is done on -destination). Some hypervisors do not support this feature and will return an -error if this parameter is used. - -Optional I<disks-port> sets the port that hypervisor on destination side should -bind to for incoming disks traffic. Currently it is supported only by qemu. - -=item B<migrate-compcache> I<domain> [I<--size> B<bytes>] - -Sets and/or gets size of the cache (in bytes) used for compressing repeatedly -transferred memory pages during live migration. When called without I<size>, -the command just prints current size of the compression cache. When I<size> -is specified, the hypervisor is asked to change compression cache to I<size> -bytes and then the current size is printed (the result may differ from the -requested size due to rounding done by the hypervisor). The I<size> option -is supposed to be used while the domain is being live-migrated as a reaction -to migration progress and increasing number of compression cache misses -obtained from domjobinfo. - -=item B<migrate-getmaxdowntime> I<domain> - -Get the maximum tolerable downtime for a domain which is being live-migrated to -another host. This is the number of milliseconds the guest is allowed -to be down at the end of live migration. - -=item B<migrate-getspeed> I<domain> [I<--postcopy>] - -Get the maximum migration bandwidth (in MiB/s) for a domain. If the -I<--postcopy> option is specified, the command will get the maximum bandwidth -allowed during a post-copy migration phase. - -=item B<migrate-postcopy> I<domain> - -Switch the current migration from pre-copy to post-copy. This is only -supported for a migration started with I<--postcopy> option. - -=item B<migrate-setmaxdowntime> I<domain> I<downtime> - -Set maximum tolerable downtime for a domain which is being live-migrated to -another host. The I<downtime> is a number of milliseconds the guest is allowed -to be down at the end of live migration. - -=item B<migrate-setspeed> I<domain> I<bandwidth> [I<--postcopy>] - -Set the maximum migration bandwidth (in MiB/s) for a domain which is being -migrated to another host. I<bandwidth> is interpreted as an unsigned long -long value. Specifying a negative value results in an essentially unlimited -value being provided to the hypervisor. The hypervisor can choose whether to -reject the value or convert it to the maximum value allowed. If the -I<--postcopy> option is specified, the command will set the maximum bandwidth -allowed during a post-copy migration phase. - -=item B<numatune> I<domain> [I<--mode> B<mode>] [I<--nodeset> B<nodeset>] -[[I<--config>] [I<--live>] | [I<--current>]] - -Set or get a domain's numa parameters, corresponding to the <numatune> -element of domain XML. Without flags, the current settings are -displayed. - -I<mode> can be one of `strict', `interleave' and `preferred' or any -valid number from the virDomainNumatuneMemMode enum in case the daemon -supports it. For a running domain, the mode can't be changed, and the -nodeset can be changed only if the domain was started with a mode of -`strict'. - -I<nodeset> is a list of numa nodes used by the host for running the domain. -Its syntax is a comma separated list, with '-' for ranges and '^' for -excluding a node. - -If I<--live> is specified, set scheduler information of 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. - -=item B<perf> I<domain> [I<--enable> B<eventSpec>] -[I<--disable> B<eventSpec>] -[[I<--config>] [I<--live>] | [I<--current>]] - -Get the current perf events setting or enable/disable specific perf -events for a guest domain. - -Perf is a performance analyzing tool in Linux, and it can instrument -CPU performance counters, tracepoints, kprobes, and uprobes (dynamic -tracing). Perf supports a list of measurable events, and can measure -events coming from different sources. For instance, some event are -pure kernel counters, in this case they are called software events, -including context-switches, minor-faults, etc.. Now dozens of events -from different sources can be supported by perf. - -Currently only QEMU/KVM supports this command. The I<--enable> and I<--disable> -option combined with B<eventSpec> can be used to enable or disable specific -performance event. B<eventSpec> is a string list of one or more events -separated by commas. Valid event names are as follows: - -B<Valid perf event names> - cmt - A PQos (Platform Qos) feature to monitor the - usage of cache by applications running on the - platform. - mbmt - Provides a way to monitor the total system - memory bandwidth between one level of cache - and another. - mbml - Provides a way to limit the amount of data - (bytes/s) send through the memory controller - on the socket. - cache_misses - Provides the count of cache misses by - applications running on the platform. - cache_references - Provides the count of cache hits by - applications running on th e platform. - instructions - Provides the count of instructions executed - by applications running on the platform. - cpu_cycles - Provides the count of cpu cycles - (total/elapsed). May be used with - instructions in order to get a cycles - per instruction. - branch_instructions - Provides the count of branch instructions - executed by applications running on the - platform. - branch_misses - Provides the count of branch misses executed - by applications running on the platform. - bus_cycles - Provides the count of bus cycles executed - by applications running on the platform. - stalled_cycles_frontend - Provides the count of stalled cpu - cycles in the frontend of the - instruction processor pipeline by - applications running on the platform. - stalled_cycles_backend - Provides the count of stalled cpu - cycles in the backend of the - instruction processor pipeline by - applications running on the platform. - ref_cpu_cycles - Provides the count of total cpu cycles - not affected by CPU frequency scaling by - applications running on the platform. - cpu_clock - Provides the cpu clock time consumed by - applications running on the platform. - task_clock - Provides the task clock time consumed by - applications running on the platform. - page_faults - Provides the count of page faults by - applications running on the platform. - context_switches - Provides the count of context switches - by applications running on the platform. - cpu_migrations - Provides the count cpu migrations by - applications running on the platform. - page_faults_min - Provides the count minor page faults - by applications running on the platform. - page_faults_maj - Provides the count major page faults - by applications running on the platform. - alignment_faults - Provides the count alignment faults - by applications running on the platform. - emulation_faults - Provides the count emulation faults - by applications running on the platform. - -B<Note>: The statistics can be retrieved using the B<domstats> command using -the I<--perf> flag. - -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<reboot> I<domain> [I<--mode MODE-LIST>] - -Reboot a domain. This acts just as if the domain had the B<reboot> -command run from the console. The command returns as soon as it has -executed the reboot action, which may be significantly before the -domain actually reboots. - -The exact behavior of a domain when it reboots is set by the -I<on_reboot> parameter in the domain's XML definition. - -By default the hypervisor will try to pick a suitable shutdown -method. To specify an alternative method, the I<--mode> parameter -can specify a comma separated list which includes C<acpi>, C<agent>, -C<initctl>, C<signal> and C<paravirt>. The order in which drivers will -try each mode is undefined, and not related to the order specified to virsh. -For strict control over ordering, use a single mode at a time and -repeat the command. - -=item B<reset> I<domain> - -Reset a domain immediately without any guest shutdown. B<reset> -emulates the power reset button on a machine, where all guest -hardware sees the RST line set and reinitializes internal state. - -B<Note>: Reset without any guest OS shutdown risks data loss. - -=item B<restore> I<state-file> [I<--bypass-cache>] [I<--xml> B<file>] -[{I<--running> | I<--paused>}] - -Restores a domain from a B<virsh save> state file. See I<save> for more info. - -If I<--bypass-cache> is specified, the restore will avoid the file system -cache, although this may slow down the operation. - -I<--xml> B<file> is usually omitted, but can be used to supply an -alternative XML file for use on the restored guest with changes only -in the host-specific portions of the domain XML. For example, it can -be used to account for file naming differences in underlying storage -due to disk snapshots taken after the guest was saved. - -Normally, restoring a saved image will use the state recorded in the -save image to decide between running or paused; passing either the -I<--running> or I<--paused> flag will allow overriding which state the -domain should be started in. - -B<Note>: To avoid corrupting file system contents within the domain, you -should not reuse the saved state file for a second B<restore> unless you -have also reverted all storage volumes back to the same contents as when -the state file was created. - -=item B<resume> I<domain> - -Moves a domain out of the suspended state. This will allow a previously -suspended domain to now be eligible for scheduling by the underlying -hypervisor. - -=item B<save> I<domain> I<state-file> [I<--bypass-cache>] [I<--xml> B<file>] -[{I<--running> | I<--paused>}] [I<--verbose>] - -Saves a running domain (RAM, but not disk state) to a state file so that -it can be restored -later. Once saved, the domain will no longer be running on the -system, thus the memory allocated for the domain will be free for -other domains to use. B<virsh restore> restores from this state file. -If I<--bypass-cache> is specified, the save will avoid the file system -cache, although this may slow down the operation. - -The progress may be monitored using B<domjobinfo> virsh command and canceled -with B<domjobabort> command (sent by another virsh instance). Another option -is to send SIGINT (usually with C<Ctrl-C>) to the virsh process running -B<save> command. I<--verbose> displays the progress of save. - -This is roughly equivalent to doing a hibernate on a running computer, -with all the same limitations. Open network connections may be -severed upon restore, as TCP timeouts may have expired. - -I<--xml> B<file> is usually omitted, but can be used to supply an -alternative XML file for use on the restored guest with changes only -in the host-specific portions of the domain XML. For example, it can -be used to account for file naming differences that are planned to -be made via disk snapshots of underlying storage after the guest is saved. - -Normally, restoring a saved image will decide between running or paused -based on the state the domain was in when the save was done; passing -either the I<--running> or I<--paused> flag will allow overriding which -state the B<restore> should use. - -Domain saved state files assume that disk images will be unchanged -between the creation and restore point. For a more complete system -restore point, where the disk state is saved alongside the memory -state, see the B<snapshot> family of commands. - -=item B<save-image-define> I<file> I<xml> [{I<--running> | I<--paused>}] - -Update the domain XML that will be used when I<file> is later -used in the B<restore> command. The I<xml> argument must be a file -name containing the alternative XML, with changes only in the -host-specific portions of the domain XML. For example, it can -be used to account for file naming differences resulting from creating -disk snapshots of underlying storage after the guest was saved. - -The save image records whether the domain should be restored to a -running or paused state. Normally, this command does not alter the -recorded state; passing either the I<--running> or I<--paused> flag -will allow overriding which state the B<restore> should use. - -=item B<save-image-dumpxml> I<file> [I<--security-info>] - -Extract the domain XML that was in effect at the time the saved state -file I<file> was created with the B<save> command. Using -I<--security-info> will also include security sensitive information. - -=item B<save-image-edit> I<file> [{I<--running> | I<--paused>}] - -Edit the XML configuration associated with a saved state file I<file> -created by the B<save> command. - -The save image records whether the domain should be restored to a -running or paused state. Normally, this command does not alter the -recorded state; passing either the I<--running> or I<--paused> flag -will allow overriding which state the B<restore> should use. - -This is equivalent to: - - virsh save-image-dumpxml state-file > state-file.xml - vi state-file.xml (or make changes with your other text editor) - virsh save-image-define state-file state-file-xml - -except that it does some error checking. - -The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment -variables, and defaults to C<vi>. - -=item B<schedinfo> I<domain> [[I<--config>] [I<--live>] | [I<--current>]] -[[I<--set>] B<parameter=value>]... - -=item B<schedinfo> [I<--weight> B<number>] [I<--cap> B<number>] -I<domain> - -Allows you to show (and set) the domain scheduler parameters. The parameters -available for each hypervisor are: - -LXC (posix scheduler) : cpu_shares, vcpu_period, vcpu_quota - -QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota, -emulator_period, emulator_quota, iothread_quota, iothread_period - -Xen (credit scheduler): weight, cap - -ESX (allocation scheduler): reservation, limit, shares - -If I<--live> is specified, set scheduler information of 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. - -B<Note>: The cpu_shares parameter has a valid value range of 0-262144; Negative -values are wrapped to positive, and larger values are capped at the maximum. -Therefore, -1 is a useful shorthand for 262144. On the Linux kernel, the -values 0 and 1 are automatically converted to a minimal value of 2. - -B<Note>: The weight and cap parameters are defined only for the -XEN_CREDIT scheduler. - -B<Note>: The vcpu_period, emulator_period, and iothread_period parameters -have a valid value range of 1000-1000000 or 0, and the vcpu_quota, -emulator_quota, and iothread_quota parameters have a valid value range of -1000-18446744073709551 or less than 0. The value 0 for -either parameter is the same as not specifying that parameter. - -=item B<screenshot> I<domain> [I<imagefilepath>] [I<--screen> B<screenID>] - -Takes a screenshot of a current domain console and stores it into a file. -Optionally, if the hypervisor supports more displays for a domain, I<screenID> -allows specifying which screen will be captured. It is the sequential number -of screen. In case of multiple graphics cards, heads are enumerated before -devices, e.g. having two graphics cards, both with four heads, screen ID 5 -addresses the second head on the second card. - -=item B<send-key> I<domain> [I<--codeset> B<codeset>] -[I<--holdtime> B<holdtime>] I<keycode>... - -Parse the I<keycode> sequence as keystrokes to send to I<domain>. -Each I<keycode> can either be a numeric value or a symbolic name from -the corresponding codeset. If I<--holdtime> is given, each keystroke -will be held for that many milliseconds. The default codeset is -B<linux>, but use of the I<--codeset> option allows other codesets to -be chosen. - -If multiple keycodes are specified, they are all sent simultaneously -to the guest, and they may be received in random order. If you need -distinct keypresses, you must use multiple send-key invocations. - -=over 4 - -=item B<linux> - -The numeric values are those defined by the Linux generic input -event subsystem. The symbolic names match the corresponding -Linux key constant macro names. - -See L<virkeycode-linux(7)> and L<virkeyname-linux(7)> - -=item B<xt> - -The numeric values are those defined by the original XT keyboard -controller. No symbolic names are provided - -See L<virkeycode-xt(7)> - -=item B<atset1> - -The numeric values are those defined by the AT keyboard controller, -set 1 (aka XT compatible set). Extended keycoes from B<atset1> -may differ from extended keycodes in the B<xt> codeset. No symbolic -names are provided - -See L<virkeycode-atset1(7)> - -=item B<atset2> - -The numeric values are those defined by the AT keyboard controller, -set 2. No symbolic names are provided - -See L<virkeycode-atset2(7)> - -=item B<atset3> - -The numeric values are those defined by the AT keyboard controller, -set 3 (aka PS/2 compatible set). No symbolic names are provided - -See L<virkeycode-atset3(7)> - -=item B<os_x> - -The numeric values are those defined by the macOS keyboard input -subsystem. The symbolic names match the corresponding macOS key -constant macro names - -See L<virkeycode-osx(7)> and L<virkeyname-osx(7)> - -=item B<xt_kbd> - -The numeric values are those defined by the Linux KBD device. -These are a variant on the original XT codeset, but often with -different encoding for extended keycodes. No symbolic names are -provided. - -See L<virkeycode-xtkbd(7)> - -=item B<win32> - -The numeric values are those defined by the Win32 keyboard input -subsystem. The symbolic names match the corresponding Win32 key -constant macro names - -See L<virkeycode-win32(7)> and L<virkeyname-win32(7)> - -=item B<usb> - -The numeric values are those defined by the USB HID specification -for keyboard input. No symbolic names are provided - -See L<virkeycode-usb(7)> - -=item B<qnum> - -The numeric values are those defined by the QNUM extension for sending -raw keycodes. These are a variant on the XT codeset, but extended -keycodes have the low bit of the second byte set, instead of the high -bit of the first byte. No symbolic names are provided. - -See L<virkeycode-qnum(7)> - -=back - -B<Examples> - # send three strokes 'k', 'e', 'y', using xt codeset. these - # are all pressed simultaneously and may be received by the guest - # in random order - virsh send-key dom --codeset xt 37 18 21 - - # send one stroke 'right-ctrl+C' - virsh send-key dom KEY_RIGHTCTRL KEY_C - - # send a tab, held for 1 second - virsh send-key --holdtime 1000 0xf - -=item B<send-process-signal> I<domain-id> I<pid> I<signame> - -Send a signal I<signame> to the process identified by I<pid> running in -the virtual domain I<domain-id>. The I<pid> is a process ID in the virtual -domain namespace. - -The I<signame> argument may be either an integer signal constant number, -or one of the symbolic names: - - "nop", "hup", "int", "quit", "ill", - "trap", "abrt", "bus", "fpe", "kill", - "usr1", "segv", "usr2", "pipe", "alrm", - "term", "stkflt", "chld", "cont", "stop", - "tstp", "ttin", "ttou", "urg", "xcpu", - "xfsz", "vtalrm", "prof", "winch", "poll", - "pwr", "sys", "rt0", "rt1", "rt2", "rt3", - "rt4", "rt5", "rt6", "rt7", "rt8", "rt9", - "rt10", "rt11", "rt12", "rt13", "rt14", "rt15", - "rt16", "rt17", "rt18", "rt19", "rt20", "rt21", - "rt22", "rt23", "rt24", "rt25", "rt26", "rt27", - "rt28", "rt29", "rt30", "rt31", "rt32" - -The symbol name may optionally be prefixed with 'sig' or 'sig_' and -may be in uppercase or lowercase. - -B<Examples> - virsh send-process-signal myguest 1 15 - virsh send-process-signal myguest 1 term - virsh send-process-signal myguest 1 sigterm - virsh send-process-signal myguest 1 SIG_HUP - -=item B<set-lifecycle-action> I<domain> I<type> I<action> -[[I<--config>] [I<--live>] | [I<--current>]] - -Set the lifecycle I<action> for specified lifecycle I<type>. -The valid types are "poweroff", "reboot" and "crash", and for each of -them valid I<action> is one of "destroy", "restart", "rename-restart", -"preserve". For I<type> "crash", additional actions "coredump-destroy" -and "coredump-restart" are supported. - -=item B<set-user-password> I<domain> I<user> I<password> [I<--encrypted>] - -Set the password for the I<user> account in the guest domain. - -If I<--encrypted> is specified, the password is assumed to be already -encrypted by the method required by the guest OS. - -For QEMU/KVM, this requires the guest agent to be configured -and running. - -=item B<setmaxmem> I<domain> B<size> [[I<--config>] [I<--live>] | -[I<--current>]] - -Change the maximum memory allocation limit for a guest domain. -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. - -Some hypervisors such as QEMU/KVM don't support live changes (especially -increasing) of the maximum memory limit. Even persistent configuration changes -might not be performed with some hypervisors/configuration (e.g. on NUMA enabled -domains on QEMU). For complex configuration changes use command B<edit> -instead). - -I<size> is a scaled integer (see B<NOTES> above); it defaults to kibibytes -(blocks of 1024 bytes) unless you provide a suffix (and the older option -name I<--kilobytes> is available as a deprecated synonym) . Libvirt rounds -up to the nearest kibibyte. Some hypervisors require a larger granularity -than KiB, and requests that are not an even multiple will be rounded up. -For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes). - -=item B<setmem> I<domain> B<size> [[I<--config>] [I<--live>] | -[I<--current>]] - -Change the memory allocation for a guest domain. -If I<--live> is specified, perform a memory balloon of 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. - -I<size> is a scaled integer (see B<NOTES> above); it defaults to kibibytes -(blocks of 1024 bytes) unless you provide a suffix (and the older option -name I<--kilobytes> is available as a deprecated synonym) . Libvirt rounds -up to the nearest kibibyte. Some hypervisors require a larger granularity -than KiB, and requests that are not an even multiple will be rounded up. -For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes). - -For Xen, you can only adjust the memory of a running domain if the domain is -paravirtualized or running the PV balloon driver. - -For LXC, the value being set is the cgroups value for limit_in_bytes or the -maximum amount of user memory (including file cache). When viewing memory -inside the container, this is the /proc/meminfo "MemTotal" value. When viewing -the value from the host, use the B<virsh memtune> command. In order to view -the current memory in use and the maximum value allowed to set memory, use -the B<virsh dominfo> command. - -=item B<setvcpus> I<domain> I<count> [I<--maximum>] [[I<--config>] -[I<--live>] | [I<--current>]] [I<--guest>] [I<--hotpluggable>] - -Change the number of virtual CPUs active in a guest domain. By default, -this command works on active guest domains. To change the settings for an -inactive guest domain, use the I<--config> flag. - -The I<count> value may be limited by host, hypervisor, or a limit coming -from the original description of the guest domain. For Xen, you can only -adjust the virtual CPUs of a running domain if the domain is paravirtualized. - -If the I<--config> flag is specified, the change is made to the stored XML -configuration for the guest domain, and will only take effect when the guest -domain is next started. - -If I<--live> is specified, the guest domain must be active, and the change -takes place immediately. Both the I<--config> and I<--live> flags may be -specified together if supported by the hypervisor. If this command is run -before the guest has finished booting, the guest may fail to process -the change. - -If I<--current> is specified, affect the current guest state. - -When no flags are given, the I<--live> -flag is assumed and the guest domain must be active. In this situation it -is up to the hypervisor whether the I<--config> flag is also assumed, and -therefore whether the XML configuration is adjusted to make the change -persistent. - -If I<--guest> is specified, then the count of cpus is modified in the guest -instead of the hypervisor. This flag is usable only for live domains -and may require guest agent to be configured in the guest. - -To allow adding vcpus to persistent definitions that can be later hotunplugged -after the domain is booted it is necessary to specify the I<--hotpluggable> -flag. Vcpus added to live domains supporting vcpu unplug are automatically -marked as hotpluggable. - -The I<--maximum> flag controls the maximum number of virtual cpus that can -be hot-plugged the next time the domain is booted. As such, it must only be -used with the I<--config> flag, and not with the I<--live> or the I<--current> -flag. Note that it may not be possible to change the maximum vcpu count if -the processor topology is specified for the guest. - -=item B<setvcpu> I<domain> I<vcpulist> [I<--enable>] | [I<--disable>] -[[I<--live>] [I<--config>] | [I<--current>]] - -Change state of individual vCPUs using hot(un)plug mechanism. - -See B<vcpupin> for information on format of I<vcpulist>. Hypervisor drivers may -require that I<vcpulist> contains exactly vCPUs belonging to one hotpluggable -entity. This is usually just a single vCPU but certain architectures such as -ppc64 require a full core to be specified at once. - -Note that hypervisors may refuse to disable certain vcpus such as vcpu 0 or -others. - -If I<--live> is specified, affect a running domain. -If I<--config> is specified, affect the next startup of a persistent domain. -If I<--current> is specified, affect the current domain state. This is the -default. Both I<--live> and I<--config> flags may be given, but I<--current> is -exclusive. - -=item B<shutdown> I<domain> [I<--mode MODE-LIST>] - -Gracefully shuts down a domain. This coordinates with the domain OS -to perform graceful shutdown, so there is no guarantee that it will -succeed, and may take a variable length of time depending on what -services must be shutdown in the domain. - -The exact behavior of a domain when it shuts down is set by the -I<on_poweroff> parameter in the domain's XML definition. - -If I<domain> is transient, then the metadata of any snapshots and -checkpoints will be lost once the guest stops running, but the underlying -contents still exist, and a new domain with the same name and UUID can -restore the snapshot metadata with B<snapshot-create>, and the checkpoint -metadata with B<checkpoint-create>. - -By default the hypervisor will try to pick a suitable shutdown -method. To specify an alternative method, the I<--mode> parameter -can specify a comma separated list which includes C<acpi>, C<agent>, -C<initctl>, C<signal> and C<paravirt>. The order in which drivers will -try each mode is undefined, and not related to the order specified to virsh. -For strict control over ordering, use a single mode at a time and -repeat the command. - -=item B<start> I<domain-name-or-uuid> [I<--console>] [I<--paused>] -[I<--autodestroy>] [I<--bypass-cache>] [I<--force-boot>] [I<--pass-fds N,M,...>] - -Start a (previously defined) inactive domain, either from the last -B<managedsave> state, or via a fresh boot if no managedsave state is -present. The domain will be paused if the I<--paused> option is -used and supported by the driver; otherwise it will be running. -If I<--console> is requested, attach to the console after creation. -If I<--autodestroy> is requested, then the guest will be automatically -destroyed when virsh closes its connection to libvirt, or otherwise -exits. If I<--bypass-cache> is specified, and managedsave state exists, -the restore will avoid the file system cache, although this may slow -down the operation. If I<--force-boot> is specified, then any -managedsave state is discarded and a fresh boot occurs. - -If I<--pass-fds> is specified, the argument is a comma separated list -of open file descriptors which should be pass on into the guest. The -file descriptors will be re-numbered in the guest, starting from 3. This -is only supported with container based virtualization. - -=item B<suspend> I<domain> - -Suspend a running domain. It is kept in memory but won't be scheduled -anymore. - -=item B<ttyconsole> I<domain> - -Output the device used for the TTY console of the domain. If the information -is not available the processes will provide an exit code of 1. - -=item B<undefine> I<domain> [I<--managed-save>] [I<--snapshots-metadata>] -[I<--checkpoints-metadata>] [I<--nvram>] [I<--keep-nvram>] -[ {I<--storage> B<volumes> | I<--remove-all-storage> -[I<--delete-storage-volume-snapshots>]} I<--wipe-storage>] - -Undefine a domain. If the domain is running, this converts it to a -transient domain, without stopping it. If the domain is inactive, -the domain configuration is removed. - -The I<--managed-save> flag guarantees that any managed save image (see -the B<managedsave> command) is also cleaned up. Without the flag, attempts -to undefine a domain with a managed save image will fail. - -The I<--snapshots-metadata> flag guarantees that any snapshots (see the -B<snapshot-list> command) are also cleaned up when undefining an inactive -domain. Without the flag, attempts to undefine an inactive domain with -snapshot metadata will fail. If the domain is active, this flag is -ignored. - -The I<--checkpoints-metadata> flag guarantees that any checkpoints (see the -B<checkpoint-list> command) are also cleaned up when undefining an inactive -domain. Without the flag, attempts to undefine an inactive domain with -checkpoint metadata will fail. If the domain is active, this flag is -ignored. - -I<--nvram> and I<--keep-nvram> specify accordingly to delete or keep nvram -(/domain/os/nvram/) file. If the domain has an nvram file and the flags are -omitted, the undefine will fail. - -The I<--storage> flag takes a parameter B<volumes>, which is a comma separated -list of volume target names or source paths of storage volumes to be removed -along with the undefined domain. Volumes can be undefined and thus removed only -on inactive domains. Volume deletion is only attempted after the domain is -undefined; if not all of the requested volumes could be deleted, the -error message indicates what still remains behind. If a volume path is not -found in the domain definition, it's treated as if the volume was successfully -deleted. Only volumes managed by libvirt in storage pools can be removed this -way. -(See B<domblklist> for list of target names associated to a domain). -Example: --storage vda,/path/to/storage.img - -The I<--remove-all-storage> flag specifies that all of the domain's storage -volumes should be deleted. - -The I<--delete-storage-volume-snapshots> (previously I<--delete-snapshots>) -flag specifies that any snapshots associated with -the storage volume should be deleted as well. Requires the -I<--remove-all-storage> flag to be provided. Not all storage drivers -support this option, presently only rbd. Using this when also removing volumes -handled by a storage driver which does not support the flag will result in -failure. - -The flag I<--wipe-storage> specifies that the storage volumes should be -wiped before removal. - -NOTE: For an inactive domain, the domain name or UUID must be used as the -I<domain>. - -=item B<vcpucount> I<domain> [{I<--maximum> | I<--active>} -{I<--config> | I<--live> | I<--current>}] [I<--guest>] - -Print information about the virtual cpu counts of the given -I<domain>. If no flags are specified, all possible counts are -listed in a table; otherwise, the output is limited to just the -numeric value requested. For historical reasons, the table -lists the label "current" on the rows that can be queried in isolation -via the I<--active> flag, rather than relating to the I<--current> flag. - -I<--maximum> requests information on the maximum cap of vcpus that a -domain can add via B<setvcpus>, while I<--active> shows the current -usage; these two flags cannot both be specified. I<--config> -requires a persistent domain and requests information regarding the next -time the domain will be booted, I<--live> requires a running domain and -lists current values, and I<--current> queries according to the current -state of the domain (corresponding to I<--live> if running, or -I<--config> if inactive); these three flags are mutually exclusive. - -If I<--guest> is specified, then the count of cpus is reported from -the perspective of the guest. This flag is usable only for live domains -and may require guest agent to be configured in the guest. - -=item B<vcpuinfo> I<domain> [I<--pretty>] - -Returns basic information about the domain virtual CPUs, like the number of -vCPUs, the running time, the affinity to physical processors. - -With I<--pretty>, cpu affinities are shown as ranges. - -An example output is - - $ virsh vcpuinfo fedora - VCPU: 0 - CPU: 0 - State: running - CPU time: 7,0s - CPU Affinity: yyyy - - VCPU: 1 - CPU: 1 - State: running - CPU time: 0,7s - CPU Affinity: yyyy - -B<STATES> - -The State field displays the current operating state of a virtual CPU - -=over 4 - -=item B<offline> - -The virtual CPU is offline and not usable by the domain. -This state is not supported by all hypervisors. - -=item B<running> - -The virtual CPU is available to the domain and is operating. - -=item B<blocked> - -The virtual CPU is available to the domain but is waiting for a resource. -This state is not supported by all hypervisors, in which case I<running> -may be reported instead. - -=item B<no state> - -The virtual CPU state could not be determined. This could happen if -the hypervisor is newer than virsh. - -=item B<N/A> - -There's no information about the virtual CPU state available. This can -be the case if the domain is not running or the hypervisor does -not report the virtual CPU state. - -=back - -=item B<vcpupin> I<domain> [I<vcpu>] [I<cpulist>] [[I<--live>] -[I<--config>] | [I<--current>]] - -Query or change the pinning of domain VCPUs to host physical CPUs. To -pin a single I<vcpu>, specify I<cpulist>; otherwise, you can query one -I<vcpu> or omit I<vcpu> to list all at once. - -I<cpulist> is a list of physical CPU numbers. Its syntax is a comma -separated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2') can -also be allowed. The '-' denotes the range and the '^' denotes exclusive. -For pinning the I<vcpu> to all physical cpus specify 'r' as a I<cpulist>. -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 if I<cpulist> is present, -but I<--current> is exclusive. -If no flag is specified, behavior is different depending on hypervisor. - -B<Note>: The expression is sequentially evaluated, so "0-15,^8" is -identical to "9-14,0-7,15" but not identical to "^8,0-15". - -=item B<vncdisplay> I<domain> - -Output the IP address and port number for the VNC display. If the information -is not available the processes will provide an exit code of 1. - -=back - -=head1 DEVICE COMMANDS - -The following commands manipulate devices associated to domains. -The I<domain> can be specified as a short integer, a name or a full UUID. -To better understand the values allowed as options for the command -reading the documentation at L<https://libvirt.org/formatdomain.html> on the -format of the device sections to get the most accurate set of accepted values. - -=over 4 - -=item B<attach-device> I<domain> I<FILE> -[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]] - -Attach a device to the domain, using a device definition in an XML -file using a device definition element such as <disk> or <interface> -as the top-level element. See the documentation at -L<https://libvirt.org/formatdomain.html#elementsDevices> to learn about -libvirt XML format for a device. If I<--config> is specified the -command alters the persistent domain configuration with the device -attach taking effect the next time libvirt starts the domain. -For cdrom and floppy devices, this command only replaces the media -within an existing device; consider using B<update-device> for this -usage. For passthrough host devices, see also B<nodedev-detach>, -needed if the PCI device does not use managed mode. - -If I<--live> is specified, affect a running domain. -If I<--config> is specified, affect the next startup of a persistent domain. -If I<--current> is specified, affect the current domain state. -Both I<--live> and I<--config> flags may be given, but I<--current> is -exclusive. When no flag is specified legacy API is used whose behavior depends -on the hypervisor driver. - -For compatibility purposes, I<--persistent> behaves like I<--config> for -an offline domain, and like I<--live> I<--config> for a running domain. - -B<Note>: using of partial device definition XML files may lead to unexpected -results as some fields may be autogenerated and thus match devices other than -expected. - -=item B<attach-disk> I<domain> I<source> I<target> [[[I<--live>] [I<--config>] -| [I<--current>]] | [I<--persistent>]] [I<--targetbus bus>] [I<--driver -driver>] [I<--subdriver subdriver>] [I<--iothread iothread>] -[I<--cache cache>] [I<--io io>] [I<--type type>] [I<--alias alias>] -[I<--mode mode>] [I<--sourcetype sourcetype>] [I<--serial serial>] [I<--wwn -wwn>] [I<--rawio>] [I<--address address>] [I<--multifunction>] [I<--print-xml>] - -Attach a new disk device to the domain. -I<source> is path for the files and devices. I<target> controls the bus or -device under which the disk is exposed to the guest OS. It indicates the -"logical" device name; the optional I<targetbus> attribute specifies the type -of disk device to emulate; possible values are driver specific, with typical -values being I<ide>, I<scsi>, I<virtio>, I<xen>, I<usb>, I<sata>, or I<sd>, if -omitted, the bus type is inferred from the style of the device name (e.g. a -device named 'sda' will typically be exported using a SCSI bus). I<driver> can -be I<file>, I<tap> or I<phy> for the Xen -hypervisor depending on the kind of access; or I<qemu> for the QEMU emulator. -Further details to the driver can be passed using I<subdriver>. For Xen -I<subdriver> can be I<aio>, while for QEMU subdriver should match the format -of the disk source, such as I<raw> or I<qcow2>. Hypervisor default will be -used if I<subdriver> is not specified. However, the default may not be -correct, esp. for QEMU as for security reasons it is configured not to detect -disk formats. I<type> can indicate I<lun>, I<cdrom> or I<floppy> as -alternative to the disk default, although this use only replaces the media -within the existing virtual cdrom or floppy device; consider using -B<update-device> for this usage instead. -I<alias> can set user supplied alias. -I<mode> can specify the two specific mode I<readonly> or I<shareable>. -I<sourcetype> can indicate the type of source (block|file) -I<cache> can be one of "default", "none", "writethrough", "writeback", -"directsync" or "unsafe". -I<io> controls specific policies on I/O; QEMU guests support "threads" and "native". -I<iothread> is the number within the range of domain IOThreads to which -this disk may be attached (QEMU only). -I<serial> is the serial of disk device. I<wwn> is the wwn of disk device. -I<rawio> indicates the disk needs rawio capability. -I<address> is the address of disk device in the form of -pci:domain.bus.slot.function, scsi:controller.bus.unit, -ide:controller.bus.unit, usb:bus.port, sata:controller.bus.unit or -ccw:cssid.ssid.devno. Virtio-ccw devices must have their cssid set to 0xfe. -I<multifunction> indicates specified pci address is a multifunction pci device -address. - -If I<--print-xml> is specified, then the XML of the disk that would be attached -is printed instead. - -If I<--live> is specified, affect a running domain. -If I<--config> is specified, affect the next startup of a persistent domain. -If I<--current> is specified, affect the current domain state. -Both I<--live> and I<--config> flags may be given, but I<--current> is -exclusive. When no flag is specified legacy API is used whose behavior depends -on the hypervisor driver. - -For compatibility purposes, I<--persistent> behaves like I<--config> for -an offline domain, and like I<--live> I<--config> for a running domain. -Likewise, I<--shareable> is an alias for I<--mode shareable>. - -=item B<attach-interface> I<domain> I<type> I<source> -[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]] -[I<--target target>] [I<--mac mac>] [I<--script script>] [I<--model model>] -[I<--inbound average,peak,burst,floor>] [I<--outbound average,peak,burst>] -[I<--alias alias>] [I<--managed>] [I<--print-xml>] - -Attach a new network interface to the domain. - -B<type> can be one of the: - -=over 4 - -I<network> to indicate connection via a libvirt virtual network, - -I<bridge> to indicate connection via a bridge device on the host, - -I<direct> to indicate connection directly to one of the host's network -interfaces or bridges, - -I<hostdev> to indicate connection using a passthrough of PCI device -on the host. - -=back - -B<source> indicates the source of the connection. The source depends -on the type of the interface: - -=over 4 - -I<network> name of the virtual network, - -I<bridge> the name of the bridge device, - -I<direct> the name of the host's interface or bridge, - -I<hostdev> the PCI address of the host's interface formatted -as domain:bus:slot.function. - -=back - -B<--target> is used to specify the tap/macvtap device to be used to -connect the domain to the source. Names starting with 'vnet' are -considered as auto-generated and are blanked out/regenerated each -time the interface is attached. - -B<--mac> specifies the MAC address of the network interface; if a MAC -address is not given, a new address will be automatically generated -(and stored in the persistent configuration if "--config" is given on -the command line). - -B<--script> is used to specify a path to a custom script to be called -while attaching to a bridge - this will be called instead of the default -script not in addition to it. This is valid only for interfaces of -I<bridge> type and only for Xen domains. - -B<--model> specifies the network device model to be presented to the -domain. - -B<alias> can set user supplied alias. - -B<--inbound> and B<--outbound> control the bandwidth of the -interface. At least one from the I<average>, I<floor> pair must be -specified. The other two I<peak> and I<burst> are optional, so -"average,peak", "average,,burst", "average,,,floor", "average" and -",,,floor" are also legal. Values for I<average>, I<floor> and I<peak> -are expressed in kilobytes per second, while I<burst> is expressed in -kilobytes in a single burst at I<peak> speed as described in the -Network XML documentation at -L<https://libvirt.org/formatnetwork.html#elementQoS>. - -B<--managed> is usable only for I<hostdev> type and tells libvirt -that the interface should be managed, which means detached and reattached -from/to the host by libvirt. - -If B<--print-xml> is specified, then the XML of the interface that would be -attached is printed instead. - -If B<--live> is specified, affect a running domain. -If B<--config> is specified, affect the next startup of a persistent domain. -If B<--current> is specified, affect the current domain state. -Both B<--live> and B<--config> flags may be given, but B<--current> is -exclusive. When no flag is specified legacy API is used whose behavior -depends on the hypervisor driver. - -For compatibility purposes, B<--persistent> behaves like B<--config> for -an offline domain, and like B<--live> B<--config> for a running domain. - -B<Note>: the optional target value is the name of a device to be created -as the back-end on the node. If not provided a device named "vnetN" or "vifN" -will be created automatically. - -=item B<detach-device> I<domain> I<FILE> -[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]] - -Detach a device from the domain, takes the same kind of XML descriptions -as command B<attach-device>. -For passthrough host devices, see also B<nodedev-reattach>, needed if -the device does not use managed mode. - -B<Note>: The supplied XML description of the device should be as specific -as its definition in the domain XML. The set of attributes used -to match the device are internal to the drivers. Using a partial definition, -or attempting to detach a device that is not present in the domain XML, -but shares some specific attributes with one that is present, -may lead to unexpected results. - -B<Quirk>: Device unplug is asynchronous in most cases and requires guest -cooperation. This means that it's up to the discretion of the guest to disallow -or delay the unplug arbitrarily. As the libvirt API used in this command was -designed as synchronous it returns success after some timeout even if the device -was not unplugged yet to allow further interactions with the domain e.g. if the -guest is unresponsive. Callers which need to make sure that the -device was unplugged can use libvirt events (see virsh event) to be notified -when the device is removed. Note that the event may arrive before the command -returns. - -If I<--live> is specified, affect a running domain. -If I<--config> is specified, affect the next startup of a persistent domain. -If I<--current> is specified, affect the current domain state. -Both I<--live> and I<--config> flags may be given, but I<--current> is -exclusive. When no flag is specified legacy API is used whose behavior depends -on the hypervisor driver. - -For compatibility purposes, I<--persistent> behaves like I<--config> for -an offline domain, and like I<--live> I<--config> for a running domain. - -Note that older versions of virsh used I<--config> as an alias for -I<--persistent>. - -=item B<detach-device-alias> I<domain> I<alias> -[[[I<--live>] [I<--config>] | [I<--current>]]]] - -Detach a device with given I<alias> from the I<domain>. This command returns -successfully after the unplug request was sent to the hypervisor. The actual -removal of the device is notified asynchronously via libvirt events -(see virsh event). - -If I<--live> is specified, affect a running domain. -If I<--config> is specified, affect the next startup of a persistent domain. -If I<--current> is specified, affect the current domain state. -Both I<--live> and I<--config> flags may be given, but I<--current> is -exclusive. - -=item B<detach-disk> I<domain> I<target> -[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]] -[I<--print-xml>] - -Detach a disk device from a domain. The I<target> is the device as seen -from the domain. - -If I<--live> is specified, affect a running domain. -If I<--config> is specified, affect the next startup of a persistent domain. -If I<--current> is specified, affect the current domain state. -Both I<--live> and I<--config> flags may be given, but I<--current> is -exclusive. When no flag is specified legacy API is used whose behavior depends -on the hypervisor driver. - -For compatibility purposes, I<--persistent> behaves like I<--config> for -an offline domain, and like I<--live> I<--config> for a running domain. - -Note that older versions of virsh used I<--config> as an alias for -I<--persistent>. - -If B<--print-xml> is specified, then the XML which would be used to detach the -disk is printed instead. - -Please see documentation for B<detach-device> for known quirks. - -=item B<detach-interface> I<domain> I<type> [I<--mac mac>] -[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]] - -Detach a network interface from a domain. -I<type> can be either I<network> to indicate a physical network device or -I<bridge> to indicate a bridge to a device. It is recommended to use the -I<mac> option to distinguish between the interfaces if more than one are -present on the domain. - -If I<--live> is specified, affect a running domain. -If I<--config> is specified, affect the next startup of a persistent domain. -If I<--current> is specified, affect the current domain state. -Both I<--live> and I<--config> flags may be given, but I<--current> is -exclusive. When no flag is specified legacy API is used whose behavior depends -on the hypervisor driver. - -For compatibility purposes, I<--persistent> behaves like I<--config> for -an offline domain, and like I<--live> I<--config> for a running domain. - -Note that older versions of virsh used I<--config> as an alias for -I<--persistent>. - -Please see documentation for B<detach-device> for known quirks. - -=item B<update-device> I<domain> I<file> [I<--force>] -[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]] - -Update the characteristics of a device associated with I<domain>, -based on the device definition in an XML I<file>. The I<--force> option -can be used to force device update, e.g., to eject a CD-ROM even if it is -locked/mounted in the domain. See the documentation at -L<https://libvirt.org/formatdomain.html#elementsDevices> to learn about -libvirt XML format for a device. - -If I<--live> is specified, affect a running domain. -If I<--config> is specified, affect the next startup of a persistent domain. -If I<--current> is specified, affect the current domain state. -Both I<--live> and I<--config> flags may be given, but I<--current> is -exclusive. Not specifying any flag is the same as specifying I<--current>. - -For compatibility purposes, I<--persistent> behaves like I<--config> for -an offline domain, and like I<--live> I<--config> for a running domain. - -Note that older versions of virsh used I<--config> as an alias for -I<--persistent>. - -B<Note>: using of partial device definition XML files may lead to unexpected -results as some fields may be autogenerated and thus match devices other than -expected. - -=item B<change-media> I<domain> I<path> [I<--eject>] [I<--insert>] -[I<--update>] [I<source>] [I<--force>] [[I<--live>] [I<--config>] | [I<--current>]] -[I<--print-xml>] [I<--block>] - -Change media of CDROM or floppy drive. I<path> can be the fully-qualified path -or the unique target name (<target dev='hdc'>) of the disk device. I<source> -specifies the path of the media to be inserted or updated. The I<--block> flag -allows setting the backing type in case a block device is used as media for the -CDROM or floppy drive instead of a file. - -I<--eject> indicates the media will be ejected. -I<--insert> indicates the media will be inserted. I<source> must be specified. -If the device has source (e.g. <source file='media'>), and I<source> is not -specified, I<--update> is equal to I<--eject>. If the device has no source, -and I<source> is specified, I<--update> is equal to I<--insert>. If the device -has source, and I<source> is specified, I<--update> behaves like combination -of I<--eject> and I<--insert>. -If none of I<--eject>, I<--insert>, and I<--update> is specified, I<--update> -is used by default. -The I<--force> option can be used to force media changing. -If I<--live> is specified, alter live configuration of running guest. -If I<--config> is specified, alter persistent configuration, effect observed -on next boot. -I<--current> can be either or both of I<live> and I<config>, depends on -the hypervisor's implementation. -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. -If I<--print-xml> is specified, the XML that would be used to change media is -printed instead of changing the media. - -=back - -=head1 NODEDEV COMMANDS - -The following commands manipulate host devices that are intended to be -passed through to guest domains via <hostdev> elements in a domain's -<devices> section. A node device key is generally specified by the bus -name followed by its address, using underscores between all components, -such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00. -The B<nodedev-list> gives the full list of host devices that are known -to libvirt, although this includes devices that cannot be assigned to -a guest (for example, attempting to detach the PCI device that controls -the host's hard disk controller where the guest's disk images live could -cause the host system to lock up or reboot). - -For more information on node device definition see: -L<https://libvirt.org/formatnode.html>. - -Passthrough devices cannot be simultaneously used by the host and its -guest domains, nor by multiple active guests at once. If the -<hostdev> description of a PCI device includes the attribute B<managed='yes'>, -and the hypervisor driver supports it, then the device is in managed mode, and -attempts to use that passthrough device in an active guest will -automatically behave as if B<nodedev-detach> (guest start, device -hot-plug) and B<nodedev-reattach> (guest stop, device hot-unplug) were -called at the right points. If a PCI device is not marked as managed, -then it must manually be detached before guests can use it, and manually -reattached to be returned to the host. Also, if a device is manually detached, -then the host does not regain control of the device without a matching -reattach, even if the guests use the device in managed mode. - -=over 4 - -=item B<nodedev-create> I<FILE> - -Create a device on the host node that can then be assigned to virtual -machines. Normally, libvirt is able to automatically determine which -host nodes are available for use, but this allows registration of -host hardware that libvirt did not automatically detect. I<file> -contains xml for a top-level <device> description of a node device. - -=item B<nodedev-destroy> I<device> - -Destroy (stop) a device on the host. I<device> can be either device -name or wwn pair in "wwnn,wwpn" format (only works for vHBA currently). -Note that this makes libvirt quit managing a host device, and may even -make that device unusable by the rest of the physical host until a reboot. - -=item B<nodedev-detach> I<nodedev> [I<--driver backend_driver>] - -Detach I<nodedev> from the host, so that it can safely be used by -guests via <hostdev> passthrough. This is reversed with -B<nodedev-reattach>, and is done automatically for managed devices. - -Different backend drivers expect the device to be bound to different -dummy devices. For example, QEMU's "kvm" backend driver (the default) -expects the device to be bound to pci-stub, but its "vfio" backend -driver expects the device to be bound to vfio-pci. The I<--driver> -parameter can be used to specify the desired backend driver. - -=item B<nodedev-dumpxml> I<device> - -Dump a <device> XML representation for the given node device, including -such information as the device name, which bus owns the device, the -vendor and product id, and any capabilities of the device usable by -libvirt (such as whether device reset is supported). I<device> can -be either device name or wwn pair in "wwnn,wwpn" format (only works -for HBA). - -=item B<nodedev-list> I<cap> I<--tree> - -List all of the devices available on the node that are known by libvirt. -I<cap> is used to filter the list by capability types, the types must be -separated by comma, e.g. --cap pci,scsi. Valid capability types include -'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host', 'scsi_target', -'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic', 'drm', 'mdev', -'mdev_types', 'ccw'. -If I<--tree> is used, the output is formatted in a tree representing parents of each -node. I<cap> and I<--tree> are mutually exclusive. - -=item B<nodedev-reattach> I<nodedev> - -Declare that I<nodedev> is no longer in use by any guests, and that -the host can resume normal use of the device. This is done -automatically for PCI devices in managed mode and USB devices, but -must be done explicitly to match any explicit B<nodedev-detach>. - -=item B<nodedev-reset> I<nodedev> - -Trigger a device reset for I<nodedev>, useful prior to transferring -a node device between guest passthrough or the host. Libvirt will -often do this action implicitly when required, but this command -allows an explicit reset when needed. - -=item B<nodedev-event> {[I<nodedev>] I<event> [I<--loop>] [I<--timeout> -I<seconds>] [I<--timestamp>] | I<--list>} - -Wait for a class of node device events to occur, and print appropriate -details of events as they happen. The events can optionally be filtered -by I<nodedev>. Using I<--list> as the only argument will provide a list -of possible I<event> values known by this client, although the connection -might not allow registering for all these events. - -By default, this command is one-shot, and returns success once an event -occurs; you can send SIGINT (usually via C<Ctrl-C>) to quit immediately. -If I<--timeout> is specified, the command gives up waiting for events -after I<seconds> have elapsed. With I<--loop>, the command prints all -events until a timeout or interrupt key. - -When I<--timestamp> is used, a human-readable timestamp will be printed -before the event. - -=back - -=head1 VIRTUAL NETWORK COMMANDS - -The following commands manipulate networks. Libvirt has the capability to -define virtual networks which can then be used by domains and linked to -actual network devices. For more detailed information about this feature -see the documentation at L<https://libvirt.org/formatnetwork.html> . Many -of the commands for virtual networks are similar to the ones used for domains, -but the way to name a virtual network is either by its name or UUID. - -=over 4 - -=item B<net-autostart> I<network> [I<--disable>] - -Configure a virtual network to be automatically started at boot. -The I<--disable> option disable autostarting. - -=item B<net-create> I<file> - -Create a transient (temporary) virtual network from an -XML I<file> and instantiate (start) the network. -See the documentation at L<https://libvirt.org/formatnetwork.html> -to get a description of the XML network format used by libvirt. - -=item B<net-define> I<file> - -Define an inactive persistent virtual network or modify an existing persistent -one from the XML I<file>. - -=item B<net-destroy> I<network> - -Destroy (stop) a given transient or persistent virtual network -specified by its name or UUID. This takes effect immediately. - -=item B<net-dumpxml> I<network> [I<--inactive>] - -Output the virtual network information as an XML dump to stdout. -If I<--inactive> is specified, then physical functions are not -expanded into their associated virtual functions. - -=item B<net-edit> I<network> - -Edit the XML configuration file for a network. - -This is equivalent to: - - virsh net-dumpxml --inactive network > network.xml - vi network.xml (or make changes with your other text editor) - virsh net-define network.xml - -except that it does some error checking. - -The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment -variables, and defaults to C<vi>. - -=item B<net-event> {[I<network>] I<event> [I<--loop>] [I<--timeout> -I<seconds>] [I<--timestamp>] | I<--list>} - -Wait for a class of network events to occur, and print appropriate details -of events as they happen. The events can optionally be filtered by -I<network>. Using I<--list> as the only argument will provide a list -of possible I<event> values known by this client, although the connection -might not allow registering for all these events. - -By default, this command is one-shot, and returns success once an event -occurs; you can send SIGINT (usually via C<Ctrl-C>) to quit immediately. -If I<--timeout> is specified, the command gives up waiting for events -after I<seconds> have elapsed. With I<--loop>, the command prints all -events until a timeout or interrupt key. - -When I<--timestamp> is used, a human-readable timestamp will be printed -before the event. - -=item B<net-info> I<network> - -Returns basic information about the I<network> object. - -=item B<net-list> [I<--inactive> | I<--all>] - { [I<--table>] | I<--name> | I<--uuid> } - [I<--persistent>] [<--transient>] - [I<--autostart>] [<--no-autostart>] - -Returns the list of active networks, if I<--all> is specified this will also -include defined but inactive networks, if I<--inactive> is specified only the -inactive ones will be listed. You may also want to filter the returned networks -by I<--persistent> to list the persistent ones, I<--transient> to list the -transient ones, I<--autostart> to list the ones with autostart enabled, and -I<--no-autostart> to list the ones with autostart disabled. - -If I<--name> is specified, network names are printed instead of the table -formatted one per line. If I<--uuid> is specified network's UUID's are printed -instead of names. Flag I<--table> specifies that the legacy table-formatted -output should be used. This is the default. All of these are mutually -exclusive. - -NOTE: When talking to older servers, this command is forced to use a series of -API calls with an inherent race, where a pool might not be listed or might appear -more than once if it changed state between calls while the list was being -collected. Newer servers do not have this problem. - -=item B<net-name> I<network-UUID> - -Convert a network UUID to network name. - -=item B<net-start> I<network> - -Start a (previously defined) inactive network. - -=item B<net-undefine> I<network> - -Undefine the configuration for a persistent network. If the network is active, -make it transient. - -=item B<net-uuid> I<network-name> - -Convert a network name to network UUID. - -=item B<net-update> I<network> I<command> I<section> I<xml> - [I<--parent-index> I<index>] [[I<--live>] [I<--config>] | [I<--current>]] - -Update the given section of an existing network definition, with the -changes optionally taking effect immediately, without needing to -destroy and re-start the network. - -I<command> is one of "add-first", "add-last", "add" (a synonym for -add-last), "delete", or "modify". - -I<section> is one of "bridge", "domain", "ip", "ip-dhcp-host", -"ip-dhcp-range", "forward", "forward-interface", "forward-pf", -"portgroup", "dns-host", "dns-txt", or "dns-srv", each section being -named by a concatenation of the xml element hierarchy leading to the -element being changed. For example, "ip-dhcp-host" will change a -<host> element that is contained inside a <dhcp> element inside an -<ip> element of the network. - -I<xml> is either the text of a complete xml element of the type being -changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the -name of a file that contains a complete xml element. Disambiguation is -done by looking at the first character of the provided text - if the -first character is "<", it is xml text, if the first character is not -"<", it is the name of a file that contains the xml text to be used. - -The I<--parent-index> option is used to specify which of several -parent elements the requested element is in (0-based). For example, a -dhcp <host> element could be in any one of multiple <ip> elements in -the network; if a parent-index isn't provided, the "most appropriate" -<ip> element will be selected (usually the only one that already has a -<dhcp> element), but if I<--parent-index> is given, that particular -instance of <ip> will get the modification. - -If I<--live> is specified, affect a running network. -If I<--config> is specified, affect the next startup of a persistent network. -If I<--current> is specified, affect the current network state. -Both I<--live> and I<--config> flags may be given, but I<--current> is -exclusive. Not specifying any flag is the same as specifying I<--current>. - -=item B<net-dhcp-leases> I<network> [I<mac>] - -Get a list of dhcp leases for all network interfaces connected to the given -virtual I<network> or limited output just for one interface if I<mac> is -specified. - -=back - -=head1 NETWORK PORT COMMANDS - -The following commands manipulate network ports. Libvirt virtual networks -have ports created when a virtual machine has a virtual network interface -added. In general there should be no need to use any of the commands -here, since the hypervisor drivers run these commands are the right -point in a virtual machine's lifecycle. They can be useful for debugging -problems and / or recovering from bugs / stale state. - -=over 4 - -=item B<net-port-list> { [I<--table>] | I<--uuid> } - I<network> - -List all network ports recorded against the network. - -If I<--uuid> is specified network ports' UUID's are printed -instead of a table. Flag I<--table> specifies that the legacy -table-formatted output should be used. This is the default. -All of these are mutually exclusive. - -=item B<net-port-create> I<network> I<file> - -Allocate a new network port reserving resources based on the -port description. - -=item B<net-port-dumpxml> I<network> I<port> - -Output the network port information as an XML dump to stdout. - -=item B<net-port-delete> I<network> I<port> - -Delete record of the network port and release its resources - -=back - -=head1 INTERFACE COMMANDS - -The following commands manipulate host interfaces. Often, these host -interfaces can then be used by name within domain <interface> elements -(such as a system-created bridge interface), but there is no -requirement that host interfaces be tied to any particular guest -configuration XML at all. - -Many of the commands for host interfaces are similar to the ones used -for domains, and the way to name an interface is either by its name or -its MAC address. However, using a MAC address for an I<iface> -argument only works when that address is unique (if an interface and a -bridge share the same MAC address, which is often the case, then using -that MAC address results in an error due to ambiguity, and you must -resort to a name instead). - -=over 4 - -=item B<iface-bridge> I<interface> I<bridge> [I<--no-stp>] [I<delay>] -[I<--no-start>] - -Create a bridge device named I<bridge>, and attach the existing -network device I<interface> to the new bridge. The new bridge -defaults to starting immediately, with STP enabled and a delay of 0; -these settings can be altered with I<--no-stp>, I<--no-start>, and an -integer number of seconds for I<delay>. All IP address configuration -of I<interface> will be moved to the new bridge device. - -See also B<iface-unbridge> for undoing this operation. - -=item B<iface-define> I<file> - -Define an inactive persistent physical host interface or modify an existing -persistent one from the XML I<file>. - -=item B<iface-destroy> I<interface> - -Destroy (stop) a given host interface, such as by running "if-down" to -disable that interface from active use. This takes effect immediately. - -=item B<iface-dumpxml> I<interface> [I<--inactive>] - -Output the host interface information as an XML dump to stdout. If -I<--inactive> is specified, then the output reflects the persistent -state of the interface that will be used the next time it is started. - -=item B<iface-edit> I<interface> - -Edit the XML configuration file for a host interface. - -This is equivalent to: - - virsh iface-dumpxml iface > iface.xml - vi iface.xml (or make changes with your other text editor) - virsh iface-define iface.xml - -except that it does some error checking. - -The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment -variables, and defaults to C<vi>. - -=item B<iface-list> [I<--inactive> | I<--all>] - -Returns the list of active host interfaces. If I<--all> is specified -this will also include defined but inactive interfaces. If -I<--inactive> is specified only the inactive ones will be listed. - -=item B<iface-name> I<interface> - -Convert a host interface MAC to interface name, if the MAC address is unique -among the host's interfaces. - -I<interface> specifies the interface MAC address. - -=item B<iface-mac> I<interface> - -Convert a host interface name to MAC address. - -I<interface> specifies the interface name. - -=item B<iface-start> I<interface> - -Start a (previously defined) host interface, such as by running "if-up". - -=item B<iface-unbridge> I<bridge> [I<--no-start>] - -Tear down a bridge device named I<bridge>, releasing its underlying -interface back to normal usage, and moving all IP address -configuration from the bridge device to the underlying device. The -underlying interface is restarted unless I<--no-start> is present; -this flag is present for symmetry, but generally not recommended. - -See also B<iface-bridge> for creating a bridge. - -=item B<iface-undefine> I<interface> - -Undefine the configuration for an inactive host interface. - -=item B<iface-begin> - -Create a snapshot of current host interface settings, which can later -be committed (I<iface-commit>) or restored (I<iface-rollback>). If a -snapshot already exists, then this command will fail until the -previous snapshot has been committed or restored. Undefined behavior -results if any external changes are made to host interfaces outside of -the libvirt API between the beginning of a snapshot and its eventual -commit or rollback. - -=item B<iface-commit> - -Declare all changes since the last I<iface-begin> as working, and -delete the rollback point. If no interface snapshot has already been -started, then this command will fail. - -=item B<iface-rollback> - -Revert all host interface settings back to the state recorded in the -last I<iface-begin>. If no interface snapshot has already been -started, then this command will fail. Rebooting the host also serves -as an implicit rollback point. - -=back - -=head1 STORAGE POOL COMMANDS - -The following commands manipulate storage pools. Libvirt has the -capability to manage various storage solutions, including files, raw -partitions, and domain-specific formats, used to provide the storage -volumes visible as devices within virtual machines. For more detailed -information about this feature, see the documentation at -L<https://libvirt.org/formatstorage.html> . Many of the commands for -pools are similar to the ones used for domains. - -=over 4 - -=item B<find-storage-pool-sources> I<type> [I<srcSpec>] - -Returns XML describing all possible available storage pool sources that -could be used to create or define a storage pool of a given I<type>. If -I<srcSpec> is provided, it is a file that contains XML to further restrict -the query for pools. - -Not all storage pools support discovery in this manner. Furthermore, for -those that do support discovery, only specific XML elements are required -in order to return valid data, while other elements and even attributes -of some elements are ignored since they are not necessary to find the pool -based on the search criteria. The following lists the supported I<type> -options and the expected minimal XML elements used to perform the search. - -For a "netfs" or "gluster" pool, the minimal expected XML required is the -<host> element with a "name" attribute describing the IP address or hostname -to be used to find the pool. The "port" attribute will be ignored as will -any other provided XML elements in I<srcSpec>. - -For a "logical" pool, the contents of the I<srcSpec> file are ignored, -although if provided the file must at least exist. - -For an "iscsi" pool, the minimal expect XML required is the <host> element -with a "name" attribute describing the IP address or hostname to be used to -find the pool (the iSCSI server address). Optionally, the "port" attribute -may be provided, although it will default to 3260. Optionally, an <initiator> -XML element with a "name" attribute may be provided to further restrict the -iSCSI target search to a specific initiator for multi-iqn iSCSI storage pools. - -=item B<find-storage-pool-sources-as> I<type> [I<host>] [I<port>] -[I<initiator>] - -Rather than providing I<srcSpec> XML file for B<find-storage-pool-sources> -use this command option in order to have virsh generate the query XML file -using the optional arguments. The command will return the same output -XML as B<find-storage-pool-sources>. - -Use I<host> to describe a specific host to use for networked storage, such -as netfs, gluster, and iscsi I<type> pools. - -Use I<port> to further restrict which networked port to utilize for the -connection if required by the specific storage backend, such as iscsi. - -Use I<initiator> to further restrict the iscsi I<type> pool searches to -specific target initiators. - -=item B<pool-autostart> I<pool-or-uuid> [I<--disable>] - -Configure whether I<pool> should automatically start at boot. - -=item B<pool-build> I<pool-or-uuid> [I<--overwrite>] [I<--no-overwrite>] - -Build a given pool. - -Options I<--overwrite> and I<--no-overwrite> can only be used for -B<pool-build> a filesystem, disk, or logical pool. - -For a file system pool if neither flag is specified, then B<pool-build> -just makes the target path directory and no attempt to run mkfs on the -target volume device. If I<--no-overwrite> is specified, it probes to -determine if a filesystem already exists on the target device, returning -an error if one exists or using mkfs to format the target device if not. -If I<--overwrite> is specified, mkfs is always executed and any existing -data on the target device is overwritten unconditionally. - -For a disk pool, if neither of them is specified or I<--no-overwrite> -is specified, B<pool-build> will check the target volume device for -existing filesystems or partitions before attempting to write a new -label on the target volume device. If the target volume device already -has a label, the command will fail. If I<--overwrite> is specified, -then no check will be made on the target volume device prior to writing -a new label. Writing of the label uses the pool source format type -or "dos" if not specified. - -For a logical pool, if neither of them is specified or I<--no-overwrite> -is specified, B<pool-build> will check the target volume devices for -existing filesystems or partitions before attempting to initialize -and format each device for usage by the logical pool. If any target -volume device already has a label, the command will fail. If -I<--overwrite> is specified, then no check will be made on the target -volume devices prior to initializing and formatting each device. Once -all the target volume devices are properly formatted via pvcreate, -the volume group will be created using all the devices. - -=item B<pool-create> I<file> -[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] - -Create and start a pool object from the XML I<file>. - -[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] perform a -B<pool-build> after creation in order to remove the need for a -follow-up command to build the pool. The I<--overwrite> and -I<--no-overwrite> flags follow the same rules as B<pool-build>. If -just I<--build> is provided, then B<pool-build> is called with no flags. - -=item B<pool-create-as> I<name> I<type> -[I<--source-host hostname>] [I<--source-path path>] [I<--source-dev path>] -[I<--source-name name>] [I<--target path>] [I<--source-format format>] -[I<--auth-type authtype> I<--auth-username username> -[I<--secret-usage usage> | I<--secret-uuid uuid>]] -[I<--source-protocol-ver ver>] -[[I<--adapter-name name>] | [I<--adapter-wwnn> wwnn I<--adapter-wwpn> wwpn] -[I<--adapter-parent parent> | - I<--adapter-parent-wwnn parent_wwnn> I<adapter-parent-wwpn parent_wwpn> | - I<--adapter-parent-fabric-wwn parent_fabric_wwn>]] -[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] [I<--print-xml>] - - -Create and start a pool object I<name> from the raw parameters. If -I<--print-xml> is specified, then print the XML of the pool object -without creating the pool. Otherwise, the pool has the specified -I<type>. When using B<pool-create-as> for a pool of I<type> "disk", -the existing partitions found on the I<--source-dev path> will be used -to populate the disk pool. Therefore, it is suggested to use -B<pool-define-as> and B<pool-build> with the I<--overwrite> in order -to properly initialize the disk pool. - -[I<--source-host hostname>] provides the source hostname for pools backed -by storage from a remote server (pool types netfs, iscsi, rbd, sheepdog, -gluster). - -[I<--source-path path>] provides the source directory path for pools backed -by directories (pool type dir). - -[I<--source-dev path>] provides the source path for pools backed by physical -devices (pool types fs, logical, disk, iscsi, zfs). - -[I<--source-name name>] provides the source name for pools backed by storage -from a named element (pool types logical, rbd, sheepdog, gluster). - -[I<--target path>] is the path for the mapping of the storage pool into -the host file system. - -[I<--source-format format>] provides information about the format of the -pool (pool types fs, netfs, disk, logical). - -[I<--auth-type authtype> I<--auth-username username> -[I<--secret-usage usage> | I<--secret-uuid uuid>]] -provides the elements required to generate authentication credentials for -the storage pool. The I<authtype> is either chap for iscsi I<type> pools or -ceph for rbd I<type> pools. Either the secret I<usage> or I<uuid> value may -be provided, but not both. - -[I<--source-protocol-ver ver>] provides the NFS protocol version number used -to contact the server's NFS service via nfs mount option 'nfsvers=n'. It is -expect the I<ver> value is an unsigned integer. - -[I<--adapter-name name>] defines the scsi_hostN adapter name to be used for -the scsi_host adapter type pool. - -[I<--adapter-wwnn wwnn> I<--adapter-wwpn wwpn> [I<--adapter-parent parent> | -I<--adapter-parent-wwnn parent_wwnn> I<adapter-parent-wwpn parent_wwpn> | -I<--adapter-parent-fabric-wwn parent_fabric_wwn>]] -defines the wwnn and wwpn to be used for the fc_host adapter type pool. -Optionally provide the parent scsi_hostN node device to be used for the -vHBA either by parent name, parent_wwnn and parent_wwpn, or parent_fabric_wwn. -The parent name could change between reboots if the hardware environment -changes, so providing the parent_wwnn and parent_wwpn ensure usage of the -same physical HBA even if the scsi_hostN node device changes. Usage of the -parent_fabric_wwn allows a bit more flexibility to choose an HBA on the -same storage fabric in order to define the pool. - -[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] perform a -B<pool-build> after creation in order to remove the need for a -follow-up command to build the pool. The I<--overwrite> and -I<--no-overwrite> flags follow the same rules as B<pool-build>. If -just I<--build> is provided, then B<pool-build> is called with no flags. - -For a "logical" pool only [I<--name>] needs to be provided. The -[I<--source-name>] if provided must match the Volume Group name. -If not provided, one will be generated using the [I<--name>]. If -provided the [I<--target>] is ignored and a target source is generated -using the [I<--source-name>] (or as generated from the [I<--name>]). - -=item B<pool-define> I<file> - -Define an inactive persistent storage pool or modify an existing persistent one -from the XML I<file>. - -=item B<pool-define-as> I<name> I<type> -[I<--source-host hostname>] [I<--source-path path>] [I<--source-dev path>] -[I<--source-name name>] [I<--target path>] [I<--source-format format>] -[I<--auth-type authtype> I<--auth-username username> -[I<--secret-usage usage> | I<--secret-uuid uuid>]] -[I<--source-protocol-ver ver>] -[[I<--adapter-name name>] | [I<--adapter-wwnn> I<--adapter-wwpn>] -[I<--adapter-parent parent>]] [I<--print-xml>] - -Create, but do not start, a pool object I<name> from the raw parameters. If -I<--print-xml> is specified, then print the XML of the pool object -without defining the pool. Otherwise, the pool has the specified -I<type>. - -Use the same arguments as B<pool-create-as>, except for the I<--build>, -I<--overwrite>, and I<--no-overwrite> options. - -=item B<pool-destroy> I<pool-or-uuid> - -Destroy (stop) a given I<pool> object. Libvirt will no longer manage the -storage described by the pool object, but the raw data contained in -the pool is not changed, and can be later recovered with -B<pool-create>. - -=item B<pool-delete> I<pool-or-uuid> - -Destroy the resources used by a given I<pool> object. This operation -is non-recoverable. The I<pool> object will still exist after this -command, ready for the creation of new storage volumes. - -=item B<pool-dumpxml> [I<--inactive>] I<pool-or-uuid> - -Returns the XML information about the I<pool> object. -I<--inactive> tells virsh to dump pool configuration that will be used -on next start of the pool as opposed to the current pool configuration. - -=item B<pool-edit> I<pool-or-uuid> - -Edit the XML configuration file for a storage pool. - -This is equivalent to: - - virsh pool-dumpxml pool > pool.xml - vi pool.xml (or make changes with your other text editor) - virsh pool-define pool.xml - -except that it does some error checking. - -The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment -variables, and defaults to C<vi>. - -=item B<pool-info> [I<--bytes>] I<pool-or-uuid> - -Returns basic information about the I<pool> object. If I<--bytes> is specified the sizes -of basic info are not converted to human friendly units. - -=item B<pool-list> [I<--inactive>] [I<--all>] - [I<--persistent>] [I<--transient>] - [I<--autostart>] [I<--no-autostart>] - [[I<--details>] [I<--uuid>] - [I<--name>] [<type>] - -List pool objects known to libvirt. By default, only active pools -are listed; I<--inactive> lists just the inactive pools, and I<--all> -lists all pools. - -In addition, there are several sets of filtering flags. I<--persistent> is to -list the persistent pools, I<--transient> is to list the transient pools. -I<--autostart> lists the autostarting pools, I<--no-autostart> lists the pools -with autostarting disabled. If I<--uuid> is specified only pool's UUIDs are printed. -If I<--name> is specified only pool's names are printed. If both I<--name> -and I<--uuid> are specified, pool's UUID and names are printed side by side -without any header. Option I<--details> is mutually exclusive with options -I<--uuid> and I<--name>. - -You may also want to list pools with specified types using I<type>, the -pool types must be separated by comma, e.g. --type dir,disk. The valid pool -types include 'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi', 'scsi', -'mpath', 'rbd', 'sheepdog', 'gluster', 'zfs', 'vstorage' and 'iscsi-direct'. - -The I<--details> option instructs virsh to additionally -display pool persistence and capacity related information where available. - -NOTE: When talking to older servers, this command is forced to use a series of -API calls with an inherent race, where a pool might not be listed or might appear -more than once if it changed state between calls while the list was being -collected. Newer servers do not have this problem. - -=item B<pool-name> I<uuid> - -Convert the I<uuid> to a pool name. - -=item B<pool-refresh> I<pool-or-uuid> - -Refresh the list of volumes contained in I<pool>. - -=item B<pool-start> I<pool-or-uuid> -[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] - -Start the storage I<pool>, which is previously defined but inactive. - -[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] perform a -B<pool-build> prior to B<pool-start> to ensure the pool environment is -in an expected state rather than needing to run the build command prior -to startup. The I<--overwrite> and I<--no-overwrite> flags follow the -same rules as B<pool-build>. If just I<--build> is provided, then -B<pool-build> is called with no flags. - -B<Note>: A storage pool that relies on remote resources such as an -"iscsi" or a (v)HBA backed "scsi" pool may need to be refreshed multiple -times in order to have all the volumes detected (see B<pool-refresh>). -This is because the corresponding volume devices may not be present in -the host's filesystem during the initial pool startup or the current -refresh attempt. The number of refresh retries is dependent upon the -network connection and the time the host takes to export the -corresponding devices. - -=item B<pool-undefine> I<pool-or-uuid> - -Undefine the configuration for an inactive I<pool>. - -=item B<pool-uuid> I<pool> - -Returns the UUID of the named I<pool>. - -=item B<pool-event> {[I<pool>] I<event> [I<--loop>] [I<--timeout> -I<seconds>] [I<--timestamp>] | I<--list>} - -Wait for a class of storage pool events to occur, and print appropriate -details of events as they happen. The events can optionally be filtered -by I<pool>. Using I<--list> as the only argument will provide a list -of possible I<event> values known by this client, although the connection -might not allow registering for all these events. - -By default, this command is one-shot, and returns success once an event -occurs; you can send SIGINT (usually via C<Ctrl-C>) to quit immediately. -If I<--timeout> is specified, the command gives up waiting for events -after I<seconds> have elapsed. With I<--loop>, the command prints all -events until a timeout or interrupt key. - -When I<--timestamp> is used, a human-readable timestamp will be printed -before the event. - -=back - -=head1 VOLUME COMMANDS - -=over 4 - -=item B<vol-create> I<pool-or-uuid> I<FILE> [I<--prealloc-metadata>] - -Create a volume from an XML <file>. - -I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in. - -I<FILE> is the XML <file> with the volume definition. An easy way to create the -XML <file> is to use the B<vol-dumpxml> command to obtain the definition of a -pre-existing volume. - -[I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't -support full allocation). This option creates a sparse image file with metadata, -resulting in higher performance compared to images with no preallocation and -only slightly higher initial disk space usage. - -B<Example> - - virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml - vi newvolume.xml (or make changes with your other text editor) - virsh vol-create differentstoragepool newvolume.xml - -=item B<vol-create-from> I<pool-or-uuid> I<FILE> I<vol-name-or-key-or-path> -[I<--inputpool> I<pool-or-uuid>] [I<--prealloc-metadata>] [I<--reflink>] - -Create a volume, using another volume as input. - -I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in. - -I<FILE> is the XML <file> with the volume definition. - -I<vol-name-or-key-or-path> is the name or key or path of the source volume. - -I<--inputpool> I<pool-or-uuid> is the name or uuid of the storage pool the -source volume is in. - -[I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't -support full allocation). This option creates a sparse image file with metadata, -resulting in higher performance compared to images with no preallocation and -only slightly higher initial disk space usage. - -When I<--reflink> is specified, perform a COW lightweight copy, -where the data blocks are copied only when modified. -If this is not possible, the copy fails. - -=item B<vol-create-as> I<pool-or-uuid> I<name> I<capacity> -[I<--allocation> I<size>] [I<--format> I<string>] -[I<--backing-vol> I<vol-name-or-key-or-path>] -[I<--backing-vol-format> I<string>] [I<--prealloc-metadata>] [I<--print-xml>] - -Create a volume from a set of arguments unless I<--print-xml> is specified, in -which case just the XML of the volume object is printed out without any actual -object creation. - -I<pool-or-uuid> is the name or UUID of the storage pool to create the volume -in. - -I<name> is the name of the new volume. For a disk pool, this must match the -partition name as determined from the pool's source device path and the next -available partition. For example, a source device path of /dev/sdb and there -are no partitions on the disk, then the name must be sdb1 with the next -name being sdb2 and so on. - -I<capacity> is the size of the volume to be created, as a scaled integer -(see B<NOTES> above), defaulting to bytes if there is no suffix. - -I<--allocation> I<size> is the initial size to be allocated in the volume, -also as a scaled integer defaulting to bytes. - -I<--format> I<string> is used in file based storage pools to specify the volume -file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use extended for disk -storage pools in order to create an extended partition (other values are -validity checked but not preserved when libvirtd is restarted or the pool -is refreshed). - -I<--backing-vol> I<vol-name-or-key-or-path> is the source backing -volume to be used if taking a snapshot of an existing volume. - -I<--backing-vol-format> I<string> is the format of the snapshot backing volume; -raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, however, meant for -file based storage pools. - -[I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't -support full allocation). This option creates a sparse image file with metadata, -resulting in higher performance compared to images with no preallocation and -only slightly higher initial disk space usage. - -=item B<vol-clone> I<vol-name-or-key-or-path> I<name> -[I<--pool> I<pool-or-uuid>] [I<--prealloc-metadata>] [I<--reflink>] - -Clone an existing volume within the parent pool. Less powerful, -but easier to type, version of B<vol-create-from>. - -I<vol-name-or-key-or-path> is the name or key or path of the source volume. - -I<name> is the name of the new volume. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool -that contains the source volume and will contain the new volume. -If the source volume name is provided instead of the key or path, then -providing the pool is necessary to find the volume to be cloned; otherwise, -the first volume found by the key or path will be used. - -[I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't -support full allocation). This option creates a sparse image file with metadata, -resulting in higher performance compared to images with no preallocation and -only slightly higher initial disk space usage. - -When I<--reflink> is specified, perform a COW lightweight copy, -where the data blocks are copied only when modified. -If this is not possible, the copy fails. - -=item B<vol-delete> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>] -[I<--delete-snapshots>] - -Delete a given volume. - -I<vol-name-or-key-or-path> is the volume name or key or path of the volume -to delete. - -[I<--pool> I<pool-or-uuid>] is the name or UUID of the storage pool the volume -is in. If the volume name is provided instead of the key or path, then -providing the pool is necessary to find the volume to be deleted; otherwise, -the first volume found by the key or path will be used. - -The I<--delete-snapshots> flag specifies that any snapshots associated with -the storage volume should be deleted as well. Not all storage drivers -support this option, presently only rbd. - -=item B<vol-upload> I<vol-name-or-key-or-path> I<local-file> -[I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>] -[I<--length> I<bytes>] [I<--sparse>] - -Upload the contents of I<local-file> to a storage volume. - -I<vol-name-or-key-or-path> is the name or key or path of the volume where the -I<local-file> will be uploaded. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. If the volume name is provided instead of the key or path, then -providing the pool is necessary to find the volume to be uploaded into; -otherwise, the first volume found by the key or path will be used. - -I<--offset> is the position in the storage volume at which to start writing -the data. The value must be 0 or larger. - -I<--length> is an upper bound of the amount of data to be uploaded. -A negative value is interpreted as an unsigned long long value to -essentially include everything from the offset to the end of the volume. - -If I<--sparse> is specified, this command will preserve volume sparseness. - -An error will occur if the I<local-file> is greater than the specified -I<length>. - -See the description for the libvirt virStorageVolUpload API for details -regarding possible target volume and pool changes as a result of the -pool refresh when the upload is attempted. - -=item B<vol-download> I<vol-name-or-key-or-path> I<local-file> -[I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>] [I<--length> I<bytes>] -[I<--sparse>] - -Download the contents of a storage volume to I<local-file>. - -I<vol-name-or-key-or-path> is the name or key or path of the volume to -download into I<local-file>. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. If the volume name is provided instead of the key or path, then -providing the pool is necessary to find the volume to be uploaded into; -otherwise, the first volume found by the key or path will be used. - -I<--offset> is the position in the storage volume at which to start reading -the data. The value must be 0 or larger. - -I<--length> is an upper bound of the amount of data to be downloaded. -A negative value is interpreted as an unsigned long long value to -essentially include everything from the offset to the end of the volume. - -If I<--sparse> is specified, this command will preserve volume sparseness. - -=item B<vol-wipe> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>] -[I<--algorithm> I<algorithm>] - -Wipe a volume, ensure data previously on the volume is not accessible to -future reads. - -I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe. -It is possible to choose different wiping algorithms instead of re-writing -volume with zeroes. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the -volume is in. If the volume name is provided instead of the key or path, -then providing the pool is necessary to find the volume to be wiped; -otherwise, the first volume found by the key or path will be used. - -Use the I<--algorithm> switch choosing from the list of the following -algorithms in order to define which algorithm to use for the wipe. - -B<Supported algorithms> - zero - 1-pass all zeroes - nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for - sanitizing removable and non-removable hard disks: - random x2, 0x00, verify. - dod - 4-pass DoD 5220.22-M section 8-306 procedure for - sanitizing removable and non-removable rigid - disks: random, 0x00, 0xff, verify. - bsi - 9-pass method recommended by the German Center of - Security in Information Technologies - (http://www.bsi.bund.de): 0xff, 0xfe, 0xfd, 0xfb, - 0xf7, 0xef, 0xdf, 0xbf, 0x7f. - gutmann - The canonical 35-pass sequence described in - Gutmann's paper. - schneier - 7-pass method described by Bruce Schneier in - "Applied Cryptography" (1996): 0x00, 0xff, - random x5. - pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7. - pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33. - random - 1-pass pattern: random. - trim - 1-pass trimming the volume using TRIM or DISCARD - -B<Note>: The C<scrub> binary will be used to handle the 'nnsa', 'dod', -'bsi', 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33' algorithms. -The availability of the algorithms may be limited by the version of -the C<scrub> binary installed on the host. The 'zero' algorithm will -write zeroes to the entire volume. For some volumes, such as sparse -or rbd volumes, this may result in completely filling the volume with -zeroes making it appear to be completely full. As an alternative, the -'trim' algorithm does not overwrite all the data in a volume, rather -it expects the storage driver to be able to discard all bytes in a -volume. It is up to the storage driver to handle how the discarding -occurs. Not all storage drivers or volume types can support 'trim'. - -=item B<vol-dumpxml> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>] - -Output the volume information as an XML dump to stdout. - -I<vol-name-or-key-or-path> is the name or key or path of the volume -to output the XML. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. If the volume name is provided instead of the key or path, then -providing the pool is necessary to find the volume to be uploaded into; -otherwise, the first volume found by the key or path will be used. - -=item B<vol-info> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>] -[I<--bytes>] [I<--physical>] - -Returns basic information about the given storage volume. - -I<vol-name-or-key-or-path> is the name or key or path of the volume -to return information for. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. If the volume name is provided instead of the key or path, then -providing the pool is necessary to find the volume to be uploaded into; -otherwise, the first volume found by the key or path will be used. - -If I<--bytes> is specified the sizes are not converted to human friendly -units. - -If I<--physical> is specified, then the host physical size is returned -and displayed instead of the allocation value. The physical value for -some file types, such as qcow2 may have a different (larger) physical -value than is shown for allocation. Additionally sparse files will -have different physical and allocation values. - -=item B<vol-list> [I<--pool> I<pool-or-uuid>] [I<--details>] - -Return the list of volumes in the given storage pool. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool. - -The I<--details> option instructs virsh to additionally display volume -type and capacity related information where available. - -=item B<vol-pool> I<vol-key-or-path> [I<--uuid>] - -Return the pool name or UUID for a given volume. By default, the pool name is -returned. - -I<vol-key-or-path> is the key or path of the volume to return the pool -information. - -If the I<--uuid> option is given, the pool UUID is returned instead. - -=item B<vol-path> I<vol-name-or-key> [I<--pool> I<pool-or-uuid>] - -Return the path for a given volume. - -I<vol-name-or-key> is the name or key of the volume to return the path. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. If the volume name is provided instead of the key, then providing -the pool is necessary to find the volume to be uploaded into; otherwise, -the first volume found by the key will be used. - -=item B<vol-name> I<vol-key-or-path> - -Return the name for a given volume. - -I<vol-key-or-path> is the key or path of the volume to return the name. - -=item B<vol-key> I<vol-name-or-path> [I<--pool> I<pool-or-uuid>] - -Return the volume key for a given volume. - -I<vol-name-or-path> is the name or path of the volume to return the -volume key. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. If the volume name is provided instead of the path, then providing -the pool is necessary to find the volume to be uploaded into; otherwise, -the first volume found by the path will be used. - -=item B<vol-resize> I<vol-name-or-path> I<capacity> [I<--pool> I<pool-or-uuid>] -[I<--allocate>] [I<--delta>] [I<--shrink>] - -Resize the capacity of the given volume, in bytes. - -I<vol-name-or-key-or-path> is the name or key or path of the volume -to resize. - -I<capacity> is a scaled integer (see B<NOTES> above) for the volume, -which defaults to bytes if there is no suffix. - -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. If the volume name is provided instead of the key or path, then -providing the pool is necessary to find the volume to be uploaded into; -otherwise, the first volume found by the key or path will be used. - -The new I<capacity> might be sparse unless I<--allocate> is specified. - -Normally, I<capacity> is the new size, but if I<--delta> -is present, then it is added to the existing size. - -Attempts to shrink the volume will fail unless I<--shrink> is present. -The I<capacity> cannot be negative unless I<--shrink> is provided, but -a negative sign is not necessary. - -This command is only safe for storage volumes not in use by an active -guest; see also B<blockresize> for live resizing. - -=back - -=head1 SECRET COMMANDS - -The following commands manipulate "secrets" (e.g. passwords, passphrases and -encryption keys). Libvirt can store secrets independently from their use, and -other objects (e.g. volumes or domains) can refer to the secrets for encryption -or possibly other uses. Secrets are identified using a UUID. See -L<https://libvirt.org/formatsecret.html> for documentation of the XML format -used to represent properties of secrets. - -=over 4 - -=item B<secret-define> I<file> - -Create a secret with the properties specified in I<file>, with no associated -secret value. If I<file> does not specify a UUID, choose one automatically. -If I<file> specifies a UUID of an existing secret, replace its properties by -properties defined in I<file>, without affecting the secret value. - -=item B<secret-dumpxml> I<secret> - -Output properties of I<secret> (specified by its UUID) as an XML dump to stdout. - -=item B<secret-event> {[I<secret>] I<event> [I<--loop>] [I<--timeout> -I<seconds>] [I<--timestamp>] | I<--list>} - -Wait for a class of secret events to occur, and print appropriate details -of events as they happen. The events can optionally be filtered by -I<secret>. Using I<--list> as the only argument will provide a list -of possible I<event> values known by this client, although the connection -might not allow registering for all these events. - -By default, this command is one-shot, and returns success once an event -occurs; you can send SIGINT (usually via C<Ctrl-C>) to quit immediately. -If I<--timeout> is specified, the command gives up waiting for events -after I<seconds> have elapsed. With I<--loop>, the command prints all -events until a timeout or interrupt key. - -When I<--timestamp> is used, a human-readable timestamp will be printed -before the event. - -=item B<secret-set-value> I<secret> I<base64> - -Set the value associated with I<secret> (specified by its UUID) to the value -Base64-encoded value I<base64>. - -=item B<secret-get-value> I<secret> - -Output the value associated with I<secret> (specified by its UUID) to stdout, -encoded using Base64. - -=item B<secret-undefine> I<secret> - -Delete a I<secret> (specified by its UUID), including the associated value, if -any. - -=item B<secret-list> [I<--ephemeral>] [I<--no-ephemeral>] - [I<--private>] [I<--no-private>] - -Returns the list of secrets. You may also want to filter the returned secrets -by I<--ephemeral> to list the ephemeral ones, I<--no-ephemeral> to list the -non-ephemeral ones, I<--private> to list the private ones, and -I<--no-private> to list the non-private ones. - -=back - -=head1 SNAPSHOT COMMANDS - -The following commands manipulate domain snapshots. Snapshots take the -disk, memory, and device state of a domain at a point-of-time, and save it -for future use. They have many uses, from saving a "clean" copy of an OS -image to saving a domain's state before a potentially destructive operation. -Snapshots are identified with a unique name. See -L<https://libvirt.org/formatsnapshot.html> for documentation of the XML format -used to represent properties of snapshots. - -=over 4 - -=item B<snapshot-create> I<domain> [I<xmlfile>] {[I<--redefine> [I<--current>]] -| [I<--no-metadata>] [I<--halt>] [I<--disk-only>] [I<--reuse-external>] -[I<--quiesce>] [I<--atomic>] [I<--live>]} [I<--validate>] - -Create a snapshot for domain I<domain> with the properties specified in -I<xmlfile>. Optionally, the I<--validate> option can be passed to -validate the format of the input XML file against an internal RNG -schema (identical to using the L<virt-xml-validate(1)> tool). Normally, -the only properties settable for a domain snapshot -are the <name> and <description> elements, as well as <disks> if -I<--disk-only> is given; the rest of the fields are -ignored, and automatically filled in by libvirt. If I<xmlfile> is -completely omitted, then libvirt will choose a value for all fields. -The new snapshot will become current, as listed by B<snapshot-current>. - -If I<--halt> is specified, the domain will be left in an inactive state -after the snapshot is created. - -If I<--disk-only> is specified, the snapshot will only include disk -content rather than the usual full system snapshot with vm state. Disk -snapshots are captured faster than full system snapshots, but reverting to a -disk snapshot may require fsck or journal replays, since it is like -the disk state at the point when the power cord is abruptly pulled; -and mixing I<--halt> and I<--disk-only> loses any data that was not -flushed to disk at the time. - -If I<--redefine> is specified, then all XML elements produced by -B<snapshot-dumpxml> are valid; this can be used to migrate snapshot -hierarchy from one machine to another, to recreate hierarchy for the -case of a transient domain that goes away and is later recreated with -the same name and UUID, or to make slight alterations in the snapshot -metadata (such as host-specific aspects of the domain XML embedded in -the snapshot). When this flag is supplied, the I<xmlfile> argument -is mandatory, and the domain's current snapshot will not be altered -unless the I<--current> flag is also given. - -If I<--no-metadata> is specified, then the snapshot data is created, -but any metadata is immediately discarded (that is, libvirt does not -treat the snapshot as current, and cannot revert to the snapshot -unless I<--redefine> is later used to teach libvirt about the -metadata again). - -If I<--reuse-external> is specified, and the snapshot XML requests an -external snapshot with a destination of an existing file, then the -destination must exist and be pre-created with correct format and -metadata. The file is then reused; otherwise, a snapshot is refused -to avoid losing contents of the existing files. - -If I<--quiesce> is specified, libvirt will try to use guest agent -to freeze and unfreeze domain's mounted file systems. However, -if domain has no guest agent, snapshot creation will fail. -Currently, this requires I<--disk-only> to be passed as well. - -If I<--atomic> is specified, libvirt will guarantee that the snapshot -either succeeds, or fails with no changes; not all hypervisors support -this. If this flag is not specified, then some hypervisors may fail -after partially performing the action, and B<dumpxml> must be used to -see whether any partial changes occurred. - -If I<--live> is specified, libvirt takes the snapshot while -the guest is running. Both disk snapshot and domain memory snapshot are -taken. This increases the size of the memory image of the external -snapshot. This is currently supported only for full system external snapshots. - -Existence of snapshot metadata will prevent attempts to B<undefine> -a persistent domain. However, for transient domains, snapshot -metadata is silently lost when the domain quits running (whether -by command such as B<destroy> or by internal guest action). - -For now, it is not possible to create snapshots in a domain that has -checkpoints, although this restriction will be lifted in a future -release. - -=item B<snapshot-create-as> I<domain> {[I<--print-xml>] -[I<--no-metadata>] [I<--halt>] [I<--reuse-external>]} [I<name>] -[I<description>] [I<--disk-only> [I<--quiesce>]] [I<--atomic>] -[[I<--live>] [I<--memspec> B<memspec>]] [I<--diskspec>] B<diskspec>]... - -Create a snapshot for domain I<domain> with the given <name> and -<description>; if either value is omitted, libvirt will choose a -value. If I<--print-xml> is specified, then XML appropriate for -I<snapshot-create> is output, rather than actually creating a snapshot. -Otherwise, if I<--halt> is specified, the domain will be left in an -inactive state after the snapshot is created, and if I<--disk-only> -is specified, the snapshot will not include vm state. - -The I<--memspec> option can be used to control whether a full system snapshot -is internal or external. The I<--memspec> flag is mandatory, followed -by a B<memspec> of the form B<[file=]name[,snapshot=type]>, where -type can be B<no>, B<internal>, or B<external>. To include a literal -comma in B<file=name>, escape it with a second comma. I<--memspec> cannot -be used together with I<--disk-only>. - -The I<--diskspec> option can be used to control how I<--disk-only> and -external full system snapshots create external files. This option can occur -multiple times, according to the number of <disk> elements in the domain -xml. Each <diskspec> is in the -form B<disk[,snapshot=type][,driver=type][,stype=type][,file=name]>. -A I<diskspec> must be provided for disks backed by block devices as libvirt -doesn't auto-generate file names for those. The optional B<stype> parameter -allows to control the type of the source file. Supported values are 'file' -(default) and 'block'. - -To include a literal comma in B<disk> or in B<file=name>, escape it with a -second comma. A literal I<--diskspec> must precede each B<diskspec> unless -all three of I<domain>, I<name>, and I<description> are also present. -For example, a diskspec of "vda,snapshot=external,file=/path/to,,new" -results in the following XML: - <disk name='vda' snapshot='external'> - <source file='/path/to,new'/> - </disk> - -If I<--reuse-external> is specified, and the domain XML or I<diskspec> -option requests an external snapshot with a destination of an existing -file, then the destination must exist and be pre-created with correct -format and metadata. The file is then reused; otherwise, a snapshot -is refused to avoid losing contents of the existing files. - -If I<--quiesce> is specified, libvirt will try to use guest agent -to freeze and unfreeze domain's mounted file systems. However, -if domain has no guest agent, snapshot creation will fail. -Currently, this requires I<--disk-only> to be passed as well. - -If I<--no-metadata> is specified, then the snapshot data is created, -but any metadata is immediately discarded (that is, libvirt does not -treat the snapshot as current, and cannot revert to the snapshot -unless B<snapshot-create> is later used to teach libvirt about the -metadata again). - -If I<--atomic> is specified, libvirt will guarantee that the snapshot -either succeeds, or fails with no changes; not all hypervisors support -this. If this flag is not specified, then some hypervisors may fail -after partially performing the action, and B<dumpxml> must be used to -see whether any partial changes occurred. - -If I<--live> is specified, libvirt takes the snapshot while the guest is -running. This increases the size of the memory image of the external -snapshot. This is currently supported only for external full system snapshots. - -For now, it is not possible to create snapshots in a domain that has -checkpoints, although this restriction will be lifted in a future -release. - -=item B<snapshot-current> I<domain> {[I<--name>] | [I<--security-info>] -| [I<snapshotname>]} - -Without I<snapshotname>, this will output the snapshot XML for the domain's -current snapshot (if any). If I<--name> is specified, just the -current snapshot name instead of the full xml. Otherwise, using -I<--security-info> will also include security sensitive information in -the XML. - -With I<snapshotname>, this is a request to make the existing named -snapshot become the current snapshot, without reverting the domain. - -=item B<snapshot-edit> I<domain> [I<snapshotname>] [I<--current>] -{[I<--rename>] | [I<--clone>]} - -Edit the XML configuration file for I<snapshotname> of a domain. If -both I<snapshotname> and I<--current> are specified, also force the -edited snapshot to become the current snapshot. If I<snapshotname> -is omitted, then I<--current> must be supplied, to edit the current -snapshot. - -This is equivalent to: - - virsh snapshot-dumpxml dom name > snapshot.xml - vi snapshot.xml (or make changes with your other text editor) - virsh snapshot-create dom snapshot.xml --redefine [--current] - -except that it does some error checking. - -The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment -variables, and defaults to C<vi>. - -If I<--rename> is specified, then the edits can change the snapshot -name. If I<--clone> is specified, then changing the snapshot name -will create a clone of the snapshot metadata. If neither is specified, -then the edits must not change the snapshot name. Note that changing -a snapshot name must be done with care, since the contents of some -snapshots, such as internal snapshots within a single qcow2 file, are -accessible only from the original name. - -=item B<snapshot-info> I<domain> {I<snapshot> | I<--current>} - -Output basic information about a named <snapshot>, or the current snapshot -with I<--current>. - -=item B<snapshot-list> I<domain> [I<--metadata>] [I<--no-metadata>] -[{I<--parent> | I<--roots> | [{I<--tree> | I<--name>}]}] [I<--topological>] -[{[I<--from>] B<snapshot> | I<--current>} [I<--descendants>]] -[I<--leaves>] [I<--no-leaves>] [I<--inactive>] [I<--active>] -[I<--disk-only>] [I<--internal>] [I<--external>] - -List all of the available snapshots for the given domain, defaulting -to show columns for the snapshot name, creation time, and domain state. - -Normally, table form output is sorted by snapshot name; using -I<--topological> instead sorts so that no child is listed before its -ancestors (although there may be more than one possible ordering with -this property). - -If I<--parent> is specified, add a column to the output table giving -the name of the parent of each snapshot. If I<--roots> is specified, -the list will be filtered to just snapshots that have no parents. -If I<--tree> is specified, the output will be in a tree format, listing -just snapshot names. These three options are mutually exclusive. If -I<--name> is specified only the snapshot name is printed. This option is -mutually exclusive with I<--tree>. - -If I<--from> is provided, filter the list to snapshots which are -children of the given B<snapshot>; or if I<--current> is provided, -start at the current snapshot. When used in isolation or with -I<--parent>, the list is limited to direct children unless -I<--descendants> is also present. When used with I<--tree>, the -use of I<--descendants> is implied. This option is not compatible -with I<--roots>. Note that the starting point of I<--from> or -I<--current> is not included in the list unless the I<--tree> -option is also present. - -If I<--leaves> is specified, the list will be filtered to just -snapshots that have no children. Likewise, if I<--no-leaves> is -specified, the list will be filtered to just snapshots with -children. (Note that omitting both options does no filtering, -while providing both options will either produce the same list -or error out depending on whether the server recognizes the flags). -Filtering options are not compatible with I<--tree>. - -If I<--metadata> is specified, the list will be filtered to just -snapshots that involve libvirt metadata, and thus would prevent -B<undefine> of a persistent domain, or be lost on B<destroy> of -a transient domain. Likewise, if I<--no-metadata> is specified, -the list will be filtered to just snapshots that exist without -the need for libvirt metadata. - -If I<--inactive> is specified, the list will be filtered to snapshots -that were taken when the domain was shut off. If I<--active> is -specified, the list will be filtered to snapshots that were taken -when the domain was running, and where the snapshot includes the -memory state to revert to that running state. If I<--disk-only> is -specified, the list will be filtered to snapshots that were taken -when the domain was running, but where the snapshot includes only -disk state. - -If I<--internal> is specified, the list will be filtered to snapshots -that use internal storage of existing disk images. If I<--external> -is specified, the list will be filtered to snapshots that use external -files for disk images or memory state. - -=item B<snapshot-dumpxml> I<domain> I<snapshot> [I<--security-info>] - -Output the snapshot XML for the domain's snapshot named I<snapshot>. -Using I<--security-info> will also include security sensitive information. -Use B<snapshot-current> to easily access the XML of the current snapshot. - -=item B<snapshot-parent> I<domain> {I<snapshot> | I<--current>} - -Output the name of the parent snapshot, if any, for the given -I<snapshot>, or for the current snapshot with I<--current>. - -=item B<snapshot-revert> I<domain> {I<snapshot> | I<--current>} -[{I<--running> | I<--paused>}] [I<--force>] - -Revert the given domain to the snapshot specified by I<snapshot>, or to -the current snapshot with I<--current>. Be aware -that this is a destructive action; any changes in the domain since the last -snapshot was taken will be lost. Also note that the state of the domain after -snapshot-revert is complete will be the state of the domain at the time -the original snapshot was taken. - -Normally, reverting to a snapshot leaves the domain in the state it was -at the time the snapshot was created, except that a disk snapshot with -no vm state leaves the domain in an inactive state. Passing either the -I<--running> or I<--paused> flag will perform additional state changes -(such as booting an inactive domain, or pausing a running domain). Since -transient domains cannot be inactive, it is required to use one of these -flags when reverting to a disk snapshot of a transient domain. - -There are two cases where a snapshot revert involves extra risk, which -requires the use of I<--force> to proceed. One is the case of a -snapshot that lacks full domain information for reverting -configuration (such as snapshots created prior to libvirt 0.9.5); -since libvirt cannot prove that the current configuration matches what -was in use at the time of the snapshot, supplying I<--force> assures -libvirt that the snapshot is compatible with the current configuration -(and if it is not, the domain will likely fail to run). The other is -the case of reverting from a running domain to an active state where a -new hypervisor has to be created rather than reusing the existing -hypervisor, because it implies drawbacks such as breaking any existing -VNC or Spice connections; this condition happens with an active -snapshot that uses a provably incompatible configuration, as well as -with an inactive snapshot that is combined with the I<--start> or -I<--pause> flag. - -=item B<snapshot-delete> I<domain> {I<snapshot> | I<--current>} [I<--metadata>] -[{I<--children> | I<--children-only>}] - -Delete the snapshot for the domain named I<snapshot>, or the current -snapshot with I<--current>. If this snapshot -has child snapshots, changes from this snapshot will be merged into the -children. If I<--children> is passed, then delete this snapshot and any -children of this snapshot. If I<--children-only> is passed, then delete -any children of this snapshot, but leave this snapshot intact. These -two flags are mutually exclusive. - -If I<--metadata> is specified, then only delete the snapshot metadata -maintained by libvirt, while leaving the snapshot contents intact for -access by external tools; otherwise deleting a snapshot also removes -the data contents from that point in time. - -=back - -=head1 CHECKPOINT COMMANDS - -The following commands manipulate domain checkpoints. Checkpoints serve as -a point in time to identify which portions of a guest's disks have changed -after that time, making it possible to perform incremental and differential -backups. Checkpoints are identified with a unique name. See -L<https://libvirt.org/formatcheckpoint.html> for documentation of the XML -format used to represent properties of checkpoints. - -=over 4 - -=item B<checkpoint-create> I<domain> [I<xmlfile>] { I<--redefine> -| [I<--quiesce>]} - -Create a checkpoint for domain I<domain> with the properties specified -in I<xmlfile> describing a <domaincheckpoint> top-level element. The -format of the input XML file will be validated against an internal RNG -schema (idential to using the L<virt-xml-validate(1)> tool). If -I<xmlfile> is completely omitted, then libvirt will create a -checkpoint with a name based on the current time. - -If I<--redefine> is specified, then all XML elements produced by -B<checkpoint-dumpxml> are valid; this can be used to migrate -checkpoint hierarchy from one machine to another, to recreate -hierarchy for the case of a transient domain that goes away and is -later recreated with the same name and UUID, or to make slight -alterations in the checkpoint metadata (such as host-specific aspects -of the domain XML embedded in the checkpoint). When this flag is -supplied, the I<xmlfile> argument is mandatory. - -If I<--quiesce> is specified, libvirt will try to use guest agent -to freeze and unfreeze domain's mounted file systems. However, -if domain has no guest agent, checkpoint creation will fail. - -Existence of checkpoint metadata will prevent attempts to B<undefine> -a persistent domain. However, for transient domains, checkpoint -metadata is silently lost when the domain quits running (whether -by command such as B<destroy> or by internal guest action). - -For now, it is not possible to create checkpoints in a domain that has -snapshots, although this restriction will be lifted in a future -release. - -=item B<checkpoint-create-as> I<domain> [I<--print-xml>] -[I<name>] [I<description>] [I<--quiesce>] [I<--diskspec>] B<diskspec>]... - -Create a checkpoint for domain I<domain> with the given <name> and -<description>; if either value is omitted, libvirt will choose a -value. If I<--print-xml> is specified, then XML appropriate for -I<checkpoint-create> is output, rather than actually creating a -checkpoint. - -The I<--diskspec> option can be used to control which guest disks -participate in the checkpoint. This option can occur multiple times, -according to the number of <disk> elements in the domain xml. Each -<diskspec> is in the form B<disk[,checkpoint=type][,bitmap=name]>. A -literal I<--diskspec> must precede each B<diskspec> unless -all three of I<domain>, I<name>, and I<description> are also present. -For example, a diskspec of "vda,checkpoint=bitmap,bitmap=map1" -results in the following XML: - <disk name='vda' checkpoint='bitmap' bitmap='map1'/> - -If I<--quiesce> is specified, libvirt will try to use guest agent -to freeze and unfreeze domain's mounted file systems. However, -if domain has no guest agent, checkpoint creation will fail. - -For now, it is not possible to create checkpoints in a domain that has -snapshots, although this restriction will be lifted in a future -release. - -=item B<checkpoint-edit> I<domain> I<checkpointname> - -Edit the XML configuration file for I<checkpointname> of a domain. - -This is equivalent to: - - virsh checkpoint-dumpxml dom name > checkpoint.xml - vi checkpoint.xml (or make changes with your other text editor) - virsh checkpoint-create dom checkpoint.xml --redefine - -except that it does some error checking, including that the edits -should not attempt to change the checkpoint name. - -The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment -variables, and defaults to C<vi>. - -=item B<checkpoint-info> I<domain> I<checkpoint> - -Output basic information about a named <checkpoint>. - -=item B<checkpoint-list> I<domain> [{I<--parent> | I<--roots> | -[{I<--tree> | I<--name>}]}] [I<--topological>] -[[I<--from>] B<checkpoint> | [I<--descendants>]] -[I<--leaves>] [I<--no-leaves>] - -List all of the available checkpoints for the given domain, defaulting -to show columns for the checkpoint name and creation time. - -Normally, table form output is sorted by checkpoint name; using -I<--topological> instead sorts so that no child is listed before its -ancestors (although there may be more than one possible ordering with -this property). - -If I<--parent> is specified, add a column to the output table giving -the name of the parent of each checkpoint. If I<--roots> is -specified, the list will be filtered to just checkpoints that have no -parents. If I<--tree> is specified, the output will be in a tree -format, listing just checkpoint names. These three options are -mutually exclusive. If I<--name> is specified only the checkpoint name -is printed. This option is mutually exclusive with I<--tree>. - -If I<--from> is provided, filter the list to checkpoints which are -children of the given B<checkpoint>. When used in isolation or with -I<--parent>, the list is limited to direct children unless -I<--descendants> is also present. When used with I<--tree>, the use -of I<--descendants> is implied. This option is not compatible with -I<--roots>. Note that the starting point of I<--from> -is not included in the list unless the I<--tree> option is also -present. - -If I<--leaves> is specified, the list will be filtered to just -checkpoints that have no children. Likewise, if I<--no-leaves> is -specified, the list will be filtered to just checkpoints with -children. (Note that omitting both options does no filtering, while -providing both options will either produce the same list or error out -depending on whether the server recognizes the flags). Filtering -options are not compatible with I<--tree>. - -=item B<checkpoint-dumpxml> I<domain> I<checkpoint> -[I<--security-info>] [I<--no-domain>] [I<--size>] - -Output the checkpoint XML for the domain's checkpoint named -I<checkpoint>. Using -I<--security-info> will also include security sensitive information. -Using I<--size> will add XML indicating the current size in bytes of -guest data that has changed since the checkpoint was created (although -remember that guest activity between a size check and actually -creating a backup can result in the backup needing slightly more -space). Using I<--no-domain> will omit the <domain> element from the -output for a more compact view. - -=item B<checkpoint-parent> I<domain> I<checkpoint> - -Output the name of the parent checkpoint, if any, for the given -I<checkpoint>. - -=item B<checkpoint-delete> I<domain> I<checkpoint> -[I<--metadata>] [{I<--children> | I<--children-only>}] - -Delete the checkpoint for the domain named I<checkpoint>. The -record of which portions of -the disk changed since the checkpoint are merged into the parent -checkpoint (if any). If I<--children> is passed, then delete this -checkpoint and any children of this checkpoint. If I<--children-only> -is passed, then delete any children of this checkpoint, but leave this -checkpoint intact. These two flags are mutually exclusive. - -If I<--metadata> is specified, then only delete the checkpoint -metadata maintained by libvirt, while leaving the checkpoint contents -intact for access by external tools; otherwise deleting a checkpoint -also removes the ability to perform an incremental backup from that -point in time. - -=back - -=head1 NWFILTER COMMANDS - -The following commands manipulate network filters. Network filters allow -filtering of the network traffic coming from and going to virtual machines. -Individual network traffic filters are written in XML and may contain -references to other network filters, describe traffic filtering rules, -or contain both. Network filters are referenced by virtual machines -from within their interface description. A network filter may be referenced -by multiple virtual machines' interfaces. - -=over 4 - -=item B<nwfilter-define> I<xmlfile> - -Make a new network filter known to libvirt. If a network filter with -the same name already exists, it will be replaced with the new XML. -Any running virtual machine referencing this network filter will have -its network traffic rules adapted. If for any reason the network traffic -filtering rules cannot be instantiated by any of the running virtual -machines, then the new XML will be rejected. - -=item B<nwfilter-undefine> I<nwfilter-name> - -Delete a network filter. The deletion will fail if any running virtual -machine is currently using this network filter. - -=item B<nwfilter-list> - -List all of the available network filters. - -=item B<nwfilter-dumpxml> I<nwfilter-name> - -Output the network filter XML. - -=item B<nwfilter-edit> I<nwfilter-name> - -Edit the XML of a network filter. - -This is equivalent to: - - virsh nwfilter-dumpxml myfilter > myfilter.xml - vi myfilter.xml (or make changes with your other text editor) - virsh nwfilter-define myfilter.xml - -except that it does some error checking. -The new network filter may be rejected due to the same reason as -mentioned in I<nwfilter-define>. - -The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment -variables, and defaults to C<vi>. - -=back - -=head1 NWFILTER BINDING COMMANDS - -The following commands manipulate network filter bindings. Network filter -bindings track the association between a network port and a network -filter. Generally the bindings are managed automatically by the hypervisor -drivers when adding/removing NICs on a guest. - -If an admin is creating/deleting TAP devices for non-guest usage, -however, the network filter binding commands provide a way to make use -of the network filters directly. - -=over 4 - -=item B<nwfilter-binding-create> I<xmlfile> - -Associate a network port with a network filter. The network filter backend -will immediately attempt to instantiate the filter rules on the port. This -command may be used to associate a filter with a currently running guest -that does not have a filter defined for a specific network port. Since the -bindings are generally automatically managed by the hypervisor, using this -command to define a filter for a network port and then starting the guest -afterwards may prevent the guest from starting if it attempts to use the -network port and finds a filter already defined. - -=item B<nwfilter-binding-delete> I<port-name> - -Disassociate a network port from a network filter. The network filter -backend will immediately tear down the filter rules that exist on the -port. This command may be used to remove the network port binding for -a filter currently in use for the guest while the guest is running -without needing to restart the guest. Restoring the network port binding -filter for the running guest would be accomplished by using -I<nwfilter-binding-create>. - -=item B<nwfilter-binding-list> - -List all of the network ports which have filters associated with them. - -=item B<nwfilter-binding-dumpxml> I<port-name> - -Output the network filter binding XML for the network device called -C<port-name>. - -=back - -=head1 HYPERVISOR-SPECIFIC COMMANDS - -NOTE: Use of the following commands is B<strongly> discouraged. They -can cause libvirt to become confused and do the wrong thing on subsequent -operations. Once you have used these commands, please do not report -problems to the libvirt developers; the reports will be ignored. If -you find that these commands are the only way to accomplish something, -then it is better to request that the feature be added as a first-class -citizen in the regular libvirt library. - -=over 4 - -=item B<qemu-attach> I<pid> - -Attach an externally launched QEMU process to the libvirt QEMU driver. -The QEMU process must have been created with a monitor connection -using the UNIX driver. Ideally the process will also have had the -'-name' argument specified. - -=over 4 - - $ qemu-kvm -cdrom ~/demo.iso \ - -monitor unix:/tmp/demo,server,nowait \ - -name foo \ - -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea & - $ QEMUPID=$! - $ virsh qemu-attach $QEMUPID - -=back - -Not all functions of libvirt are expected to work reliably after -attaching to an externally launched QEMU process. There may be -issues with the guest ABI changing upon migration and device hotplug -or hotunplug may not work. The attached environment should be considered -primarily read-only. - -=item B<qemu-monitor-command> I<domain> { [I<--hmp>] | [I<--pretty>] } -I<command>... - -Send an arbitrary monitor command I<command> to domain I<domain> through the -qemu monitor. The results of the command will be printed on stdout. If -I<--hmp> is passed, the command is considered to be a human monitor command -and libvirt will automatically convert it into QMP if needed. In that case -the result will also be converted back from QMP. If I<--pretty> is given, -and the monitor uses QMP, then the output will be pretty-printed. If more -than one argument is provided for I<command>, they are concatenated with a -space in between before passing the single command to the monitor. - -=item B<qemu-agent-command> I<domain> [I<--timeout> I<seconds> | I<--async> | -I<--block>] I<command>... - -Send an arbitrary guest agent command I<command> to domain I<domain> through -qemu agent. -I<--timeout>, I<--async> and I<--block> options are exclusive. -I<--timeout> requires timeout seconds I<seconds> and it must be positive. -When I<--aysnc> is given, the command waits for timeout whether success or -failed. And when I<--block> is given, the command waits forever with blocking -timeout. - -=item B<qemu-monitor-event> [I<domain>] [I<--event> I<event-name>] [I<--loop>] -[I<--timeout> I<seconds>] [I<--pretty>] [I<--regex>] [I<--no-case>] -[I<--timestamp>] - -Wait for arbitrary QEMU monitor events to occur, and print out the -details of events as they happen. The events can optionally be filtered -by I<domain> or I<event-name>. The 'query-events' QMP command can be -used via I<qemu-monitor-command> to learn what events are supported. -If I<--regex> is used, I<event-name> is a basic regular expression -instead of a literal string. If I<--no-case> is used, I<event-name> -will match case-insensitively. - -By default, this command is one-shot, and returns success once an event -occurs; you can send SIGINT (usually via C<Ctrl-C>) to quit immediately. -If I<--timeout> is specified, the command gives up waiting for events -after I<seconds> have elapsed. With I<--loop>, the command prints all -events until a timeout or interrupt key. If I<--pretty> is specified, -any JSON event details are pretty-printed for better legibility. - -When I<--timestamp> is used, a human-readable timestamp will be printed -before the event, and the timing information provided by QEMU will be -omitted. - -=item B<lxc-enter-namespace> I<domain> [I<--noseclabel>] -- /path/to/binary [arg1, [arg2, ...]] - -Enter the namespace of I<domain> and execute the command C</path/to/binary> -passing the requested args. The binary path is relative to the container -root filesystem, not the host root filesystem. The binary will inherit the -environment variables / console visible to virsh. The command will be run -with the same sVirt context and cgroups placement as processes within the -container. This command only works when connected to the LXC hypervisor -driver. This command succeeds only if C</path/to/binary> has 0 exit status. - -By default the new process will run with the security label of the new -parent container. Use the I<--noseclabel> option to instead have the -process keep the same security label as C<virsh>. - -=back - -=head1 ENVIRONMENT - -The following environment variables can be set to alter the behaviour -of C<virsh> - -=over 4 - -=item VIRSH_DEBUG=<0 to 4> - -Turn on verbose debugging of virsh commands. Valid levels are - -=over 4 - -=item * VIRSH_DEBUG=0 - -DEBUG - Messages at ALL levels get logged - -=item * VIRSH_DEBUG=1 - -INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR - -=item * VIRSH_DEBUG=2 - -NOTICE - Logs messages at levels NOTICE, WARNING and ERROR - -=item * VIRSH_DEBUG=3 - -WARNING - Logs messages at levels WARNING and ERROR - -=item * VIRSH_DEBUG=4 - -ERROR - Messages at only ERROR level gets logged. - -=back - -=item VIRSH_LOG_FILE=C<LOGFILE> - -The file to log virsh debug messages. - -=item VIRSH_DEFAULT_CONNECT_URI - -The hypervisor to connect to by default. Set this to a URI, in the same -format as accepted by the B<connect> option. This environment variable -is deprecated in favour of the global B<LIBVIRT_DEFAULT_URI> variable -which serves the same purpose. - -=item LIBVIRT_DEFAULT_URI - -The hypervisor to connect to by default. Set this to a URI, in the -same format as accepted by the B<connect> option. This overrides -the default URI set in any client config file and prevents libvirt -from probing for drivers. - -=item VISUAL - -The editor to use by the B<edit> and related options. - -=item EDITOR - -The editor to use by the B<edit> and related options, if C<VISUAL> -is not set. - -=item VIRSH_HISTSIZE - -The number of commands to remember in the command history. The -default value is 500. - -=item LIBVIRT_DEBUG=LEVEL - -Turn on verbose debugging of all libvirt API calls. Valid levels are - -=over 4 - -=item * LIBVIRT_DEBUG=1 - -Messages at level DEBUG or above - -=item * LIBVIRT_DEBUG=2 - -Messages at level INFO or above - -=item * LIBVIRT_DEBUG=3 - -Messages at level WARNING or above - -=item * LIBVIRT_DEBUG=4 - -Messages at level ERROR - -=back - -For further information about debugging options consult -L<https://libvirt.org/logging.html> - -=back - -=head1 BUGS - -Report any bugs discovered to the libvirt community via the mailing -list L<https://libvirt.org/contact.html> or bug tracker -L<https://libvirt.org/bugs.html>. -Alternatively report bugs to your software distributor / vendor. - -=head1 AUTHORS - - Please refer to the AUTHORS file distributed with libvirt. - - Based on the xm man page by: - Sean Dague <sean at dague dot net> - Daniel Stekloff <dsteklof at us dot ibm dot com> - -=head1 COPYRIGHT - -Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in the -libvirt AUTHORS file. - -=head1 LICENSE - -virsh is distributed under the terms of the GNU LGPL v2+. -This is free software; see the source for copying conditions. There -is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR -PURPOSE - -=head1 SEE ALSO - -L<virt-install(1)>, L<virt-xml-validate(1)>, L<virt-top(1)>, L<virt-df(1)>, -L<https://libvirt.org/> - -=cut -- 2.23.0