From nobody Tue Nov 26 11:25:58 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) client-ip=205.139.110.61; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575643921; cv=none; d=zohomail.com; s=zohoarc; b=Q3cMHWTRohi99WEGJFuuNHYIFrIn9kuXaO4snbqa4mt3FxZbk7FPe0FwjZ/h0YBOZ7pwIrsiVrVFn223LzTc34WszWnxsUbj1MP4Fg/Nobo7ZgB1S3Bp96N2tTajarI0yWaRiWYsGCu30tBhnlYTXxsu4G9VxtRcMuA73WqsukE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575643921; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=ujYcZhFR7uFxl7XS3WdT66FwatI4wKde4BTsikiOYRU=; b=ktwkPWC/AQ+BbqepQEZYu+vba7F4g1tyU/fPwWm9Y9xk/JsChDzbaSon2NimCllSsLYPDjZeG+VpCuWxJT+g7mQjX0zEF9YjkQY85Nst6Of84nDkaIEGff20z7OE4vCJFyVizdxWGz4psBGyPNrceKxfC/9/S12X2/gothOP2dg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-2.mimecast.com [205.139.110.61]) by mx.zohomail.com with SMTPS id 1575643921318499.76168089603766; Fri, 6 Dec 2019 06:52:01 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-350-E7lgIQ18O-S0_mWygC2hTw-1; Fri, 06 Dec 2019 09:51:54 -0500 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 3D7B8800C7B; Fri, 6 Dec 2019 14:51:49 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 04363194B2; Fri, 6 Dec 2019 14:51:49 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id B10F36B54E; Fri, 6 Dec 2019 14:51:48 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id xB6Epl38017210 for ; Fri, 6 Dec 2019 09:51:47 -0500 Received: by smtp.corp.redhat.com (Postfix) id 016755DA60; Fri, 6 Dec 2019 14:51:47 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-112-49.ams2.redhat.com [10.36.112.49]) by smtp.corp.redhat.com (Postfix) with ESMTP id BD8A05DA76; Fri, 6 Dec 2019 14:51:40 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1575643919; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=ujYcZhFR7uFxl7XS3WdT66FwatI4wKde4BTsikiOYRU=; b=ZGJDB6DDx1hPR+dxIbX5LsM40pp0UJQl8aILiCj2CO7Bh0YTV0RmZtlbmwwD4uwtPL9S5y +B64F4CtDozXfyOwki5s5+VQBzlQAGW9LIGyqKUypZHEytGaTup5TehYURW2arroNT2tD7 mDSyxN5+DBE5Z3HY9CaVRDCQ9MGSxgM= From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Date: Fri, 6 Dec 2019 14:50:40 +0000 Message-Id: <20191206145042.3777845-16-berrange@redhat.com> In-Reply-To: <20191206145042.3777845-1-berrange@redhat.com> References: <20191206145042.3777845-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH 15/17] docs: convert virsh man page from pod to rst X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-MC-Unique: E7lgIQ18O-S0_mWygC2hTw-1 X-Mimecast-Spam-Score: 0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) 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=C3=A9 --- 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 =3D \ manpages/virt-pki-validate.rst \ manpages/virt-xml-validate.rst \ manpages/virt-admin.rst \ + manpages/virsh.rst \ $(NULL) manpages7_rst =3D \ $(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) `__ - remove stale s= anlock resource lease files * `virt-login-shell(1) `__ - tool to execute a shel= l within a container * `virt-admin(1) `__ - daemon administration interface +* `virsh(1) `__ - 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 @@ +=3D=3D=3D=3D=3D +virsh +=3D=3D=3D=3D=3D + +------------------------- +management user interface +------------------------- + +:Manual section: 1 +:Manual group: Virtualization Support + +.. contents:: :depth: 2 + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + + +``virsh`` [*OPTION*]... [*COMMAND_STRING*] + +``virsh`` [*OPTION*]... *COMMAND* [*ARG*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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]... [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 newl= ine. +If no command is given in the command line, ``virsh`` will then start a mi= nimal +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[=3Dshort]`` + +Ignore all other arguments, and prints the version of the libvirt library +virsh is coming from + + + +- ``-V``, ``--version=3Dlong`` + +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 +=3D=3D=3D=3D=3D + + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + +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 architect= ure + 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 t= he +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 `_ 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 `_ 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-a= cross-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 physic= ally +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 Sam= epage +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 = `_ + +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 top +level element from the domain XML or the 'type' attribute found within +each element from the ``virsh capabilities`` output. The +*emulatorbin* option specifies the path to the emulator. The value to +be used is either the 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 element and +subelement or the "name" attribute of an 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 element and 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 filte= ring +flags supported by the ``list`` command. These flags are grouped by functi= on. +Specifying one or more flags from a group enables the filter group. Note t= hat +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 domain= s, +*--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 w= ith +this feature disabled use *--no-autostart*. + +Snapshot existence +.................. + +Domains that have snapshot images can be listed using flag *--with-snapsho= t*, +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 A= PI +calls with an inherent race, where a domain might not be listed or might a= ppear +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 speci= fy +*--inactive* or *--all* to actually list them) will instead show as ``save= d`` +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 print= ed +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] ce= llno] [--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 . +(See ``hypervisor-cpu-baseline`` command to get a CPU which can be provide= d by a +specific hypervisor.) The list of host CPUs is built by extracting all +elements from the . Thus, the can contain either a set of +elements separated by new lines or even a set of complete +elements printed by ``capabilities`` command. If *--features* is specifie= d, +then the resulting XML description will explicitly include all features th= at +make up the CPU, without this option features that are part of the CPU mod= el +will not be listed in the XML description. If *--migratable* is specifie= d, +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 with host CPU. (See +``hypervisor-cpu-compare`` command for comparing the CPU definition with t= he CPU +which a specific hypervisor is able to provide on the host.) The XML may +contain either host or guest CPU definition. The host CPU definition is the + element and its contents as printed by ``capabilities`` command. The +guest CPU definition is the 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 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 `_. 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 architectu= re. +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`` com= mand. +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 act= ual +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] [--e= rror] + +Compare CPU definition from XML with the CPU the hypervisor is able= to +provide on the host. (This is different from ``cpu-compare`` which compare= s the +CPU definition with the host CPU without considering any specific hypervis= or +and its abilities.) + +The XML *FILE* may contain either a host or guest CPU definition. The host= CPU +definition is the element and its contents as printed by the +``capabilities`` command. The guest CPU definition is the element an= d 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 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 `_. + +The *virttype* option specifies the virtualization type (usable in the 'ty= pe' +attribute of the top level element from the domain XML). *emulato= r* +specifies the path to the emulator, *arch* specifies the CPU architecture,= and +*machine* specifies the machine type. If *--error* is specified, the comma= nd +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 o= ut. + + +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 a= n XML +*file* and with the CPU the hypervisor is able to provide on the host. (Th= is +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 element and its conte= nts +as printed by ``capabilities`` command. The guest CPU definition may be cr= eated +from the host CPU model found in domain capabilities XML (printed by +``domcapabilities`` command). In addition to the elements, this comm= and +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 transfo= rm the +host CPU model from domain capabilities XML to a form directly usable in d= omain +XML. + +The *virttype* option specifies the virtualization type (usable in the 'ty= pe' +attribute of the top level element from the domain XML). *emulato= r* +specifies the path to the emulator, *arch* specifies the CPU architecture,= and +*machine* specifies the machine type. If *--features* is specified, then t= he +resulting XML description will explicitly include all features that make u= p 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 th= at +block migration will not be included in the resulting CPU. + + +DOMAIN COMMANDS +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 () or source +file () 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 scal= ed +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 scal= ed +integer, the default being bytes per second if no suffix is specified. +*--total-iops-sec-max* specifies maximum total I/O operations limit per se= cond. +*--read-iops-sec-max* specifies maximum read I/O operations limit per seco= nd. +*--write-iops-sec-max* specifies maximum write I/O operations limit per se= cond. +*--total-bytes-sec-max-length* specifies duration in seconds to allow maxi= mum +total throughput limit. +*--read-bytes-sec-max-length* specifies duration in seconds to allow maxim= um +read throughput limit. +*--write-bytes-sec-max-length* specifies duration in seconds to allow maxi= mum +write throughput limit. +*--total-iops-sec-max-length* specifies duration in seconds to allow maxim= um +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 maxim= um +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 dr= ives. +For a qemu domain, if no name is provided, then the default is to have a s= ingle +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, behav= ior +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/rea= d_iops_sec +pairs, int the format of /path/to/device,read_iops_sec,/path/to/device,rea= d_iops_sec. +Each read_iops_sec is a number which type is unsigned int, value 0 to remo= ve 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/wr= ite_iops_sec +pairs, int the format of /path/to/device,write_iops_sec,/path/to/device,wr= ite_iops_sec. +Each write_iops_sec is a number which type is unsigned int, value 0 to rem= ove 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/re= ad_bytes_sec +pairs, int the format of /path/to/device,read_bytes_sec,/path/to/device,re= ad_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/w= rite_bytes_sec +pairs, int the format of /path/to/device,write_bytes_sec,/path/to/device,w= rite_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 relati= ve. + +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 () or source file () 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 ``blockj= ob`` +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 contain= ing +a top-level 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=3Draw*. When using *dest*, the destination is treated as a regu= lar +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 ha= ve +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 negat= ive +value is interpreted as an unsigned long long value that might be essentia= lly +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 fa= ll +within a certain range. Specifying *buf-size* will control how much data c= an +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 () or source file () 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). Usi= ng +*--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 () or source file () 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 inform= ation +on the *bandwidth* argument see the corresponding section for the ``blockj= ob`` +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 () or source file () 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 . 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 usi= ng +this command are going to be either transient (temporary ones that will va= nish +once destroyed) or existing persistent domains that will run with one-time= use +configuration, leaving the persistent XML untouched (this can come handy d= uring +an automated testing of various configurations all based on the original X= ML). +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 writ= ing + one from scratch) + + .. code-block:: shell + + # virsh dumpxml > domain.xml + +#. edit the template using an editor of your choice and: + + a. DO CHANGE! and ( can also be removed), or + b. DON'T CHANGE! either or + + .. 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 . 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 wil= l 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 enforc= ed. +(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 curre= nt +description and both live configuration and config are updated while setti= ng +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 afterwar= ds. + +Flag *--title* selects operation on the title field instead of description. + +If neither of *--edit* and *--new-desc* are specified the note or descript= ion +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 () or source file () 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 () or source file () 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 n= ewer +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 consiste= nt +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 froz= en. + +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 con= tains +mountpoints, names of a mounted device in the guest, filesystem types, and +unique target names used in the domain XML (). + +Note that this command requires a guest agent configured and running in the +domain's guest OS. + + +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 thaw= ed. + + +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 na= me +within guest OS or the name you would see in domain XML. Moreover, the who= le +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; otherwi= se, +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 (), +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 kilob= ytes +in a single burst at *peak* speed as described in the Network XML +documentation at `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] [--raws= tats] + +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 pri= nted. +*--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 n= ewer +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 requ= ired +* ``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 domai= n (in KiB) +* ``actual`` - Current balloon value (in KiB) +* ``rss`` - Resident Set Size of the running domain's proces= s (in KiB) +* ``usable`` - The amount of memory which can be reclaimed by b= alloon + without causing host swapping (in KiB) +* ``last-update`` - Timestamp of the last update of statistics (in s= econds) +* ``disk_caches`` - The amount of memory that can be reclaimed witho= ut + additional I/O, typically disk caches (in KiB) +* ``hugetlb_pgalloc`` - The number of successful huge page allocations i= nitiated + from within the domain +* ``hugetlb_pgfail`` - The number of failed huge page allocations initi= ated 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 collect= ion, +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 persist= ent +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 f= or +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 ask= ed +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 pmsuspe= nded +state, rather than waiting for the previously requested duration (if any) = to +elapse. This operation doesn't not necessarily fail if the domain is runni= ng. + + +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 sta= te +- 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..name`` - the name of cache monitor +* ``cpu.cache.monitor..vcpus`` - vcpu list of cache monitor +* ``cpu.cache.monitor..bank.count`` - the number of cache banks + in cache monitor +* ``cpu.cache.monitor..bank..id`` - host allocated cache id + for bank in cache monitor +* ``cpu.cache.monitor..bank..bytes`` - the number of bytes + of last level cache that the domain is using on cache bank + + +*--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..state`` - state of the virtual CPU , as + number from virVcpuState enum +* ``vcpu..time`` - virtual cpu time spent by virtual + CPU (in microseconds) +* ``vcpu..wait`` - virtual cpu time spent by virtual + CPU waiting on I/O (in microseconds) +* ``vcpu..halted`` - virtual CPU 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..name`` - name of the interface +* ``net..rx.bytes`` - number of bytes received +* ``net..rx.pkts`` - number of packets received +* ``net..rx.errs`` - number of receive errors +* ``net..rx.drop`` - number of receive packets dropped +* ``net..tx.bytes`` - number of bytes transmitted +* ``net..tx.pkts`` - number of packets transmitted +* ``net..tx.errs`` - number of transmission errors +* ``net..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..name`` - name of the target of the block + device (the same name for multiple entries if I<--backing> + is present) +* ``block..backingIndex`` - when I<--backing> is present, + matches up with the index listed in domain XML for + backing files +* ``block..path`` - file source of block device , if + it is a local file or block device +* ``block..rd.reqs`` - number of read requests +* ``block..rd.bytes`` - number of read bytes +* ``block..rd.times`` - total time (ns) spent on reads +* ``block..wr.reqs`` - number of write requests +* ``block..wr.bytes`` - number of written bytes +* ``block..wr.times`` - total time (ns) spent on writes +* ``block..fl.reqs`` - total flush requests +* ``block..fl.times`` - total time (ns) spent on cache flushing +* ``block..errors`` - Xen only: the 'oo_req' value +* ``block..allocation`` - offset of highest written sector in bytes +* ``block..capacity`` - logical size of source file in bytes +* ``block..physical`` - physical size of source file in bytes +* ``block..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..poll-max-ns`` - maximum polling time in nanoseconds used + by the IOThread. A value of 0 (zero) indicates polling is disabled. +* ``iothread..poll-grow`` - polling time grow value. A value of 0 (zer= o) + growth is managed by the hypervisor. +* ``iothread..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-u= uid } + +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-compress= ed). + +The progress may be monitored using ``domjobinfo`` virsh command and cance= led +with ``domjobabort`` command (sent by another virsh instance). Another opt= ion +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 l= oaded +and processed by crash utility since its version 6.1.0. A --memory-only op= tion +is required in order to produce valid ELF file which can be later processe= d by +the crash utility. + + +dumpxml +------- + +.. code-block:: shell + + dumpxml domain [--inactive] [--security-info] [--update-cpu] [--migrata= ble] + +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 u= sed +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 amen= ded +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`` environm= ent +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] [--times= tamp] | --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] [--filesyste= m] + +Print information about the guest from the point of view of the guest agen= t. +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 t= hat +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 ag= ent +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..name`` - username of user +* ``user..domain`` - domain of the user (may only be present on= certain + guets types) +* ``user..login-time`` - the login time of user 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 oper= ating + 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..mountpoint`` - the path to the mount point for filesystem +* ``fs..name`` - device name in the guest (e.g. ``sda1``) for filesys= tem +* ``fs..fstype`` - the type of filesystem +* ``fs..total-bytes`` - the total size of filesystem +* ``fs..used-bytes`` - the number of bytes used in filesystem +* ``fs..disk.count`` - the number of disks targeted by filesystem +* ``fs..disk..alias`` - the device alias of disk (e.g. sda) +* ``fs..disk..serial`` - the serial number of disk +* ``fs..disk..device`` - the device node of disk + + +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 vC= PUs, +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 runn= ing, +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 cance= led +with ``domjobabort`` command (sent by another virsh instance). Another opt= ion +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`` environm= ent +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 element of XML. + + +memtune +------- + +.. code-block:: shell + + memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-lim= it 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 kibiby= tes). + +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 definitio= n. +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 curre= nt +description and both live configuration and config are updated while setti= ng +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 correspond= ing +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-p= recopy] + 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 *--tunnelle= d* +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 wi= th +*--persistent* option. *--persistent* leaves the domain persistent on +destination host, *--undefinesource* undefines the domain on the source ho= st, +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 destinati= on). +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 destina= tion +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-protect= ion* +enforces that no incompatible configuration changes will be made to the do= main +while the migration is underway; this flag is implicitly enabled when supp= orted +by the hypervisor, but can be explicitly used to reject the migration if t= he +hypervisor lacks change protection support. *--verbose* displays the prog= ress +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 fini= shed. +The maximum bandwidth consumed during the post-copy phase may be limited u= sing +*--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 m= emory +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). Doi= ng so +may be dangerous to both the domain and the host itself since the host's k= ernel +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 dis= ks +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 metho= ds +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 targ= et +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 perf= orm +the migration of the domain. Usage requires proper TLS setup for both sour= ce +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 migra= tion +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 s= een from the source machine. + +When *migrateuri* is not specified, libvirt will automatically determine t= he +hypervisor specific URI. Some hypervisors, including QEMU, have an option= al +"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 publ= ic IP addresses, then + libvirt will generate an incorrect URI. In this case *migrateuri* shoul= d 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 se= nt over + a specific interface for either security or performance reasons. In thi= s case + *migrateuri* should be explicitly specified, using an IP address associa= ted + 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 rule= s. + 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 *migra= teuri* + 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 `_ for more details on +migration URIs. + +Optional *graphicsuri* overrides connection parameters used for automatica= lly +reconnecting a graphical clients at the end of migration. If omitted, libv= irt +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 a= re +connected to and needs to connect through a proxy, *graphicsuri* may be us= ed +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 prot= ocol +specific parameters separated by '&'. Currently recognized parameters are +"tlsPort" and "tlsSubject". For example, + +.. code-block:: shell + + spice://target.host.com:1234/?tlsPort=3D4567 + +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 sh= ould +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 repeate= dly +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 reacti= on +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-migrat= ed 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 bandwid= th +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 all= owed +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 bandwid= th +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 +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 *--disab= le* +option combined with ``eventSpec`` can be used to enable or disable specif= ic +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 u= sing +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 virs= h. +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 in= fo. + +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 cance= led +with ``domjobabort`` command (sent by another virsh instance). Another opt= ion +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`` environm= ent +variables, and defaults to ``vi``. + + +schedinfo +--------- + +.. code-block:: shell + + schedinfo domain [[--config] [--live] | [--current]] [[--set] parameter= =3Dvalue]... + schedinfo [--weight number] [--cap number] domain + +Allows you to show (and set) the domain scheduler parameters. The paramete= rs +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; Ne= gative +values are wrapped to positive, and larger values are capped at the maximu= m. +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, *screen= ID* +allows specifying which screen will be captured. It is the sequential numb= er +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 ch= anges +might not be performed with some hypervisors/configuration (e.g. on NUMA e= nabled +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 kibiby= tes). + + +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 kibiby= tes). + +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 vie= wing +the value from the host, use the ``virsh memtune`` command. In order to vi= ew +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 paravirtualiz= ed. + +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 gue= st +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 hotunplu= gged +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 driver= s may +require that *vcpulist* contains exactly vCPUs belonging to one hotpluggab= le +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 virs= h. +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 informati= on +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, attemp= ts +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 inacti= ve +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 separ= ated +list of volume target names or source paths of storage volumes to be remov= ed +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 successf= ully +deleted. Only volumes managed by libvirt in storage pools can be removed t= his +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 vol= umes +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 informat= ion +is not available the processes will provide an exit code of 1. + + +DEVICE COMMANDS +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 `_ on the +format of the device sections to get the most accurate set of accepted val= ues. + + +attach-device +------------- + +.. code-block:: shell + + attach-device domain FILE [[[--live] [--config] | [--current]] | [--per= sistent]] + +Attach a device to the domain, using a device definition in an XML +file using a device definition element such as or +as the top-level element. See the documentation at +`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 dep= ends +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 unexpec= ted +results as some fields may be autogenerated and thus match devices other t= han +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 ty= pe +of disk device to emulate; possible values are driver specific, with typic= al +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 emulato= r. +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 det= ect +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 dev= ice +address. + +If *--print-xml* is specified, then the XML of the disk that would be atta= ched +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 dep= ends +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 `_. + +``--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 doma= in. +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 "v= ifN" +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 definitio= n, +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 dis= allow +or delay the unplug arbitrarily. As the libvirt API used in this command w= as +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. i= f the +guest is unresponsive. Callers which need to make sure that the +device was unplugged can use libvirt events (see virsh event) to be notifi= ed +when the device is removed. Note that the event may arrive before the comm= and +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 dep= ends +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 actu= al +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 dep= ends +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 detac= h 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 dep= ends +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 `_ 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 unexpec= ted +results as some fields may be autogenerated and thus match devices other t= han +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 p= ath +or the unique target name () of the disk device. *sour= ce* +specifies the path of the media to be inserted or updated. The *--block* f= lag +allows setting the backing type in case a block device is used as media fo= r 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 specifie= d. +If the device has source (e.g. ), and *source* is n= ot +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The following commands manipulate host devices that are intended to be +passed through to guest domains via elements in a domain's + 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 = `_. + +Passthrough devices cannot be simultaneously used by the host and its +guest domains, nor by multiple active guests at once. If the + description of a PCI device includes the attribute ``managed=3D'= 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 deta= ched, +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 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 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 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 parent= s 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] [--timestam= p] | --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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 `_ . Many +of the commands for virtual networks are similar to the ones used for doma= ins, +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 `_ +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 persis= tent +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`` environm= ent +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 t= he +inactive ones will be listed. You may also want to filter the returned net= works +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 prin= ted +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 serie= s 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 act= ive, +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 + element that is contained inside a element inside an + element of the network. + +*xml* is either the text of a complete xml element of the type being +changed (e.g. "", 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 element could be in any one of multiple elements in +the network; if a parent-index isn't provided, the "most appropriate" + element will be selected (usually the only one that already has a + element), but if *--parent-index* is given, that particular +instance of will get the modification. + +If *--live* is specified, affect a running network. +If *--config* is specified, affect the next startup of a persistent networ= k. +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The following commands manipulate host interfaces. Often, these host +interfaces can then be used by name within domain 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`` environm= ent +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 uniq= ue +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 `_ . 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 + element with a "name" attribute describing the IP address or hostna= me +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 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 +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 po= ols. + + +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=3Dn'. 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 persisten= t 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`` environm= ent +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 specifi= ed 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] [] + +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 poo= ls +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 serie= s 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +vol-create +---------- + +.. code-block:: shell + + vol-create pool-or-uuid FILE [--prealloc-metadata] + +Create a volume from an XML . + +*pool-or-uuid* is the name or UUID of the storage pool to create the volum= e in. + +*FILE* is the XML with the volume definition. An easy way to create= the +XML 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 met= adata, +resulting in higher performance compared to images with no preallocation a= nd +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 volum= e in. + +*FILE* is the XML 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 met= adata, +resulting in higher performance compared to images with no preallocation a= nd +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 ac= tual +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 ne= xt +available partition. For example, a source device path of /dev/sdb and the= re +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 vol= ume +file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use extended for d= isk +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 volu= me; +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 met= adata, +resulting in higher performance compared to images with no preallocation a= nd +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 met= adata, +resulting in higher performance compared to images with no preallocation a= nd +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-snap= shots] + +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 volu= me +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; otherwis= e, +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 t= he +*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 alg= orithm] + +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] [--phy= sical] + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The following commands manipulate "secrets" (e.g. passwords, passphrases a= nd +encryption keys). Libvirt can store secrets independently from their use,= and +other objects (e.g. volumes or domains) can refer to the secrets for encry= ption +or possibly other uses. Secrets are identified using a UUID. See +`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 st= dout. + + +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 stdou= t, +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 secr= ets +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 operatio= n. +Snapshots are identified with a unique name. See +`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 and elements, as well as 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 snapsh= ots. + +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 and +; 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 snapsh= ot +is internal or external. The *--memspec* flag is mandatory, followed +by a ``memspec`` of the form ``[file=3D]name[,snapshot=3Dtype]``, where +type can be ``no``, ``internal``, or ``external``. To include a literal +comma in ``file=3Dname``, 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 occ= ur +multiple times, according to the number of elements in the domain +xml. Each is in the +form ``disk[,snapshot=3Dtype][,driver=3Dtype][,stype=3Dtype][,file=3Dname]= ``. +A *diskspec* must be provided for disks backed by block devices as libvirt +doesn't auto-generate file names for those. The optional ``stype`` parame= ter +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=3Dname``, escape it wi= th 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=3Dexternal,file=3D/path/to,,new" +results in the following XML: + +.. code-block:: xml + + + + + +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 snapsh= ots. + +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`` environm= ent +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 , 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 a= fter +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 `_ 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 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 and +; 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 elements in the domain xml. Each + is in the form ``disk[,checkpoint=3Dtype][,bitmap=3Dname]``. 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=3Dbitmap,bitmap=3Dmap1" +results in the following XML: + +.. code-block:: xml + + + +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`` environm= ent +variables, and defaults to ``vi``. + + +checkpoint-info +--------------- + +.. code-block:: shell + + checkpoint-info domain checkpoint + +Output basic information about a named . + + +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 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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`` environm= ent +variables, and defaults to ``vi``. + + +NWFILTER BINDING COMMANDS +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D + +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=3D$! + $ 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] comma= nd... + +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 blocki= ng +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 stat= us. + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The following environment variables can be set to alter the behaviour +of ``virsh`` + +- VIRSH_DEBUG=3D<0 to 4> + + Turn on verbose debugging of virsh commands. Valid levels are + + * VIRSH_DEBUG=3D0 + + DEBUG - Messages at ALL levels get logged + + * VIRSH_DEBUG=3D1 + + INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR + + * VIRSH_DEBUG=3D2 + + NOTICE - Logs messages at levels NOTICE, WARNING and ERROR + + * VIRSH_DEBUG=3D3 + + WARNING - Logs messages at levels WARNING and ERROR + + * VIRSH_DEBUG=3D4 + + ERROR - Messages at only ERROR level gets logged. + +- VIRSH_LOG_FILE=3D``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=3DLEVEL + + Turn on verbose debugging of all libvirt API calls. Valid levels are + + * LIBVIRT_DEBUG=3D1 + + Messages at level DEBUG or above + + * LIBVIRT_DEBUG=3D2 + + Messages at level INFO or above + + * LIBVIRT_DEBUG=3D3 + + Messages at level WARNING or above + + * LIBVIRT_DEBUG=3D4 + + Messages at level ERROR + + +For further information about debugging options consult +`https://libvirt.org/logging.html `_ + + +BUGS +=3D=3D=3D=3D + +Please report all bugs you discover. This should be done via either: + +#. the mailing list + + `https://libvirt.org/contact.html `_ + +#. the bug tracker + + `https://libvirt.org/bugs.html `_ + +Alternatively, you may report bugs to your software distributor / vendor. + + +AUTHORS +=3D=3D=3D=3D=3D=3D=3D + +Please refer to the AUTHORS file distributed with libvirt. + + +COPYRIGHT +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D + +virt-install(1), virt-xml-validate(1), virt-top(1), virt-df(1), +`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 =3D \ virsh_win_icon.rc =20 PODFILES =3D \ - virsh.pod \ $(NULL) =20 MANINFILES =3D \ - virsh.1.in \ $(NULL) =20 EXTRA_DIST =3D \ @@ -85,8 +83,7 @@ conf_DATA =3D bin_SCRIPTS =3D virt-xml-validate virt-pki-validate bin_PROGRAMS =3D virsh virt-admin libexec_SCRIPTS =3D libvirt-guests.sh -man1_MANS =3D \ - virsh.1 +man1_MANS =3D =20 if WITH_SANLOCK sbin_SCRIPTS =3D 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 @@ -=3Dhead1 NAME - -virsh - management user interface - -=3Dhead1 SYNOPSIS - -B [I