1VIRSH(1)                    Virtualization Support                    VIRSH(1)
2
3
4

NAME

6       virsh - management user interface
7

SYNOPSIS

9       virsh [OPTION]... [COMMAND_STRING]
10
11       virsh [OPTION]... COMMAND [ARG]...
12

DESCRIPTION

14       The  virsh  program  is the main interface for managing virsh guest do‐
15       mains. The program can be used to create, pause, and shutdown  domains.
16       It  can also be used to list current domains. Libvirt is a C toolkit to
17       interact with the virtualization capabilities  of  recent  versions  of
18       Linux  (and  other  OSes).  It is free software available under the GNU
19       Lesser General Public License. Virtualization of  the  Linux  Operating
20       System means the ability to run multiple instances of Operating Systems
21       concurrently on a single hardware system where the basic resources  are
22       driven  by  a Linux instance. The library aims at providing a long term
23       stable C API.  It currently supports Xen, QEMU, KVM, LXC, OpenVZ,  Vir‐
24       tualBox and VMware ESX.
25
26       The basic structure of most virsh usage is:
27
28          virsh [OPTION]... <command> <domain> [ARG]...
29
30       Where  command  is  one of the commands listed below; domain is the nu‐
31       meric domain id, or the domain name, or the domain UUID; and  ARGS  are
32       command  specific  options.  There are a few exceptions to this rule in
33       the cases where the command in question acts on all domains, the entire
34       machine,  or  directly on the xen hypervisor.  Those exceptions will be
35       clear for each of those commands.  Note: it is permissible to give  nu‐
36       meric  names to domains, however, doing so will result in a domain that
37       can only be identified by domain id. In other words, if a numeric value
38       is  supplied  it will be interpreted as a domain id, not as a name. Any
39       command starting with # is treated as a comment and  silently  ignored,
40       all other unrecognized commands are diagnosed.
41
42       The  virsh  program can be used either to run one COMMAND by giving the
43       command and its  arguments  on  the  shell  command  line,  or  a  COM‐
44       MAND_STRING  which  is  a  single shell argument consisting of multiple
45       COMMAND actions and their arguments joined with  whitespace  and  sepa‐
46       rated  by semicolons or newlines between commands, where unquoted back‐
47       slash-newline pairs are elided.  Within  COMMAND_STRING,  virsh  under‐
48       stands the same single, double, and backslash escapes as the shell, al‐
49       though you must add another layer of shell  escaping  in  creating  the
50       single  shell  argument, and any word starting with unquoted # begins a
51       comment that ends at newline.  If no command is given  in  the  command
52       line, virsh will then start a minimal interpreter waiting for your com‐
53       mands, and the quit command will then exit the program.
54
55       The virsh program understands the following OPTIONS.
56
57       -c, --connect URI
58
59       Connect to the specified URI, as if by the connect command, instead  of
60       the default connection.
61
62       -d, --debug LEVEL
63
64       Enable debug messages at integer LEVEL and above.  LEVEL can range from
65       0 to 4 (default).  See the  documentation  of  VIRSH_DEBUG  environment
66       variable below for the description of each LEVEL.
67
68-e, --escape string
69
70       Set  alternative  escape sequence for console command. By default, tel‐
71       net's ^] is used. Allowed characters when using hat notation  are:  al‐
72       phabetic character, @, [, ], , ^, _.
73
74-h, --help
75
76       Ignore  all  other  arguments,  and  behave as if the help command were
77       given instead.
78
79-k, --keepalive-interval INTERVAL
80
81       Set an INTERVAL (in seconds) for sending keepalive  messages  to  check
82       whether  connection to the server is still alive.  Setting the interval
83       to 0 disables client keepalive mechanism.
84
85-K, --keepalive-count COUNT
86
87       Set a number of times keepalive message can be sent without getting  an
88       answer  from  the server without marking the connection dead.  There is
89       no effect to this setting in case the INTERVAL is set to 0.
90
91-l, --log FILE
92
93       Output logging details to FILE.
94
95-q, --quiet
96
97       Avoid extra informational messages.
98
99-r, --readonly
100
101       Make the initial connection read-only, as if by the  --readonly  option
102       of the connect command.
103
104-t, --timing
105
106       Output elapsed time information for each command.
107
108-v, --version[=short]
109
110       Ignore  all  other arguments, and prints the version of the libvirt li‐
111       brary virsh is coming from
112
113-V, --version=long
114
115       Ignore all other arguments, and prints the version of the  libvirt  li‐
116       brary  virsh  is  coming from and which options and driver are compiled
117       in.
118

NOTES

120       Most virsh operations rely upon the libvirt library being able to  con‐
121       nect  to an already running libvirtd service.  This can usually be done
122       using the command service libvirtd start.
123
124       Most virsh commands require root privileges to run due to the  communi‐
125       cations  channels  used to talk to the hypervisor.  Running as non root
126       will return an error.
127
128       Most virsh commands act synchronously, except maybe shutdown,  setvcpus
129       and  setmem.  In  those cases the fact that the virsh program returned,
130       may not mean the action is complete and you must poll  periodically  to
131       detect that the guest completed the operation.
132
133       virsh  strives  for  backward compatibility.  Although the help command
134       only lists the preferred usage of a command, if  an  older  version  of
135       virsh  supported  an alternate spelling of a command or option (such as
136       --tunnelled instead of  --tunneled),  then  scripts  using  that  older
137       spelling will continue to work.
138
139       Several  virsh  commands take an optionally scaled integer; if no scale
140       is provided, then the default is listed in the command (for  historical
141       reasons,  some  commands default to bytes, while other commands default
142       to kibibytes).  The following case-insensitive suffixes can be used  to
143       select a specific scale:
144
145          b, byte  byte      1
146          KB       kilobyte  1,000
147          k, KiB   kibibyte  1,024
148          MB       megabyte  1,000,000
149          M, MiB   mebibyte  1,048,576
150          GB       gigabyte  1,000,000,000
151          G, GiB   gibibyte  1,073,741,824
152          TB       terabyte  1,000,000,000,000
153          T, TiB   tebibyte  1,099,511,627,776
154          PB       petabyte  1,000,000,000,000,000
155          P, PiB   pebibyte  1,125,899,906,842,624
156          EB       exabyte   1,000,000,000,000,000,000
157          E, EiB   exbibyte  1,152,921,504,606,846,976
158

GENERIC COMMANDS

160       The following commands are generic i.e. not specific to a domain.
161
162   help
163       Syntax:
164
165          help [command-or-group]
166
167       This  lists each of the virsh commands.  When used without options, all
168       commands are listed, one per line,  grouped  into  related  categories,
169       displaying the keyword for each group.
170
171       To  display  only  commands  for a specific group, give the keyword for
172       that group as an option.  For example:
173
174       Example 1:
175
176          virsh # help host
177
178          Host and Hypervisor (help keyword 'host'):
179              capabilities                   capabilities
180              cpu-models                     show the CPU models for an architecture
181              connect                        (re)connect to hypervisor
182              freecell                       NUMA free memory
183              hostname                       print the hypervisor hostname
184              qemu-attach                    Attach to existing QEMU process
185              qemu-monitor-command           QEMU Monitor Command
186              qemu-agent-command             QEMU Guest Agent Command
187              sysinfo                        print the hypervisor sysinfo
188              uri                            print the hypervisor canonical URI
189
190       To display detailed information for a specific command, give  its  name
191       as the option instead.  For example:
192
193       Example 2:
194
195          virsh # help list
196            NAME
197              list - list domains
198
199            SYNOPSIS
200              list [--inactive] [--all]
201
202            DESCRIPTION
203              Returns list of domains.
204
205            OPTIONS
206              --inactive       list inactive domains
207              --all            list inactive & active domains
208
209   quit, exit
210       Syntax:
211
212          quit
213          exit
214
215       quit this interactive terminal
216
217   version
218       Syntax:
219
220          version [--daemon]
221
222       Will  print  out the major version info about what this built from.  If
223       --daemon is specified then the version of the  libvirt  daemon  is  in‐
224       cluded in the output.
225
226       Example:
227
228          $ virsh version
229          Compiled against library: libvirt 1.2.3
230          Using library: libvirt 1.2.3
231          Using API: QEMU 1.2.3
232          Running hypervisor: QEMU 2.0.50
233
234          $ virsh version --daemon
235          Compiled against library: libvirt 1.2.3
236          Using library: libvirt 1.2.3
237          Using API: QEMU 1.2.3
238          Running hypervisor: QEMU 2.0.50
239          Running against daemon: 1.2.6
240
241   cd
242       Syntax:
243
244          cd [directory]
245
246       Will  change current directory to directory.  The default directory for
247       the cd command is the home directory or, if there is no  HOME  variable
248       in the environment, the root directory.
249
250       This command is only available in interactive mode.
251
252   pwd
253       Syntax:
254
255          pwd
256
257       Will print the current directory.
258
259   connect
260       Syntax:
261
262          connect [URI] [--readonly]
263
264       (Re)-Connect  to  the hypervisor. When the shell is first started, this
265       is automatically run with the URI parameter requested by the -c  option
266       on  the command line. The URI parameter specifies how to connect to the
267       hypervisor. The URI docs https://libvirt.org/uri.html list  the  values
268       supported, but the most common are:
269
270       • xen:///system
271
272         this is used to connect to the local Xen hypervisor
273
274       • qemu:///system
275
276         connect  locally  as  root to the daemon supervising QEMU and KVM do‐
277         mains
278
279       • qemu:///session
280
281         connect locally as a normal user to his own set of QEMU and  KVM  do‐
282         mains
283
284       • lxc:///system
285
286         connect to a local linux container
287
288       To find the currently used URI, check the uri command documented below.
289
290       For  remote access see the URI docs https://libvirt.org/uri.html on how
291       to make URIs. The --readonly option allows for read-only connection
292
293   uri
294       Syntax:
295
296          uri
297
298       Prints the hypervisor canonical URI, can be useful in shell mode.
299
300   hostname
301       Syntax:
302
303          hostname
304
305       Print the hypervisor hostname.
306
307   sysinfo
308       Syntax:
309
310          sysinfo
311
312       Print the XML representation of the hypervisor sysinfo, if available.
313
314   nodeinfo
315       Syntax:
316
317          nodeinfo
318
319       Returns basic information about the node, like number and type of  CPU,
320       and  size of the physical memory. The output corresponds to virNodeInfo
321       structure. Specifically, the "CPU socket(s)" field means number of  CPU
322       sockets  per  NUMA  cell. The information libvirt displays is dependent
323       upon what each architecture may provide.
324
325   nodecpumap
326       Syntax:
327
328          nodecpumap [--pretty]
329
330       Displays the node's total number of CPUs, the number of online CPUs and
331       the list of online CPUs.
332
333       With --pretty the online CPUs are printed as a range instead of a list.
334
335   nodecpustats
336       Syntax:
337
338          nodecpustats [cpu] [--percent]
339
340       Returns  cpu  stats  of the node.  If cpu is specified, this will print
341       the specified cpu statistics only.  If  --percent  is  specified,  this
342       will  print the percentage of each kind of cpu statistics during 1 sec‐
343       ond.
344
345   nodememstats
346       Syntax:
347
348          nodememstats [cell]
349
350       Returns memory stats of the node.  If  cell  is  specified,  this  will
351       print the specified cell statistics only.
352
353   nodesevinfo
354       Syntax:
355
356          nodesevinfo
357
358       Reports  information about the AMD SEV launch security features for the
359       node, if any. Some of this information is also reported in  the  domain
360       capabilities XML document.
361
362   nodesuspend
363       Syntax:
364
365          nodesuspend [target] [duration]
366
367       Puts  the node (host machine) into a system-wide sleep state and sched‐
368       ule the node's Real-Time-Clock interrupt to resume the node  after  the
369       time duration specified by duration is out.  target specifies the state
370       to which the host will be suspended to, it can  be  "mem"  (suspend  to
371       RAM),  "disk"  (suspend  to disk), or "hybrid" (suspend to both RAM and
372       disk).  duration specifies the time duration in seconds for  which  the
373       host has to be suspended, it should be at least 60 seconds.
374
375   node-memory-tune
376       Syntax:
377
378          node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs] [shm-merge-across-nodes]
379
380       Allows   you   to   display   or   set   the  node  memory  parameters.
381       shm-pages-to-scan can be used to set the number of pages to scan before
382       the  shared  memory  service  goes to sleep; shm-sleep-millisecs can be
383       used to set the number of millisecs the shared  memory  service  should
384       sleep  before next scan; shm-merge-across-nodes specifies if pages from
385       different numa nodes can be merged. When set to  0,  only  pages  which
386       physically  reside  in the memory area of same NUMA node can be merged.
387       When set to 1, pages from all nodes can be merged. Default to 1.
388
389       Note: Currently the "shared memory  service"  only  means  KSM  (Kernel
390       Samepage Merging).
391
392   capabilities
393       Syntax:
394
395          capabilities
396
397       Print  an XML document describing the capabilities of the hypervisor we
398       are currently connected to. This includes a section on the  host  capa‐
399       bilities  in  terms  of  CPU and features, and a set of description for
400       each kind of guest which can be virtualized. For a  more  complete  de‐
401       scription see:
402
403       https://libvirt.org/formatcaps.html
404
405       The XML also show the NUMA topology information if available.
406
407   domcapabilities
408       Syntax:
409
410          domcapabilities [virttype] [emulatorbin] [arch] [machine]
411
412       Print an XML document describing the domain capabilities for the hyper‐
413       visor we are connected to using information either sourced from an  ex‐
414       isting  domain or taken from the virsh capabilities output. This may be
415       useful if you intend to create a new domain and are curious if for  in‐
416       stance  it could make use of VFIO by creating a domain for the hypervi‐
417       sor with a specific emulator and architecture.
418
419       Each hypervisor will have different requirements  regarding  which  op‐
420       tions  are  required  and  which are optional. A hypervisor can support
421       providing a default value for any of the options.
422
423       The virttype option specifies the virtualization type used.  The  value
424       to  be  used  is  either from the 'type' attribute of the <domain/> top
425       level element from the domain XML or the 'type' attribute found  within
426       each  <guest/>  element from the virsh capabilities output.  The emula‐
427       torbin option specifies the path to the emulator. The value to be  used
428       is  either  the <emulator> element in the domain XML or the virsh capa‐
429       bilities output. The arch option specifies the architecture to be  used
430       for  the  domain.  The  value to be used is either the "arch" attribute
431       from the domain's XML <os/>  element  and  <type/>  subelement  or  the
432       "name"  attribute  of  an  <arch/> element from the virsh capabililites
433       output. The machine specifies the machine type for  the  emulator.  The
434       value  to  be  used is either the "machine" attribute from the domain's
435       XML <os/> element and <type/> subelement or one from a list of machines
436       from  the virsh capabilities output for a specific architecture and do‐
437       main type.
438
439       For the QEMU hypervisor, a virttype of either 'qemu' or 'kvm'  must  be
440       supplied along with either the emulatorbin or arch in order to generate
441       output for the default machine.  Supplying a machine value will  gener‐
442       ate output for the specific machine.
443
444   pool-capabilities
445       Syntax:
446
447          pool-capabilities
448
449       Print  an XML document describing the storage pool capabilities for the
450       connected storage driver. This may be useful if you intend to create  a
451       new  storage  pool  and  need to know the available pool types and sup‐
452       ported storage pool source and target volume formats as well as the re‐
453       quired source elements to create the pool.
454
455   inject-nmi
456       Syntax:
457
458          inject-nmi domain
459
460       Inject NMI to the guest.
461
462   list
463       Syntax:
464
465          list [--inactive | --all]
466               [--managed-save] [--title]
467               { [--table] | --name | --uuid | --id }
468               [--persistent] [--transient]
469               [--with-managed-save] [--without-managed-save]
470               [--autostart] [--no-autostart]
471               [--with-snapshot] [--without-snapshot]
472               [--with-checkpoint] [--without-checkpoint]
473               [--state-running] [--state-paused]
474               [--state-shutoff] [--state-other]
475
476       Prints information about existing domains.  If no options are specified
477       it prints out information about running domains.
478
479       Example 1:
480
481       An example format for the list is as follows:
482
483          ``virsh`` list
484            Id    Name                           State
485          ----------------------------------------------------
486            0     Domain-0                       running
487            2     fedora                         paused
488
489       Name is the name of the domain.  ID the domain numeric  id.   State  is
490       the run state (see below).
491
492       STATES
493
494       The  State field lists what state each domain is currently in. A domain
495       can be in one of the following possible states:
496
497running
498
499         The domain is currently running on a CPU
500
501idle
502
503         The domain is idle, and not running or runnable.  This can be  caused
504         because the domain is waiting on IO (a traditional wait state) or has
505         gone to sleep because there was nothing else for it to do.
506
507paused
508
509         The domain has been paused, usually occurring through the administra‐
510         tor  running  virsh  suspend.  When in a paused state the domain will
511         still consume allocated resources like memory, but will not be eligi‐
512         ble for scheduling by the hypervisor.
513
514in shutdown
515
516         The domain is in the process of shutting down, i.e. the guest operat‐
517         ing system has been notified and should be in the process of stopping
518         its operations gracefully.
519
520shut off
521
522         The  domain  is  not  running.  Usually this indicates the domain has
523         been shut down completely, or has not been started.
524
525crashed
526
527         The domain has crashed, which is always a  violent  ending.   Usually
528         this  state  can  only occur if the domain has been configured not to
529         restart on crash.
530
531pmsuspended
532
533         The domain has been suspended by guest power management, e.g. entered
534         into s3 state.
535
536       Normally only active domains are listed. To list inactive domains spec‐
537       ify --inactive or --all to list both active and inactive domains.
538
539       Filtering
540
541       To further filter the list of domains you may specify one  or  more  of
542       filtering  flags supported by the list command. These flags are grouped
543       by function.  Specifying one or more flags from  a  group  enables  the
544       filter  group.  Note  that  some combinations of flags may yield no re‐
545       sults. Supported filtering flags and groups:
546
547   Persistence
548       Flag --persistent is used to include persistent guests in the  returned
549       list. To include transient guests specify --transient.
550
551   Existence of managed save image
552       To  list  domains  having a managed save image specify flag --with-man‐
553       aged-save. For domains that don't have a  managed  save  image  specify
554       --without-managed-save.
555
556   Domain state
557       The  following  filter flags select a domain by its state: --state-run‐
558       ning  for  running  domains,  --state-paused    for   paused   domains,
559       --state-shutoff  for turned off domains and --state-other for all other
560       states as a fallback.
561
562   Autostarting domains
563       To list autostarting domains use the flag --autostart. To list  domains
564       with this feature disabled use --no-autostart.
565
566   Snapshot existence
567       Domains that have snapshot images can be listed using flag --with-snap‐
568       shot, domains without a snapshot --without-snapshot.
569
570   Checkpoint existence
571       Domains that have checkpoints can be listed  using  flag  --with-check‐
572       point, domains without a checkpoint --without-checkpoint.
573
574       When  talking  to older servers, this command is forced to use a series
575       of API calls with an inherent race, where a domain might not be  listed
576       or  might appear more than once if it changed state between calls while
577       the list was being collected.  Newer servers do not have this problem.
578
579       If --managed-save is specified, then domains  that  have  managed  save
580       state  (only possible if they are in the shut off state, so you need to
581       specify --inactive or --all to actually list them) will instead show as
582       saved in the listing. This flag is usable only with the default --table
583       output.  Note that this flag does not filter the list of domains.
584
585       If --name is specified, domain names are printed instead of  the  table
586       formatted  one  per  line.  If  --uuid is specified domain's UUID's are
587       printed instead of names. If --id is specified then domain's  ID's  are
588       printed  indead  of  names.  However, it is possible to combine --name,
589       --uuid and --id to select only desired fields for printing. Flag  --ta‐
590       ble  specifies  that  the legacy table-formatted output should be used,
591       but it is mutually exclusive with --name, --uuid and --id. This is  the
592       default and will be used if neither of --name, --uuid or --id is speci‐
593       fied. If neither --name nor --uuid is specified, but --id is, then only
594       active  domains  are listed, even with the --all parameter as otherwise
595       the output would just contain bunch of lines with just -1.
596
597       If --title is specified, then the short domain description  (title)  is
598       printed  in  an extra column. This flag is usable only with the default
599       --table output.
600
601       Example 2:
602
603          $ virsh list --title
604            Id    Name        State      Title
605           -------------------------------------------
606            0     Domain-0    running    Mailserver 1
607            2     fedora      paused
608
609   freecell
610       Syntax:
611
612          freecell [{ [--cellno] cellno | --all }]
613
614       Prints the available amount of memory on the machine or within  a  NUMA
615       cell.  The freecell command can provide one of three different displays
616       of available memory on the machine depending on the options  specified.
617       With  no  options,  it  displays  the total free memory on the machine.
618       With the --all option, it displays the free memory in each cell and the
619       total  free memory on the machine.  Finally, with a numeric argument or
620       with --cellno plus a cell number it will display the  free  memory  for
621       the specified cell only.
622
623   freepages
624       Syntax:
625
626          freepages [{ [--cellno] cellno [--pagesize] pagesize |     --all }]
627
628       Prints  the available amount of pages within a NUMA cell. cellno refers
629       to the NUMA cell you're interested in. pagesize  is  a  scaled  integer
630       (see  NOTES above).  Alternatively, if --all is used, info on each pos‐
631       sible combination of NUMA cell and page size is printed out.
632
633   allocpages
634       Syntax:
635
636          allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno] cellno] [--add] [--all]
637
638       Change the size of pages pool of pagesize on  the  host.  If  --add  is
639       specified,  then  pagecount  pages are added into the pool. However, if
640       --add wasn't specified, then the pagecount is taken as the new absolute
641       size of the pool (this may be used to free some pages and size the pool
642       down). The cellno modifier can be used to narrow the modification  down
643       to  a  single  host  NUMA cell. On the other end of spectrum lies --all
644       which executes the modification on all NUMA cells.
645
646   cpu-baseline
647       Syntax:
648
649          cpu-baseline FILE [--features] [--migratable]
650
651       Compute baseline CPU which will be supported by all host CPUs given  in
652       <file>.  (See hypervisor-cpu-baseline command to get a CPU which can be
653       provided by a specific hypervisor.) The list of host CPUs is  built  by
654       extracting  all  <cpu>  elements  from the <file>. Thus, the <file> can
655       contain either a set of <cpu> elements separated by new lines or even a
656       set  of  complete  <capabilities> elements printed by capabilities com‐
657       mand.  If --features is specified, then the resulting  XML  description
658       will explicitly include all features that make up the CPU, without this
659       option features that are part of the CPU model will not  be  listed  in
660       the  XML  description.    If  --migratable  is specified, features that
661       block migration will not be included in the resulting CPU.
662
663   cpu-compare
664       Syntax:
665
666          cpu-compare FILE [--error] [--validate]
667
668       Compare CPU definition from XML <file> with  host  CPU.  (See  hypervi‐
669       sor-cpu-compare  command  for comparing the CPU definition with the CPU
670       which a specific hypervisor is able to provide on the  host.)  The  XML
671       <file>  may  contain  either host or guest CPU definition. The host CPU
672       definition is the <cpu> element and its contents as printed by capabil‐
673       ities  command.  The  guest CPU definition is the <cpu> element and its
674       contents from domain XML definition or the CPU definition created  from
675       the  host CPU model found in domain capabilities XML (printed by domca‐
676       pabilities command). In addition to the <cpu> element itself, this com‐
677       mand  accepts full domain XML, capabilities XML, or domain capabilities
678       XML containing the CPU definition. For more information  on  guest  CPU
679       definition  see:  https://libvirt.org/formatdomain.html#elementsCPU. If
680       --error is specified, the command will return an error when  the  given
681       CPU  is incompatible with host CPU and a message providing more details
682       about the incompatibility will be printed out. If --validate is  speci‐
683       fied,  validates the format of the XML document against an internal RNG
684       schema.
685
686   cpu-models
687       Syntax:
688
689          cpu-models arch
690
691       Print the list of CPU models known by libvirt for the specified  archi‐
692       tecture.   Whether  a  specific  hypervisor  is able to create a domain
693       which uses any of the printed CPU models is a separate  question  which
694       can  be  answered by looking at the domain capabilities XML returned by
695       domcapabilities command.  Moreover, for some architectures libvirt does
696       not  know  any CPU models and the usable CPU models are only limited by
697       the hypervisor. This command will print that all  CPU  models  are  ac‐
698       cepted  for  these  architectures  and the actual list of supported CPU
699       models can be checked in the domain capabilities XML.
700
701   hypervisor-cpu-compare
702       Syntax:
703
704          hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine] [--error] [--validate]
705
706       Compare CPU definition from XML <file> with the CPU the  hypervisor  is
707       able  to provide on the host. (This is different from cpu-compare which
708       compares the CPU definition with the host CPU without  considering  any
709       specific hypervisor and its abilities.)
710
711       The  XML  FILE  may  contain either a host or guest CPU definition. The
712       host CPU definition is the <cpu> element and its contents as printed by
713       the capabilities command. The guest CPU definition is the <cpu> element
714       and its contents from the domain XML definition or the  CPU  definition
715       created  from  the  host CPU model found in the domain capabilities XML
716       (printed by the domcapabilities command). In addition to the <cpu> ele‐
717       ment itself, this command accepts full domain XML, capabilities XML, or
718       domain capabilities XML containing the CPU definition. For more  infor‐
719       mation         on        guest        CPU        definition        see:
720       https://libvirt.org/formatdomain.html#elementsCPU.
721
722       The virttype option specifies the virtualization type  (usable  in  the
723       'type'  attribute  of  the  <domain>  top level element from the domain
724       XML). emulator specifies the path to the emulator, arch  specifies  the
725       CPU architecture, and machine specifies the machine type. If --error is
726       specified, the command will return an error when the given CPU  is  in‐
727       compatible with the host CPU and a message providing more details about
728       the incompatibility will be printed out.  If --validate  is  specified,
729       validates  the  format  of  the  XML  document  against an internal RNG
730       schema.
731
732   hypervisor-cpu-baseline
733       Syntax:
734
735          hypervisor-cpu-baseline FILE [virttype] [emulator] [arch] [machine] [--features] [--migratable]
736
737       Compute a baseline CPU which will be compatible with all  CPUs  defined
738       in  an  XML  file and with the CPU the hypervisor is able to provide on
739       the host. (This is different from cpu-baseline which does not  consider
740       any hypervisor abilities when computing the baseline CPU.)
741
742       The  XML FILE may contain either host or guest CPU definitions describ‐
743       ing the host CPU model. The host CPU definition is  the  <cpu>  element
744       and its contents as printed by capabilities command. The guest CPU def‐
745       inition may be created from the host CPU model found in domain capabil‐
746       ities  XML  (printed  by  domcapabilities  command). In addition to the
747       <cpu> elements, this command accepts full capabilities XMLs, or  domain
748       capabilities  XMLs containing the CPU definitions. It is recommended to
749       use only the CPU definitions from domain capabilities, as on  some  ar‐
750       chitectures  using  the  host CPU definition may either fail or provide
751       unexpected results.
752
753       When FILE contains only a single CPU definition, the command will print
754       the  same  CPU with restrictions imposed by the capabilities of the hy‐
755       pervisor.  Specifically, running th virsh hypervisor-cpu-baseline  com‐
756       mand  with no additional options on the result of virsh domcapabilities
757       will transform the host CPU model from domain  capabilities  XML  to  a
758       form directly usable in domain XML.
759
760       The  virttype  option  specifies the virtualization type (usable in the
761       'type' attribute of the <domain> top  level  element  from  the  domain
762       XML).  emulator  specifies the path to the emulator, arch specifies the
763       CPU architecture, and machine specifies the machine type. If --features
764       is  specified,  then  the resulting XML description will explicitly in‐
765       clude all features that make up the CPU, without this  option  features
766       that  are  part of the CPU model will not be listed in the XML descrip‐
767       tion. If --migratable is specified, features that block migration  will
768       not be included in the resulting CPU.
769

DOMAIN COMMANDS

771       The  following  commands  manipulate domains directly, as stated previ‐
772       ously most commands take domain as the first parameter. The domain  can
773       be specified as a short integer, a name or a full UUID.
774
775   autostart
776       Syntax:
777
778          autostart [--disable] domain
779
780       Configure a domain to be automatically started at boot.
781
782       The option --disable disables autostarting.
783
784   blkdeviotune
785       Syntax:
786
787          blkdeviotune domain device [[--config] [--live] | [--current]]
788             [[total-bytes-sec] | [read-bytes-sec] [write-bytes-sec]]
789             [[total-iops-sec] | [read-iops-sec] [write-iops-sec]]
790             [[total-bytes-sec-max] | [read-bytes-sec-max] [write-bytes-sec-max]]
791             [[total-iops-sec-max] | [read-iops-sec-max] [write-iops-sec-max]]
792             [[total-bytes-sec-max-length] |
793              [read-bytes-sec-max-length] [write-bytes-sec-max-length]]
794             [[total-iops-sec-max-length] |
795              [read-iops-sec-max-length] [write-iops-sec-max-length]]
796             [size-iops-sec] [group-name]
797
798       Set or query the block disk io parameters for a block device of domain.
799       device specifies a unique target name (<target dev='name'/>) or  source
800       file  (<source  file='name'/>)  for one of the disk devices attached to
801       domain (see also domblklist for listing these names).
802
803       If no limit is specified, it will query  current  I/O  limits  setting.
804       Otherwise,  alter the limits with these flags: --total-bytes-sec speci‐
805       fies total throughput limit as a  scaled  integer,  the  default  being
806       bytes per second if no suffix is specified.  --read-bytes-sec specifies
807       read throughput limit as a scaled integer, the default being bytes  per
808       second  if  no  suffix is specified.  --write-bytes-sec specifies write
809       throughput limit as a scaled integer, the default being bytes per  sec‐
810       ond  if  no  suffix is specified.  --total-iops-sec specifies total I/O
811       operations limit per second.  --read-iops-sec specifies read I/O opera‐
812       tions  limit  per  second.  --write-iops-sec specifies write I/O opera‐
813       tions limit per second.  --total-bytes-sec-max specifies maximum  total
814       throughput  limit as a scaled integer, the default being bytes per sec‐
815       ond if no suffix is specified  --read-bytes-sec-max  specifies  maximum
816       read  throughput limit as a scaled integer, the default being bytes per
817       second if no suffix is specified.  --write-bytes-sec-max specifies max‐
818       imum  write  throughput  limit  as  a scaled integer, the default being
819       bytes per second if no suffix is specified.  --total-iops-sec-max spec‐
820       ifies    maximum    total    I/O    operations    limit   per   second.
821       --read-iops-sec-max specifies maximum read  I/O  operations  limit  per
822       second.   --write-iops-sec-max  specifies  maximum write I/O operations
823       limit per second.  --total-bytes-sec-max-length specifies  duration  in
824       seconds     to     allow     maximum     total     throughput    limit.
825       --read-bytes-sec-max-length specifies duration in seconds to allow max‐
826       imum read throughput limit.  --write-bytes-sec-max-length specifies du‐
827       ration in seconds to  allow  maximum  write  throughput  limit.   --to‐
828       tal-iops-sec-max-length  specifies duration in seconds to allow maximum
829       total I/O operations limit.  --read-iops-sec-max-length specifies dura‐
830       tion   in   seconds   to  allow  maximum  read  I/O  operations  limit.
831       --write-iops-sec-max-length specifies duration in seconds to allow max‐
832       imum  write  I/O  operations limit.  --size-iops-sec specifies size I/O
833       operations limit per second.   --group-name  specifies  group  name  to
834       share I/O quota between multiple drives.  For a QEMU domain, if no name
835       is provided, then the default is to have a single group  for  each  de‐
836       vice.
837
838       Older versions of virsh only accepted these options with underscore in‐
839       stead of dash, as in --total_bytes_sec.
840
841       Bytes and iops values are independent, but setting only one value (such
842       as  --read-bytes-sec)  resets  the other two in that category to unlim‐
843       ited.  An explicit 0 also clears any limit.  A  non-zero  value  for  a
844       given total cannot be mixed with non-zero values for read or write.
845
846       It  is  up to the hypervisor to determine how to handle the length val‐
847       ues.  For the QEMU hypervisor, if an I/O limit value or  maximum  value
848       is set, then the default value of 1 second will be displayed. Supplying
849       a 0 will reset the value back to the default.
850
851       If --live is specified, affect a running guest.  If --config is  speci‐
852       fied,  affect  the  next  start of a persistent guest.  If --current is
853       specified, it is equivalent to either --live or --config, depending  on
854       the  current  state  of the guest.  When setting the disk io parameters
855       both --live and --config flags may be given, but  --current  is  exclu‐
856       sive.  For  querying  only  one of --live, --config or --current can be
857       specified. If no flag is specified, behavior is different depending  on
858       hypervisor.
859
860   blkiotune
861       Syntax:
862
863          blkiotune domain [--weight weight] [--device-weights device-weights]
864             [--device-read-iops-sec device-read-iops-sec]
865             [--device-write-iops-sec device-write-iops-sec]
866             [--device-read-bytes-sec device-read-bytes-sec]
867             [--device-write-bytes-sec device-write-bytes-sec]
868             [[--config] [--live] | [--current]]
869
870       Display  or  set  the  blkio  parameters.  QEMU/KVM  supports --weight.
871       --weight is in range [100, 1000]. After kernel 2.6.39, the value  could
872       be in the range [10, 1000].
873
874       device-weights  is  a  single  string listing one or more device/weight
875       pairs, in the format of  /path/to/device,weight,/path/to/device,weight.
876       Each  weight  is  in  the  range  [100,  1000], [10, 1000] after kernel
877       2.6.39, or the value 0 to remove that device from per-device  listings.
878       Only  the  devices  listed  in  the  string  are modified; any existing
879       per-device weights for other devices remain unchanged.
880
881       device-read-iops-sec is  a  single  string  listing  one  or  more  de‐
882       vice/read_iops_sec    pairs,    int    the   format   of   /path/to/de‐
883       vice,read_iops_sec,/path/to/device,read_iops_sec.   Each  read_iops_sec
884       is  a  number which type is unsigned int, value 0 to remove that device
885       from per-device listing.  Only the devices listed  in  the  string  are
886       modified;  any  existing per-device read_iops_sec for other devices re‐
887       main unchanged.
888
889       device-write-iops-sec is a  single  string  listing  one  or  more  de‐
890       vice/write_iops_sec    pairs,    int   the   format   of   /path/to/de‐
891       vice,write_iops_sec,/path/to/device,write_iops_sec.                Each
892       write_iops_sec  is  a number which type is unsigned int, value 0 to re‐
893       move that device from per-device listing.  Only the devices  listed  in
894       the  string  are  modified;  any existing per-device write_iops_sec for
895       other devices remain unchanged.
896
897       device-read-bytes-sec is a  single  string  listing  one  or  more  de‐
898       vice/read_bytes_sec    pairs,    int   the   format   of   /path/to/de‐
899       vice,read_bytes_sec,/path/to/device,read_bytes_sec.                Each
900       read_bytes_sec is a number which type is unsigned long long, value 0 to
901       remove that device from per-device listing.  Only the devices listed in
902       the  string  are  modified;  any existing per-device read_bytes_sec for
903       other devices remain unchanged.
904
905       device-write-bytes-sec is a single  string  listing  one  or  more  de‐
906       vice/write_bytes_sec    pairs,   int   the   format   of   /path/to/de‐
907       vice,write_bytes_sec,/path/to/device,write_bytes_sec.              Each
908       write_bytes_sec  is  a number which type is unsigned long long, value 0
909       to remove that device from per-device listing.  Only the devices listed
910       in the string are modified; any existing per-device write_bytes_sec for
911       other devices remain unchanged.
912
913       If --live is specified, affect a running guest.  If --config is  speci‐
914       fied,  affect  the  next  start of a persistent guest.  If --current is
915       specified, it is equivalent to either --live or --config, depending  on
916       the  current state of the guest.  Both --live and --config flags may be
917       given, but --current is exclusive. If no flag is specified, behavior is
918       different depending on hypervisor.
919
920   blockcommit
921       Syntax:
922
923          blockcommit domain path [bandwidth] [--bytes] [base]
924             [--shallow] [top] [--delete] [--keep-relative]
925             [--wait [--async] [--verbose]] [--timeout seconds]
926             [--active] [{--pivot | --keep-overlay}]
927
928       Reduce  the  length  of a backing image chain, by committing changes at
929       the top of the chain (snapshot or delta files) into backing images.  By
930       default,  this  command  attempts to flatten the entire chain.  If base
931       and/or top are specified as files within the backing  chain,  then  the
932       operation  is constrained to committing just that portion of the chain;
933       --shallow can be used instead of base to specify the immediate  backing
934       file  of the resulting top image to be committed.  The files being com‐
935       mitted are rendered invalid, possibly as soon as the operation  starts;
936       using  the --delete flag will attempt to remove these invalidated files
937       at  the  successful  completion  of  the  commit  operation.  When  the
938       --keep-relative flag is used, the backing file paths will be kept rela‐
939       tive.
940
941       When top is omitted or specified as the active image, it is also possi‐
942       ble  to  specify  --active to trigger a two-phase active commit. In the
943       first phase, top is copied into base and the job can only be  canceled,
944       with  top  still  containing data not yet in base. In the second phase,
945       top and base remain identical until a call to blockjob with the --abort
946       flag  (keeping  top  as  the active image that tracks changes from that
947       point in time) or the --pivot flag (making base the  new  active  image
948       and invalidating top).
949
950       By  default, this command returns as soon as possible, and data for the
951       entire disk is committed in the background; the progress of the  opera‐
952       tion  can  be  checked with blockjob.  However, if --wait is specified,
953       then this command will block until  the  operation  completes  (or  for
954       --active,  enters the second phase), or until the operation is canceled
955       because the optional timeout in seconds elapses or SIGINT is sent (usu‐
956       ally  with Ctrl-C).  Using --verbose along with --wait will produce pe‐
957       riodic status updates.  If job cancellation is triggered, --async  will
958       return  control  to the user as fast as possible, otherwise the command
959       may continue to block a little while  longer  until  the  job  is  done
960       cleaning  up.  Using --pivot is shorthand for combining --active --wait
961       with an automatic blockjob --pivot; and using --keep-overlay is  short‐
962       hand for combining --active --wait with an automatic blockjob --abort.
963
964       path  specifies  fully-qualified  path of the disk; it corresponds to a
965       unique target name  (<target  dev='name'/>)  or  source  file  (<source
966       file='name'/>) for one of the disk devices attached to domain (see also
967       domblklist for listing these names).  bandwidth specifies copying band‐
968       width limit in MiB/s, although for QEMU, it may be non-zero only for an
969       online domain. For further information on the  bandwidth  argument  see
970       the corresponding section for the blockjob command.
971
972   blockcopy
973       Syntax:
974
975          blockcopy domain path { dest [format] [--blockdev] | --xml file }
976             [--shallow] [--reuse-external] [bandwidth]
977             [--wait [--async] [--verbose]] [{--pivot | --finish}]
978             [--timeout seconds] [granularity] [buf-size] [--bytes]
979             [--transient-job] [--synchronous-writes] [--print-xml]
980
981       Copy  a  disk backing image chain to a destination.  Either dest as the
982       destination file name, or --xml with the name of an XML file containing
983       a top-level <disk> element describing the destination, must be present.
984       Additionally, if dest is given, format should be specified  to  declare
985       the  format of the destination (if format is omitted, then libvirt will
986       reuse the format of the source, or with --reuse-external will be forced
987       to  probe  the  destination format, which could be a potential security
988       hole).  The command supports --raw as a boolean flag synonym for --for‐
989       mat=raw.  When using dest, the destination is treated as a regular file
990       unless --blockdev is used to signal that it is a block device.  By  de‐
991       fault,  this  command  flattens  the  entire chain; but if --shallow is
992       specified, the copy shares the backing chain.
993
994       If --reuse-external is specified, then the destination must  exist  and
995       have  sufficient  space  to hold the copy. If --shallow is used in con‐
996       junction with --reuse-external then the  pre-created  image  must  have
997       guest visible contents identical to guest visible contents of the back‐
998       ing file of the original image. This may be used to modify the  backing
999       file names on the destination.
1000
1001       By  default,  the  copy job runs in the background, and consists of two
1002       phases.  Initially, the job must copy all data  from  the  source,  and
1003       during  this  phase, the job can only be canceled to revert back to the
1004       source disk, with no guarantees  about  the  destination.   After  this
1005       phase  completes,  both  the source and the destination remain mirrored
1006       until a call to blockjob with the --abort and --pivot flags pivots over
1007       to  the  copy,  or  a  call without --pivot leaves the destination as a
1008       faithful copy of that point in time.  However, if --wait is  specified,
1009       then  this command will block until the mirroring phase begins, or can‐
1010       cel the operation if the optional timeout in seconds elapses or  SIGINT
1011       is  sent (usually with Ctrl-C).  Using --verbose along with --wait will
1012       produce periodic status updates.  Using --pivot  (similar  to  blockjob
1013       --pivot)  or --finish (similar to blockjob --abort) implies --wait, and
1014       will additionally end the job cleanly rather than leaving things in the
1015       mirroring  phase.   If  job  cancellation is triggered by timeout or by
1016       --finish, --async will return control to the user as fast as  possible,
1017       otherwise the command may continue to block a little while longer until
1018       the job has actually cancelled.
1019
1020       path specifies fully-qualified path of the disk.   bandwidth  specifies
1021       copying bandwidth limit in MiB/s. Specifying a negative value is inter‐
1022       preted as an unsigned long long value that might be essentially  unlim‐
1023       ited,  but  more  likely  would overflow; it is safer to use 0 for that
1024       purpose. For further information on the bandwidth argument see the cor‐
1025       responding  section  for  the blockjob command.  Specifying granularity
1026       allows fine-tuning of the granularity that will be copied when a  dirty
1027       region is detected; larger values trigger less I/O overhead but may end
1028       up copying more data overall (the default value  is  usually  correct);
1029       hypervisors  may  restrict  this  to be a power of two or fall within a
1030       certain range. Specifying buf-size will control how much  data  can  be
1031       simultaneously in-flight during the copy; larger values use more memory
1032       but may allow faster completion (the default value is usually correct).
1033
1034       --transient-job allows specifying that the user does  not  require  the
1035       job  to  be recovered if the VM crashes or is turned off before the job
1036       completes. This flag removes the restriction of copy jobs to  transient
1037       domains if that restriction is applied by the hypervisor.
1038
1039       If  --synchronous-writes is specified the block job will wait for guest
1040       writes to be propagated both to the original image and to the  destina‐
1041       tion  of the copy so that it's guaranteed that the job converges if the
1042       destination storage is slower. This may impact  performance  of  writes
1043       while the blockjob is running.
1044
1045       If  --print-xml is specified, then the XML used to start the block copy
1046       job is printed instead of starting the job.
1047
1048   blockjob
1049       Syntax:
1050
1051          blockjob domain path { [--abort] [--async] [--pivot] |
1052             [--info] [--raw] [--bytes] | [bandwidth] }
1053
1054       Manage active block operations.   There  are  three  mutually-exclusive
1055       modes: --info, bandwidth, and --abort.  --async and --pivot imply abort
1056       mode; --raw implies info mode; and if no mode was given, --info mode is
1057       assumed.
1058
1059       path  specifies  fully-qualified  path of the disk; it corresponds to a
1060       unique target name  (<target  dev='name'/>)  or  source  file  (<source
1061       file='name'/>) for one of the disk devices attached to domain (see also
1062       domblklist for listing these names).
1063
1064       In --abort mode, the active job on the specified disk will be  aborted.
1065       If  --async  is  also  specified, this command will return immediately,
1066       rather than waiting for the cancellation to complete.   If  --pivot  is
1067       specified,  this  requests  that an active copy or active commit job be
1068       pivoted over to the new image.
1069
1070       In --info mode, the active job information on the specified  disk  will
1071       be  printed.  By default, the output is a single human-readable summary
1072       line; this format may change in future versions.   Adding  --raw  lists
1073       each  field  of the struct, in a stable format.  If the --bytes flag is
1074       set, then the command errors out if the server could not supply bytes/s
1075       resolution;  when  omitting the flag, raw output is listed in MiB/s and
1076       human-readable output automatically selects the  best  resolution  sup‐
1077       ported by the server.
1078
1079       bandwidth  can  be  used  to  set bandwidth limit for the active job in
1080       MiB/s.  If --bytes is specified then the bandwidth value is interpreted
1081       in  bytes/s.  Specifying a negative value is interpreted as an unsigned
1082       long value or essentially unlimited. The hypervisor can choose  whether
1083       to reject the value or convert it to the maximum value allowed. Option‐
1084       ally a scaled positive number may  be  used  as  bandwidth  (see  NOTES
1085       above).  Using  --bytes with a scaled value permits a finer granularity
1086       to be selected.  A scaled value used without --bytes  will  be  rounded
1087       down to MiB/s. Note that the --bytes may be unsupported by the hypervi‐
1088       sor.
1089
1090       Note that the  progress  reported  for  blockjobs  corresponding  to  a
1091       pull-mode  backup  don't report progress of the backup but rather usage
1092       of temporary space required for the backup.
1093
1094   blockpull
1095       Syntax:
1096
1097          blockpull domain path [bandwidth] [--bytes] [base]
1098             [--wait [--verbose] [--timeout seconds] [--async]]
1099             [--keep-relative]
1100
1101       Populate a disk from its backing image chain. By default, this  command
1102       flattens  the  entire  chain;  but if base is specified, containing the
1103       name of one of the backing files in the chain, then that  file  becomes
1104       the  new backing file and only the intermediate portion of the chain is
1105       pulled.  Once all requested data from the backing image chain has  been
1106       pulled,  the  disk  no  longer  depends  on that portion of the backing
1107       chain.
1108
1109       By default, this command returns as soon as possible, and data for  the
1110       entire  disk is pulled in the background; the progress of the operation
1111       can be checked with blockjob.  However, if --wait  is  specified,  then
1112       this  command  will  block until the operation completes, or cancel the
1113       operation if the optional timeout in seconds elapses or SIGINT is  sent
1114       (usually  with Ctrl-C).  Using --verbose along with --wait will produce
1115       periodic status updates.  If job  cancellation  is  triggered,  --async
1116       will return control to the user as fast as possible, otherwise the com‐
1117       mand may continue to block a little while longer until the job is  done
1118       cleaning up.
1119
1120       Using  the --keep-relative flag will keep the backing chain names rela‐
1121       tive.
1122
1123       path specifies fully-qualified path of the disk; it  corresponds  to  a
1124       unique  target  name  (<target  dev='name'/>)  or  source file (<source
1125       file='name'/>) for one of the disk devices attached to domain (see also
1126       domblklist for listing these names).  bandwidth specifies copying band‐
1127       width limit in MiB/s. For further information on the bandwidth argument
1128       see the corresponding section for the blockjob command.
1129
1130   blockresize
1131       Syntax:
1132
1133          blockresize domain path size
1134
1135       Resize a block device of domain while the domain is running, path spec‐
1136       ifies the absolute path of the block device; it corresponds to a unique
1137       target   name   (<target   dev='name'/>)   or   source   file  (<source
1138       file='name'/>) for one of the disk devices attached to domain (see also
1139       domblklist for listing these names).
1140
1141       size  is  a  scaled  integer  (see  NOTES  above) which defaults to KiB
1142       (blocks of 1024 bytes) if there is no suffix.  You must use a suffix of
1143       "B"  to  get bytes (note that for historical reasons, this differs from
1144       vol-resize which defaults to bytes without a suffix).
1145
1146   console
1147       Syntax:
1148
1149          console domain [devname] [--safe] [--force]
1150
1151       Connect the virtual serial console for the guest. The optional  devname
1152       parameter refers to the device alias of an alternate console, serial or
1153       parallel device configured for the guest.  If omitted, the primary con‐
1154       sole will be opened.
1155
1156       If  the  flag  --safe is specified, the connection is only attempted if
1157       the driver supports safe console handling. This flag specifies that the
1158       server  has  to  ensure exclusive access to console devices. Optionally
1159       the --force flag may be specified, requesting to disconnect any  exist‐
1160       ing sessions, such as in a case of a broken connection.
1161
1162   cpu-stats
1163       Syntax:
1164
1165          cpu-stats domain [--total] [start] [count]
1166
1167       Provide  cpu  statistics  information of a domain. The domain should be
1168       running. Default it shows stats for all CPUs, and a total. Use  --total
1169       for  only the total stats, start for only the per-cpu stats of the CPUs
1170       from start, count for only count CPUs' stats.
1171
1172   create
1173       Syntax:
1174
1175          create FILE [--console] [--paused] [--autodestroy]
1176             [--pass-fds N,M,...] [--validate] [--reset-nvram]
1177
1178       Create a domain from an XML <file>. Optionally, --validate  option  can
1179       be  passed  to validate the format of the input XML file against an in‐
1180       ternal RNG schema (identical to using virt-xml-validate(1)  tool).  Do‐
1181       mains created using this command are going to be either transient (tem‐
1182       porary ones that will vanish once  destroyed)  or  existing  persistent
1183       guests  that will run with one-time use configuration, leaving the per‐
1184       sistent XML untouched (this can come handy during an automated  testing
1185       of  various configurations all based on the original XML).  See the ex‐
1186       ample below for usage demonstration.
1187
1188       The domain will be paused if the --paused option is used and  supported
1189       by the driver; otherwise it will be running. If --console is requested,
1190       attach to the console after creation.  If --autodestroy  is  requested,
1191       then  the  guest  will be automatically destroyed when virsh closes its
1192       connection to libvirt, or otherwise exits.
1193
1194       If --pass-fds is specified, the argument is a comma separated  list  of
1195       open  file descriptors which should be pass on into the guest. The file
1196       descriptors will be re-numbered in the guest, starting from 3. This  is
1197       only supported with container based virtualization.
1198
1199       If  --reset-nvram is specified, any existing NVRAM file will be deleted
1200       and re-initialized from its pristine template.
1201
1202       Example:
1203
1204       1. prepare a template from an existing domain (skip directly to  3a  if
1205          writing one from scratch)
1206
1207             # virsh dumpxml <domain> > domain.xml
1208
1209       2. edit the template using an editor of your choice and:
1210
1211          a. DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or
1212
1213          b. DON'T CHANGE! either <name> or <uuid>
1214
1215             # $EDITOR domain.xml
1216
1217       3. create  a  domain from domain.xml, depending on whether following 2a
1218          or 2b respectively:
1219
1220          a. the domain is going to be transient
1221
1222          b. an existing persistent guest will run with  a  modified  one-time
1223             configuration
1224
1225             # virsh create domain.xml
1226
1227   define
1228       Syntax:
1229
1230          define FILE [--validate]
1231
1232       Define a domain from an XML <file>. Optionally, the format of the input
1233       XML file can be validated against an internal RNG schema  with  --vali‐
1234       date (identical to using virt-xml-validate(1) tool). The domain defini‐
1235       tion is registered but not started.  If domain is already running,  the
1236       changes will take effect on the next boot.
1237
1238   desc
1239       Syntax:
1240
1241          desc domain [[--live] [--config] |
1242             [--current]] [--title] [--edit] [--new-desc
1243             New description or title message]
1244
1245       Show or modify description and title of a domain. These values are user
1246       fields that allow storing arbitrary textual data to allow easy  identi‐
1247       fication of domains. Title should be short, although it's not enforced.
1248       (See also metadata that works with XML based domain metadata.)
1249
1250       Flags --live or --config select whether this command works on  live  or
1251       persistent  definitions  of the domain. If both --live and --config are
1252       specified, the --config option takes precedence on getting the  current
1253       description  and  both  live configuration and config are updated while
1254       setting the description. --current is exclusive and implied if none  of
1255       these was specified.
1256
1257       Flag  --edit  specifies that an editor with the contents of current de‐
1258       scription or title should be opened and the contents saved back  after‐
1259       wards.
1260
1261       Flag  --title  selects operation on the title field instead of descrip‐
1262       tion.
1263
1264       If neither of --edit and --new-desc are specified the note or  descrip‐
1265       tion is displayed instead of being modified.
1266
1267   destroy
1268       Syntax:
1269
1270          destroy domain [--graceful] [--remove-logs]
1271
1272       Immediately  terminate the domain domain.  This doesn't give the domain
1273       OS any chance to react, and it's the equivalent of  ripping  the  power
1274       cord out on a physical machine.  In most cases you will want to use the
1275       shutdown command instead.  However, this does not  delete  any  storage
1276       volumes  used  by the guest, and if the domain is persistent, it can be
1277       restarted later.
1278
1279       If domain is transient, then the metadata of any snapshots will be lost
1280       once  the  guest  stops running, but the snapshot contents still exist,
1281       and a new domain with the same name and UUID can restore  the  snapshot
1282       metadata  with  snapshot-create.  Similarly, the metadata of any check‐
1283       points will be lost, but can be restored with checkpoint-create.
1284
1285       If --graceful is specified, don't  resort  to  extreme  measures  (e.g.
1286       SIGKILL) when the guest doesn't stop after a reasonable timeout; return
1287       an error instead.
1288
1289       If --remove-logs is specified, remove per domain log files. Not all de‐
1290       ployment configuration can be supported.
1291
1292       In case of QEMU the flag is only supported if virlogd is used to handle
1293       QEMU process output. Otherwise the flag is ignored.
1294
1295   domblkerror
1296       Syntax:
1297
1298          domblkerror domain
1299
1300       Show errors on block devices.  This command usually  comes  handy  when
1301       domstate  command  says that a domain was paused due to I/O error.  The
1302       domblkerror command lists all block devices in error state and the  er‐
1303       ror seen on each of them.
1304
1305   domblkinfo
1306       Syntax:
1307
1308          domblkinfo domain [block-device --all] [--human]
1309
1310       Get block device size info for a domain.  A block-device corresponds to
1311       a unique target name (<target dev='name'/>)  or  source  file  (<source
1312       file='name'/>) for one of the disk devices attached to domain (see also
1313       domblklist for listing these names). If --human is set, the output will
1314       have  a  human  readable output.  If --all is set, the output will be a
1315       table showing all block devices size info associated with domain.   The
1316       --all option takes precedence of the others.
1317
1318   domblklist
1319       Syntax:
1320
1321          domblklist domain [--inactive] [--details]
1322
1323       Print  a table showing the brief information of all block devices asso‐
1324       ciated with domain. If --inactive is specified, query the block devices
1325       that  will be used on the next boot, rather than those currently in use
1326       by a running domain. If --details is specified, disk  type  and  device
1327       value  will also be printed. Other contexts that require a block device
1328       name (such as domblkinfo or snapshot-create for  disk  snapshots)  will
1329       accept either target or unique source names printed by this command.
1330
1331   domblkstat
1332       Syntax:
1333
1334          domblkstat domain [block-device] [--human]
1335
1336       Get  device  block  stats  for a running domain.  A block-device corre‐
1337       sponds to a unique target name (<target dev='name'/>)  or  source  file
1338       (<source  file='name'/>) for one of the disk devices attached to domain
1339       (see also domblklist for listing these names). On a LXC or QEMU domain,
1340       omitting  the  block-device yields device block stats summarily for the
1341       entire domain.
1342
1343       Use --human for a more human readable output.
1344
1345       Availability of these fields depends on hypervisor. Unsupported  fields
1346       are  missing  from the output. Other fields may appear if communicating
1347       with a newer version of libvirtd.
1348
1349       Explanation of fields (fields appear in the following order):
1350
1351       • rd_req            - count of read operations
1352
1353       • rd_bytes          - count of read bytes
1354
1355       • wr_req            - count of write operations
1356
1357       • wr_bytes          - count of written bytes
1358
1359       • errs              - error count
1360
1361       • flush_operations  - count of flush operations
1362
1363       • rd_total_times    - total time read operations took (ns)
1364
1365       • wr_total_times    - total time write operations took (ns)
1366
1367       • flush_total_times - total time flush operations took (ns)
1368
1369       • <-- other fields provided by hypervisor -->
1370
1371   domblkthreshold
1372       Syntax:
1373
1374          domblkthreshold domain dev threshold
1375
1376       Set the threshold value for delivering the block-threshold  event.  dev
1377       specifies  the disk device target or backing chain element of given de‐
1378       vice using the 'target[1]' syntax. threshold is a scaled value  of  the
1379       offset.  If  the block device should write beyond that offset the event
1380       will be delivered.
1381
1382   domcontrol
1383       Syntax:
1384
1385          domcontrol domain
1386
1387       Returns state of an interface to VMM used to  control  a  domain.   For
1388       states  other  than  "ok"  or "error" the command also prints number of
1389       seconds elapsed since the control interface entered its current state.
1390
1391   domdirtyrate-calc
1392       Syntax:
1393
1394          domdirtyrate-calc <domain> [--seconds <sec>]
1395             --mode=[page-sampling | dirty-bitmap | dirty-ring]
1396
1397       Calculate an active domain's memory dirty rate which may be expected by
1398       user  in order to decide whether it's proper to be migrated out or not.
1399       The seconds parameter can be used to calculate dirty rate in a specific
1400       time  which  allows 60s at most now and would be default to 1s if miss‐
1401       ing. These three page-sampling, dirty-bitmap, dirty-ring modes are  mu‐
1402       tually   exclusive  and  alternative  when  specify  calculation  mode,
1403       page-sampling is the default mode if missing. The calculated dirty rate
1404       information is available by calling 'domstats --dirtyrate'.
1405
1406   domdisplay
1407       Syntax:
1408
1409          domdisplay domain [--include-password] [[--type] type] [--all]
1410
1411       Output  a  URI which can be used to connect to the graphical display of
1412       the domain via VNC, SPICE or RDP.   The  particular  graphical  display
1413       type  can  be  selected  using the type parameter (e.g. "vnc", "spice",
1414       "rdp").  If --include-password is specified, the SPICE channel password
1415       will  be  included in the URI. If --all is specified, then all show all
1416       possible graphical displays, for a VM could have more than one  graphi‐
1417       cal displays.
1418
1419   domfsfreeze
1420       Syntax:
1421
1422          domfsfreeze domain [[--mountpoint] mountpoint...]
1423
1424       Freeze  mounted filesystems within a running domain to prepare for con‐
1425       sistent snapshots.
1426
1427       The --mountpoint option takes a parameter mountpoint, which is a  mount
1428       point path of the filesystem to be frozen. This option can occur multi‐
1429       ple times. If this  is  not  specified,  every  mounted  filesystem  is
1430       frozen.
1431
1432       Note: snapshot-create command has a --quiesce option to freeze and thaw
1433       the filesystems automatically to  keep  snapshots  consistent.   domfs‐
1434       freeze  command  is only needed when a user wants to utilize the native
1435       snapshot features of storage devices not supported by libvirt.
1436
1437   domfsinfo
1438       Syntax:
1439
1440          domfsinfo domain
1441
1442       Show a list of mounted filesystems within the running domain. The  list
1443       contains  mountpoints, names of a mounted device in the guest, filesys‐
1444       tem types, and unique target names used  in  the  domain  XML  (<target
1445       dev='name'/>).
1446
1447       Note that this command requires a guest agent configured and running in
1448       the domain's guest OS.
1449
1450   domfsthaw
1451       Syntax:
1452
1453          domfsthaw domain [[--mountpoint] mountpoint...]
1454
1455       Thaw mounted filesystems within  a  running  domain,  which  have  been
1456       frozen by domfsfreeze command.
1457
1458       The  --mountpoint option takes a parameter mountpoint, which is a mount
1459       point path of the filesystem to be thawed. This option can occur multi‐
1460       ple  times.  If  this  is  not  specified,  every mounted filesystem is
1461       thawed.
1462
1463   domfstrim
1464       Syntax:
1465
1466          domfstrim domain [--minimum bytes] [--mountpoint mountPoint]
1467
1468       Issue a fstrim command on all mounted filesystems within a running  do‐
1469       main.  It  discards  blocks which are not in use by the filesystem.  If
1470       --minimum bytes is specified, it tells guest kernel length of  contigu‐
1471       ous  free  range.  Smaller than this may be ignored (this is a hint and
1472       the guest may not respect it). By increasing this value, the fstrim op‐
1473       eration  will  complete  more  quickly for filesystems with badly frag‐
1474       mented free space, although not all blocks will be discarded.  The  de‐
1475       fault value is zero, meaning "discard every free block". Moreover, if a
1476       user wants to trim only one mount point, it can be  specified  via  op‐
1477       tional --mountpoint parameter.
1478
1479   domhostname
1480       Syntax:
1481
1482          domhostname domain [--source lease|agent]
1483
1484       Returns the hostname of a domain, if the hypervisor makes it available.
1485
1486       The  --source  argument specifies what data source to use for the host‐
1487       names, currently 'lease' to read DHCP leases or 'agent'  to  query  the
1488       guest  OS  via  an  agent.  If  unspecified, driver returns the default
1489       method available (some drivers support only one type of source).
1490
1491   domid
1492       Syntax:
1493
1494          domid domain-name-or-uuid
1495
1496       Convert a domain name (or UUID) to a domain id
1497
1498   domif-getlink
1499       Syntax:
1500
1501          domif-getlink domain interface-device [--config]
1502
1503       Query link state of the domain's  virtual  interface.  If  --config  is
1504       specified,  query  the persistent configuration, for compatibility pur‐
1505       poses, --persistent is alias of --config.
1506
1507       interface-device can be the interface's target name or the MAC address.
1508
1509   domif-setlink
1510       Syntax:
1511
1512          domif-setlink domain interface-device state [--config]
1513
1514       Modify link state of the domain's virtual  interface.  Possible  values
1515       for  state are "up" and "down". If --config is specified, only the per‐
1516       sistent configuration of the domain is modified, for compatibility pur‐
1517       poses,  --persistent is alias of --config.  interface-device can be the
1518       interface's target name or the MAC address.
1519
1520   domifaddr
1521       Syntax:
1522
1523          domifaddr domain [interface] [--full]
1524             [--source lease|agent|arp]
1525
1526       Get a list of interfaces of a running domain along with  their  IP  and
1527       MAC addresses, or limited output just for one interface if interface is
1528       specified. Note that interface can be driver dependent, it can  be  the
1529       name within guest OS or the name you would see in domain XML. Moreover,
1530       the whole command may require a guest agent to be  configured  for  the
1531       queried domain under some hypervisors, notably QEMU.
1532
1533       If  --full  is  specified, the interface name and MAC address is always
1534       displayed when the interface has multiple IP addresses or aliases; oth‐
1535       erwise,  only  the  interface name and MAC address is displayed for the
1536       first name and MAC address with "-" for the others using the same  name
1537       and MAC address.
1538
1539       The  --source  argument  specifies  what data source to use for the ad‐
1540       dresses, currently 'lease' to read DHCP leases, 'agent'  to  query  the
1541       guest  OS  via an agent, or 'arp' to get IP from host's arp tables.  If
1542       unspecified, 'lease' is the default.
1543
1544   backup-begin
1545       Syntax:
1546
1547          backup-begin domain [backupxml] [checkpointxml] [--reuse-external]
1548
1549       Begin a new backup job. If backupxml is omitted,  this  defaults  to  a
1550       full  backup using a push model to filenames generated by libvirt; sup‐
1551       plying XML allows fine-tuning such as requesting an incremental  backup
1552       relative  to an earlier checkpoint, controlling which disks participate
1553       or which filenames are involved, or requesting the use of a pull  model
1554       backup.  The backup-dumpxml command shows any resulting values assigned
1555       by   libvirt.   For   more   information   on    backup    XML,    see:
1556       https://libvirt.org/formatbackup.html
1557
1558       If --reuse-external is used it instructs libvirt to reuse temporary and
1559       output files provided by the user in backupxml.
1560
1561       If checkpointxml is specified, a second file with a  top-level  element
1562       of  domaincheckpoint  is  used to create a simultaneous checkpoint, for
1563       doing a later incremental backup relative to the time  the  backup  was
1564       created. See checkpoint-create for more details on checkpoints.
1565
1566       This  command  returns  as soon as possible, and the backup job runs in
1567       the background; the progress of a push model backup can be checked with
1568       domjobinfo  or  by  waiting  for an event with event (the progress of a
1569       pull model backup is under the control of whatever third party connects
1570       to the NBD export). The job is ended with domjobabort.
1571
1572   backup-dumpxml
1573       Syntax:
1574
1575          backup-dumpxml [--xpath EXPRESSION] [--wrap] domain
1576
1577       Output XML describing the current backup job.
1578
1579       If the --xpath argument provides an XPath expression, it will be evalu‐
1580       ated against the output XML and  only  those  matching  nodes  will  be
1581       printed.  The  default  behaviour  is  to print each matching node as a
1582       standalone document, however, for ease of  additional  processing,  the
1583       --wrap  argument will cause the matching node to be wrapped in a common
1584       root node.
1585
1586   domiflist
1587       Syntax:
1588
1589          domiflist domain [--inactive]
1590
1591       Print a table showing the brief information of all  virtual  interfaces
1592       associated  with  domain. If --inactive is specified, query the virtual
1593       interfaces that will be used on the next boot, rather than  those  cur‐
1594       rently  in  use  by a running domain. Other contexts that require a MAC
1595       address   of   virtual   interface   (such   as   detach-interface   or
1596       domif-setlink) will accept the MAC address printed by this command.
1597
1598   domifstat
1599       Syntax:
1600
1601          domifstat domain interface-device
1602
1603       Get network interface stats for a running domain. The network interface
1604       stats are only available for interfaces that have a physical source in‐
1605       terface.  This  does  not include, for example, a 'user' interface type
1606       since it is a virtual LAN with NAT to the outside world.  interface-de‐
1607       vice can be the interface target by name or MAC address.
1608
1609   domiftune
1610       Syntax:
1611
1612          domiftune domain interface-device [[--config] [--live] | [--current]]
1613             [*--inbound average,peak,burst,floor*]
1614             [*--outbound average,peak,burst*]
1615
1616       Set  or  query  the  domain's network interface's bandwidth parameters.
1617       interface-device  can  be  the   interface's   target   name   (<target
1618       dev='name'/>), or the MAC address.
1619
1620       If no --inbound or --outbound is specified, this command will query and
1621       show the bandwidth settings. Otherwise, it will set the inbound or out‐
1622       bound bandwidth. average,peak,burst,floor is the same as in command at‐
1623       tach-interface.  Values for average, peak and floor  are  expressed  in
1624       kilobytes per second, while burst is expressed in kilobytes in a single
1625       burst at peak speed as described in the Network  XML  documentation  at
1626       https://libvirt.org/formatnetwork.html#quality-of-service.
1627
1628       To  clear inbound or outbound settings, use --inbound or --outbound re‐
1629       spectfully with average value of zero.
1630
1631       If --live is specified, affect a running guest.  If --config is  speci‐
1632       fied,  affect  the  next  start of a persistent guest.  If --current is
1633       specified, it is equivalent to either --live or --config, depending  on
1634       the  current state of the guest.  Both --live and --config flags may be
1635       given, but --current is exclusive. If no flag is specified, behavior is
1636       different depending on hypervisor.
1637
1638   dominfo
1639       Syntax:
1640
1641          dominfo domain
1642
1643       Returns basic information about the domain.
1644
1645   domjobabort
1646       Syntax:
1647
1648          domjobabort domain [--postcopy]
1649
1650       Abort the currently running domain job.
1651
1652       When the job to be aborted is a migration which entered post-copy mode,
1653       it cannot be aborted as none of the hosts involved in migration  has  a
1654       complete state of the domain. Optional --postcopy can be used to inter‐
1655       rupt such migration although doing so may effectively suspend  the  do‐
1656       main  until the migration is resumed (see also --postcopy-resume option
1657       of migrate).
1658
1659   domjobinfo
1660       Syntax:
1661
1662          domjobinfo domain [--completed [--keep-completed]] [--anystats] [--rawstats]
1663
1664       Returns information about jobs running on a domain.  --completed  tells
1665       virsh  to  return information about a recently finished job. Statistics
1666       of a completed  job  are  automatically  destroyed  once  read  (unless
1667       --keep-completed is used) or when libvirtd is restarted.
1668
1669       Normally  only statistics for running and successful completed jobs are
1670       printed.  --anystats can be used to also display statistics for  failed
1671       jobs.
1672
1673       In case --rawstats is used, all fields are printed as received from the
1674       server without any attempts to interpret  the  data.  The  "Job  type:"
1675       field is special, since it's reported by the API and not part of stats.
1676
1677       Note  that  time  information  returned for completed migrations may be
1678       completely irrelevant unless both source  and  destination  hosts  have
1679       synchronized time (i.e., NTP daemon is running on both of them).
1680
1681   domlaunchsecinfo
1682       Syntax:
1683
1684          domlaunchsecinfo domain
1685
1686       Returns  information  about  the  launch security parameters associated
1687       with a running domain.
1688
1689       The set of parameters reported will vary depending  on  which  type  of
1690       launch  security protection is active. If none is active, no parameters
1691       will be reported.
1692
1693   domsetlaunchsecstate
1694       Syntax:
1695
1696          domsetlaunchsecstate domain --secrethdr hdr-filename
1697              --secret secret-filename [--set-address address]
1698
1699       Set a launch security secret in the guest's memory. The guest must have
1700       a  launchSecurity  type enabled in its configuration and be in a paused
1701       state.  On success, the guest can be transitioned to a  running  state.
1702       On failure, the guest should be destroyed.
1703
1704       --secrethdr  specifies  a filename containing the base64-encoded secret
1705       header.   The  header  includes  artifacts  needed  by  the  hypervisor
1706       firmware to recover the plain text of the launch secret. --secret spec‐
1707       ifies the filename containing the base64-encoded encrypted  launch  se‐
1708       cret.
1709
1710       The  --set-address  option  can  be  used to specify a physical address
1711       within the guest's memory to set the secret. If not specified, the  ad‐
1712       dress will be determined by the hypervisor.
1713
1714   dommemstat
1715       Syntax:
1716
1717          dommemstat domain [--period seconds] [[--config] [--live] | [--current]]
1718
1719       Get memory stats for a running domain.
1720
1721       Availability  of these fields depends on hypervisor. Unsupported fields
1722       are missing from the output. Other fields may appear  if  communicating
1723       with a newer version of libvirtd.
1724
1725       Explanation of fields:
1726
1727swap_in           - The amount of data read from swap space (in KiB)
1728
1729swap_out           -  The  amount of memory written out to swap space
1730         (in KiB)
1731
1732major_fault       - The number of page faults where disk IO  was  re‐
1733         quired
1734
1735minor_fault       - The number of other page faults
1736
1737unused             -  The  amount of memory left unused by the system
1738         (in KiB)
1739
1740available         - The amount of usable memory as seen by the domain
1741         (in KiB)
1742
1743actual            - Current balloon value (in KiB)
1744
1745rss               - Resident Set Size of the running domain's process
1746         (in KiB)
1747
1748usable            - The amount of memory which can  be  reclaimed  by
1749         balloon without causing host swapping (in KiB)
1750
1751last-update        -  Timestamp  of the last update of statistics (in
1752         seconds)
1753
1754disk_caches       - The amount of memory that can be reclaimed  with‐
1755         out additional I/O, typically disk caches (in KiB)
1756
1757hugetlb_pgalloc    -  The  number of successful huge page allocations
1758         initiated from within the domain
1759
1760hugetlb_pgfail    - The number of failed huge page allocations initi‐
1761         ated from within the domain
1762
1763       For  QEMU/KVM with a memory balloon, setting the optional --period to a
1764       value larger than 0 in seconds will allow the balloon driver to  return
1765       additional  statistics which will be displayed by subsequent dommemstat
1766       commands. Setting the --period to 0 will stop the balloon  driver  col‐
1767       lection,  but  does not clear the statistics in the balloon driver. Re‐
1768       quires at least QEMU/KVM 1.5 to be running on the host.
1769
1770       The --live, --config, and --current flags are only valid when using the
1771       --period  option  in order to set the collection period for the balloon
1772       driver. If --live is specified, only the running guest  collection  pe‐
1773       riod  is affected. If --config is specified, affect the next start of a
1774       persistent guest. If --current is specified, it is equivalent to either
1775       --live or --config, depending on the current state of the guest.
1776
1777       Both  --live  and  --config flags may be given, but --current is exclu‐
1778       sive. If no flag is specified, behavior is different depending  on  the
1779       guest state.
1780
1781   domname
1782       Syntax:
1783
1784          domname domain-id-or-uuid
1785
1786       Convert a domain Id (or UUID) to domain name
1787
1788   dompmsuspend
1789       Syntax:
1790
1791          dompmsuspend domain target [--duration]
1792
1793       Suspend a running domain into one of these states (possible target val‐
1794       ues):
1795
1796mem - equivalent of S3 ACPI state
1797
1798disk - equivalent of S4 ACPI state
1799
1800hybrid - RAM is saved to disk but not powered off
1801
1802       The --duration argument specifies number of seconds before  the  domain
1803       is woken up after it was suspended (see also dompmwakeup). Default is 0
1804       for unlimited suspend time. (This feature isn't currently supported  by
1805       any hypervisor driver and 0 should be used.).
1806
1807       Note that this command requires a guest agent configured and running in
1808       the domain's guest OS.
1809
1810       Beware that at least for QEMU, the domain's process will be  terminated
1811       when  target  disk is used and a new process will be launched when lib‐
1812       virt is asked to wake up the domain. As a result of this,  any  runtime
1813       changes,  such  as  device  hotplug or memory settings, are lost unless
1814       such changes were made with --config flag.
1815
1816   dompmwakeup
1817       Syntax:
1818
1819          dompmwakeup domain
1820
1821       Wakeup a domain from pmsuspended state (either suspended  by  dompmsus‐
1822       pend or from the guest itself). Injects a wakeup into the guest that is
1823       in pmsuspended state, rather than waiting for the previously  requested
1824       duration  (if  any) to elapse. This operation does not necessarily fail
1825       if the domain is running.
1826
1827   domrename
1828       Syntax:
1829
1830          domrename domain new-name
1831
1832       Rename a domain. This command changes current domain name  to  the  new
1833       name specified in the second argument.
1834
1835       Note: Domain must be inactive.
1836
1837   domstate
1838       Syntax:
1839
1840          domstate domain [--reason]
1841
1842       Returns  state about a domain.  --reason tells virsh to also print rea‐
1843       son for the state.
1844
1845   domstats
1846       Syntax:
1847
1848          domstats [--raw] [--enforce] [--backing] [--nowait] [--state]
1849             [--cpu-total] [--balloon] [--vcpu] [--interface]
1850             [--block] [--perf] [--iothread] [--memory] [--dirtyrate]
1851             [[--list-active] [--list-inactive]
1852              [--list-persistent] [--list-transient] [--list-running]y
1853              [--list-paused] [--list-shutoff] [--list-other]] | [domain ...]
1854
1855       Get statistics for multiple or all domains. Without any  argument  this
1856       command prints all available statistics for all domains.
1857
1858       The  list of domains to gather stats for can be either limited by list‐
1859       ing the domains as a space separated list, or by specifying one of  the
1860       filtering flags --list-NNN. (The approaches can't be combined.)
1861
1862       By  default  some of the returned fields may be converted to more human
1863       friendly values by a set of pretty-printers. To suppress this  behavior
1864       use the --raw flag.
1865
1866       The  individual statistics groups are selectable via specific flags. By
1867       default all supported statistics groups are returned. Supported statis‐
1868       tics  groups  flags are: --state, --cpu-total, --balloon, --vcpu, --in‐
1869       terface, --block, --perf, --iothread, --memory, --dirtyrate.
1870
1871       Note that - depending on the hypervisor type and version or the  domain
1872       state - not all of the following statistics may be returned.
1873
1874       When selecting the --state group the following fields are returned:
1875
1876state.state - state of the VM, returned as number from virDomainState
1877         enum
1878
1879state.reason - reason for entering given state, returned as int  from
1880         virDomain*Reason enum corresponding to given state
1881
1882       --cpu-total returns:
1883
1884cpu.time - total cpu time spent for this domain in nanoseconds
1885
1886cpu.user - user cpu time spent in nanoseconds
1887
1888cpu.system - system cpu time spent in nanoseconds
1889
1890cpu.haltpoll.success.time  -  cpu  halt polling success time spent in
1891         nanoseconds
1892
1893cpu.haltpoll.fail.time - cpu halt polling fail time spent in nanosec‐
1894         onds
1895
1896cpu.cache.monitor.count  -  the number of cache monitors for this do‐
1897         main
1898
1899cpu.cache.monitor.<num>.name - the name of cache monitor <num>
1900
1901cpu.cache.monitor.<num>.vcpus - vcpu list of cache monitor <num>
1902
1903cpu.cache.monitor.<num>.bank.count - the number  of  cache  banks  in
1904         cache monitor <num>
1905
1906cpu.cache.monitor.<num>.bank.<index>.id - host allocated cache id for
1907         bank <index> in cache monitor <num>
1908
1909cpu.cache.monitor.<num>.bank.<index>.bytes - the number of  bytes  of
1910         last level cache that the domain is using on cache bank <index>
1911
1912       --balloon returns:
1913
1914balloon.current - the memory in KiB currently used
1915
1916balloon.maximum - the maximum memory in KiB allowed
1917
1918balloon.swap_in - the amount of data read from swap space (in KiB)
1919
1920balloon.swap_out - the amount of memory written out to swap space (in
1921         KiB)
1922
1923balloon.major_fault - the number of page faults when disk IO was  re‐
1924         quired
1925
1926balloon.minor_fault - the number of other page faults
1927
1928balloon.unused  -  the amount of memory left unused by the system (in
1929         KiB)
1930
1931balloon.available - the amount of usable memory as seen by the domain
1932         (in KiB)
1933
1934balloon.rss - Resident Set Size of running domain's process (in KiB)
1935
1936balloon.usable  - the amount of memory which can be reclaimed by bal‐
1937         loon without causing host swapping (in KiB)
1938
1939balloon.last-update - timestamp of the last update of statistics  (in
1940         seconds)
1941
1942balloon.disk_caches  -  the  amount  of  memory that can be reclaimed
1943         without additional I/O, typically disk (in KiB)
1944
1945balloon.hugetlb_pgalloc - the number of successful huge page  alloca‐
1946         tions from inside the domain via virtio balloon
1947
1948balloon.hugetlb_pgfail  -  the number of failed huge page allocations
1949         from inside the domain via virtio balloon
1950
1951       --vcpu returns:
1952
1953vcpu.current - current number of online virtual CPUs
1954
1955vcpu.maximum - maximum number of online virtual CPUs
1956
1957vcpu.<num>.state - state of the virtual CPU  <num>,  as  number  from
1958         virVcpuState enum
1959
1960vcpu.<num>.time - virtual cpu time spent by virtual CPU <num> (in mi‐
1961         croseconds)
1962
1963vcpu.<num>.wait - virtual cpu time spent by virtual CPU <num> waiting
1964         on I/O (in microseconds)
1965
1966vcpu.<num>.halted - virtual CPU <num> is halted: yes or no (may indi‐
1967         cate the processor is idle or even disabled, depending on the  archi‐
1968         tecture)
1969
1970vcpu.<num>.delay  -  time  the  vCPU <num> thread was enqueued by the
1971         host scheduler, but was waiting in the queue instead of running.  Ex‐
1972         posed to the VM as a steal time.
1973
1974       --interface returns:
1975
1976net.count - number of network interfaces on this domain
1977
1978net.<num>.name - name of the interface <num>
1979
1980net.<num>.rx.bytes - number of bytes received
1981
1982net.<num>.rx.pkts - number of packets received
1983
1984net.<num>.rx.errs - number of receive errors
1985
1986net.<num>.rx.drop - number of receive packets dropped
1987
1988net.<num>.tx.bytes - number of bytes transmitted
1989
1990net.<num>.tx.pkts - number of packets transmitted
1991
1992net.<num>.tx.errs - number of transmission errors
1993
1994net.<num>.tx.drop - number of transmit packets dropped
1995
1996       --perf returns the statistics of all enabled perf events:
1997
1998perf.cmt - the cache usage in Byte currently used
1999
2000perf.mbmt - total system bandwidth from one level of cache
2001
2002perf.mbml - bandwidth of memory traffic for a memory controller
2003
2004perf.cpu_cycles - the count of cpu cycles (total/elapsed)
2005
2006perf.instructions - the count of instructions
2007
2008perf.cache_references - the count of cache hits
2009
2010perf.cache_misses - the count of caches misses
2011
2012perf.branch_instructions - the count of branch instructions
2013
2014perf.branch_misses - the count of branch misses
2015
2016perf.bus_cycles - the count of bus cycles
2017
2018perf.stalled_cycles_frontend  - the count of stalled frontend cpu cy‐
2019         cles
2020
2021perf.stalled_cycles_backend - the count of stalled backend cpu cycles
2022
2023perf.ref_cpu_cycles - the count of ref cpu cycles
2024
2025perf.cpu_clock - the count of cpu clock time
2026
2027perf.task_clock - the count of task clock time
2028
2029perf.page_faults - the count of page faults
2030
2031perf.context_switches - the count of context switches
2032
2033perf.cpu_migrations - the count of cpu migrations
2034
2035perf.page_faults_min - the count of minor page faults
2036
2037perf.page_faults_maj - the count of major page faults
2038
2039perf.alignment_faults - the count of alignment faults
2040
2041perf.emulation_faults - the count of emulation faults
2042
2043       See the perf command for more details about each event.
2044
2045       --block returns information about disks associated  with  each  domain.
2046       Using  the  --backing  flag  extends  this information to cover all re‐
2047       sources in the backing chain, rather than the default of  limiting  in‐
2048       formation  to the active layer for each guest disk.  Information listed
2049       includes:
2050
2051block.count - number of block devices being listed
2052
2053block.<num>.name - name of the target of the block device <num>  (the
2054         same name for multiple entries if --backing is present)
2055
2056block.<num>.backingIndex - when --backing is present, matches up with
2057         the <backingStore> index listed in domain XML for backing files
2058
2059block.<num>.path - file source of block device <num>, if it is a  lo‐
2060         cal file or block device
2061
2062block.<num>.rd.reqs - number of read requests
2063
2064block.<num>.rd.bytes - number of read bytes
2065
2066block.<num>.rd.times - total time (ns) spent on reads
2067
2068block.<num>.wr.reqs - number of write requests
2069
2070block.<num>.wr.bytes - number of written bytes
2071
2072block.<num>.wr.times - total time (ns) spent on writes
2073
2074block.<num>.fl.reqs - total flush requests
2075
2076block.<num>.fl.times - total time (ns) spent on cache flushing
2077
2078block.<num>.errors - Xen only: the 'oo_req' value
2079
2080block.<num>.allocation - offset of highest written sector in bytes
2081
2082block.<num>.capacity - logical size of source file in bytes
2083
2084block.<num>.physical - physical size of source file in bytes
2085
2086block.<num>.threshold  -  threshold  (in  bytes)  for  delivering the
2087         VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event. See domblkthreshold.
2088
2089       --iothread returns information about IOThreads on the running guest  if
2090       supported by the hypervisor.
2091
2092       The  "poll-max-ns"  for each thread is the maximum nanoseconds to allow
2093       each polling interval to occur. A polling interval is a period of  time
2094       allowed  for  a  thread to process data before being the guest gives up
2095       its CPU quantum back to the host. A value set too small will not  allow
2096       the  IOThread  to run long enough on a CPU to process data. A value set
2097       too high will consume too much CPU time per IOThread failing  to  allow
2098       other  threads  running on the CPU to get time. The polling interval is
2099       not available for statistical purposes.
2100
2101
2102
2103         iothread.count - maximum number of IOThreads in the subsequent list
2104                as unsigned int. Each IOThread in the list will will use  it's
2105                iothread_id value as the <id>. There may be fewer <id> entries
2106                than the iothread.count value if the polling  values  are  not
2107                supported.
2108
2109iothread.<id>.poll-max-ns  - maximum polling time in nanoseconds used
2110         by the <id> IOThread. A value of 0 (zero) indicates polling  is  dis‐
2111         abled.
2112
2113iothread.<id>.poll-grow  -  polling  time  grow  value.  A value of 0
2114         (zero) growth is managed by the hypervisor.
2115
2116iothread.<id>.poll-shrink - polling time shrink  value.  A  value  of
2117         (zero) indicates shrink is managed by hypervisor.
2118
2119       --memory returns:
2120
2121memory.bandwidth.monitor.count - the number of memory bandwidth moni‐
2122         tors for this domain
2123
2124memory.bandwidth.monitor.<num>.name  - the name of monitor <num>
2125
2126memory.bandwidth.monitor.<num>.vcpus - the vcpu list of monitor <num>
2127
2128
2129
2130         memory.bandwidth.monitor.<num>.node.count - the number of memory
2131                controller in monitor <num>
2132
2133memory.bandwidth.monitor.<num>.node.<index>.id - host allocated  mem‐
2134         ory controller id for controller <index> of monitor <num>
2135
2136memory.bandwidth.monitor.<num>.node.<index>.bytes.local - the accumu‐
2137         lative bytes consumed by @vcpus that passing through the memory  con‐
2138         troller in the same processor that the scheduled host CPU belongs to.
2139
2140memory.bandwidth.monitor.<num>.node.<index>.bytes.total  -  the total
2141         bytes consumed by @vcpus that passing through all memory controllers,
2142         either local or remote controller.
2143
2144       --dirtyrate returns:
2145
2146dirtyrate.calc_status - the status of last memory dirty rate calcula‐
2147         tion, returned as number from virDomainDirtyRateStatus enum.
2148
2149dirtyrate.calc_start_time - the start time of last memory dirty  rate
2150         calculation.
2151
2152dirtyrate.calc_period - the period of last memory dirty rate calcula‐
2153         tion.
2154
2155dirtyrate.megabytes_per_second - the calculated memory dirty rate  in
2156         MiB/s.
2157
2158dirtyrate.calc_mode  -  the  calculation  mode  used last measurement
2159         (page-sampling/dirty-bitmap/dirty-ring)
2160
2161dirtyrate.vcpu.<num>.megabytes_per_second  -  the  calculated  memory
2162         dirty rate for a virtual cpu in MiB/s
2163
2164       Selecting  a specific statistics groups doesn't guarantee that the dae‐
2165       mon supports the selected group of stats.  Flag  --enforce  forces  the
2166       command to fail if the daemon doesn't support the selected group.
2167
2168       When  collecting  stats  libvirtd may wait for some time if there's al‐
2169       ready another job running on given domain for it to finish.   This  may
2170       cause  unnecessary delay in delivering stats. Using --nowait suppresses
2171       this behaviour. On the other hand some statistics might be missing  for
2172       such domain.
2173
2174   domtime
2175       Syntax:
2176
2177          domtime domain { [--now] [--pretty] [--sync] [--time time] }
2178
2179       Gets  or  sets the domain's system time. When run without any arguments
2180       (but domain), the current domain's system  time  is  printed  out.  The
2181       --pretty  modifier can be used to print the time in more human readable
2182       form.
2183
2184       When --time time is specified, the domain's time is not gotten but  set
2185       instead.  The  --now  modifier  acts like if it was an alias for --time
2186       $now, which means it sets the time that is currently on the host  virsh
2187       is  running at. In both cases (setting and getting), time is in seconds
2188       relative to Epoch of 1970-01-01 in UTC.  The --sync  modifies  the  set
2189       behavior a bit: The time passed is ignored, but the time to set is read
2190       from domain's RTC instead. Please note, that some hypervisors  may  re‐
2191       quire  a  guest agent to be configured in order to get or set the guest
2192       time.
2193
2194   domuuid
2195       Syntax:
2196
2197          domuuid domain-name-or-id
2198
2199       Convert a domain name or id to domain UUID
2200
2201   domxml-from-native
2202       Syntax:
2203
2204          domxml-from-native format config
2205
2206       Convert the file config in the native guest configuration format  named
2207       by  format  to a domain XML format. For QEMU/KVM hypervisor, the format
2208       argument must be qemu-argv. For Xen hypervisor, the format argument may
2209       be xen-xm, xen-xl, or xen-sxpr. For LXC hypervisor, the format argument
2210       must be lxc-tools. For VMware/ESX hypervisor, the format argument  must
2211       be  vmware-vmx.   For the Bhyve hypervisor, the format argument must be
2212       bhyve-argv.
2213
2214   domxml-to-native
2215       Syntax:
2216
2217          domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-uuid }
2218
2219       Convert the file xml into domain XML  format  or  convert  an  existing
2220       --domain to the native guest configuration format named by format.  The
2221       xml and --domain arguments are mutually exclusive.  For  the  types  of
2222       format argument, refer to domxml-from-native.
2223
2224   dump
2225       Syntax:
2226
2227          dump domain corefilepath [--bypass-cache]
2228             { [--live] | [--crash] | [--reset] }
2229             [--verbose] [--memory-only] [--format string]
2230
2231       Dumps the core of a domain to a file for analysis.  If --live is speci‐
2232       fied, the domain continues to run until  the  core  dump  is  complete,
2233       rather  than  pausing up front.  If --crash is specified, the domain is
2234       halted with a crashed status, rather  than  merely  left  in  a  paused
2235       state.   If  --reset is specified, the domain is reset after successful
2236       dump.  Note, these three switches are  mutually  exclusive.   If  --by‐
2237       pass-cache is specified, the save will avoid the file system cache, al‐
2238       though this may slow down the operation.  If  --memory-only  is  speci‐
2239       fied,  the  file is elf file, and will only include domain's memory and
2240       cpu common register value. It is very useful if the  domain  uses  host
2241       devices  directly.   --format  string  is used to specify the format of
2242       'memory-only'   dump,   and   string    can    be    one    of:    elf,
2243       kdump-zlib(kdump-compressed      format      with     zlib-compressed),
2244       kdump-lzo(kdump-compressed      format      with       lzo-compressed),
2245       kdump-snappy(kdump-compressed     format    with    snappy-compressed),
2246       win-dmp(Windows full crashdump format).
2247
2248       The progress may be monitored using domjobinfo virsh command  and  can‐
2249       celed  with  domjobabort  command (sent by another virsh instance). An‐
2250       other option is to send SIGINT  (usually  with  Ctrl-C)  to  the  virsh
2251       process running dump command. --verbose displays the progress of dump.
2252
2253       NOTE:  Some  hypervisors may require the user to manually ensure proper
2254       permissions on file and path specified by argument corefilepath.
2255
2256       NOTE: Crash dump in a old kvmdump format is being obsolete  and  cannot
2257       be  loaded  and  processed  by crash utility since its version 6.1.0. A
2258       --memory-only option is required in order to  produce  valid  ELF  file
2259       which can be later processed by the crash utility.
2260
2261   dumpxml
2262       Syntax:
2263
2264          dumpxml [--inactive] [--security-info] [--update-cpu] [--migratable]
2265                  [--xpath EXPRESSION] [--wrap] domain
2266
2267       Output the domain information as an XML dump to stdout, this format can
2268       be used by the create command. Additional  options  affecting  the  XML
2269       dump  may  be used. --inactive tells virsh to dump domain configuration
2270       that will be used on next start of the domain as opposed to the current
2271       domain configuration.  Using --security-info will also include security
2272       sensitive information in the XML dump. --update-cpu updates domain  CPU
2273       requirements  according  to host CPU. With --migratable one can request
2274       an XML that is suitable for migrations,  i.e.,  compatible  with  older
2275       libvirt  releases  and possibly amended with internal run-time options.
2276       This option may automatically enable other options (--update-cpu, --se‐
2277       curity-info, ...) as necessary.
2278
2279       If the --xpath argument provides an XPath expression, it will be evalu‐
2280       ated against the output XML and  only  those  matching  nodes  will  be
2281       printed.  The  default  behaviour  is  to print each matching node as a
2282       standalone document, however, for ease of  additional  processing,  the
2283       --wrap  argument will cause the matching node to be wrapped in a common
2284       root node.
2285
2286   edit
2287       Syntax:
2288
2289          edit domain
2290
2291       Edit the XML configuration file for a domain,  which  will  affect  the
2292       next boot of the guest.
2293
2294       This is equivalent to:
2295
2296          virsh dumpxml --inactive --security-info domain > domain.xml
2297          vi domain.xml (or make changes with your other text editor)
2298          virsh define domain.xml
2299
2300       except that it does some error checking.
2301
2302       The  editor  used can be supplied by the $VISUAL or $EDITOR environment
2303       variables, and defaults to vi.
2304
2305   emulatorpin
2306       Syntax:
2307
2308          emulatorpin domain [cpulist] [[--live] [--config]  | [--current]]
2309
2310       Query or change the pinning of domain's emulator threads to host physi‐
2311       cal CPUs.
2312
2313       See vcpupin for cpulist.
2314
2315       If  --live is specified, affect a running guest.  If --config is speci‐
2316       fied, affect the next start of a persistent  guest.   If  --current  is
2317       specified,  it is equivalent to either --live or --config, depending on
2318       the current state of the guest.  Both --live and --config flags may  be
2319       given if cpulist is present, but --current is exclusive.  If no flag is
2320       specified, behavior is different depending on hypervisor.
2321
2322   event
2323       Syntax:
2324
2325          event {[domain] { event | --all } [--loop] [--timeout seconds] [--timestamp] | --list}
2326
2327       Wait for a class of domain events to occur, and print  appropriate  de‐
2328       tails  of events as they happen.  The events can optionally be filtered
2329       by domain.  Using --list as the only argument will provide  a  list  of
2330       possible  event  values  known  by this client, although the connection
2331       might not allow registering for all these events.  It is also  possible
2332       to  use --all instead of event to register for all possible event types
2333       at once.
2334
2335       By default, this command is one-shot, and returns success once an event
2336       occurs;  you  can send SIGINT (usually via Ctrl-C) to quit immediately.
2337       If --timeout is specified, the command gives up waiting for events  af‐
2338       ter  seconds have elapsed.   With --loop, the command prints all events
2339       until a timeout or interrupt key.
2340
2341       When --timestamp is used, a human-readable timestamp  will  be  printed
2342       before the event.
2343
2344   get-user-sshkeys
2345       Syntax:
2346
2347          get-user-sshkeys domain user
2348
2349       Print  SSH  authorized  keys for given user in the guest domain. Please
2350       note, that an entry in the file has internal structure  as  defined  by
2351       sshd(8) and virsh/libvirt does handle keys as opaque strings, i.e. does
2352       not interpret them.
2353
2354   guest-agent-timeout
2355       Syntax:
2356
2357          guest-agent-timeout domain [--timeout value]
2358
2359       Set how long to wait for a response from guest agent commands.  By  de‐
2360       fault,  agent commands block forever waiting for a response. value must
2361       be a positive value (wait for given amount of seconds) or  one  of  the
2362       following values:
2363
2364       • -2 - block forever waiting for a result (used when --timeout is omit‐
2365         ted),
2366
2367       • -1 - reset timeout to the default value (currently defined as 5  sec‐
2368         onds in libvirt daemon),
2369
2370       • 0 - do not wait at all,
2371
2372   guestinfo
2373       Syntax:
2374
2375          guestinfo domain [--user] [--os] [--timezone] [--hostname] [--filesystem]
2376             [--disk] [--interface]
2377
2378       Print  information  about the guest from the point of view of the guest
2379       agent.  Note that this command requires a guest agent to be  configured
2380       and running in the domain's guest OS.
2381
2382       When  run  without  any  arguments, this command prints all information
2383       types that are supported by the guest agent at that point, omitting un‐
2384       available ones.  Success is always reported in this case.
2385
2386       You  can limit the types of information that are returned by specifying
2387       one or more flags.  Available information types flags are --user, --os,
2388       --timezone,  --hostname,  --filesystem,  --disk and --interface.  If an
2389       explicitly requested information type is not  supported  by  the  guest
2390       agent at that point, the processes will provide an exit code of 1.
2391
2392       Note that depending on the hypervisor type and the version of the guest
2393       agent running within the domain, not all of the  following  information
2394       may be returned.
2395
2396       When selecting the --user information type, the following fields may be
2397       returned:
2398
2399user.count - the number of active users on this domain
2400
2401user.<num>.name - username of user <num>
2402
2403user.<num>.domain - domain of the user <num> (may only be present  on
2404         certain guets types)
2405
2406user.<num>.login-time  - the login time of user <num> in milliseconds
2407         since the epoch
2408
2409       --os returns:
2410
2411os.id - a string identifying the operating system
2412
2413os.name - the name of the operating system
2414
2415os.pretty-name - a pretty name for the operating system
2416
2417os.version - the version of the operating system
2418
2419os.version-id - the version id of the operating system
2420
2421os.kernel-release - the release of the operating system kernel
2422
2423os.kernel-version - the version of the operating system kernel
2424
2425os.machine - the machine hardware name
2426
2427os.variant - a specific variant or edition of the operating system
2428
2429os.variant-id - the id for a specific variant or edition of the oper‐
2430         ating system
2431
2432       --timezone returns:
2433
2434timezone.name - the name of the timezone
2435
2436timezone.offset - the offset to UTC in seconds
2437
2438       --hostname returns:
2439
2440hostname - the hostname of the domain
2441
2442       --filesystem returns:
2443
2444fs.count - the number of filesystems defined on this domain
2445
2446fs.<num>.mountpoint  -  the  path  to  the mount point for filesystem
2447         <num>
2448
2449fs.<num>.name - device name in the guest (e.g. sda1)  for  filesystem
2450         <num>
2451
2452fs.<num>.fstype - the type of filesystem <num>
2453
2454fs.<num>.total-bytes - the total size of filesystem <num>
2455
2456fs.<num>.used-bytes - the number of bytes used in filesystem <num>
2457
2458fs.<num>.disk.count  -  the  number  of  disks targeted by filesystem
2459         <num>
2460
2461fs.<num>.disk.<num>.alias - the device alias of disk <num> (e.g. sda)
2462
2463fs.<num>.disk.<num>.serial - the serial number of disk <num>
2464
2465fs.<num>.disk.<num>.device - the device node of disk <num>
2466
2467       --disk returns:
2468
2469disk.count - the number of disks defined on this domain
2470
2471disk.<num>.name - device node (Linux) or device UNC (Windows)
2472
2473disk.<num>.partition - whether this is a partition or disk
2474
2475disk.<num>.dependency.count - the number of device dependencies
2476
2477disk.<num>.dependency.<num>.name - a dependency name
2478
2479disk.<num>.serial -  optional disk serial number
2480
2481disk.<num>.alias - the device alias of the disk (e.g. sda)
2482
2483disk.<num>.guest_alias - optional alias assigned to the disk
2484
2485       --interface returns: * if.count - the number of interfaces  defined  on
2486       this  domain * if.<num>.name - name in the guest (e.g. eth0) for inter‐
2487       face <num> * if.<num>.hwaddr - hardware address in the guest for inter‐
2488       face <num> * if.<num>.addr.count - the number of IP addresses of inter‐
2489       face <num> * if.<num>.addr.<num1>.type - the IP address  type  of  addr
2490       <num1> (e.g. ipv4) * if.<num>.addr.<num1>.addr - the IP address of addr
2491       <num1> * if.<num>.addr.<num1>.prefix - the prefix of IP address of addr
2492       <num1>
2493
2494   guestvcpus
2495       Syntax:
2496
2497          guestvcpus domain [[--enable] | [--disable]] [cpulist]
2498
2499       Query  or  change  state  of vCPUs from guest's point of view using the
2500       guest agent.  When invoked without cpulist the  guest  is  queried  for
2501       available guest vCPUs, their state and possibility to be offlined.
2502
2503       If  cpulist  is provided then one of --enable or --disable must be pro‐
2504       vided too. The desired operation is then executed on the domain.
2505
2506       See vcpupin for information on cpulist.
2507
2508   iothreadadd
2509       Syntax:
2510
2511          iothreadadd domain iothread_id [[--config] [--live] | [--current]]
2512
2513       Add a new IOThread to the domain using the specified  iothread_id.   If
2514       the  iothread_id already exists, the command will fail. The iothread_id
2515       must be greater than zero.
2516
2517       If --live is specified, affect a running guest. If  the  guest  is  not
2518       running  an  error  is  returned.  If --config is specified, affect the
2519       next start of a persistent guest.  If --current  is  specified,  it  is
2520       equivalent to either --live or --config, depending on the current state
2521       of the guest.
2522
2523   iothreaddel
2524       Syntax:
2525
2526          iothreaddel domain iothread_id [[--config] [--live] | [--current]]
2527
2528       Delete an IOThread from the domain using the specified iothread_id.  If
2529       an  IOThread  is  currently assigned to a disk resource such as via the
2530       attach-disk command, then the attempt to remove the IOThread will fail.
2531       If the iothread_id does not exist an error will occur.
2532
2533       If  --live  is  specified,  affect a running guest. If the guest is not
2534       running an error is returned.  If --config  is  specified,  affect  the
2535       next  start  of  a  persistent guest.  If --current is specified, it is
2536       equivalent to either --live or --config, depending on the current state
2537       of the guest.
2538
2539   iothreadinfo
2540       Syntax:
2541
2542          iothreadinfo domain [[--live] [--config] | [--current]]
2543
2544       Display  basic  domain  IOThreads information including the IOThread ID
2545       and the CPU Affinity for each IOThread.
2546
2547       If --live is specified, get the IOThreads data from the running  guest.
2548       If  the  guest  is  not  running, an error is returned.  If --config is
2549       specified, get the IOThreads data from the next start of  a  persistent
2550       guest.  If --current is specified or --live and --config are not speci‐
2551       fied, then get the IOThread data based  on  the  current  guest  state,
2552       which can either be live or offline.
2553
2554   iothreadpin
2555       Syntax:
2556
2557          iothreadpin domain iothread cpulist [[--live] [--config] | [--current]]
2558
2559       Change the pinning of a domain IOThread to host physical CPUs. In order
2560       to retrieve a list of all IOThreads, use iothreadinfo. To  pin  an  io‐
2561       thread specify the cpulist desired for the IOThread ID as listed in the
2562       iothreadinfo output.
2563
2564       cpulist is a list of physical CPU numbers. Its syntax is a comma  sepa‐
2565       rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
2566       can also be allowed. The '-' denotes the range and the '^' denotes  ex‐
2567       clusive.   If you want to reset iothreadpin setting, that is, to pin an
2568       iothread to all physical cpus, simply specify 'r' as a cpulist.
2569
2570       If --live is specified, affect a running guest. If  the  guest  is  not
2571       running,  an  error  is returned.  If --config is specified, affect the
2572       next start of a persistent guest.  If --current  is  specified,  it  is
2573       equivalent to either --live or --config, depending on the current state
2574       of the guest.  Both --live and --config flags may be given  if  cpulist
2575       is  present,  but --current is exclusive.  If no flag is specified, be‐
2576       havior is different depending on hypervisor.
2577
2578       Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
2579       cal to "9-14,0-7,15" but not identical to "^8,0-15".
2580
2581   iothreadset
2582       Syntax:
2583
2584          iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor]
2585             [--poll-shrink divisor] [--thread-pool-min value]
2586             [--thread-pool-max value]]
2587             [[--config] [--live] | [--current]]
2588
2589       Modifies  an  existing  iothread  of the domain using the specified io‐
2590       thread_id. The --poll-max-ns provides the maximum polling  interval  to
2591       be  allowed  for  an  IOThread  in  ns. If a 0 (zero) is provided, then
2592       polling for the IOThread is disabled.  The --poll-grow is the factor by
2593       which  the  current polling time will be adjusted in order to reach the
2594       maximum polling time. If a 0 (zero) is provided, then the default  fac‐
2595       tor  will  be used. The --poll-shrink is the quotient by which the cur‐
2596       rent polling time will be reduced in order to  get  below  the  maximum
2597       polling  interval. If a 0 (zero) is provided, then the default quotient
2598       will be used. The polling values  are  purely  dynamic  for  a  running
2599       guest.  Saving, destroying, stopping, etc. the guest will result in the
2600       polling values returning to hypervisor defaults at the next start,  re‐
2601       store, etc.
2602
2603       The  --thread-pool-min and --thread-pool-max options then set lower and
2604       upper bound, respectively of number of threads in worker pool of  given
2605       iothread.  For changes to an inactive configuration -1 can be specified
2606       to remove corresponding boundary from  the  domain  configuration.  For
2607       changes  to  a running guest it's recommended to set the upper boundary
2608       first (--thread-pool-max) and only after that set  the  lower  boundary
2609       (--thread-pool-min).  It  is  allowed  for the lower boundary to be the
2610       same as the upper boundary, however it's  not  allowed  for  the  upper
2611       boundary to be value of zero.
2612
2613       If  --live  is  specified,  affect a running guest. If the guest is not
2614       running an error is returned.  If --current is specified or  --live  is
2615       not  specified,  then  handle as if --live was specified.  (Where "cur‐
2616       rent" here means whatever the present guest state is: live or offline.)
2617
2618   managedsave
2619       Syntax:
2620
2621          managedsave domain [--bypass-cache] [{--running | --paused}] [--verbose]
2622
2623       Save and destroy (stop) a running domain, so it can be  restarted  from
2624       the  same  state at a later time.  When the virsh start command is next
2625       run for the domain, it will automatically be started  from  this  saved
2626       state.   If  --bypass-cache  is specified, the save will avoid the file
2627       system cache, although this may slow down the operation.
2628
2629       The progress may be monitored using domjobinfo virsh command  and  can‐
2630       celed  with  domjobabort  command (sent by another virsh instance). An‐
2631       other option is to send SIGINT  (usually  with  Ctrl-C)  to  the  virsh
2632       process running managedsave command. --verbose displays the progress of
2633       save.
2634
2635       Normally, starting a managed save will decide between running or paused
2636       based  on  the  state the domain was in when the save was done; passing
2637       either the --running or --paused flag will allow overriding which state
2638       the start should use.
2639
2640       The dominfo command can be used to query whether a domain currently has
2641       any managed save image.
2642
2643   managedsave-define
2644       Syntax:
2645
2646          managedsave-define domain xml [{--running | --paused}]
2647
2648       Update the domain XML that will be used when domain is  later  started.
2649       The  xml  argument  must be a file name containing the alternative XML,
2650       with changes only in the host-specific portions of the domain XML.  For
2651       example, it can be used to change disk file paths.
2652
2653       The  managed save image records whether the domain should be started to
2654       a running or paused state.  Normally, this command does not  alter  the
2655       recorded  state; passing either the --running or --paused flag will al‐
2656       low overriding which state the start should use.
2657
2658   managedsave-dumpxml
2659       Syntax:
2660
2661          managedsave-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap] domain
2662
2663       Extract the domain XML that was in effect at the time the  saved  state
2664       file  file  was  created  with  the managedsave command.  Using --secu‐
2665       rity-info will also include security sensitive information.
2666
2667       If the --xpath argument provides an XPath expression, it will be evalu‐
2668       ated  against  the  output  XML  and  only those matching nodes will be
2669       printed. The default behaviour is to print  each  matching  node  as  a
2670       standalone  document,  however,  for ease of additional processing, the
2671       --wrap argument will cause the matching node to be wrapped in a  common
2672       root node.
2673
2674   managedsave-edit
2675       Syntax:
2676
2677          managedsave-edit domain [{--running | --paused}]
2678
2679       Edit  the XML configuration associated with a saved state file of a do‐
2680       main was created by the managedsave command.
2681
2682       The managed save image records whether the domain should be started  to
2683       a  running  or paused state.  Normally, this command does not alter the
2684       recorded state; passing either the --running or --paused flag will  al‐
2685       low overriding which state the restore should use.
2686
2687       This is equivalent to:
2688
2689          virsh managedsave-dumpxml domain-name > state-file.xml
2690          vi state-file.xml (or make changes with your other text editor)
2691          virsh managedsave-define domain-name state-file-xml
2692
2693       except that it does some error checking.
2694
2695       The  editor  used can be supplied by the $VISUAL or $EDITOR environment
2696       variables, and defaults to vi.
2697
2698   managedsave-remove
2699       Syntax:
2700
2701          managedsave-remove domain
2702
2703       Remove the managedsave state file for a domain, if it exists.  This en‐
2704       sures the domain will do a full boot the next time it is started.
2705
2706   maxvcpus
2707       Syntax:
2708
2709          maxvcpus [type]
2710
2711       Provide  the maximum number of virtual CPUs supported for a guest VM on
2712       this connection.  If provided, the type parameter must be a valid  type
2713       attribute for the <domain> element of XML.
2714
2715   memtune
2716       Syntax:
2717
2718          memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-limit size]
2719             [--min-guarantee size] [[--config] [--live] | [--current]]
2720
2721       Allows  you  to  display  or  set the domain memory parameters. Without
2722       flags, the current settings are displayed; with a flag, the appropriate
2723       limit  is  adjusted  if  supported by the hypervisor.  LXC and QEMU/KVM
2724       support --hard-limit, --soft-limit, and --swap-hard-limit.  --min-guar‐
2725       antee  is  supported  only by ESX hypervisor.  Each of these limits are
2726       scaled integers (see NOTES above), with a default of kibibytes  (blocks
2727       of  1024 bytes) if no suffix is present. Libvirt rounds up to the near‐
2728       est kibibyte.  Some hypervisors require a larger granularity than  KiB,
2729       and requests that are not an even multiple will be rounded up.  For ex‐
2730       ample,  vSphere/ESX  rounds  the  parameter  up  to   mebibytes   (1024
2731       kibibytes).
2732
2733       If  --live is specified, affect a running guest.  If --config is speci‐
2734       fied, affect the next start of a persistent  guest.   If  --current  is
2735       specified,  it is equivalent to either --live or --config, depending on
2736       the current state of the guest.  Both --live and --config flags may  be
2737       given, but --current is exclusive. If no flag is specified, behavior is
2738       different depending on hypervisor.
2739
2740       For QEMU/KVM, the parameters are applied  to  the  QEMU  process  as  a
2741       whole.   Thus, when counting them, one needs to add up guest RAM, guest
2742       video RAM, and some memory overhead of QEMU itself.  The last piece  is
2743       hard to determine so one needs guess and try.
2744
2745       For  LXC,  the displayed hard_limit value is the current memory setting
2746       from the XML or the results from a virsh setmem command.
2747
2748--hard-limit
2749
2750         The maximum memory the guest can use.
2751
2752--soft-limit
2753
2754         The memory limit to enforce during memory contention.
2755
2756--swap-hard-limit
2757
2758         The maximum memory plus swap the guest can use.  This has to be  more
2759         than hard-limit value provided.
2760
2761--min-guarantee
2762
2763         The guaranteed minimum memory allocation for the guest.
2764
2765       Specifying -1 as a value for these limits is interpreted as unlimited.
2766
2767   metadata
2768       Syntax:
2769
2770          metadata domain [[--live] [--config] | [--current]]
2771             [--edit] [uri] [key] [set] [--remove]
2772
2773       Show  or modify custom XML metadata of a domain. The metadata is a user
2774       defined XML that allows storing arbitrary XML data in the domain  defi‐
2775       nition.   Multiple separate custom metadata pieces can be stored in the
2776       domain XML.  The pieces are identified by a private XML namespace  pro‐
2777       vided  via  the  uri  argument.  (See also desc that works with textual
2778       metadata of a domain.)
2779
2780       Flags --live or --config select whether this command works on  live  or
2781       persistent  definitions  of the domain. If both --live and --config are
2782       specified, the --config option takes precedence on getting the  current
2783       description  and  both  live configuration and config are updated while
2784       setting the description. --current is exclusive and implied if none  of
2785       these was specified.
2786
2787       Flag  --remove specifies that the metadata element specified by the uri
2788       argument should be removed rather than updated.
2789
2790       Flag --edit specifies that an editor with the  metadata  identified  by
2791       the  uri  argument  should be opened and the contents saved back after‐
2792       wards.  Otherwise the new contents can be provided via  the  set  argu‐
2793       ment.
2794
2795       When setting metadata via --edit or set the key argument must be speci‐
2796       fied and is used to prefix the custom elements to bind them to the pri‐
2797       vate namespace.
2798
2799       If neither of --edit and set are specified the XML metadata correspond‐
2800       ing to the uri namespace is displayed instead of being modified.
2801
2802   migrate
2803       Syntax:
2804
2805          migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]]
2806             [--persistent] [--undefinesource] [--suspend] [--copy-storage-all]
2807             [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose]
2808             [--rdma-pin-all] [--abort-on-error] [--postcopy]
2809             [--postcopy-after-precopy] [--postcopy-resume] [--zerocopy]
2810             domain desturi [migrateuri] [graphicsuri] [listen-address] [dname]
2811             [--timeout seconds [--timeout-suspend | --timeout-postcopy]]
2812             [--xml file] [--migrate-disks disk-list] [--disks-port port]
2813             [--compressed] [--comp-methods method-list]
2814             [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads]
2815             [--comp-xbzrle-cache] [--auto-converge] [auto-converge-initial]
2816             [auto-converge-increment] [--persistent-xml file] [--tls]
2817             [--postcopy-bandwidth bandwidth]
2818             [--parallel [--parallel-connections connections]]
2819             [--bandwidth bandwidth] [--tls-destination hostname]
2820             [--disks-uri URI] [--copy-storage-synchronous-writes]
2821
2822       Migrate domain to another host.  Add --live for live migration; <--p2p>
2823       for  peer-2-peer  migration;  --direct  for direct migration; or --tun‐
2824       nelled for tunnelled migration.  --offline migrates  domain  definition
2825       without  starting  the domain on destination and without stopping it on
2826       source host.  Offline migration may be used with inactive  domains  and
2827       it must be used with --persistent option.
2828
2829       --persistent  leaves the domain persistent on destination host, --unde‐
2830       finesource undefines the domain  on  the  source  host,  and  --suspend
2831       leaves the domain paused on the destination host.
2832
2833       --copy-storage-all  indicates  migration  with  non-shared storage with
2834       full disk copy, --copy-storage-inc indicates migration with  non-shared
2835       storage  with  incremental  copy (same base image shared between source
2836       and destination).  In both cases the disk images have to exist on  des‐
2837       tination  host,  the  --copy-storage-...  options  only tell libvirt to
2838       transfer data from the images on source host to the images found at the
2839       same  place  on  the  destination  host.  By  default  only  non-shared
2840       non-readonly images are transferred. Use --migrate-disks to  explicitly
2841       specify  a  list  of  disk  targets to transfer via the comma separated
2842       disk-list argument.  With --copy-storage-synchronous-writes  flag  used
2843       the  disk data migration will synchronously handle guest disk writes to
2844       both the original source and the destination to ensure  that  the  disk
2845       migration  converges  at  the price of possibly decreased burst perfor‐
2846       mance.
2847
2848       --change-protection enforces that no incompatible configuration changes
2849       will  be  made to the domain while the migration is underway; this flag
2850       is implicitly enabled when supported by the hypervisor, but can be  ex‐
2851       plicitly  used  to  reject the migration if the hypervisor lacks change
2852       protection support.
2853
2854       --verbose displays the progress of migration.
2855
2856       --abort-on-error cancels the migration if a soft error (for example I/O
2857       error) happens during the migration.
2858
2859       --postcopy  enables post-copy logic in migration, but does not actually
2860       start post-copy, i.e., migration is started in pre-copy mode.  Once mi‐
2861       gration  is  running,  the  user  may switch to post-copy using the mi‐
2862       grate-postcopy command sent from another virsh instance or use  --post‐
2863       copy-after-precopy  along  with --postcopy to let libvirt automatically
2864       switch to post-copy after the first pass of pre-copy is finished.   The
2865       maximum  bandwidth  consumed  during the post-copy phase may be limited
2866       using --postcopy-bandwidth. The maximum bandwidth consumed  during  the
2867       pre-copy phase may be limited using --bandwidth. In case connection be‐
2868       tween the hosts breaks while migration is in post-copy mode, the domain
2869       cannot  be resumed on either source or destination host and the migrate
2870       command will report an error leaving the domain active on  both  hosts.
2871       To recover from such situation repeat the original migrate command with
2872       an additional --postcopy-resume flag.
2873
2874       --auto-converge forces convergence during live migration.  The  initial
2875       guest CPU throttling rate can be set with auto-converge-initial. If the
2876       initial throttling rate is not enough to ensure convergence,  the  rate
2877       is periodically increased by auto-converge-increment.
2878
2879       --rdma-pin-all  can  be used with RDMA migration (i.e., when migrateuri
2880       starts with rdma://) to tell the hypervisor to pin all domain's  memory
2881       at once before migration starts rather than letting it pin memory pages
2882       as needed. For QEMU/KVM this requires hard_limit memory tuning  element
2883       (in the domain XML) to be used and set to the maximum memory configured
2884       for the domain plus any memory consumed by the QEMU process itself. Be‐
2885       ware of setting the memory limit too high (and thus allowing the domain
2886       to lock most of the host's memory). Doing so may be dangerous  to  both
2887       the  domain  and the host itself since the host's kernel may run out of
2888       memory.
2889
2890       --zerocopy requests zero-copy mechanism to be used for migrating memory
2891       pages.   For  QEMU/KVM  this  means QEMU will be temporarily allowed to
2892       lock all guest pages in host's memory, although  only  those  that  are
2893       queued for transfer will be locked at the same time.
2894
2895       Note:  Individual hypervisors usually do not support all possible types
2896       of migration. For example, QEMU does not support direct migration.
2897
2898       In some cases libvirt may refuse to migrate the domain because doing so
2899       may  lead  to  potential problems such as data corruption, and thus the
2900       migration is considered unsafe. For QEMU domain, this may happen if the
2901       domain  uses disks without explicitly setting cache mode to "none". Mi‐
2902       grating such domains is unsafe unless the disk images are stored on co‐
2903       herent  clustered filesystem, such as GFS2 or GPFS. If you are sure the
2904       migration is safe or you just do not care, use --unsafe  to  force  the
2905       migration.
2906
2907       dname  is  used  for  renaming the domain to new name during migration,
2908       which also usually can be omitted.  Likewise,  --xml  file  is  usually
2909       omitted,  but  can be used to supply an alternative XML file for use on
2910       the destination to supply a larger set of changes to any  host-specific
2911       portions  of  the domain XML, such as accounting for naming differences
2912       between source and destination in  accessing  underlying  storage.   If
2913       --persistent is enabled, --persistent-xml file can be used to supply an
2914       alternative XML file which will be used as the persistent guest defini‐
2915       tion on the destination host.
2916
2917       --timeout  seconds  tells virsh to run a specified action when live mi‐
2918       gration exceeds that many seconds.  It can only be  used  with  --live.
2919       If  --timeout-suspend  is specified, the domain will be suspended after
2920       the timeout and the migration will complete offline; this  is  the  de‐
2921       fault  if  no  --timeout-\``  option  is specified on the command line.
2922       When *--timeout-postcopy is used,  virsh  will  switch  migration  from
2923       pre-copy  to  post-copy  upon timeout; migration has to be started with
2924       --postcopy option for this to work.
2925
2926       --compressed activates compression, the compression  method  is  chosen
2927       with --comp-methods. Supported methods are "mt" and "xbzrle" and can be
2928       used in any combination. When no methods are  specified,  a  hypervisor
2929       default  methods  will  be used. QEMU defaults to "xbzrle". Compression
2930       methods can be tuned further. --comp-mt-level sets  compression  level.
2931       Values are in range from 0 to 9, where 1 is maximum speed and 9 is max‐
2932       imum compression. --comp-mt-threads and --comp-mt-dthreads set the num‐
2933       ber  of compress threads on source and the number of decompress threads
2934       on target respectively. --comp-xbzrle-cache sets size of page cache  in
2935       bytes.
2936
2937       Providing  --tls  causes  the  migration to use the host configured TLS
2938       setup (see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in  or‐
2939       der  to  perform the migration of the domain. Usage requires proper TLS
2940       setup for both source and target. Normally the TLS certificate from the
2941       destination  host  must  match  the host's name for TLS verification to
2942       succeed. When the certificate does not match the  destination  hostname
2943       and the expected certificate's hostname is known, --tls-destination can
2944       be used to pass the expected hostname when starting the migration.
2945
2946       --parallel option will cause migration data to be  sent  over  multiple
2947       parallel  connections.  The number of such connections can be set using
2948       --parallel-connections. Parallel connections may help  with  saturating
2949       the network link between the source and the target and thus speeding up
2950       the migration.
2951
2952       Running migration can be canceled by interrupting virsh (usually  using
2953       Ctrl-C) or by domjobabort command sent from another virsh instance.
2954
2955       The desturi and migrateuri parameters can be used to control which des‐
2956       tination the migration uses.  desturi is important for  managed  migra‐
2957       tion,  but  unused for direct migration; migrateuri is required for di‐
2958       rect migration, but can usually be automatically determined for managed
2959       migration.
2960
2961       Note:  The  desturi parameter for normal migration and peer2peer migra‐
2962       tion has different semantics:
2963
2964       • normal migration: the desturi is an address of  the  target  host  as
2965         seen from the client machine.
2966
2967       • peer2peer  migration: the desturi is an address of the target host as
2968         seen from the source machine.
2969
2970       In a special circumstance where you require a complete control  of  the
2971       connection  and/or  libvirt  does not have network access to the remote
2972       side you can use a UNIX transport in the URI and specify a socket  path
2973       in the query, for example with the qemu driver you could use this:
2974
2975          qemu+unix:///system?socket=/path/to/socket
2976
2977       When  migrateuri is not specified, libvirt will automatically determine
2978       the hypervisor specific URI.  Some hypervisors, including QEMU, have an
2979       optional "migration_host" configuration parameter (useful when the host
2980       has multiple network interfaces).  If this is unspecified, libvirt  de‐
2981       termines a name by looking up the target host's configured hostname.
2982
2983       There are a few scenarios where specifying migrateuri may help:
2984
2985       • The  configured  hostname  is incorrect, or DNS is broken.  If a host
2986         has a hostname which will not resolve to match one of its  public  IP
2987         addresses, then libvirt will generate an incorrect URI.  In this case
2988         migrateuri should be explicitly specified, using an IP address, or  a
2989         correct hostname.
2990
2991       • The  host  has  multiple  network interfaces.  If a host has multiple
2992         network interfaces, it might be  desirable  for  the  migration  data
2993         stream  to  be  sent over a specific interface for either security or
2994         performance reasons.  In this case migrateuri  should  be  explicitly
2995         specified,  using  an  IP  address  associated with the network to be
2996         used.
2997
2998       • The firewall restricts what ports are available.  When libvirt gener‐
2999         ates  a  migration  URI,  it will pick a port number using hypervisor
3000         specific rules.  Some hypervisors only require a single  port  to  be
3001         open  in  the  firewalls,  while others require a whole range of port
3002         numbers.  In the latter case migrateuri might be specified to  choose
3003         a  specific  port number outside the default range in order to comply
3004         with local firewall policies.
3005
3006       • The desturi uses UNIX transport method.  In this advanced  case  lib‐
3007         virt  should  not guess a migrateuri and it should be specified using
3008         UNIX socket path URI:
3009
3010          unix:///path/to/socket
3011
3012       See https://libvirt.org/migration.html#uris for more details on  migra‐
3013       tion URIs.
3014
3015       Optional graphicsuri overrides connection parameters used for automati‐
3016       cally reconnecting a graphical clients at  the  end  of  migration.  If
3017       omitted,  libvirt  will  compute the parameters based on target host IP
3018       address. In case the client does not have a direct access to  the  net‐
3019       work virtualization hosts are connected to and needs to connect through
3020       a proxy, graphicsuri may be used to  specify  the  address  the  client
3021       should connect to. The URI is formed as follows:
3022
3023          protocol://hostname[:port]/[?parameters]
3024
3025       where  protocol  is either "spice" or "vnc" and parameters is a list of
3026       protocol specific parameters separated by '&'. Currently recognized pa‐
3027       rameters are "tlsPort" and "tlsSubject". For example,
3028
3029          spice://target.host.com:1234/?tlsPort=4567
3030
3031       Optional  listen-address sets the listen address that hypervisor on the
3032       destination side should bind to for incoming migration. Both  IPv4  and
3033       IPv6 addresses are accepted as well as hostnames (the resolving is done
3034       on destination).  Some hypervisors do not support specifying the listen
3035       address and will return an error if this parameter is used. This param‐
3036       eter cannot be used if desturi uses UNIX transport method.
3037
3038       Optional disks-port sets the port that hypervisor on  destination  side
3039       should  bind  to  for incoming disks traffic. Currently it is supported
3040       only by QEMU.
3041
3042       Optional disks-uri can  also  be  specified  (mutually  exclusive  with
3043       disks-port)  to  specify what the remote hypervisor should bind/connect
3044       to when migrating disks.  This can be tcp://address:port to  specify  a
3045       listen  address (which overrides --migrate-uri and --listen-address for
3046       the disk migration) and a port or unix:///path/to/socket  in  case  you
3047       need  the  disk migration to happen over a UNIX socket with that speci‐
3048       fied path.  In this case you need to make sure the same socket path  is
3049       accessible to both source and destination hypervisors and connecting to
3050       the socket on the source (after hypervisor creates it on  the  destina‐
3051       tion)  will  actually  connect  to  the  destination.  If you are using
3052       SELinux (at least on the source host) you need to make sure the  socket
3053       on  the  source is accessible to libvirtd/QEMU for connection.  Libvirt
3054       cannot change the context of the existing socket because it is  differ‐
3055       ent  from the file representation of the socket and the context is cho‐
3056       sen by its creator (usually by  using  setsockcreatecon{,_raw}()  func‐
3057       tions).
3058
3059   migrate-compcache
3060       Syntax:
3061
3062          migrate-compcache domain [--size bytes]
3063
3064       Sets  and/or gets size of the cache (in bytes) used for compressing re‐
3065       peatedly transferred memory pages during live  migration.  When  called
3066       without  size,  the command just prints current size of the compression
3067       cache. When size is specified, the hypervisor is asked to  change  com‐
3068       pression  cache to size bytes and then the current size is printed (the
3069       result may differ from the requested size due to rounding done  by  the
3070       hypervisor). The size option is supposed to be used while the domain is
3071       being live-migrated as a reaction to migration progress and  increasing
3072       number of compression cache misses obtained from domjobinfo.
3073
3074   migrate-getmaxdowntime
3075       Syntax:
3076
3077          migrate-getmaxdowntime domain
3078
3079       Get the maximum tolerable downtime for a domain which is being live-mi‐
3080       grated to another host.  This is the number of milliseconds  the  guest
3081       is allowed to be down at the end of live migration.
3082
3083   migrate-getspeed
3084       Syntax:
3085
3086          migrate-getspeed domain [--postcopy]
3087
3088       Get  the  maximum  migration  bandwidth (in MiB/s) for a domain. If the
3089       --postcopy option is specified, the command will get the maximum  band‐
3090       width allowed during a post-copy migration phase.
3091
3092   migrate-postcopy
3093       Syntax:
3094
3095          migrate-postcopy domain
3096
3097       Switch  the  current migration from pre-copy to post-copy. This is only
3098       supported for a migration started with --postcopy option.
3099
3100   migrate-setmaxdowntime
3101       Syntax:
3102
3103          migrate-setmaxdowntime domain downtime
3104
3105       Set maximum tolerable downtime for a domain  which  is  being  live-mi‐
3106       grated  to  another host.  The downtime is a number of milliseconds the
3107       guest is allowed to be down at the end of live migration.
3108
3109   migrate-setspeed
3110       Syntax:
3111
3112          migrate-setspeed domain bandwidth [--postcopy]
3113
3114       Set the maximum migration bandwidth (in MiB/s) for a  domain  which  is
3115       being migrated to another host. bandwidth is interpreted as an unsigned
3116       long long value. Specifying a negative value results in an  essentially
3117       unlimited  value  being  provided to the hypervisor. The hypervisor can
3118       choose whether to reject the value or convert it to the  maximum  value
3119       allowed.  If  the  --postcopy option is specified, the command will set
3120       the maximum bandwidth allowed during a post-copy migration phase.
3121
3122   numatune
3123       Syntax:
3124
3125          numatune domain [--mode mode] [--nodeset nodeset]
3126             [[--config] [--live] | [--current]]
3127
3128       Set or get a domain's numa parameters, corresponding to the  <numatune>
3129       element  of  domain  XML.  Without flags, the current settings are dis‐
3130       played.
3131
3132       mode can be one of `strict', `interleave',  `preferred'  and  'restric‐
3133       tive'  or  any  valid  number from the virDomainNumatuneMemMode enum in
3134       case the daemon supports it.  For a running domain, the mode  can't  be
3135       changed,  and the nodeset can be changed only if the domain was started
3136       with `restrictive' mode.
3137
3138       nodeset is a list of numa nodes used by the host for  running  the  do‐
3139       main.   Its  syntax  is a comma separated list, with '-' for ranges and
3140       '^' for excluding a node.
3141
3142       If --live is specified, set scheduler information of a  running  guest.
3143       If  --config is specified, affect the next start of a persistent guest.
3144       If --current is specified, it is equivalent to either --live or  --con‐
3145       fig, depending on the current state of the guest.
3146
3147       For  running  guests  in  Linux hosts, the changes made in the domain's
3148       numa parameters does not imply that the guest memory will be moved to a
3149       different  nodeset  immediately.  The  memory  migration depends on the
3150       guest activity, and the memory of an idle guest will remain in its pre‐
3151       vious  nodeset  for longer. The presence of VFIO devices will also lock
3152       parts of the guest memory in the same nodeset used to start the  guest,
3153       regardless of nodeset changes.
3154
3155   perf
3156       Syntax:
3157
3158          perf domain [--enable eventSpec] [--disable eventSpec]
3159             [[--config] [--live] | [--current]]
3160
3161       Get  the  current  perf  events setting or enable/disable specific perf
3162       events for a guest domain.
3163
3164       Perf is a performance analyzing tool in Linux, and  it  can  instrument
3165       CPU  performance  counters,  tracepoints, kprobes, and uprobes (dynamic
3166       tracing). Perf supports a list of measurable events,  and  can  measure
3167       events coming from different sources. For instance, some event are pure
3168       kernel counters, in this case they are called software events,  includ‐
3169       ing  context-switches,  minor-faults,  etc..  Now dozens of events from
3170       different sources can be supported by perf.
3171
3172       Currently only QEMU/KVM supports this command. The --enable and  --dis‐
3173       able  option  combined  with eventSpec can be used to enable or disable
3174       specific performance event. eventSpec is a string list of one  or  more
3175       events separated by commas. Valid event names are as follows:
3176
3177       Valid perf event names
3178
3179cmt  - A PQos (Platform Qos) feature to monitor the usage of cache by
3180         applications running on the platform.
3181
3182mbmt - Provides a way to monitor the total  system  memory  bandwidth
3183         between one level of cache and another.
3184
3185mbml  -  Provides  a  way  to limit the amount of data (bytes/s) send
3186         through the memory controller on the socket.
3187
3188cache_misses - Provides the count of  cache  misses  by  applications
3189         running on the platform.
3190
3191cache_references  -  Provides the count of cache hits by applications
3192         running on th e platform.
3193
3194instructions - Provides the count of instructions executed by  appli‐
3195         cations running on the platform.
3196
3197cpu_cycles - Provides the count of cpu cycles (total/elapsed). May be
3198         used with instructions in order to get a cycles per instruction.
3199
3200branch_instructions - Provides the count of branch instructions  exe‐
3201         cuted by applications running on the platform.
3202
3203branch_misses  -  Provides the count of branch misses executed by ap‐
3204         plications running on the platform.
3205
3206bus_cycles - Provides the count of bus cycles  executed  by  applica‐
3207         tions running on the platform.
3208
3209stalled_cycles_frontend - Provides the count of stalled cpu cycles in
3210         the frontend of the instruction processor  pipeline  by  applications
3211         running on the platform.
3212
3213stalled_cycles_backend  - Provides the count of stalled cpu cycles in
3214         the backend of the instruction  processor  pipeline  by  applications
3215         running on the platform.
3216
3217ref_cpu_cycles -  Provides the count of total cpu cycles not affected
3218         by CPU frequency scaling by applications running on the platform.
3219
3220cpu_clock - Provides the cpu clock time consumed by applications run‐
3221         ning on the platform.
3222
3223task_clock  -  Provides  the task clock time consumed by applications
3224         running on the platform.
3225
3226page_faults - Provides the count of page faults by applications  run‐
3227         ning on the platform.
3228
3229context_switches - Provides the count of context switches by applica‐
3230         tions running on the platform.
3231
3232cpu_migrations - Provides the count cpu  migrations  by  applications
3233         running on the platform.
3234
3235page_faults_min  -  Provides  the count minor page faults by applica‐
3236         tions running on the platform.
3237
3238page_faults_maj - Provides the count major page  faults  by  applica‐
3239         tions running on the platform.
3240
3241alignment_faults  -  Provides  the count alignment faults by applica‐
3242         tions running on the platform.
3243
3244emulation_faults - Provides the count emulation  faults  by  applica‐
3245         tions running on the platform.
3246
3247       Note:  The statistics can be retrieved using the domstats command using
3248       the --perf flag.
3249
3250       If --live is specified, affect a running guest.  If --config is  speci‐
3251       fied,  affect  the  next  start of a persistent guest.  If --current is
3252       specified, it is equivalent to either --live or --config, depending  on
3253       the  current state of the guest.  Both --live and --config flags may be
3254       given, but --current is exclusive. If no flag is specified, behavior is
3255       different depending on hypervisor.
3256
3257   reboot
3258       Syntax:
3259
3260          reboot domain [--mode MODE-LIST]
3261
3262       Reboot  a  domain.  This acts just as if the domain had the reboot com‐
3263       mand run from the console.  The command returns as soon as it has  exe‐
3264       cuted  the  reboot action, which may be significantly before the domain
3265       actually reboots.
3266
3267       The exact behavior of a domain when it reboots is set by the  on_reboot
3268       parameter in the domain's XML definition.
3269
3270       By  default the hypervisor will try to pick a suitable shutdown method.
3271       To specify an alternative method, the --mode parameter  can  specify  a
3272       comma  separated  list  which includes acpi, agent, initctl, signal and
3273       paravirt. The order in which drivers will try each mode  is  undefined,
3274       and  not  related  to the order specified to virsh.  For strict control
3275       over ordering, use a single mode at a time and repeat the command.
3276
3277   reset
3278       Syntax:
3279
3280          reset domain
3281
3282       Reset a domain immediately without any guest shutdown.  reset  emulates
3283       the  power reset button on a machine, where all guest hardware sees the
3284       RST line set and reinitializes internal state.
3285
3286       Note: Reset without any guest OS shutdown risks data loss.
3287
3288   restore
3289       Syntax:
3290
3291          restore state-file [--bypass-cache] [--xml file]
3292             [{--running | --paused}] [--reset-nvram]
3293
3294       Restores a domain from a virsh save state file. See save for more info.
3295
3296       If --bypass-cache is specified, the restore will avoid the file  system
3297       cache, although this may slow down the operation.
3298
3299       --xml file is usually omitted, but can be used to supply an alternative
3300       XML file for use on  the  restored  guest  with  changes  only  in  the
3301       host-specific  portions of the domain XML.  For example, it can be used
3302       to account for file naming differences in  underlying  storage  due  to
3303       disk snapshots taken after the guest was saved.
3304
3305       Normally,  restoring  a  saved image will use the state recorded in the
3306       save image to decide between running  or  paused;  passing  either  the
3307       --running or --paused flag will allow overriding which state the domain
3308       should be started in.
3309
3310       If --reset-nvram is specified, any existing NVRAM file will be  deleted
3311       and re-initialized from its pristine template.
3312
3313       Note:  To  avoid corrupting file system contents within the domain, you
3314       should not reuse the saved state file for a second restore  unless  you
3315       have  also  reverted  all  storage volumes back to the same contents as
3316       when the state file was created.
3317
3318   resume
3319       Syntax:
3320
3321          resume domain
3322
3323       Moves a domain out of the suspended state.  This will  allow  a  previ‐
3324       ously  suspended domain to now be eligible for scheduling by the under‐
3325       lying hypervisor.
3326
3327   save
3328       Syntax:
3329
3330          save domain state-file [--bypass-cache] [--xml file]
3331             [{--running | --paused}] [--verbose]
3332
3333       Saves a running domain (RAM, but not disk state) to  a  state  file  so
3334       that  it  can be restored later.  Once saved, the domain will no longer
3335       be running on the system, thus the memory allocated for the domain will
3336       be  free  for  other  domains to use.  virsh restore restores from this
3337       state file.  If --bypass-cache is specified, the save  will  avoid  the
3338       file system cache, although this may slow down the operation.
3339
3340       The  progress  may be monitored using domjobinfo virsh command and can‐
3341       celed with domjobabort command (sent by another  virsh  instance).  An‐
3342       other  option  is  to  send  SIGINT  (usually with Ctrl-C) to the virsh
3343       process running save command. --verbose displays the progress of save.
3344
3345       This is roughly equivalent to doing a hibernate on a running  computer,
3346       with all the same limitations.  Open network connections may be severed
3347       upon restore, as TCP timeouts may have expired.
3348
3349       --xml file is usually omitted, but can be used to supply an alternative
3350       XML  file  for  use  on  the  restored  guest  with changes only in the
3351       host-specific portions of the domain XML.  For example, it can be  used
3352       to  account for file naming differences that are planned to be made via
3353       disk snapshots of underlying storage after the guest is saved.
3354
3355       Normally, restoring a saved image will decide between running or paused
3356       based  on  the  state the domain was in when the save was done; passing
3357       either the --running or --paused flag will allow overriding which state
3358       the restore should use.
3359
3360       Domain  saved state files assume that disk images will be unchanged be‐
3361       tween the creation and restore point.  For a more complete  system  re‐
3362       store  point, where the disk state is saved alongside the memory state,
3363       see the snapshot family of commands.
3364
3365   save-image-define
3366       Syntax:
3367
3368          save-image-define file xml [{--running | --paused}]
3369
3370       Update the domain XML that will be used when file is later used in  the
3371       restore  command.   The xml argument must be a file name containing the
3372       alternative XML, with changes only in the host-specific portions of the
3373       domain  XML.   For  example,  it can be used to account for file naming
3374       differences resulting from creating disk snapshots of underlying  stor‐
3375       age after the guest was saved.
3376
3377       The  save image records whether the domain should be restored to a run‐
3378       ning or paused state.   Normally,  this  command  does  not  alter  the
3379       recorded  state; passing either the --running or --paused flag will al‐
3380       low overriding which state the restore should use.
3381
3382   save-image-dumpxml
3383       Syntax:
3384
3385          save-image-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap] file
3386
3387       Extract the domain XML that was in effect at the time the  saved  state
3388       file  file  was  created  with the save command.  Using --security-info
3389       will also include security sensitive information.
3390
3391       If the --xpath argument provides an XPath expression, it will be evalu‐
3392       ated  against  the  output  XML  and  only those matching nodes will be
3393       printed. The default behaviour is to print  each  matching  node  as  a
3394       standalone  document,  however,  for ease of additional processing, the
3395       --wrap argument will cause the matching node to be wrapped in a  common
3396       root node.
3397
3398   save-image-edit
3399       Syntax:
3400
3401          save-image-edit file [{--running | --paused}]
3402
3403       Edit the XML configuration associated with a saved state file file cre‐
3404       ated by the save command.
3405
3406       The save image records whether the domain should be restored to a  run‐
3407       ning  or  paused  state.   Normally,  this  command  does not alter the
3408       recorded state; passing either the --running or --paused flag will  al‐
3409       low overriding which state the restore should use.
3410
3411       This is equivalent to:
3412
3413          virsh save-image-dumpxml state-file > state-file.xml
3414          vi state-file.xml (or make changes with your other text editor)
3415          virsh save-image-define state-file state-file-xml
3416
3417       except that it does some error checking.
3418
3419       The  editor  used can be supplied by the $VISUAL or $EDITOR environment
3420       variables, and defaults to vi.
3421
3422   schedinfo
3423       Syntax:
3424
3425          schedinfo domain [[--config] [--live] | [--current]] [[--set] parameter=value]...
3426          schedinfo [--weight number] [--cap number] domain
3427
3428       Allows you to show (and set) the domain scheduler parameters.  The  pa‐
3429       rameters available for each hypervisor are:
3430
3431       LXC (posix scheduler) : cpu_shares, vcpu_period, vcpu_quota
3432
3433       QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota, emula‐
3434       tor_period, emulator_quota, global_period,  global_quota,  iothread_pe‐
3435       riod, iothread_quota
3436
3437       Xen (credit scheduler): weight, cap
3438
3439       ESX (allocation scheduler): reservation, limit, shares
3440
3441       If  --live  is specified, set scheduler information of a running guest.
3442       If --config is specified, affect the next start of a persistent  guest.
3443       If  --current is specified, it is equivalent to either --live or --con‐
3444       fig, depending on the current state of the guest.
3445
3446       Note: The cpu_shares parameter has a valid value range of 2-262144.
3447
3448       Note: The weight and cap parameters are defined only for the XEN_CREDIT
3449       scheduler.
3450
3451       Note:  The vcpu_period, emulator_period, and iothread_period parameters
3452       have a valid value range of 1000-1000000 or 0, and the vcpu_quota, emu‐
3453       lator_quota,  and iothread_quota parameters have a valid value range of
3454       1000-17592186044415 or less than 0. The value 0 for either parameter is
3455       the same as not specifying that parameter.
3456
3457   screenshot
3458       Syntax:
3459
3460          screenshot domain [imagefilepath] [--screen screenID]
3461
3462       Takes  a  screenshot  of  a current domain console and stores it into a
3463       file.  Optionally, if the hypervisor supports more displays for  a  do‐
3464       main,  screenID  allows specifying which screen will be captured. It is
3465       the sequential number of screen. In case of  multiple  graphics  cards,
3466       heads  are  enumerated  before devices, e.g. having two graphics cards,
3467       both with four heads, screen ID 5 addresses the second head on the sec‐
3468       ond card.
3469
3470   send-key
3471       Syntax:
3472
3473          send-key domain [--codeset codeset] [--holdtime holdtime] keycode...
3474
3475       Parse  the keycode sequence as keystrokes to send to domain.  Each key‐
3476       code can either be a numeric value or a symbolic name from  the  corre‐
3477       sponding  codeset.  If --holdtime is given, each keystroke will be held
3478       for that many milliseconds.  The default codeset is linux, but  use  of
3479       the --codeset option allows other codesets to be chosen.
3480
3481       If multiple keycodes are specified, they are all sent simultaneously to
3482       the guest, and they may be received in random order. If you  need  dis‐
3483       tinct keypresses, you must use multiple send-key invocations.
3484
3485linux
3486
3487         The numeric values are those defined by the Linux generic input event
3488         subsystem. The symbolic names match the corresponding Linux key  con‐
3489         stant macro names.
3490
3491         See virkeycode-linux(7) and virkeyname-linux(7)
3492
3493xt
3494
3495         The numeric values are those defined by the original XT keyboard con‐
3496         troller. No symbolic names are provided
3497
3498         See virkeycode-xt(7)
3499
3500atset1
3501
3502         The numeric values are those defined by the AT  keyboard  controller,
3503         set  1 (aka XT compatible set). Extended keycoes from atset1 may dif‐
3504         fer from extended keycodes in the xt codeset. No symbolic  names  are
3505         provided
3506
3507         See virkeycode-atset1(7)
3508
3509atset2
3510
3511         The  numeric  values are those defined by the AT keyboard controller,
3512         set 2. No symbolic names are provided
3513
3514         See virkeycode-atset2(7)
3515
3516atset3
3517
3518         The numeric values are those defined by the AT  keyboard  controller,
3519         set 3 (aka PS/2 compatible set). No symbolic names are provided
3520
3521         See virkeycode-atset3(7)
3522
3523os_x
3524
3525         The numeric values are those defined by the macOS keyboard input sub‐
3526         system. The symbolic names match the corresponding macOS key constant
3527         macro names
3528
3529         See virkeycode-osx(7) and virkeyname-osx(7)
3530
3531xt_kbd
3532
3533         The  numeric values are those defined by the Linux KBD device.  These
3534         are a variant on the original XT codeset, but  often  with  different
3535         encoding for extended keycodes. No symbolic names are provided.
3536
3537         See virkeycode-xtkbd(7)
3538
3539win32
3540
3541         The numeric values are those defined by the Win32 keyboard input sub‐
3542         system. The symbolic names match the corresponding Win32 key constant
3543         macro names
3544
3545         See virkeycode-win32(7) and virkeyname-win32(7)
3546
3547usb
3548
3549         The numeric values are those defined by the USB HID specification for
3550         keyboard input. No symbolic names are provided
3551
3552         See virkeycode-usb(7)
3553
3554qnum
3555
3556         The numeric values are those defined by the QNUM extension for  send‐
3557         ing raw keycodes. These are a variant on the XT codeset, but extended
3558         keycodes have the low bit of the second byte set, instead of the high
3559         bit of the first byte. No symbolic names are provided.
3560
3561         See virkeycode-qnum(7)
3562
3563       Examples:
3564
3565          # send three strokes 'k', 'e', 'y', using xt codeset. these
3566          # are all pressed simultaneously and may be received by the guest
3567          # in random order
3568          virsh send-key dom --codeset xt 37 18 21
3569
3570          # send one stroke 'right-ctrl+C'
3571          virsh send-key dom KEY_RIGHTCTRL KEY_C
3572
3573          # send a tab, held for 1 second
3574          virsh send-key --holdtime 1000 0xf
3575
3576   send-process-signal
3577       Syntax:
3578
3579          send-process-signal domain-id pid signame
3580
3581       Send  a  signal signame to the process identified by pid running in the
3582       virtual domain domain-id. The pid is a process ID in the virtual domain
3583       namespace.
3584
3585       The  signame  argument may be either an integer signal constant number,
3586       or one of the symbolic names:
3587
3588          "nop", "hup", "int", "quit", "ill",
3589          "trap", "abrt", "bus", "fpe", "kill",
3590          "usr1", "segv", "usr2", "pipe", "alrm",
3591          "term", "stkflt", "chld", "cont", "stop",
3592          "tstp", "ttin", "ttou", "urg", "xcpu",
3593          "xfsz", "vtalrm", "prof", "winch", "poll",
3594          "pwr", "sys", "rt0", "rt1", "rt2", "rt3",
3595          "rt4", "rt5", "rt6", "rt7", "rt8", "rt9",
3596          "rt10", "rt11", "rt12", "rt13", "rt14", "rt15",
3597          "rt16", "rt17", "rt18", "rt19", "rt20", "rt21",
3598          "rt22", "rt23", "rt24", "rt25", "rt26", "rt27",
3599          "rt28", "rt29", "rt30", "rt31", "rt32"
3600
3601       The symbol name may optionally be prefixed with sig or sig_ and may  be
3602       in uppercase or lowercase.
3603
3604       Examples:
3605
3606          virsh send-process-signal myguest 1 15
3607          virsh send-process-signal myguest 1 term
3608          virsh send-process-signal myguest 1 sigterm
3609          virsh send-process-signal myguest 1 SIG_HUP
3610
3611   set-lifecycle-action
3612       Syntax:
3613
3614          set-lifecycle-action domain type action
3615             [[--config] [--live] | [--current]]
3616
3617       Set the lifecycle action for specified lifecycle type.  The valid types
3618       are "poweroff", "reboot" and "crash", and for each of them valid action
3619       is one of "destroy", "restart", "rename-restart", "preserve".  For type
3620       "crash", additional actions "coredump-destroy"  and  "coredump-restart"
3621       are supported.
3622
3623   set-user-password
3624       Syntax:
3625
3626          set-user-password domain user password [--encrypted]
3627
3628       Set the password for the user account in the guest domain.
3629
3630       If  --encrypted is specified, the password is assumed to be already en‐
3631       crypted by the method required by the guest OS.
3632
3633       For QEMU/KVM, this requires the guest agent to be configured  and  run‐
3634       ning.
3635
3636   set-user-sshkeys
3637       Syntax:
3638
3639          set-user-sshkeys domain user [--file FILE] [{--reset | --remove}]
3640
3641       Append  keys read from FILE into user's SSH authorized keys file in the
3642       guest domain.  In the FILE keys must be on separate lines and each line
3643       must follow authorized keys format as defined by sshd(8).
3644
3645       If --reset is specified, then the guest authorized keys file content is
3646       removed before appending new keys. As a special  case,  if  --reset  is
3647       provided  and  no  FILE was provided then no new keys are added and the
3648       authorized keys file is cleared out.
3649
3650       If --remove is specified, then instead of adding any new keys then keys
3651       read  from  FILE  are  removed from the authorized keys file. It is not
3652       considered an error if the key does not exist in the file.
3653
3654   setmaxmem
3655       Syntax:
3656
3657          setmaxmem domain size [[--config] [--live] | [--current]]
3658
3659       Change the maximum memory allocation limit  for  a  guest  domain.   If
3660       --live is specified, affect a running guest.  If --config is specified,
3661       affect the next start of a persistent guest.  If  --current  is  speci‐
3662       fied,  it  is equivalent to either --live or --config, depending on the
3663       current state of the guest.  Both --live  and  --config  flags  may  be
3664       given, but --current is exclusive. If no flag is specified, behavior is
3665       different depending on hypervisor.
3666
3667       Some hypervisors such as QEMU/KVM don't  support  live  changes  (espe‐
3668       cially  increasing)  of the maximum memory limit.  Even persistent con‐
3669       figuration changes might not be performed with some hypervisors/config‐
3670       uration (e.g. on NUMA enabled domains on QEMU).  For complex configura‐
3671       tion changes use command edit instead).
3672
3673       size is a scaled integer (see NOTES above); it  defaults  to  kibibytes
3674       (blocks  of  1024 bytes) unless you provide a suffix (and the older op‐
3675       tion name --kilobytes is available as a deprecated synonym) .   Libvirt
3676       rounds  up  to the nearest kibibyte.  Some hypervisors require a larger
3677       granularity than KiB, and requests that are not an even  multiple  will
3678       be  rounded  up.   For  example, vSphere/ESX rounds the parameter up to
3679       mebibytes (1024 kibibytes).
3680
3681   setmem
3682       Syntax:
3683
3684          setmem domain size [[--config] [--live] | [--current]]
3685
3686       Change the memory allocation for a guest domain.  If --live  is  speci‐
3687       fied,  perform  a  memory  balloon  of a running guest.  If --config is
3688       specified, affect the next start of a persistent guest.   If  --current
3689       is  specified, it is equivalent to either --live or --config, depending
3690       on the current state of the guest.  Both --live and --config flags  may
3691       be given, but --current is exclusive. If no flag is specified, behavior
3692       is different depending on hypervisor.
3693
3694       size is a scaled integer (see NOTES above); it  defaults  to  kibibytes
3695       (blocks  of  1024 bytes) unless you provide a suffix (and the older op‐
3696       tion name --kilobytes is available as a deprecated synonym) .   Libvirt
3697       rounds  up  to the nearest kibibyte.  Some hypervisors require a larger
3698       granularity than KiB, and requests that are not an even  multiple  will
3699       be  rounded  up.   For  example, vSphere/ESX rounds the parameter up to
3700       mebibytes (1024 kibibytes).
3701
3702       For Xen, you can only adjust the memory of a running domain if the  do‐
3703       main is paravirtualized or running the PV balloon driver.
3704
3705       For LXC, the value being set is the cgroups value for limit_in_bytes or
3706       the maximum amount of user memory (including file cache). When  viewing
3707       memory  inside  the  container,  this  is  the /proc/meminfo "MemTotal"
3708       value. When viewing the value from the host, use the virsh memtune com‐
3709       mand.  In order to view the current memory in use and the maximum value
3710       allowed to set memory, use the virsh dominfo command.
3711
3712   setvcpus
3713       Syntax:
3714
3715          setvcpus domain count [--maximum] [[--config] [--live] | [--current]] [--guest] [--hotpluggable]
3716
3717       Change the number of virtual CPUs active in a  guest  domain.   By  de‐
3718       fault,  this command works on active guest domains.  To change the set‐
3719       tings for an inactive guest domain, use the --config flag.
3720
3721       The count value may be limited by host, hypervisor, or a  limit  coming
3722       from  the  original  description  of the guest domain. For Xen, you can
3723       only adjust the virtual CPUs of a running domain if the domain is  par‐
3724       avirtualized.
3725
3726       If the --config flag is specified, the change is made to the stored XML
3727       configuration for the guest domain, and will only take effect when  the
3728       guest domain is next started.
3729
3730       If --live is specified, the guest domain must be active, and the change
3731       takes place immediately.  Both the --config and  --live  flags  may  be
3732       specified  together if supported by the hypervisor.  If this command is
3733       run before the guest has  finished  booting,  the  guest  may  fail  to
3734       process the change.
3735
3736       If  --current is specified, it is equivalent to either --live or --con‐
3737       fig, depending on the current state of the guest.
3738
3739       When no flags are given, the --live flag is assumed and the  guest  do‐
3740       main  must  be  active.   In  this situation it is up to the hypervisor
3741       whether the --config flag is also assumed, and  therefore  whether  the
3742       XML configuration is adjusted to make the change persistent.
3743
3744       If  --guest  is  specified,  then  the count of cpus is modified in the
3745       guest instead of the hypervisor. This flag is usable only for live  do‐
3746       mains and may require guest agent to be configured in the guest.
3747
3748       To  allow  adding vcpus to persistent definitions that can be later ho‐
3749       tunplugged after the domain is booted it is necessary  to  specify  the
3750       --hotpluggable flag. Vcpus added to live domains supporting vcpu unplug
3751       are automatically marked as hotpluggable.
3752
3753       The --maximum flag controls the maximum number of virtual cpus that can
3754       be  hot-plugged  the  next time the domain is booted.  As such, it must
3755       only be used with the --config flag, and not with  the  --live  or  the
3756       --current  flag. Note that it may not be possible to change the maximum
3757       vcpu count if the processor topology is specified for the guest.
3758
3759   setvcpu
3760       Syntax:
3761
3762          setvcpu domain vcpulist [--enable] | [--disable]
3763             [[--live] [--config] | [--current]]
3764
3765       Change state of individual vCPUs using hot(un)plug mechanism.
3766
3767       See vcpupin for information on format of vcpulist.  Hypervisor  drivers
3768       may  require that vcpulist contains exactly vCPUs belonging to one hot‐
3769       pluggable entity. This is usually just a single vCPU but certain archi‐
3770       tectures such as ppc64 require a full core to be specified at once.
3771
3772       Note  that hypervisors may refuse to disable certain vcpus such as vcpu
3773       0 or others.
3774
3775       If --live is specified, affect a running domain.  If --config is speci‐
3776       fied,  affect  the next startup of a persistent guest.  If --current is
3777       specified, it is equivalent to either --live or --config, depending  on
3778       the  current  state of the guest.  This is the default. Both --live and
3779       --config flags may be given, but --current is exclusive.
3780
3781   shutdown
3782       Syntax:
3783
3784          shutdown domain [--mode MODE-LIST]
3785
3786       Gracefully shuts down a domain.  This coordinates with the domain OS to
3787       perform  graceful  shutdown, so there is no guarantee that it will suc‐
3788       ceed, and may take a variable length of time depending on what services
3789       must be shutdown in the domain.
3790
3791       The  exact  behavior  of  a  domain  when  it  shuts down is set by the
3792       on_poweroff parameter in the domain's XML definition.
3793
3794       If domain is transient, then the metadata of any snapshots  and  check‐
3795       points  will  be  lost once the guest stops running, but the underlying
3796       contents still exist, and a new domain with the same name and UUID  can
3797       restore  the snapshot metadata with snapshot-create, and the checkpoint
3798       metadata with checkpoint-create.
3799
3800       By default the hypervisor will try to pick a suitable shutdown  method.
3801       To  specify  an  alternative method, the --mode parameter can specify a
3802       comma separated list which includes acpi, agent,  initctl,  signal  and
3803       paravirt.  The  order in which drivers will try each mode is undefined,
3804       and not related to the order specified to virsh.   For  strict  control
3805       over ordering, use a single mode at a time and repeat the command.
3806
3807   start
3808       Syntax:
3809
3810          start domain-name-or-uuid [--console] [--paused]
3811             [--autodestroy] [--bypass-cache] [--force-boot]
3812             [--pass-fds N,M,...] [--reset-nvram]
3813
3814       Start a (previously defined) inactive domain, either from the last man‐
3815       agedsave state, or via a fresh boot if no managedsave state is present.
3816       The  domain will be paused if the --paused option is used and supported
3817       by the driver; otherwise it will  be  running.   If  --console  is  re‐
3818       quested, attach to the console after creation.  If --autodestroy is re‐
3819       quested, then the guest will  be  automatically  destroyed  when  virsh
3820       closes  its  connection  to  libvirt,  or  otherwise  exits.   If --by‐
3821       pass-cache is specified, and managedsave state exists, the restore will
3822       avoid the file system cache, although this may slow down the operation.
3823       If --force-boot is specified, then any managedsave state  is  discarded
3824       and a fresh boot occurs.
3825
3826       If  --pass-fds  is specified, the argument is a comma separated list of
3827       open file descriptors which should be pass on into the guest. The  file
3828       descriptors  will be re-numbered in the guest, starting from 3. This is
3829       only supported with container based virtualization.
3830
3831       If --reset-nvram is specified, any existing NVRAM file will be  deleted
3832       and re-initialized from its pristine template.
3833
3834   suspend
3835       Syntax:
3836
3837          suspend domain
3838
3839       Suspend  a  running domain. It is kept in memory but won't be scheduled
3840       anymore.
3841
3842   ttyconsole
3843       Syntax:
3844
3845          ttyconsole domain
3846
3847       Output the device used for the TTY console of the domain. If the infor‐
3848       mation is not available the processes will provide an exit code of 1.
3849
3850   undefine
3851       Syntax:
3852
3853          undefine domain [--managed-save] [--snapshots-metadata]
3854             [--checkpoints-metadata] [--nvram] [--keep-nvram]
3855             [ {--storage volumes | --remove-all-storage
3856                [--delete-storage-volume-snapshots]} --wipe-storage]
3857
3858       Undefine  a  domain.  If  the  domain is running, this converts it to a
3859       transient domain, without stopping it. If the domain is  inactive,  the
3860       domain configuration is removed.
3861
3862       The --managed-save flag guarantees that any managed save image (see the
3863       managedsave command) is also cleaned up.  Without the flag, attempts to
3864       undefine a domain with a managed save image will fail.
3865
3866       The  --snapshots-metadata  flag  guarantees that any snapshots (see the
3867       snapshot-list command) are also cleaned up when undefining an  inactive
3868       domain.  Without the flag, attempts to undefine an inactive domain with
3869       snapshot metadata will fail.  If the domain is active, this flag is ig‐
3870       nored.
3871
3872       The  --checkpoints-metadata  flag  guarantees that any checkpoints (see
3873       the checkpoint-list command) are also cleaned up when undefining an in‐
3874       active  domain.  Without the flag, attempts to undefine an inactive do‐
3875       main with checkpoint metadata will fail.  If the domain is active, this
3876       flag is ignored.
3877
3878       --nvram  and  --keep-nvram  specify accordingly to delete or keep nvram
3879       (/domain/os/nvram/) file. If the domain has an nvram file and the flags
3880       are omitted, the undefine will fail.
3881
3882       The  --storage  flag  takes a parameter volumes, which is a comma sepa‐
3883       rated list of volume target names or source paths of storage volumes to
3884       be  removed  along  with the undefined domain. Volumes can be undefined
3885       and thus removed only on inactive domains. Volume deletion is only  at‐
3886       tempted after the domain is undefined; if not all of the requested vol‐
3887       umes could be deleted, the error message indicates what  still  remains
3888       behind.  If  a  volume path is not found in the domain definition, it's
3889       treated as if the volume was successfully deleted. Only volumes managed
3890       by  libvirt  in storage pools can be removed this way.  (See domblklist
3891       for list of target names associated to a domain).   Example:  --storage
3892       vda,/path/to/storage.img
3893
3894       The  --remove-all-storage flag specifies that all of the domain's stor‐
3895       age volumes should be deleted.
3896
3897       The --delete-storage-volume-snapshots  (previously  --delete-snapshots)
3898       flag  specifies  that  any snapshots associated with the storage volume
3899       should be deleted as well. Requires the --remove-all-storage flag to be
3900       provided.  Not  all storage drivers support this option, presently only
3901       rbd. Using this when also removing volumes handled by a storage  driver
3902       which does not support the flag will result in failure.
3903
3904       The  flag  --wipe-storage  specifies that the storage volumes should be
3905       wiped before removal.
3906
3907       NOTE: For an inactive domain, the domain name or UUID must be  used  as
3908       the domain.
3909
3910   vcpucount
3911       Syntax:
3912
3913          vcpucount domain  [{--maximum | --active}
3914             {--config | --live | --current}] [--guest]
3915
3916       Print information about the virtual cpu counts of the given domain.  If
3917       no flags are specified, all possible counts are listed in a table; oth‐
3918       erwise, the output is limited to just the numeric value requested.  For
3919       historical reasons, the table lists the label  "current"  on  the  rows
3920       that can be queried in isolation via the --active flag, rather than re‐
3921       lating to the --current flag.
3922
3923       --maximum requests information on the maximum cap of vcpus that  a  do‐
3924       main  can  add  via  setvcpus,  while --active shows the current usage;
3925       these two flags cannot both be specified.  --config requires a  persis‐
3926       tent  guest and requests information regarding the next time the domain
3927       will be booted, --live requires a running domain and lists current val‐
3928       ues, and --current queries according to the current state of the domain
3929       (corresponding to --live if running, or --config  if  inactive);  these
3930       three flags are mutually exclusive.
3931
3932       If  --guest  is  specified, then the count of cpus is reported from the
3933       perspective of the guest. This flag is usable only for live domains and
3934       may require guest agent to be configured in the guest.
3935
3936   vcpuinfo
3937       Syntax:
3938
3939          vcpuinfo domain [--pretty]
3940
3941       Returns  basic information about the domain virtual CPUs, like the num‐
3942       ber of vCPUs, the running time, the affinity to physical processors.
3943
3944       With --pretty, cpu affinities are shown as ranges.
3945
3946       Example:
3947
3948          $ virsh vcpuinfo fedora
3949          VCPU:           0
3950          CPU:            0
3951          State:          running
3952          CPU time:       7,0s
3953          CPU Affinity:   yyyy
3954
3955          VCPU:           1
3956          CPU:            1
3957          State:          running
3958          CPU time:       0,7s
3959          CPU Affinity:   yyyy
3960
3961       STATES
3962
3963       The State field displays the current operating state of a virtual CPU
3964
3965offline
3966
3967         The virtual CPU is offline and not usable by the domain.  This  state
3968         is not supported by all hypervisors.
3969
3970running
3971
3972         The virtual CPU is available to the domain and is operating.
3973
3974blocked
3975
3976         The  virtual  CPU is available to the domain but is waiting for a re‐
3977         source.  This state is not supported by  all  hypervisors,  in  which
3978         case running may be reported instead.
3979
3980no state
3981
3982         The  virtual  CPU state could not be determined. This could happen if
3983         the hypervisor is newer than virsh.
3984
3985N/A
3986
3987         There's no information about the virtual CPU  state  available.  This
3988         can  be  the case if the domain is not running or the hypervisor does
3989         not report the virtual CPU state.
3990
3991   vcpupin
3992       Syntax:
3993
3994          vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]]
3995
3996       Query or change the pinning of domain VCPUs to host physical CPUs.   To
3997       pin  a  single vcpu, specify cpulist; otherwise, you can query one vcpu
3998       or omit vcpu to list all at once.
3999
4000       cpulist is a list of physical CPU numbers. Its syntax is a comma  sepa‐
4001       rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
4002       can also be allowed. The '-' denotes the range and the '^' denotes  ex‐
4003       clusive.   For  pinning  the vcpu to all physical cpus specify 'r' as a
4004       cpulist.  If --live is specified, affect a running guest.  If  --config
4005       is  specified,  affect the next start of a persistent guest.  If --cur‐
4006       rent is specified, it is equivalent to either --live or  --config,  de‐
4007       pending  on  the  current state of the guest.  Both --live and --config
4008       flags may be given if cpulist is present, but --current  is  exclusive.
4009       If no flag is specified, behavior is different depending on hypervisor.
4010
4011       Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
4012       cal to "9-14,0-7,15" but not identical to "^8,0-15".
4013
4014   vncdisplay
4015       Syntax:
4016
4017          vncdisplay domain
4018
4019       Output the IP address and port number for the VNC display. If  the  in‐
4020       formation  is  not available the processes will provide an exit code of
4021       1.
4022

DEVICE COMMANDS

4024       The following commands manipulate devices associated to  domains.   The
4025       domain  can be specified as a short integer, a name or a full UUID.  To
4026       better understand the values allowed as options for the command reading
4027       the  documentation at https://libvirt.org/formatdomain.html on the for‐
4028       mat of the device sections to get the most  accurate  set  of  accepted
4029       values.
4030
4031   attach-device
4032       Syntax:
4033
4034          attach-device domain FILE [[[--live] [--config] | [--current]] | [--persistent]]
4035
4036       Attach a device to the domain, using a device definition in an XML file
4037       using a device definition element such as <disk> or <interface> as  the
4038       top-level       element.        See      the      documentation      at
4039       https://libvirt.org/formatdomain.html#elementsDevices  to  learn  about
4040       libvirt  XML format for a device.  If --config is specified the command
4041       alters the persistent guest configuration with the device attach taking
4042       effect  the  next time libvirt starts the domain.  For cdrom and floppy
4043       devices, this command only replaces the media within  an  existing  de‐
4044       vice;  consider  using  update-device  for this usage.  For passthrough
4045       host devices, see also nodedev-detach, needed if the  PCI  device  does
4046       not use managed mode.
4047
4048       If --live is specified, affect a running domain.  If --config is speci‐
4049       fied, affect the next startup of a persistent guest.  If  --current  is
4050       specified,  it is equivalent to either --live or --config, depending on
4051       the current state of the guest.  Both --live and --config flags may  be
4052       given, but --current is exclusive. When no flag is specified legacy API
4053       is used whose behavior depends on the hypervisor driver.
4054
4055       For compatibility purposes, --persistent behaves like --config  for  an
4056       offline domain, and like --live --config for a running domain.
4057
4058       Note:  using  of  partial device definition XML files may lead to unex‐
4059       pected results as some fields may be autogenerated and thus  match  de‐
4060       vices other than expected.
4061
4062   attach-disk
4063       Syntax:
4064
4065          attach-disk domain source target [[[--live] [--config] |
4066             [--current]] | [--persistent]] [--targetbus bus]
4067             [--driver driver] [--subdriver subdriver] [--iothread iothread]
4068             [--cache cache] [--io io] [--type type] [--alias alias]
4069             [--mode mode] [--sourcetype sourcetype]
4070             [--source-protocol protocol] [--source-host-name hostname:port]
4071             [--source-host-transport transport] [--source-host-socket socket]
4072             [--serial serial] [--wwn wwn] [--rawio] [--address address]
4073             [--multifunction] [--print-xml]
4074
4075       Attach  a  new disk device to the domain.  source is path for the files
4076       and devices unless --source-protocol is specified, in which case source
4077       is the name of a network disk.  target controls the bus or device under
4078       which the disk is exposed to the guest OS. It indicates  the  "logical"
4079       device  name;  the  optional  targetbus attribute specifies the type of
4080       disk device to emulate; possible values are driver specific, with typi‐
4081       cal  values being ide, scsi, virtio, xen, usb, sata, or sd, if omitted,
4082       the bus type is inferred from the style of the device name (e.g.  a de‐
4083       vice  named 'sda' will typically be exported using a SCSI bus).  driver
4084       can be file, tap or phy for the Xen hypervisor depending on the kind of
4085       access;  or  qemu for the QEMU emulator.  Further details to the driver
4086       can be passed using subdriver. For Xen subdriver can be aio, while  for
4087       QEMU  subdriver should match the format of the disk source, such as raw
4088       or qcow2.  Hypervisor default will be used if subdriver is  not  speci‐
4089       fied.   However,  the  default may not be correct, esp. for QEMU as for
4090       security reasons it is configured not to detect disk formats.  type can
4091       indicate  lun,  cdrom or floppy as alternative to the disk default, al‐
4092       though this use only replaces the media  within  the  existing  virtual
4093       cdrom or floppy device; consider using update-device for this usage in‐
4094       stead.  alias can set user supplied alias.  mode can  specify  the  two
4095       specific  mode readonly or shareable.  sourcetype can indicate the type
4096       of source (block|file|network) cache can be one of  "default",  "none",
4097       "writethrough",  "writeback",  "directsync"  or  "unsafe".  io controls
4098       specific policies on I/O; QEMU guests support "threads",  "native"  and
4099       "io_uring".   iothread  is  the  number  within the range of domain IO‐
4100       Threads to which this disk may be attached (QEMU only).  serial is  the
4101       serial  of disk device. wwn is the wwn of disk device.  rawio indicates
4102       the disk needs rawio capability.  address is the address of disk device
4103       in  the form of pci:domain.bus.slot.function, scsi:controller.bus.unit,
4104       ide:controller.bus.unit,  usb:bus.port,   sata:controller.bus.unit   or
4105       ccw:cssid.ssid.devno.  Virtio-ccw  devices must have their cssid set to
4106       0xfe.  multifunction indicates specified pci address is a multifunction
4107       pci device address.
4108
4109       There  is also support for using a network disk. As specified, the user
4110       can provide a --source-protocol in which case the source parameter will
4111       be  interpreted  as the source name. --source-protocol must be provided
4112       if the user intends to provide a  network  disk  or  host  information.
4113       Host  information  can  be  provided using the tags --source-host-name,
4114       --source-host-transport, and --source-host-socket,  which  respectively
4115       denote  the  name  of  the  host,  the host's transport method, and the
4116       socket that the host uses. --source-host-socket and  --source-host-name
4117       cannot    both   be   provided,   and   the   user   must   provide   a
4118       --source-host-transport if they want to provide a --source-host-socket.
4119       The  --source-host-name parameter supports host:port syntax if the user
4120       wants to provide a port as well.
4121
4122       If --print-xml is specified, then the XML of the disk that would be at‐
4123       tached is printed instead.
4124
4125       If --live is specified, affect a running domain.  If --config is speci‐
4126       fied, affect the next startup of a persistent guest.  If  --current  is
4127       specified,  it is equivalent to either --live or --config, depending on
4128       the current state of the guest.  Both --live and --config flags may  be
4129       given, but --current is exclusive. When no flag is specified legacy API
4130       is used whose behavior depends on the hypervisor driver.
4131
4132       For compatibility purposes, --persistent behaves like --config  for  an
4133       offline  domain,  and like --live --config for a running domain.  Like‐
4134       wise, --shareable is an alias for --mode shareable.
4135
4136   attach-interface
4137       Syntax:
4138
4139          attach-interface domain type source [[[--live]
4140             [--config] | [--current]] | [--persistent]]
4141             [--target target] [--mac mac] [--script script] [--model model]
4142             [--inbound average,peak,burst,floor] [--outbound average,peak,burst]
4143             [--alias alias] [--managed] [--print-xml]
4144             [--source-mode mode]
4145
4146       Attach a new network interface to the domain.
4147
4148       type can be one of the:
4149
4150       network to indicate connection via a libvirt virtual network,
4151
4152       bridge to indicate connection via a bridge device on the host,
4153
4154       direct to indicate connection directly to one of the host's network in‐
4155       terfaces or bridges,
4156
4157       hostdev to indicate connection using a passthrough of PCI device on the
4158       host,
4159
4160       vhostuser to indicate connection using a virtio transport protocol.
4161
4162       source indicates the source of the connection.  The source  depends  on
4163       the type of the interface:
4164
4165       network name of the virtual network,
4166
4167       bridge the name of the bridge device,
4168
4169       direct the name of the host's interface or bridge,
4170
4171       hostdev  the  PCI  address  of  the  host's  interface formatted as do‐
4172       main:bus:slot.function.
4173
4174       vhostuser the path to UNIX socket (control plane)
4175
4176       --target is used to specify the tap/macvtap device to be used  to  con‐
4177       nect  the domain to the source.  Names starting with 'vnet' are consid‐
4178       ered as auto-generated and are blanked out/regenerated  each  time  the
4179       interface is attached.
4180
4181       --mac  specifies the MAC address of the network interface; if a MAC ad‐
4182       dress is not given, a new address will be automatically generated  (and
4183       stored  in  the  persistent configuration if "--config" is given on the
4184       command line).
4185
4186       --script is used to specify a path to a  custom  script  to  be  called
4187       while  attaching  to  a bridge - this will be called instead of the de‐
4188       fault script not in addition to it.  This is valid only for  interfaces
4189       of bridge type and only for Xen domains.
4190
4191       --model  specifies  the network device model to be presented to the do‐
4192       main.
4193
4194       alias can set user supplied alias.
4195
4196       --inbound and --outbound control the bandwidth of  the  interface.   At
4197       least  one  from  the average, floor pair must be specified.  The other
4198       two peak and burst are optional, so  "average,peak",  "average,,burst",
4199       "average,,,floor", "average" and ",,,floor" are also legal.  Values for
4200       average, floor and peak are expressed in kilobytes  per  second,  while
4201       burst  is expressed in kilobytes in a single burst at peak speed as de‐
4202       scribed     in     the      Network      XML      documentation      at
4203       https://libvirt.org/formatnetwork.html#quality-of-service.
4204
4205       --managed  is  usable  only for hostdev type and tells libvirt that the
4206       interface should  be  managed,  which  means  detached  and  reattached
4207       from/to the host by libvirt.
4208
4209       --source-mode  is  mandatory for vhostuser interface and accepts values
4210       server and client that control whether hypervisor waits for  the  other
4211       process to connect, or initiates connection, respectively.
4212
4213       If  --print-xml  is specified, then the XML of the interface that would
4214       be attached is printed instead.
4215
4216       If --live is specified, affect a running domain.  If --config is speci‐
4217       fied,  affect  the next startup of a persistent guest.  If --current is
4218       specified, affect the current domain state, which can either be live or
4219       offline.  Both --live and --config flags may be given, but --current is
4220       exclusive.  When no flag is specified legacy API is used whose behavior
4221       depends on the hypervisor driver.
4222
4223       For  compatibility  purposes, --persistent behaves like --config for an
4224       offline domain, and like --live --config for a running domain.
4225
4226       Note: the optional target value is the name of a device to  be  created
4227       as the back-end on the node.  If not provided a device named "vnetN" or
4228       "vifN" will be created automatically.
4229
4230   detach-device
4231       Syntax:
4232
4233          detach-device domain FILE [[[--live] [--config] |
4234             [--current]] | [--persistent]]
4235
4236       Detach a device from the domain, takes the same kind  of  XML  descrip‐
4237       tions as command attach-device.  For passthrough host devices, see also
4238       nodedev-reattach, needed if the device does not use managed mode.
4239
4240       Note: The supplied XML description of the device should be as  specific
4241       as  its  definition  in  the  domain XML. The set of attributes used to
4242       match the device are internal to the drivers. Using a  partial  defini‐
4243       tion,  or  attempting to detach a device that is not present in the do‐
4244       main XML, but shares some specific attributes with one that is present,
4245       may lead to unexpected results.
4246
4247       Quirk:  Device  unplug is asynchronous in most cases and requires guest
4248       cooperation. This means that it's up to the discretion of the guest  to
4249       disallow  or  delay  the unplug arbitrarily. As the libvirt API used in
4250       this command was designed as synchronous it returns success after  some
4251       timeout  even  if the device was not unplugged yet to allow further in‐
4252       teractions with the domain e.g. if the guest is  unresponsive.  Callers
4253       which  need  to make sure that the device was unplugged can use libvirt
4254       events (see virsh event) to be notified when  the  device  is  removed.
4255       Note that the event may arrive before the command returns.
4256
4257       If --live is specified, affect a running domain.  If --config is speci‐
4258       fied, affect the next startup of a persistent guest.  If  --current  is
4259       specified,  it is equivalent to either --live or --config, depending on
4260       the current state of the guest.  Both --live and --config flags may  be
4261       given, but --current is exclusive. When no flag is specified legacy API
4262       is used whose behavior depends on the hypervisor driver.
4263
4264       For compatibility purposes, --persistent behaves like --config  for  an
4265       offline domain, and like --live --config for a running domain.
4266
4267       Note  that older versions of virsh used --config as an alias for --per‐
4268       sistent.
4269
4270   detach-device-alias
4271       Syntax:
4272
4273          detach-device-alias domain alias [[[--live] [--config] | [--current]]]]
4274
4275       Detach a device with given alias from the domain. This command  returns
4276       successfully  after  the unplug request was sent to the hypervisor. The
4277       actual removal of the device is  notified  asynchronously  via  libvirt
4278       events (see virsh event).
4279
4280       If --live is specified, affect a running domain.  If --config is speci‐
4281       fied, affect the next startup of a persistent guest.  If  --current  is
4282       specified,  it is equivalent to either --live or --config, depending on
4283       the current state of the guest.  Both --live and --config flags may  be
4284       given, but --current is exclusive.
4285
4286   detach-disk
4287       Syntax:
4288
4289          detach-disk domain target [[[--live] [--config] |
4290             [--current]] | [--persistent]] [--print-xml]
4291
4292       Detach  a  disk  device from a domain. The target is the device as seen
4293       from the domain.
4294
4295       If --live is specified, affect a running domain.  If --config is speci‐
4296       fied,  affect  the next startup of a persistent guest.  If --current is
4297       specified, it is equivalent to either --live or --config, depending  on
4298       the  current state of the guest.  Both --live and --config flags may be
4299       given, but --current is exclusive. When no flag is specified legacy API
4300       is used whose behavior depends on the hypervisor driver.
4301
4302       For  compatibility  purposes, --persistent behaves like --config for an
4303       offline domain, and like --live --config for a running domain.
4304
4305       Note that older versions of virsh used --config as an alias for  --per‐
4306       sistent.
4307
4308       If --print-xml is specified, then the XML which would be used to detach
4309       the disk is printed instead.
4310
4311       Please see documentation for detach-device for known quirks.
4312
4313   detach-interface
4314       Syntax:
4315
4316          detach-interface domain type [--mac mac]
4317             [[[--live] [--config] | [--current]] | [--persistent]]
4318
4319       Detach a network interface from a domain.  type can be  either  network
4320       to indicate a physical network device or bridge to indicate a bridge to
4321       a device. It is recommended to use the mac option  to  distinguish  be‐
4322       tween the interfaces if more than one are present on the domain.
4323
4324       If --live is specified, affect a running domain.  If --config is speci‐
4325       fied, affect the next startup of a persistent guest.  If  --current  is
4326       specified,  it is equivalent to either --live or --config, depending on
4327       the current state of the guest.  Both --live and --config flags may  be
4328       given, but --current is exclusive. When no flag is specified legacy API
4329       is used whose behavior depends on the hypervisor driver.
4330
4331       For compatibility purposes, --persistent behaves like --config  for  an
4332       offline domain, and like --live --config for a running domain.
4333
4334       Note  that older versions of virsh used --config as an alias for --per‐
4335       sistent.
4336
4337       Please see documentation for detach-device for known quirks.
4338
4339   update-device
4340       Syntax:
4341
4342          update-device domain file [--force] [[[--live]
4343             [--config] | [--current]] | [--persistent]]
4344
4345       Update the characteristics of a device associated with domain, based on
4346       the  device  definition in an XML file.  The --force option can be used
4347       to force device  update,  e.g.,  to  eject  a  CD-ROM  even  if  it  is
4348       locked/mounted    in    the    domain.   See   the   documentation   at
4349       https://libvirt.org/formatdomain.html#elementsDevices  to  learn  about
4350       libvirt XML format for a device.
4351
4352       If --live is specified, affect a running domain.  If --config is speci‐
4353       fied, affect the next startup of a persistent guest.  If  --current  is
4354       specified,  it is equivalent to either --live or --config, depending on
4355       the current state of the guest.  Both --live and --config flags may  be
4356       given,  but --current is exclusive. Not specifying any flag is the same
4357       as specifying --current.
4358
4359       For compatibility purposes, --persistent behaves like --config  for  an
4360       offline domain, and like --live --config for a running domain.
4361
4362       Note  that older versions of virsh used --config as an alias for --per‐
4363       sistent.
4364
4365       Note: using of partial device definition XML files may  lead  to  unex‐
4366       pected  results  as some fields may be autogenerated and thus match de‐
4367       vices other than expected.
4368
4369   update-memory-device
4370       Syntax:
4371
4372          update-memory-device domain [--print-xml] [[--alias alias] | [--node node]]
4373            [[--live] [--config] | [--current]]
4374            [--requested-size size]
4375
4376       This command finds <memory/> device inside given  domain,  changes  re‐
4377       quested  values and passes updated device XML to daemon. If --print-xml
4378       is specified then the device is not changed, but the updated device XML
4379       is  printed to stdout.  If there are more than one <memory/> devices in
4380       domain use --alias or --node to select the desired one.
4381
4382       If --live is specified, affect a running domain.  If --config is speci‐
4383       fied,  affect  the next startup of a persistent guest.  If --current is
4384       specified, it is equivalent to either --live or --config, depending  on
4385       the  current state of the guest.  Both --live and --config flags may be
4386       given, but --current is exclusive. Not specifying any flag is the  same
4387       as specifying --current.
4388
4389       If  --requested-size is specified then <requested/> under memory target
4390       is changed to requested size (as scaled integer, see NOTES  above).  It
4391       defaults  to  kibibytes  if  no suffix is provided. The option is valid
4392       only for virtio-mem memory device model.
4393
4394   change-media
4395       Syntax:
4396
4397          change-media domain path [--eject] [--insert]
4398             [--update] [source] [--force] [[--live] [--config] |
4399             [--current]] [--print-xml] [--block]
4400
4401       Change media of CDROM or floppy drive. path can be the  fully-qualified
4402       path or the unique target name (<target dev='hdc'>) of the disk device.
4403       source specifies the path of the media to be inserted or  updated.  The
4404       --block  flag allows setting the backing type in case a block device is
4405       used as media for the CDROM or floppy drive instead of a file.
4406
4407       --eject indicates the media will be ejected.   --insert  indicates  the
4408       media  will  be  inserted. source must be specified.  If the device has
4409       source (e.g. <source file='media'>), and source is not specified, --up‐
4410       date  is  equal  to --eject. If the device has no source, and source is
4411       specified, --update is equal to --insert. If the device has source, and
4412       source  is  specified, --update behaves like combination of --eject and
4413       --insert.  If none of --eject, --insert,  and  --update  is  specified,
4414       --update  is  used by default.  The --force option can be used to force
4415       media changing.  If --live is specified, alter  live  configuration  of
4416       running  guest.   If --config is specified, alter persistent configura‐
4417       tion, effect observed on next startup of the guest.  --current  can  be
4418       either  or  both of live and config, depends on the hypervisor's imple‐
4419       mentation.  Both --live and --config flags may be given, but  --current
4420       is  exclusive. If no flag is specified, behavior is different depending
4421       on hypervisor.  If --print-xml is specified, the XML that would be used
4422       to change media is printed instead of changing the media.
4423

NODEDEV COMMANDS

4425       The  following commands manipulate host devices that are intended to be
4426       passed through to guest domains via <hostdev> elements  in  a  domain's
4427       <devices> section.  A node device key is generally specified by the bus
4428       name followed by its address, using underscores between all components,
4429       such  as  pci_0000_00_02_1,  usb_1_5_3,  or net_eth1_00_27_13_6a_fe_00.
4430       The nodedev-list gives the full list of host devices that are known  to
4431       libvirt,  although  this  includes devices that cannot be assigned to a
4432       guest (for example, attempting to detach the PCI device  that  controls
4433       the  host's  hard  disk  controller  where the guest's disk images live
4434       could cause the host system to lock up or reboot).
4435
4436       For   more    information    on    node    device    definition    see:
4437       https://libvirt.org/formatnode.html.
4438
4439       Passthrough  devices  cannot be simultaneously used by the host and its
4440       guest domains, nor by multiple active guests at once.  If the <hostdev>
4441       description  of  a PCI device includes the attribute managed='yes', and
4442       the hypervisor driver supports it, then the device is in managed  mode,
4443       and attempts to use that passthrough device in an active guest will au‐
4444       tomatically behave as if nodedev-detach (guest start, device  hot-plug)
4445       and nodedev-reattach (guest stop, device hot-unplug) were called at the
4446       right points.  If a PCI device is not marked as managed, then  it  must
4447       manually  be detached before guests can use it, and manually reattached
4448       to be returned to the host.  Also, if a device  is  manually  detached,
4449       then  the host does not regain control of the device without a matching
4450       reattach, even if the guests use the device in managed mode.
4451
4452   nodedev-create
4453       Syntax:
4454
4455          nodedev-create FILE
4456
4457       Create a device on the host node that can then be assigned  to  virtual
4458       machines.  Normally,  libvirt  is able to automatically determine which
4459       host nodes are available for use, but this allows registration of  host
4460       hardware  that libvirt did not automatically detect.  file contains xml
4461       for a top-level <device> description of a node device.
4462
4463   nodedev-destroy
4464       Syntax:
4465
4466          nodedev-destroy device
4467
4468       Destroy (stop) a device on the host. device can be either  device  name
4469       or  wwn  pair  in  "wwnn,wwpn"  format (only works for vHBA currently).
4470       Note that this makes libvirt quit managing a host device, and may  even
4471       make  that device unusable by the rest of the physical host until a re‐
4472       boot.
4473
4474   nodedev-define
4475       Syntax:
4476
4477          nodedev-define FILE
4478
4479       Define an inactive persistent device or modify an  existing  persistent
4480       one from the XML FILE.
4481
4482   nodedev-undefine
4483       Syntax:
4484
4485          nodedev-undefine device
4486
4487       Undefine  the  configuration  for a persistent device. If the device is
4488       active, make it transient.
4489
4490   nodedev-start
4491       Syntax:
4492
4493          nodedev-start device
4494
4495       Start a (previously defined) inactive device.
4496
4497   nodedev-detach
4498       Syntax:
4499
4500          nodedev-detach nodedev [--driver backend_driver]
4501
4502       Detach nodedev from the host, so that it can safely be used  by  guests
4503       via <hostdev> passthrough.  This is reversed with nodedev-reattach, and
4504       is done automatically for managed devices.
4505
4506       Different backend drivers expect the device to be  bound  to  different
4507       dummy  devices.  For  example, QEMU's "vfio" backend driver expects the
4508       device to be bound to vfio-pci. The --driver parameter can be  used  to
4509       specify the desired backend driver.
4510
4511   nodedev-dumpxml
4512       Syntax:
4513
4514          nodedev-dumpxml [--xpath EXPRESSION] [--wrap] device
4515
4516       Dump a <device> XML representation for the given node device, including
4517       such information as the device name, which bus  owns  the  device,  the
4518       vendor  and  product  id,  and any capabilities of the device usable by
4519       libvirt (such as whether device reset is supported). device can be  ei‐
4520       ther  device  name  or  wwn  pair in "wwnn,wwpn" format (only works for
4521       HBA).
4522
4523       If the --xpath argument provides an XPath expression, it will be evalu‐
4524       ated  against  the  output  XML  and  only those matching nodes will be
4525       printed. The default behaviour is to print  each  matching  node  as  a
4526       standalone  document,  however,  for ease of additional processing, the
4527       --wrap argument will cause the matching node to be wrapped in a  common
4528       root node.
4529
4530   nodedev-info
4531       Syntax:
4532
4533          nodedev-info device
4534
4535       Returns basic information about the device object.
4536
4537   nodedev-list
4538       Syntax:
4539
4540          nodedev-list [--cap capability] [--tree] [--inactive | --all]
4541
4542       List  all  of  the devices available on the node that are known by lib‐
4543       virt.  cap is used to filter the list by capability  types,  the  types
4544       must be separated by comma, e.g. --cap pci,scsi. Valid capability types
4545       include  'system',  'pci',  'usb_device',  'usb',  'net',  'scsi_host',
4546       'scsi_target',  'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic',
4547       'drm',  'mdev',  'mdev_types',  'ccw',  'css',  'ap_card',  'ap_queue',
4548       'ap_matrix'.  By default, only active devices are listed. --inactive is
4549       used to list only inactive devices, and -all is used to list  both  ac‐
4550       tive  and inactive devices.  If --tree is used, the output is formatted
4551       in a tree representing parents of each node.  --tree is mutually exclu‐
4552       sive with all other options.
4553
4554   nodedev-reattach
4555       Syntax:
4556
4557          nodedev-reattach nodedev
4558
4559       Declare  that  nodedev  is no longer in use by any guests, and that the
4560       host can resume normal use of the device.  This is  done  automatically
4561       for  PCI  devices in managed mode and USB devices, but must be done ex‐
4562       plicitly to match any explicit nodedev-detach.
4563
4564   nodedev-reset
4565       Syntax:
4566
4567          nodedev-reset nodedev
4568
4569       Trigger a device reset for nodedev, useful prior to transferring a node
4570       device  between  guest  passthrough or the host.  Libvirt will often do
4571       this action implicitly when required, but this command  allows  an  ex‐
4572       plicit reset when needed.
4573
4574   nodedev-event
4575       Syntax:
4576
4577          nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list}
4578
4579       Wait  for a class of node device events to occur, and print appropriate
4580       details of events as they happen.  The events can  optionally  be  fil‐
4581       tered  by  nodedev.   Using  --list as the only argument will provide a
4582       list of possible event values known by this client, although  the  con‐
4583       nection might not allow registering for all these events.
4584
4585       By default, this command is one-shot, and returns success once an event
4586       occurs; you can send SIGINT (usually via Ctrl-C) to  quit  immediately.
4587       If  --timeout is specified, the command gives up waiting for events af‐
4588       ter seconds have elapsed.   With --loop, the command prints all  events
4589       until a timeout or interrupt key.
4590
4591       When  --timestamp  is  used, a human-readable timestamp will be printed
4592       before the event.
4593
4594   nodedev-autostart
4595       Syntax:
4596
4597          nodedev-autostart [--disable] device
4598
4599       Configure a device to be automatically started when  the  host  machine
4600       boots  or  the parent device becomes available. With --disable, the de‐
4601       vice will be set to manual mode and will  no  longer  be  automatically
4602       started  by  the  host.  This  command  is  only  supported for persis‐
4603       tently-defined mediated devices.
4604

VIRTUAL NETWORK COMMANDS

4606       The following commands manipulate networks. Libvirt has the  capability
4607       to define virtual networks which can then be used by domains and linked
4608       to actual network devices. For more  detailed  information  about  this
4609       feature see the documentation at https://libvirt.org/formatnetwork.html
4610       . Many of the commands for virtual networks are  similar  to  the  ones
4611       used  for  domains,  but the way to name a virtual network is either by
4612       its name or UUID.
4613
4614   net-autostart
4615       Syntax:
4616
4617          net-autostart network [--disable]
4618
4619       Configure a virtual network to be automatically started at  boot.   The
4620       --disable option disable autostarting.
4621
4622   net-create
4623       Syntax:
4624
4625          net-create file [--validate]
4626
4627       Create a transient (temporary) virtual network from an XML file and in‐
4628       stantiate   (start)   the   network.    See   the   documentation    at
4629       https://libvirt.org/formatnetwork.html  to get a description of the XML
4630       network format used by libvirt.
4631
4632       Optionally, the format of the input XML file can be  validated  against
4633       an internal RNG schema with --validate.
4634
4635   net-define
4636       Syntax:
4637
4638          net-define file [--validate]
4639
4640       Define  an  inactive  persistent  virtual network or modify an existing
4641       persistent one from the XML file.  Optionally, the format of the  input
4642       XML  file  can be validated against an internal RNG schema with --vali‐
4643       date.
4644
4645   net-destroy
4646       Syntax:
4647
4648          net-destroy network
4649
4650       Destroy (stop) a given transient or persistent virtual  network  speci‐
4651       fied by its name or UUID. This takes effect immediately.
4652
4653   net-dumpxml
4654       Syntax:
4655
4656          net-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] network
4657
4658       Output  the  virtual  network information as an XML dump to stdout.  If
4659       --inactive is specified, then physical functions are not expanded  into
4660       their associated virtual functions.
4661
4662       If the --xpath argument provides an XPath expression, it will be evalu‐
4663       ated against the output XML and  only  those  matching  nodes  will  be
4664       printed.  The  default  behaviour  is  to print each matching node as a
4665       standalone document, however, for ease of  additional  processing,  the
4666       --wrap  argument will cause the matching node to be wrapped in a common
4667       root node.
4668
4669   net-edit
4670       Syntax:
4671
4672          net-edit network
4673
4674       Edit the XML configuration file for a network.
4675
4676       This is equivalent to:
4677
4678          virsh net-dumpxml --inactive network > network.xml
4679          vi network.xml (or make changes with your other text editor)
4680          virsh net-define network.xml
4681
4682       except that it does some error checking.
4683
4684       The editor used can be supplied by the $VISUAL or  $EDITOR  environment
4685       variables, and defaults to vi.
4686
4687   net-event
4688       Syntax:
4689
4690          net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list}
4691
4692       Wait  for a class of network events to occur, and print appropriate de‐
4693       tails of events as they happen.  The events can optionally be  filtered
4694       by  network.   Using --list as the only argument will provide a list of
4695       possible event values known by this  client,  although  the  connection
4696       might not allow registering for all these events.
4697
4698       By default, this command is one-shot, and returns success once an event
4699       occurs; you can send SIGINT (usually via Ctrl-C) to  quit  immediately.
4700       If  --timeout is specified, the command gives up waiting for events af‐
4701       ter seconds have elapsed.   With --loop, the command prints all  events
4702       until a timeout or interrupt key.
4703
4704       When  --timestamp  is  used, a human-readable timestamp will be printed
4705       before the event.
4706
4707   net-info
4708       Syntax:
4709
4710          net-info network
4711
4712       Returns basic information about the network object.
4713
4714   net-list
4715       Syntax:
4716
4717          net-list [--inactive | --all]
4718             { [--table] | --name | --uuid }
4719             [--persistent] [<--transient>]
4720             [--autostart] [<--no-autostart>]
4721
4722       Returns the list of active networks, if --all is  specified  this  will
4723       also  include defined but inactive networks, if --inactive is specified
4724       only the inactive ones will be listed. You may also want to filter  the
4725       returned  networks by --persistent to list the persistent ones, --tran‐
4726       sient to list the transient ones, --autostart to list the ones with au‐
4727       tostart  enabled,  and  --no-autostart  to list the ones with autostart
4728       disabled.
4729
4730       If --name is specified, network names are printed instead of the  table
4731       formatted  one  per  line.  If --uuid is specified network's UUID's are
4732       printed instead of names. Flag --table specifies that  the  legacy  ta‐
4733       ble-formatted  output should be used. This is the default. All of these
4734       are mutually exclusive.
4735
4736       NOTE: When talking to older servers, this command is forced  to  use  a
4737       series  of  API  calls with an inherent race, where a pool might not be
4738       listed or might appear more than once if it changed state between calls
4739       while  the  list  was  being collected.  Newer servers do not have this
4740       problem.
4741
4742   net-name
4743       Syntax:
4744
4745          net-name network-UUID
4746
4747       Convert a network UUID to network name.
4748
4749   net-start
4750       Syntax:
4751
4752          net-start network
4753
4754       Start a (previously defined) inactive network.
4755
4756   net-undefine
4757       Syntax:
4758
4759          net-undefine network
4760
4761       Undefine the configuration for a persistent network. If the network  is
4762       active, make it transient.
4763
4764   net-uuid
4765       Syntax:
4766
4767          net-uuid network-name
4768
4769       Convert a network name to network UUID.
4770
4771   net-update
4772       Syntax:
4773
4774          net-update network command section xml
4775             [--parent-index index] [[--live] [--config] | [--current]]
4776
4777       Update  the  given  section of an existing network definition, with the
4778       changes optionally taking effect immediately, without  needing  to  de‐
4779       stroy and re-start the network.
4780
4781       command  is  one  of  "add-first",  "add-last",  "add"  (a  synonym for
4782       add-last), "delete", or "modify".
4783
4784       section  is  one   of   "bridge",   "domain",   "ip",   "ip-dhcp-host",
4785       "ip-dhcp-range",  "forward",  "forward-interface", "forward-pf", "port‐
4786       group", "dns-host", "dns-txt", or "dns-srv", each section  being  named
4787       by  a concatenation of the xml element hierarchy leading to the element
4788       being changed. For example, "ip-dhcp-host" will change a <host> element
4789       that is contained inside a <dhcp> element inside an <ip> element of the
4790       network.
4791
4792       xml is either the text of a complete xml  element  of  the  type  being
4793       changed  (e.g.  "<host  mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the
4794       name of a file that contains a complete xml element. Disambiguation  is
4795       done  by  looking  at the first character of the provided text - if the
4796       first character is "<", it is xml text, if the first character  is  not
4797       "<", it is the name of a file that contains the xml text to be used.
4798
4799       The  --parent-index  option  is used to specify which of several parent
4800       elements the requested element is in (0-based).  For  example,  a  dhcp
4801       <host>  element  could  be  in any one of multiple <ip> elements in the
4802       network; if a parent-index isn't provided, the "most appropriate"  <ip>
4803       element  will  be  selected  (usually  the  only one that already has a
4804       <dhcp> element), but if --parent-index is given,  that  particular  in‐
4805       stance of <ip> will get the modification.
4806
4807       If --live is specified, affect a running network.  If --config is spec‐
4808       ified, affect the next startup of a persistent network.   If  --current
4809       is  specified, it is equivalent to either --live or --config, depending
4810       on the current state of the guest.  Both --live and --config flags  may
4811       be  given,  but  --current is exclusive. Not specifying any flag is the
4812       same as specifying --current.
4813
4814   net-dhcp-leases
4815       Syntax:
4816
4817          net-dhcp-leases network [mac]
4818
4819       Get a list of dhcp leases for all network interfaces connected  to  the
4820       given  virtual  network or limited output just for one interface if mac
4821       is specified.
4822

NETWORK PORT COMMANDS

4824       The following commands manipulate network ports. Libvirt  virtual  net‐
4825       works  have  ports created when a virtual machine has a virtual network
4826       interface added. In general there should be no need to use any  of  the
4827       commands  here, since the hypervisor drivers run these commands are the
4828       right point in a virtual machine's lifecycle. They can  be  useful  for
4829       debugging problems and / or recovering from bugs / stale state.
4830
4831   net-port-list
4832       Syntax:
4833
4834          net-port-list { [--table] | --uuid } network
4835
4836       List all network ports recorded against the network.
4837
4838       If  --uuid  is specified network ports' UUID's are printed instead of a
4839       table. Flag --table specifies that the  legacy  table-formatted  output
4840       should  be used. This is the default.  All of these are mutually exclu‐
4841       sive.
4842
4843   net-port-create
4844       Syntax:
4845
4846          net-port-create network file [--validate]
4847
4848       Allocate a new network port reserving resources based on the  port  de‐
4849       scription.   Optionally,  the format of the input XML file can be vali‐
4850       dated against an internal RNG schema with --validate.
4851
4852   net-port-dumpxml
4853       Syntax:
4854
4855          net-port-dumpxml [--xpath EXPRESSION] [--wrap] network port
4856
4857       Output the network port information as an XML dump to stdout.
4858
4859       If the --xpath argument provides an XPath expression, it will be evalu‐
4860       ated  against  the  output  XML  and  only those matching nodes will be
4861       printed. The default behaviour is to print  each  matching  node  as  a
4862       standalone  document,  however,  for ease of additional processing, the
4863       --wrap argument will cause the matching node to be wrapped in a  common
4864       root node.
4865
4866   net-port-delete
4867       Syntax:
4868
4869          net-port-delete network port
4870
4871       Delete record of the network port and release its resources
4872

INTERFACE COMMANDS

4874       The  following  commands manipulate host interfaces.  Often, these host
4875       interfaces can then be used by name within domain <interface>  elements
4876       (such  as  a system-created bridge interface), but there is no require‐
4877       ment that host interfaces be tied to any particular guest configuration
4878       XML at all.
4879
4880       Many  of  the commands for host interfaces are similar to the ones used
4881       for domains, and the way to name an interface is either by its name  or
4882       its  MAC  address.   However, using a MAC address for an iface argument
4883       only works when that address is unique (if an interface  and  a  bridge
4884       share  the  same  MAC address, which is often the case, then using that
4885       MAC address results in an error due to ambiguity, and you  must  resort
4886       to a name instead).
4887
4888   iface-bridge
4889       Syntax:
4890
4891          iface-bridge interface bridge [--no-stp] [delay] [--no-start]
4892
4893       Create  a  bridge  device named bridge, and attach the existing network
4894       device interface to the new bridge.  The new bridge defaults to  start‐
4895       ing  immediately, with STP enabled and a delay of 0; these settings can
4896       be altered with --no-stp, --no-start, and an integer number of  seconds
4897       for  delay.  All IP address configuration of interface will be moved to
4898       the new bridge device.
4899
4900       See also iface-unbridge for undoing this operation.
4901
4902   iface-define
4903       Syntax:
4904
4905          iface-define file [--validate]
4906
4907       Define an inactive persistent physical host interface or modify an  ex‐
4908       isting  persistent one from the XML file. Optionally, the format of the
4909       input XML file can be validated against an  internal  RNG  schema  with
4910       --validate.
4911
4912   iface-destroy
4913       Syntax:
4914
4915          iface-destroy interface
4916
4917       Destroy  (stop) a given host interface, such as by running "if-down" to
4918       disable that interface from active use. This takes effect immediately.
4919
4920   iface-dumpxml
4921       Syntax:
4922
4923          iface-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] interface
4924
4925       Output the host interface information as an XML  dump  to  stdout.   If
4926       --inactive  is specified, then the output reflects the persistent state
4927       of the interface that will be used the next time it is started.
4928
4929       If the --xpath argument provides an XPath expression, it will be evalu‐
4930       ated  against  the  output  XML  and  only those matching nodes will be
4931       printed. The default behaviour is to print  each  matching  node  as  a
4932       standalone  document,  however,  for ease of additional processing, the
4933       --wrap argument will cause the matching node to be wrapped in a  common
4934       root node.
4935
4936   iface-edit
4937       Syntax:
4938
4939          iface-edit interface
4940
4941       Edit the XML configuration file for a host interface.
4942
4943       This is equivalent to:
4944
4945          virsh iface-dumpxml iface > iface.xml
4946          vi iface.xml (or make changes with your other text editor)
4947          virsh iface-define iface.xml
4948
4949       except that it does some error checking.
4950
4951       The  editor  used can be supplied by the $VISUAL or $EDITOR environment
4952       variables, and defaults to vi.
4953
4954   iface-list
4955       Syntax:
4956
4957          iface-list [--inactive | --all]
4958
4959       Returns the list of active host interfaces.  If --all is specified this
4960       will  also  include  defined but inactive interfaces.  If --inactive is
4961       specified only the inactive ones will be listed.
4962
4963   iface-name
4964       Syntax:
4965
4966          iface-name interface
4967
4968       Convert a host interface MAC to interface name, if the MAC  address  is
4969       unique among the host's interfaces.
4970
4971       interface specifies the interface MAC address.
4972
4973   iface-mac
4974       Syntax:
4975
4976          iface-mac interface
4977
4978       Convert a host interface name to MAC address.
4979
4980       interface specifies the interface name.
4981
4982   iface-start
4983       Syntax:
4984
4985          iface-start interface
4986
4987       Start  a  (previously  defined)  host  interface,  such  as  by running
4988       "if-up".
4989
4990   iface-unbridge
4991       Syntax:
4992
4993          iface-unbridge bridge [--no-start]
4994
4995       Tear down a bridge device named bridge, releasing its underlying inter‐
4996       face back to normal usage, and moving all IP address configuration from
4997       the bridge device to the underlying device.  The  underlying  interface
4998       is  restarted  unless  --no-start  is present; this flag is present for
4999       symmetry, but generally not recommended.
5000
5001       See also iface-bridge for creating a bridge.
5002
5003   iface-undefine
5004       Syntax:
5005
5006          iface-undefine interface
5007
5008       Undefine the configuration for an inactive host interface.
5009
5010   iface-begin
5011       Syntax:
5012
5013          iface-begin
5014
5015       Create a snapshot of current host interface settings, which  can  later
5016       be  committed  (iface-commit) or restored (iface-rollback).  If a snap‐
5017       shot already exists, then this command will  fail  until  the  previous
5018       snapshot has been committed or restored.  Undefined behavior results if
5019       any external changes are made to host interfaces outside of the libvirt
5020       API  between  the  beginning  of  a snapshot and its eventual commit or
5021       rollback.
5022
5023   iface-commit
5024       Syntax:
5025
5026          iface-commit
5027
5028       Declare all changes since the last iface-begin as working,  and  delete
5029       the rollback point.  If no interface snapshot has already been started,
5030       then this command will fail.
5031
5032   iface-rollback
5033       Syntax:
5034
5035          iface-rollback
5036
5037       Revert all host interface settings back to the state  recorded  in  the
5038       last  iface-begin.   If no interface snapshot has already been started,
5039       then this command will fail.  Rebooting the host also serves as an  im‐
5040       plicit rollback point.
5041

STORAGE POOL COMMANDS

5043       The  following commands manipulate storage pools. Libvirt has the capa‐
5044       bility to manage various storage solutions, including files, raw parti‐
5045       tions, and domain-specific formats, used to provide the storage volumes
5046       visible as devices within virtual machines. For more detailed  informa‐
5047       tion     about    this    feature,    see    the    documentation    at
5048       https://libvirt.org/formatstorage.html . Many of the commands for pools
5049       are similar to the ones used for domains.
5050
5051   find-storage-pool-sources
5052       Syntax:
5053
5054          find-storage-pool-sources type [srcSpec]
5055
5056       Returns XML describing all possible available storage pool sources that
5057       could be used to create or define a storage pool of a  given  type.  If
5058       srcSpec is provided, it is a file that contains XML to further restrict
5059       the query for pools.
5060
5061       Not all storage pools support discovery in  this  manner.  Furthermore,
5062       for those that do support discovery, only specific XML elements are re‐
5063       quired in order to return valid data, while other elements and even at‐
5064       tributes  of  some elements are ignored since they are not necessary to
5065       find the pool based on the search criteria.  The  following  lists  the
5066       supported  type  options  and the expected minimal XML elements used to
5067       perform the search.
5068
5069       For a "netfs" or "gluster" pool, the minimal expected XML  required  is
5070       the <host> element with a "name" attribute describing the IP address or
5071       hostname to be used to find the pool. The "port" attribute will be  ig‐
5072       nored as will any other provided XML elements in srcSpec.
5073
5074       For a "logical" pool, the contents of the srcSpec file are ignored, al‐
5075       though if provided the file must at least exist.
5076
5077       For an "iscsi" or "iscsi-direct" pool, the minimal expect XML  required
5078       is the <host> element with a "name" attribute describing the IP address
5079       or hostname to be used to find the pool (the iSCSI server address). Op‐
5080       tionally,  the  "port"  attribute may be provided, although it will de‐
5081       fault to 3260. Optionally, an <initiator> XML element with a "name" at‐
5082       tribute  may be provided to further restrict the iSCSI target search to
5083       a specific initiator for multi-iqn iSCSI storage pools.
5084
5085   find-pool-sources-as
5086       Syntax:
5087
5088          find-storage-pool-sources-as type [host] [port] [initiator]
5089
5090       Rather than providing srcSpec XML  file  for  find-storage-pool-sources
5091       use  this  command option in order to have virsh generate the query XML
5092       file using the optional arguments. The command  will  return  the  same
5093       output XML as find-storage-pool-sources.
5094
5095       Use host to describe a specific host to use for networked storage, such
5096       as netfs, gluster, and iscsi type pools.
5097
5098       Use port to further restrict which networked port to  utilize  for  the
5099       connection if required by the specific storage backend, such as iscsi.
5100
5101       Use  initiator to further restrict the iscsi type pool searches to spe‐
5102       cific target initiators.
5103
5104   pool-autostart
5105       Syntax:
5106
5107          pool-autostart pool-or-uuid [--disable]
5108
5109       Configure whether pool should automatically start at boot.
5110
5111   pool-build
5112       Syntax:
5113
5114          pool-build pool-or-uuid [--overwrite] [--no-overwrite]
5115
5116       Build a given pool.
5117
5118       Options --overwrite and --no-overwrite can only be used for  pool-build
5119       a filesystem, disk, or logical pool.
5120
5121       For  a  file  system pool if neither flag is specified, then pool-build
5122       just makes the target path directory and no attempt to run mkfs on  the
5123       target  volume device. If --no-overwrite is specified, it probes to de‐
5124       termine if a filesystem already exists on the target device,  returning
5125       an  error  if  one  exists or using mkfs to format the target device if
5126       not.  If --overwrite is specified, mkfs is always executed and any  ex‐
5127       isting data on the target device is overwritten unconditionally.
5128
5129       For  a  disk pool, if neither of them is specified or --no-overwrite is
5130       specified, pool-build will check the target volume device for  existing
5131       filesystems or partitions before attempting to write a new label on the
5132       target volume device. If the target volume device already has a  label,
5133       the  command will fail. If --overwrite is specified, then no check will
5134       be made on the target volume device prior to writing a new label. Writ‐
5135       ing of the label uses the pool source format type or "dos" if not spec‐
5136       ified.
5137
5138       For a logical pool, if neither of them is specified  or  --no-overwrite
5139       is  specified,  pool-build will check the target volume devices for ex‐
5140       isting filesystems or partitions before attempting  to  initialize  and
5141       format  each device for usage by the logical pool. If any target volume
5142       device already has a label, the command will fail.  If  --overwrite  is
5143       specified,  then  no  check  will  be made on the target volume devices
5144       prior to initializing and formatting each device. Once all  the  target
5145       volume  devices  are  properly formatted via pvcreate, the volume group
5146       will be created using all the devices.
5147
5148   pool-create
5149       Syntax:
5150
5151          pool-create file [--build] [[--overwrite] | [--no-overwrite]]
5152
5153       Create and start a pool object from the XML file.
5154
5155       [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
5156       creation  in  order to remove the need for a follow-up command to build
5157       the pool. The --overwrite and  --no-overwrite  flags  follow  the  same
5158       rules  as  pool-build.  If just --build is provided, then pool-build is
5159       called with no flags.
5160
5161   pool-create-as
5162       Syntax:
5163
5164          pool-create-as name type
5165             [--source-host hostname] [--source-path path] [--source-dev path]
5166             [--source-name name] [--target path] [--source-format format]
5167             [--source-initiator initiator-iqn]
5168             [--auth-type authtype --auth-username username
5169             [--secret-usage usage | --secret-uuid uuid]]
5170             [--source-protocol-ver ver]
5171             [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn]
5172             [--adapter-parent parent |
5173             --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
5174             --adapter-parent-fabric-wwn parent_fabric_wwn]]
5175             [--build] [[--overwrite] | [--no-overwrite]] [--print-xml]
5176
5177       Create and start a pool  object  name  from  the  raw  parameters.   If
5178       --print-xml is specified, then print the XML of the pool object without
5179       creating the pool.  Otherwise, the pool has the  specified  type.  When
5180       using pool-create-as for a pool of type "disk", the existing partitions
5181       found on the --source-dev path will be used to populate the disk  pool.
5182       Therefore,  it  is  suggested to use pool-define-as and pool-build with
5183       the --overwrite in order to properly initialize the disk pool.
5184
5185       [--source-host hostname] provides the source hostname for pools  backed
5186       by  storage  from a remote server (pool types netfs, iscsi, rbd, sheep‐
5187       dog, gluster).
5188
5189       [--source-path path] provides  the  source  directory  path  for  pools
5190       backed by directories (pool type dir).
5191
5192       [--source-dev path] provides the source path for pools backed by physi‐
5193       cal devices (pool types fs, logical, disk, iscsi, zfs).
5194
5195       [--source-name name] provides the source name for pools backed by stor‐
5196       age from a named element (pool types logical, rbd, sheepdog, gluster).
5197
5198       [--target  path]  is  the path for the mapping of the storage pool into
5199       the host file system.
5200
5201       [--source-format format] provides information about the format  of  the
5202       pool (pool types fs, netfs, disk, logical).
5203
5204       [--source-initiator initiator-iqn] provides the initiator iqn for iscsi
5205       connection of the pool (pool type iscsi-direct).
5206
5207       [--auth-type authtype --auth-username username [--secret-usage usage  |
5208       --secret-uuid uuid]] provides the elements required to generate authen‐
5209       tication credentials for the storage pool. The authtype is either  chap
5210       for  iscsi type pools or ceph for rbd type pools. Either the secret us‐
5211       age or uuid value may be provided, but not both.
5212
5213       [--source-protocol-ver ver] provides the NFS  protocol  version  number
5214       used  to  contact  the  server's  NFS  service  via  nfs  mount  option
5215       'nfsvers=n'. It is expect the ver value is an unsigned integer.
5216
5217       [--adapter-name name] defines the scsi_hostN adapter name  to  be  used
5218       for the scsi_host adapter type pool.
5219
5220       [--adapter-wwnn  wwnn  --adapter-wwpn  wwpn  [--adapter-parent parent |
5221       --adapter-parent-wwnn  parent_wwnn  adapter-parent-wwpn  parent_wwpn  |
5222       --adapter-parent-fabric-wwn  parent_fabric_wwn]]  defines  the wwnn and
5223       wwpn to be used for the fc_host adapter type pool.  Optionally  provide
5224       the  parent  scsi_hostN  node  device to be used for the vHBA either by
5225       parent name, parent_wwnn and parent_wwpn,  or  parent_fabric_wwn.   The
5226       parent  name  could  change between reboots if the hardware environment
5227       changes, so providing the parent_wwnn and parent_wwpn ensure  usage  of
5228       the same physical HBA even if the scsi_hostN node device changes. Usage
5229       of the parent_fabric_wwn allows a bit more flexibility to choose an HBA
5230       on the same storage fabric in order to define the pool.
5231
5232       [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
5233       creation in order to remove the need for a follow-up command  to  build
5234       the  pool.  The  --overwrite  and  --no-overwrite flags follow the same
5235       rules as pool-build. If just --build is provided,  then  pool-build  is
5236       called with no flags.
5237
5238       For   a  "logical"  pool  only  [--name]  needs  to  be  provided.  The
5239       [--source-name] if provided must match the Volume Group name.   If  not
5240       provided,  one  will  be  generated using the [--name]. If provided the
5241       [--target] is ignored and  a  target  source  is  generated  using  the
5242       [--source-name] (or as generated from the [--name]).
5243
5244   pool-define
5245       Syntax:
5246
5247          pool-define file [--validate]
5248
5249       Define  an  inactive persistent storage pool or modify an existing per‐
5250       sistent one from the XML file.  Optionally, the format of the input XML
5251       file can be validated against an internal RNG schema with --validate.
5252
5253   pool-define-as
5254       Syntax:
5255
5256          pool-define-as name type
5257             [--source-host hostname] [--source-path path] [--source-dev path]
5258             [*--source-name name*] [*--target path*] [*--source-format format*]
5259             [--source-initiator initiator-iqn]
5260             [*--auth-type authtype* *--auth-username username*
5261             [*--secret-usage usage* | *--secret-uuid uuid*]]
5262             [*--source-protocol-ver ver*]
5263             [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*]
5264             [*--adapter-parent parent*]] [*--print-xml*]
5265
5266       Create,  but  do not start, a pool object name from the raw parameters.
5267       If --print-xml is specified, then print the  XML  of  the  pool  object
5268       without defining the pool.  Otherwise, the pool has the specified type.
5269
5270       Use  the  same  arguments  as  pool-create-as,  except for the --build,
5271       --overwrite, and --no-overwrite options.
5272
5273   pool-destroy
5274       Syntax:
5275
5276          pool-destroy pool-or-uuid
5277
5278       Destroy (stop) a given pool object. Libvirt will no longer  manage  the
5279       storage described by the pool object, but the raw data contained in the
5280       pool is not changed, and can be later recovered with pool-create.
5281
5282   pool-delete
5283       Syntax:
5284
5285          pool-delete pool-or-uuid
5286
5287       Destroy the resources used by a given pool object.  This  operation  is
5288       non-recoverable.   The pool object will still exist after this command,
5289       ready for the creation of new storage volumes.
5290
5291   pool-dumpxml
5292       Syntax:
5293
5294          pool-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] pool-or-uuid
5295
5296       Returns the XML information about the pool  object.   --inactive  tells
5297       virsh to dump pool configuration that will be used on next start of the
5298       pool as opposed to the current pool configuration.
5299
5300       If the --xpath argument provides an XPath expression, it will be evalu‐
5301       ated  against  the  output  XML  and  only those matching nodes will be
5302       printed. The default behaviour is to print  each  matching  node  as  a
5303       standalone  document,  however,  for ease of additional processing, the
5304       --wrap argument will cause the matching node to be wrapped in a  common
5305       root node.
5306
5307   pool-edit
5308       Syntax:
5309
5310          pool-edit pool-or-uuid
5311
5312       Edit the XML configuration file for a storage pool.
5313
5314       This is equivalent to:
5315
5316          virsh pool-dumpxml pool > pool.xml
5317          vi pool.xml (or make changes with your other text editor)
5318          virsh pool-define pool.xml
5319
5320       except that it does some error checking.
5321
5322       The  editor  used can be supplied by the $VISUAL or $EDITOR environment
5323       variables, and defaults to vi.
5324
5325   pool-info
5326       Syntax:
5327
5328          pool-info [--bytes] pool-or-uuid
5329
5330       Returns basic information about the pool object. If --bytes  is  speci‐
5331       fied the sizes of basic info are not converted to human friendly units.
5332
5333   pool-list
5334       Syntax:
5335
5336          pool-list [--inactive] [--all]
5337             [--persistent] [--transient]
5338             [--autostart] [--no-autostart]
5339             [[--details] [--uuid]
5340             [--name] [<type>]
5341
5342       List  pool objects known to libvirt.  By default, only active pools are
5343       listed; --inactive lists just the inactive pools, and --all  lists  all
5344       pools.
5345
5346       In addition, there are several sets of filtering flags. --persistent is
5347       to list the persistent pools, --transient  is  to  list  the  transient
5348       pools.   --autostart lists the autostarting pools, --no-autostart lists
5349       the pools with autostarting  disabled.  If  --uuid  is  specified  only
5350       pool's UUIDs are printed.  If --name is specified only pool's names are
5351       printed. If both --name and --uuid are specified, pool's UUID and names
5352       are  printed side by side without any header. Option --details is mutu‐
5353       ally exclusive with options --uuid and --name.
5354
5355       You may also want to list pools with specified types  using  type,  the
5356       pool  types must be separated by comma, e.g. --type dir,disk. The valid
5357       pool types include 'dir', 'fs', 'netfs',  'logical',  'disk',  'iscsi',
5358       'scsi',  'mpath',  'rbd',  'sheepdog', 'gluster', 'zfs', 'vstorage' and
5359       'iscsi-direct'.
5360
5361       The --details option instructs virsh to additionally display pool  per‐
5362       sistence and capacity related information where available.
5363
5364       NOTE:  When  talking  to older servers, this command is forced to use a
5365       series of API calls with an inherent race, where a pool  might  not  be
5366       listed or might appear more than once if it changed state between calls
5367       while the list was being collected.  Newer servers  do  not  have  this
5368       problem.
5369
5370   pool-name
5371       Syntax:
5372
5373          pool-name uuid
5374
5375       Convert the uuid to a pool name.
5376
5377   pool-refresh
5378       Syntax:
5379
5380          pool-refresh pool-or-uuid
5381
5382       Refresh the list of volumes contained in pool.
5383
5384   pool-start
5385       Syntax:
5386
5387          pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]
5388
5389       Start the storage pool, which is previously defined but inactive.
5390
5391       [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build prior
5392       to pool-start to ensure the pool environment is in  an  expected  state
5393       rather  than  needing  to  run  the build command prior to startup. The
5394       --overwrite  and  --no-overwrite  flags  follow  the  same   rules   as
5395       pool-build. If just --build is provided, then pool-build is called with
5396       no flags.
5397
5398       Note: A storage pool that relies on remote resources such as an "iscsi"
5399       or  a (v)HBA backed "scsi" pool may need to be refreshed multiple times
5400       in order to have all the volumes detected (see pool-refresh).  This  is
5401       because  the  corresponding  volume  devices  may not be present in the
5402       host's filesystem during the initial pool startup or  the  current  re‐
5403       fresh attempt. The number of refresh retries is dependent upon the net‐
5404       work connection and the time the host takes to export the corresponding
5405       devices.
5406
5407   pool-undefine
5408       Syntax:
5409
5410          pool-undefine pool-or-uuid
5411
5412       Undefine the configuration for an inactive pool.
5413
5414   pool-uuid
5415       Syntax:
5416
5417          pool-uuid pool
5418
5419       Returns the UUID of the named pool.
5420
5421   pool-event
5422       Syntax:
5423
5424          pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list}
5425
5426       Wait for a class of storage pool events to occur, and print appropriate
5427       details of events as they happen.  The events can  optionally  be  fil‐
5428       tered  by  pool.  Using --list as the only argument will provide a list
5429       of possible event values known by this client, although the  connection
5430       might not allow registering for all these events.
5431
5432       By default, this command is one-shot, and returns success once an event
5433       occurs; you can send SIGINT (usually via Ctrl-C) to  quit  immediately.
5434       If  --timeout is specified, the command gives up waiting for events af‐
5435       ter seconds have elapsed.   With --loop, the command prints all  events
5436       until a timeout or interrupt key.
5437
5438       When  --timestamp  is  used, a human-readable timestamp will be printed
5439       before the event.
5440

VOLUME COMMANDS

5442   vol-create
5443       Syntax:
5444
5445          vol-create pool-or-uuid FILE [--prealloc-metadata]
5446
5447       Create a volume from an XML <file>.
5448
5449       pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5450       ume in.
5451
5452       FILE  is the XML <file> with the volume definition. An easy way to cre‐
5453       ate the XML <file> is to use the vol-dumpxml command to obtain the def‐
5454       inition of a pre-existing volume.
5455
5456       [--prealloc-metadata]  preallocate  metadata  (for  qcow2  images which
5457       don't support full allocation). This option creates a sparse image file
5458       with  metadata, resulting in higher performance compared to images with
5459       no preallocation and only slightly higher initial disk space usage.
5460
5461       Example:
5462
5463          virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
5464          vi newvolume.xml (or make changes with your other text editor)
5465          virsh vol-create differentstoragepool newvolume.xml
5466
5467   vol-create-from
5468       Syntax:
5469
5470          vol-create-from pool-or-uuid FILE vol-name-or-key-or-path
5471             [--inputpool pool-or-uuid]  [--prealloc-metadata] [--reflink]
5472
5473       Create a volume, using another volume as input.
5474
5475       pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5476       ume in.
5477
5478       FILE is the XML <file> with the volume definition.
5479
5480       vol-name-or-key-or-path  is  the name or key or path of the source vol‐
5481       ume.
5482
5483       --inputpool pool-or-uuid is the name or uuid of the  storage  pool  the
5484       source volume is in.
5485
5486       [--prealloc-metadata]  preallocate  metadata  (for  qcow2  images which
5487       don't support full allocation). This option creates a sparse image file
5488       with  metadata, resulting in higher performance compared to images with
5489       no preallocation and only slightly higher initial disk space usage.
5490
5491       When --reflink is specified, perform a COW lightweight copy, where  the
5492       data  blocks  are  copied only when modified.  If this is not possible,
5493       the copy fails.
5494
5495   vol-create-as
5496       Syntax:
5497
5498          vol-create-as pool-or-uuid name capacity [--allocation size] [--format string]
5499             [--backing-vol vol-name-or-key-or-path]
5500             [--backing-vol-format string] [--prealloc-metadata] [--print-xml]
5501
5502       Create a volume from a set of arguments unless  --print-xml  is  speci‐
5503       fied,  in  which  case just the XML of the volume object is printed out
5504       without any actual object creation.
5505
5506       pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5507       ume in.
5508
5509       name  is  the  name of the new volume. For a disk pool, this must match
5510       the partition name as determined from the pool's source device path and
5511       the  next  available  partition.  For  example, a source device path of
5512       /dev/sdb and there are no partitions on the disk, then the name must be
5513       sdb1 with the next name being sdb2 and so on.
5514
5515       capacity  is  the size of the volume to be created, as a scaled integer
5516       (see NOTES above), defaulting to bytes if there is no suffix.
5517
5518       --allocation size is the initial size to be allocated  in  the  volume,
5519       also as a scaled integer defaulting to bytes.
5520
5521       --format string is used in file based storage pools to specify the vol‐
5522       ume file format to use; raw, bochs, qcow, qcow2,  vmdk,  qed.  Use  ex‐
5523       tended  for disk storage pools in order to create an extended partition
5524       (other values are validity checked but not preserved when  libvirtd  is
5525       restarted or the pool is refreshed).
5526
5527       --backing-vol  vol-name-or-key-or-path  is the source backing volume to
5528       be used if taking a snapshot of an existing volume.
5529
5530       --backing-vol-format string is the format of the snapshot backing  vol‐
5531       ume;  raw,  bochs, qcow, qcow2, qed, vmdk, host_device. These are, how‐
5532       ever, meant for file based storage pools.
5533
5534       [--prealloc-metadata] preallocate  metadata  (for  qcow2  images  which
5535       don't support full allocation). This option creates a sparse image file
5536       with metadata, resulting in higher performance compared to images  with
5537       no preallocation and only slightly higher initial disk space usage.
5538
5539   vol-clone
5540       Syntax:
5541
5542          vol-clone vol-name-or-key-or-path name
5543             [--pool pool-or-uuid] [--prealloc-metadata] [--reflink]
5544
5545       Clone  an  existing  volume within the parent pool.  Less powerful, but
5546       easier to type, version of vol-create-from.
5547
5548       vol-name-or-key-or-path is the name or key or path of the  source  vol‐
5549       ume.
5550
5551       name is the name of the new volume.
5552
5553       --pool  pool-or-uuid  is the name or UUID of the storage pool that con‐
5554       tains the source volume and will contain the new volume.  If the source
5555       volume  name is provided instead of the key or path, then providing the
5556       pool is necessary to find the volume to be cloned; otherwise, the first
5557       volume found by the key or path will be used.
5558
5559       [--prealloc-metadata]  preallocate  metadata  (for  qcow2  images which
5560       don't support full allocation). This option creates a sparse image file
5561       with  metadata, resulting in higher performance compared to images with
5562       no preallocation and only slightly higher initial disk space usage.
5563
5564       When --reflink is specified, perform a COW lightweight copy, where  the
5565       data  blocks  are  copied only when modified.  If this is not possible,
5566       the copy fails.
5567
5568   vol-delete
5569       Syntax:
5570
5571          vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots]
5572
5573       Delete a given volume.
5574
5575       vol-name-or-key-or-path is the volume name or key or path of the volume
5576       to delete.
5577
5578       [--pool  pool-or-uuid] is the name or UUID of the storage pool the vol‐
5579       ume is in. If the volume name is provided instead of the key  or  path,
5580       then  providing the pool is necessary to find the volume to be deleted;
5581       otherwise, the first volume found by the key or path will be used.
5582
5583       The --delete-snapshots flag specifies  that  any  snapshots  associated
5584       with  the  storage  volume  should  be deleted as well. Not all storage
5585       drivers support this option, presently only rbd.
5586
5587   vol-upload
5588       Syntax:
5589
5590          vol-upload vol-name-or-key-or-path local-file
5591             [--pool pool-or-uuid] [--offset bytes]
5592             [--length bytes] [--sparse]
5593
5594       Upload the contents of local-file to a storage volume.
5595
5596       vol-name-or-key-or-path is the name or key or path of the volume  where
5597       the local-file will be uploaded.
5598
5599       --pool  pool-or-uuid is the name or UUID of the storage pool the volume
5600       is in. If the volume name is provided instead of the key or path,  then
5601       providing the pool is necessary to find the volume to be uploaded into;
5602       otherwise, the first volume found by the key or path will be used.
5603
5604       --offset is the position in the storage volume at which to start  writ‐
5605       ing the data. The value must be 0 or larger.
5606
5607       --length  is  an  upper  bound of the amount of data to be uploaded.  A
5608       negative value is interpreted as an unsigned long long value to  essen‐
5609       tially include everything from the offset to the end of the volume.
5610
5611       If --sparse is specified, this command will preserve volume sparseness.
5612
5613       An  error  will  occur  if the local-file is greater than the specified
5614       length.
5615
5616       See the description for the libvirt virStorageVolUpload API for details
5617       regarding  possible  target  volume and pool changes as a result of the
5618       pool refresh when the upload is attempted.
5619
5620   vol-download
5621       Syntax:
5622
5623          vol-download vol-name-or-key-or-path local-file
5624             [--pool pool-or-uuid] [--offset bytes] [--length bytes]
5625             [--sparse]
5626
5627       Download the contents of a storage volume to local-file.
5628
5629       vol-name-or-key-or-path is the name or key or path  of  the  volume  to
5630       download into local-file.
5631
5632       --pool  pool-or-uuid is the name or UUID of the storage pool the volume
5633       is in. If the volume name is provided instead of the key or path,  then
5634       providing the pool is necessary to find the volume to be uploaded into;
5635       otherwise, the first volume found by the key or path will be used.
5636
5637       --offset is the position in the storage volume at which to start  read‐
5638       ing the data. The value must be 0 or larger.
5639
5640       --length  is  an upper bound of the amount of data to be downloaded.  A
5641       negative value is interpreted as an unsigned long long value to  essen‐
5642       tially include everything from the offset to the end of the volume.
5643
5644       If --sparse is specified, this command will preserve volume sparseness.
5645
5646   vol-wipe
5647       Syntax:
5648
5649          vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm]
5650
5651       Wipe  a  volume, ensure data previously on the volume is not accessible
5652       to future reads.
5653
5654       vol-name-or-key-or-path is the name or key or path  of  the  volume  to
5655       wipe.   It is possible to choose different wiping algorithms instead of
5656       re-writing volume with zeroes.
5657
5658       --pool pool-or-uuid is the name or UUID of the storage pool the  volume
5659       is  in. If the volume name is provided instead of the key or path, then
5660       providing the pool is necessary to find the volume to be wiped;  other‐
5661       wise, the first volume found by the key or path will be used.
5662
5663       Use  the --algorithm switch choosing from the list of the following al‐
5664       gorithms in order to define which algorithm to use for the wipe.
5665
5666       Supported algorithms
5667
5668       • zero       - 1-pass all zeroes
5669
5670       • nnsa       - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8)  for  sani‐
5671         tizing  removable and non-removable hard disks: random x2, 0x00, ver‐
5672         ify.
5673
5674       • dod        - 4-pass DoD 5220.22-M section 8-306 procedure  for  sani‐
5675         tizing  removable  and non-removable rigid disks: random, 0x00, 0xff,
5676         verify.
5677
5678       • bsi        - 9-pass method recommended by the German Center of  Secu‐
5679         rity  in  Information  Technologies  (https://www.bsi.bund.de): 0xff,
5680         0xfe, 0xfd, 0xfb, 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
5681
5682       • gutmann    - The canonical 35-pass sequence  described  in  Gutmann's
5683         paper.
5684
5685       • schneier    -  7-pass  method described by Bruce Schneier in "Applied
5686         Cryptography" (1996): 0x00, 0xff, random x5.
5687
5688       • pfitzner7  - Roy Pfitzner's 7-random-pass method: random x7.
5689
5690       • pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
5691
5692       • random     - 1-pass pattern: random.
5693
5694       • trim       - 1-pass trimming the volume using TRIM or DISCARD
5695
5696       Note: The scrub binary will be used to handle the 'nnsa', 'dod', 'bsi',
5697       'gutmann',  'schneier',  'pfitzner7'  and 'pfitzner33' algorithms.  The
5698       availability of the algorithms may be limited by  the  version  of  the
5699       scrub binary installed on the host. The 'zero' algorithm will write ze‐
5700       roes to the entire volume. For some volumes, such as sparse or rbd vol‐
5701       umes, this may result in completely filling the volume with zeroes mak‐
5702       ing it appear to be completely full. As an alternative, the 'trim'  al‐
5703       gorithm  does not overwrite all the data in a volume, rather it expects
5704       the storage driver to be able to discard all bytes in a volume.  It  is
5705       up  to  the storage driver to handle how the discarding occurs. Not all
5706       storage drivers or volume types can support 'trim'.
5707
5708   vol-dumpxml
5709       Syntax:
5710
5711          vol-dumpxml [--pool pool-or-uuid] [--xpath EXPRESSION] [--wrap]
5712                      vol-name-or-key-or-path
5713
5714       Output the volume information as an XML dump to stdout.
5715
5716       vol-name-or-key-or-path is the name or key or path  of  the  volume  to
5717       output the XML.
5718
5719       --pool  pool-or-uuid is the name or UUID of the storage pool the volume
5720       is in. If the volume name is provided instead of the key or path,  then
5721       providing the pool is necessary to find the volume to be uploaded into;
5722       otherwise, the first volume found by the key or path will be used.
5723
5724       If the --xpath argument provides an XPath expression, it will be evalu‐
5725       ated  against  the  output  XML  and  only those matching nodes will be
5726       printed. The default behaviour is to print  each  matching  node  as  a
5727       standalone  document,  however,  for ease of additional processing, the
5728       --wrap argument will cause the matching node to be wrapped in a  common
5729       root node.
5730
5731   vol-info
5732       Syntax:
5733
5734          vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical]
5735
5736       Returns basic information about the given storage volume.
5737
5738       vol-name-or-key-or-path is the name or key or path of the volume to re‐
5739       turn information for.
5740
5741       --pool pool-or-uuid is the name or UUID of the storage pool the  volume
5742       is  in. If the volume name is provided instead of the key or path, then
5743       providing the pool is necessary to find the volume to be uploaded into;
5744       otherwise, the first volume found by the key or path will be used.
5745
5746       If  --bytes  is specified the sizes are not converted to human friendly
5747       units.
5748
5749       If --physical is specified, then the host physical size is returned and
5750       displayed  instead of the allocation value. The physical value for some
5751       file types, such as qcow2 may have a different (larger) physical  value
5752       than  is shown for allocation. Additionally sparse files will have dif‐
5753       ferent physical and allocation values.
5754
5755   vol-list
5756       Syntax:
5757
5758          vol-list [--pool pool-or-uuid] [--details]
5759
5760       Return the list of volumes in the given storage pool.
5761
5762       --pool pool-or-uuid is the name or UUID of the storage pool.
5763
5764       The --details option instructs virsh  to  additionally  display  volume
5765       type and capacity related information where available.
5766
5767   vol-pool
5768       Syntax:
5769
5770          vol-pool vol-key-or-path [--uuid]
5771
5772       Return  the  pool name or UUID for a given volume. By default, the pool
5773       name is returned.
5774
5775       vol-key-or-path is the key or path of the volume to return the pool in‐
5776       formation.
5777
5778       If the --uuid option is given, the pool UUID is returned instead.
5779
5780   vol-path
5781       Syntax:
5782
5783          vol-path vol-name-or-key [--pool pool-or-uuid]
5784
5785       Return the path for a given volume.
5786
5787       vol-name-or-key is the name or key of the volume to return the path.
5788
5789       --pool  pool-or-uuid is the name or UUID of the storage pool the volume
5790       is in. If the volume name is provided instead of the key, then  provid‐
5791       ing  the pool is necessary to find the volume to be uploaded into; oth‐
5792       erwise, the first volume found by the key will be used.
5793
5794   vol-name
5795       Syntax:
5796
5797          vol-name vol-key-or-path
5798
5799       Return the name for a given volume.
5800
5801       vol-key-or-path is the key or path of the volume to return the name.
5802
5803   vol-key
5804       Syntax:
5805
5806          vol-key vol-name-or-path [--pool pool-or-uuid]
5807
5808       Return the volume key for a given volume.
5809
5810       vol-name-or-path is the name or path of the volume to return the volume
5811       key.
5812
5813       --pool  pool-or-uuid is the name or UUID of the storage pool the volume
5814       is in. If the volume name is provided instead of the path, then provid‐
5815       ing  the pool is necessary to find the volume to be uploaded into; oth‐
5816       erwise, the first volume found by the path will be used.
5817
5818   vol-resize
5819       Syntax:
5820
5821          vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink]
5822
5823       Resize the capacity of the given volume, in bytes.
5824
5825       vol-name-or-key-or-path is the name or key or path of the volume to re‐
5826       size.
5827
5828       capacity  is  a  scaled integer (see NOTES above) for the volume, which
5829       defaults to bytes if there is no suffix.
5830
5831       --pool pool-or-uuid is the name or UUID of the storage pool the  volume
5832       is  in. If the volume name is provided instead of the key or path, then
5833       providing the pool is necessary to find the volume to be uploaded into;
5834       otherwise, the first volume found by the key or path will be used.
5835
5836       The new capacity might be sparse unless --allocate is specified.
5837
5838       Normally,  capacity is the new size, but if --delta is present, then it
5839       is added to the existing size.
5840
5841       Attempts to shrink the volume will fail  unless  --shrink  is  present.
5842       The capacity cannot be negative unless --shrink is provided, but a neg‐
5843       ative sign is not necessary.
5844
5845       This command is only safe for storage volumes not in use by  an  active
5846       guest; see also blockresize for live resizing.
5847

SECRET COMMANDS

5849       The   following   commands   manipulate   "secrets"   (e.g.  passwords,
5850       passphrases and encryption keys).  Libvirt can store  secrets  indepen‐
5851       dently  from their use, and other objects (e.g. volumes or domains) can
5852       refer to the secrets for encryption or possibly  other  uses.   Secrets
5853       are identified using a UUID.  See https://libvirt.org/formatsecret.html
5854       for documentation of the XML format used to represent properties of se‐
5855       crets.
5856
5857   secret-define
5858       Syntax:
5859
5860          secret-define file [--validate]
5861
5862       Create  a secret with the properties specified in file, with no associ‐
5863       ated secret value.  If file does not specify a UUID, choose  one  auto‐
5864       matically.  If file specifies a UUID of an existing secret, replace its
5865       properties by properties defined in file, without affecting the  secret
5866       value.
5867
5868       Optionally,  the  format of the input XML file can be validated against
5869       an internal RNG schema with --validate.
5870
5871   secret-dumpxml
5872       Syntax:
5873
5874          secret-dumpxml [--xpath EXPRESSION] [--wrap] secret
5875
5876       Output properties of secret (specified by its UUID) as an XML  dump  to
5877       stdout.
5878
5879       If the --xpath argument provides an XPath expression, it will be evalu‐
5880       ated against the output XML and  only  those  matching  nodes  will  be
5881       printed.  The  default  behaviour  is  to print each matching node as a
5882       standalone document, however, for ease of  additional  processing,  the
5883       --wrap  argument will cause the matching node to be wrapped in a common
5884       root node.
5885
5886   secret-event
5887       Syntax:
5888
5889          secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list}
5890
5891       Wait for a class of secret events to occur, and print  appropriate  de‐
5892       tails  of events as they happen.  The events can optionally be filtered
5893       by secret.  Using --list as the only argument will provide  a  list  of
5894       possible  event  values  known  by this client, although the connection
5895       might not allow registering for all these events.
5896
5897       By default, this command is one-shot, and returns success once an event
5898       occurs;  you  can send SIGINT (usually via Ctrl-C) to quit immediately.
5899       If --timeout is specified, the command gives up waiting for events  af‐
5900       ter  seconds have elapsed.   With --loop, the command prints all events
5901       until a timeout or interrupt key.
5902
5903       When --timestamp is used, a human-readable timestamp  will  be  printed
5904       before the event.
5905
5906   secret-set-value
5907       Syntax:
5908
5909          secret-set-value secret (--file filename [--plain] | --interactive | base64)
5910
5911       Set  the  value  associated  with secret (specified by its UUID) to the
5912       value Base64-encoded value base64 or Base-64-encoded contents  of  file
5913       named  filename.  Using the --plain flag is together with --file allows
5914       one to use the file contents directly as the secret value.
5915
5916       If --interactive flag is used the secret value is read  as  a  password
5917       from the terminal.
5918
5919       Note  that --file, --interactive and base64 options are mutually exclu‐
5920       sive.
5921
5922       Passing secrets via the base64 option on command line is  INSECURE  and
5923       deprecated. Use the --file option instead.
5924
5925   secret-get-value
5926       Syntax:
5927
5928          secret-get-value [--plain] secret
5929
5930       Output the value associated with secret (specified by its UUID) to std‐
5931       out, encoded using Base64.
5932
5933       If the --plain flag is used the value is not base64 encoded, but rather
5934       printed raw. Note that unless virsh is started in quiet mode (virsh -q)
5935       it prints a newline at the end of the command. This newline is not part
5936       of the secret.
5937
5938   secret-undefine
5939       Syntax:
5940
5941          secret-undefine secret
5942
5943       Delete  a  secret  (specified  by  its  UUID), including the associated
5944       value, if any.
5945
5946   secret-list
5947       Syntax:
5948
5949          secret-list [--ephemeral] [--no-ephemeral]
5950             [--private] [--no-private]
5951
5952       Returns the list of secrets. You may also want to filter  the  returned
5953       secrets  by  --ephemeral  to list the ephemeral ones, --no-ephemeral to
5954       list the non-ephemeral ones, --private to list the  private  ones,  and
5955       --no-private to list the non-private ones.
5956

SNAPSHOT COMMANDS

5958       The following commands manipulate domain snapshots.  Snapshots take the
5959       disk, memory, and device state of a domain at a point-of-time, and save
5960       it  for future use.  They have many uses, from saving a "clean" copy of
5961       an OS image to saving a domain's state before a potentially destructive
5962       operation.    Snapshots   are  identified  with  a  unique  name.   See
5963       https://libvirt.org/formatsnapshot.html for documentation  of  the  XML
5964       format used to represent properties of snapshots.
5965
5966   snapshot-create
5967       Syntax:
5968
5969          snapshot-create domain [xmlfile] {[--redefine [--current]] |
5970             [--no-metadata] [--halt] [--disk-only] [--reuse-external]
5971             [--quiesce] [--atomic] [--live]} [--validate]
5972
5973       Create  a  snapshot  for domain domain with the properties specified in
5974       xmlfile.   Optionally, the --validate option can be passed to  validate
5975       the  format of the input XML file against an internal RNG schema (iden‐
5976       tical to using the virt-xml-validate(1) tool). Normally, the only prop‐
5977       erties  settable for a domain snapshot are the <name> and <description>
5978       elements, as well as <disks> if --disk-only is given; the rest  of  the
5979       fields are ignored, and automatically filled in by libvirt.  If xmlfile
5980       is completely omitted, then libvirt will choose a value for all fields.
5981       The new snapshot will become current, as listed by snapshot-current.
5982
5983       If  --halt  is  specified, the domain will be left in an inactive state
5984       after the snapshot is created.
5985
5986       If --disk-only is specified, the snapshot will only include  disk  con‐
5987       tent  rather  than  the usual full system snapshot with vm state.  Disk
5988       snapshots are captured faster than full system snapshots, but reverting
5989       to  a  disk  snapshot  may require fsck or journal replays, since it is
5990       like the disk state at the  point  when  the  power  cord  is  abruptly
5991       pulled;  and  mixing --halt and --disk-only loses any data that was not
5992       flushed to disk at the time.
5993
5994       If --redefine is specified, then all XML  elements  produced  by  snap‐
5995       shot-dumpxml  are valid; this can be used to migrate snapshot hierarchy
5996       from one machine to another, to recreate hierarchy for the  case  of  a
5997       transient  domain  that  goes away and is later recreated with the same
5998       name and UUID, or to make slight alterations in the  snapshot  metadata
5999       (such  as host-specific aspects of the domain XML embedded in the snap‐
6000       shot).  When this flag is supplied, the xmlfile argument is  mandatory,
6001       and the domain's current snapshot will not be altered unless the --cur‐
6002       rent flag is also given.
6003
6004       If --no-metadata is specified, then the snapshot data is  created,  but
6005       any  metadata is immediately discarded (that is, libvirt does not treat
6006       the snapshot as current, and cannot revert to the snapshot unless --re‐
6007       define is later used to teach libvirt about the metadata again).
6008
6009       If  --reuse-external is specified, and the snapshot XML requests an ex‐
6010       ternal snapshot with a destination of an existing file, then the desti‐
6011       nation  must exist and be pre-created with correct format and metadata.
6012       The file is then reused; otherwise, a snapshot is refused to avoid los‐
6013       ing contents of the existing files.
6014
6015       If  --quiesce  is  specified,  libvirt  will  try to use guest agent to
6016       freeze and unfreeze domain's mounted file systems. However,  if  domain
6017       has  no  guest agent, snapshot creation will fail.  Currently, this re‐
6018       quires --disk-only to be passed as well.
6019
6020       If --atomic is specified, libvirt will guarantee that the snapshot  ei‐
6021       ther  succeeds,  or  fails with no changes; not all hypervisors support
6022       this.  If this flag is not specified, then some  hypervisors  may  fail
6023       after  partially performing the action, and dumpxml must be used to see
6024       whether any partial changes occurred.
6025
6026       If --live is specified, libvirt takes the snapshot while the  guest  is
6027       running.  Both disk snapshot and domain memory snapshot are taken. This
6028       increases the size of the memory image of the external  snapshot.  This
6029       is currently supported only for full system external snapshots.
6030
6031       Existence of snapshot metadata will prevent attempts to undefine a per‐
6032       sistent guest.  However, for transient domains,  snapshot  metadata  is
6033       silently lost when the domain quits running (whether by command such as
6034       destroy or by internal guest action).
6035
6036       For now, it is not possible to create snapshots in a  domain  that  has
6037       checkpoints,  although  this restriction will be lifted in a future re‐
6038       lease.
6039
6040   snapshot-create-as
6041       Syntax:
6042
6043          snapshot-create-as domain {[--print-xml] [--no-metadata]
6044             [--halt] [--reuse-external]} [name]
6045             [description] [--disk-only [--quiesce]] [--atomic] [--validate]
6046             [[--live] [--memspec memspec]] [--diskspec] diskspec]...
6047
6048       Create a snapshot for domain domain with the given <name> and <descrip‐
6049       tion>;  if  either  value  is omitted, libvirt will choose a value.  If
6050       --print-xml is specified, then XML appropriate for  snapshot-create  is
6051       output, rather than actually creating a snapshot.  Otherwise, if --halt
6052       is specified, the domain will be left in an inactive  state  after  the
6053       snapshot is created, and if --disk-only is specified, the snapshot will
6054       not include vm state.
6055
6056       The --memspec option can be used to control whether a full system snap‐
6057       shot  is  internal  or external.  The --memspec flag is mandatory, fol‐
6058       lowed by a memspec of the form [file=]name[,snapshot=type], where  type
6059       can  be  no,  internal,  or  external.   To  include a literal comma in
6060       file=name, escape it with a second comma. --memspec cannot be used  to‐
6061       gether with --disk-only.
6062
6063       The --diskspec option can be used to control how --disk-only and exter‐
6064       nal full system snapshots create external files.  This option can occur
6065       multiple  times,  according to the number of <disk> elements in the do‐
6066       main   xml.    Each   <diskspec>   is   in   the    form    disk[,snap‐
6067       shot=type][,driver=type][,stype=type][,file=name].   A diskspec must be
6068       provided for disks backed by block devices as libvirt doesn't auto-gen‐
6069       erate file names for those.  The optional stype parameter allows one to
6070       control the type of the source file. Supported values are  'file'  (de‐
6071       fault)  and  'block'.  To  exclude a disk from an external snapshot use
6072       --diskspec disk,snapshot=no.
6073
6074       To include a literal comma in disk or in file=name, escape  it  with  a
6075       second  comma.   A literal --diskspec must precede each diskspec unless
6076       all three of domain, name, and description are also present.  For exam‐
6077       ple,  a  diskspec of "vda,snapshot=external,file=/path/to,,new" results
6078       in the following XML:
6079
6080          <disk name='vda' snapshot='external'>
6081            <source file='/path/to,new'/>
6082          </disk>
6083
6084       If --reuse-external is specified, and the domain XML or diskspec option
6085       requests  an  external snapshot with a destination of an existing file,
6086       then the destination must exist and be pre-created with correct  format
6087       and metadata. The file is then reused; otherwise, a snapshot is refused
6088       to avoid losing contents of the existing files.
6089
6090       If --quiesce is specified, libvirt will  try  to  use  guest  agent  to
6091       freeze  and  unfreeze domain's mounted file systems. However, if domain
6092       has no guest agent, snapshot creation will fail.  Currently,  this  re‐
6093       quires --disk-only to be passed as well.
6094
6095       If  --no-metadata  is specified, then the snapshot data is created, but
6096       any metadata is immediately discarded (that is, libvirt does not  treat
6097       the snapshot as current, and cannot revert to the snapshot unless snap‐
6098       shot-create is later used to teach libvirt about the metadata again).
6099
6100       If --atomic is specified, libvirt will guarantee that the snapshot  ei‐
6101       ther  succeeds,  or  fails with no changes; not all hypervisors support
6102       this.  If this flag is not specified, then some  hypervisors  may  fail
6103       after  partially performing the action, and dumpxml must be used to see
6104       whether any partial changes occurred.
6105
6106       If --live is specified, libvirt takes the snapshot while the  guest  is
6107       running.  This  increases  the size of the memory image of the external
6108       snapshot. This is currently supported only  for  external  full  system
6109       snapshots.
6110
6111       For  now,  it  is not possible to create snapshots in a domain that has
6112       checkpoints, although this restriction will be lifted in a  future  re‐
6113       lease.
6114
6115       Optionally,  the  --validate option can be passed to validate XML docu‐
6116       ment which is internally generated by this command against the internal
6117       RNG schema.
6118
6119   snapshot-current
6120       Syntax:
6121
6122          snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
6123
6124       Without  snapshotname,  this  will  output the snapshot XML for the do‐
6125       main's current snapshot (if any).  If --name  is  specified,  just  the
6126       current  snapshot name instead of the full xml.  Otherwise, using --se‐
6127       curity-info will also include security  sensitive  information  in  the
6128       XML.
6129
6130       With  snapshotname,  this is a request to make the existing named snap‐
6131       shot become the current snapshot, without reverting the domain.
6132
6133   snapshot-edit
6134       Syntax:
6135
6136          snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]}
6137
6138       Edit the XML configuration file for snapshotname of a domain.  If  both
6139       snapshotname  and  --current are specified, also force the edited snap‐
6140       shot to become the current snapshot.  If snapshotname is omitted,  then
6141       --current must be supplied, to edit the current snapshot.
6142
6143       This is equivalent to:
6144
6145          virsh snapshot-dumpxml dom name > snapshot.xml
6146          vi snapshot.xml (or make changes with your other text editor)
6147          virsh snapshot-create dom snapshot.xml --redefine [--current]
6148
6149       except that it does some error checking.
6150
6151       The  editor  used can be supplied by the $VISUAL or $EDITOR environment
6152       variables, and defaults to vi.
6153
6154       If --rename is specified, then the edits can change the snapshot  name.
6155       If  --clone is specified, then changing the snapshot name will create a
6156       clone of the snapshot metadata.  If neither is specified, then the  ed‐
6157       its  must  not change the snapshot name.  Note that changing a snapshot
6158       name must be done with care, since the contents of some snapshots, such
6159       as  internal  snapshots within a single qcow2 file, are accessible only
6160       from the original name.
6161
6162   snapshot-info
6163       Syntax:
6164
6165          snapshot-info domain {snapshot | --current}
6166
6167       Output basic information about a named <snapshot>, or the current snap‐
6168       shot with --current.
6169
6170   snapshot-list
6171       Syntax:
6172
6173          snapshot-list domain [--metadata] [--no-metadata]
6174             [{--parent | --roots | [{--tree | --name}]}] [--topological]
6175             [{[--from] snapshot | --current} [--descendants]]
6176             [--leaves] [--no-leaves] [--inactive] [--active]
6177             [--disk-only] [--internal] [--external]
6178
6179       List all of the available snapshots for the given domain, defaulting to
6180       show columns for the snapshot name, creation time, and domain state.
6181
6182       Normally, table form output is sorted by snapshot name;  using  --topo‐
6183       logical  instead  sorts so that no child is listed before its ancestors
6184       (although there may be more than one possible ordering with this  prop‐
6185       erty).
6186
6187       If  --parent  is specified, add a column to the output table giving the
6188       name of the parent of each snapshot.  If --roots is specified, the list
6189       will  be filtered to just snapshots that have no parents.  If --tree is
6190       specified, the output will be in a tree format, listing  just  snapshot
6191       names.  These three options are mutually exclusive. If --name is speci‐
6192       fied only the snapshot name is printed. This option is mutually  exclu‐
6193       sive with --tree.
6194
6195       If  --from is provided, filter the list to snapshots which are children
6196       of the given snapshot; or if --current is provided, start at  the  cur‐
6197       rent  snapshot.   When  used in isolation or with --parent, the list is
6198       limited to direct children unless --descendants is also present.   When
6199       used  with --tree, the use of --descendants is implied.  This option is
6200       not compatible with --roots.  Note that the starting point of --from or
6201       --current  is not included in the list unless the --tree option is also
6202       present.
6203
6204       If --leaves is specified, the list will be filtered to  just  snapshots
6205       that have no children.  Likewise, if --no-leaves is specified, the list
6206       will be filtered to just snapshots with children.  (Note that  omitting
6207       both  options  does no filtering, while providing both options will ei‐
6208       ther produce the same list or error out depending on whether the server
6209       recognizes  the  flags).   Filtering  options  are  not compatible with
6210       --tree.
6211
6212       If --metadata is specified, the list will be filtered to just snapshots
6213       that  involve  libvirt  metadata,  and thus would prevent undefine of a
6214       persistent guest, or be lost on destroy of a transient  domain.   Like‐
6215       wise,  if --no-metadata is specified, the list will be filtered to just
6216       snapshots that exist without the need for libvirt metadata.
6217
6218       If --inactive is specified, the list will be filtered to snapshots that
6219       were taken when the domain was shut off.  If --active is specified, the
6220       list will be filtered to snapshots that were taken when the domain  was
6221       running,  and where the snapshot includes the memory state to revert to
6222       that running state.  If --disk-only is specified, the list will be fil‐
6223       tered  to  snapshots  that  were taken when the domain was running, but
6224       where the snapshot includes only disk state.
6225
6226       If --internal is specified, the list will be filtered to snapshots that
6227       use  internal storage of existing disk images.  If --external is speci‐
6228       fied, the list will be filtered to snapshots that  use  external  files
6229       for disk images or memory state.
6230
6231   snapshot-dumpxml
6232       Syntax:
6233
6234          snapshot-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap]
6235                           domain snapshot
6236
6237       Output  the snapshot XML for the domain's snapshot named snapshot.  Us‐
6238       ing --security-info will also include security  sensitive  information.
6239       Use snapshot-current to easily access the XML of the current snapshot.
6240
6241       If the --xpath argument provides an XPath expression, it will be evalu‐
6242       ated against the output XML and  only  those  matching  nodes  will  be
6243       printed.  The  default  behaviour  is  to print each matching node as a
6244       standalone document, however, for ease of  additional  processing,  the
6245       --wrap  argument will cause the matching node to be wrapped in a common
6246       root node.
6247
6248   snapshot-parent
6249       Syntax:
6250
6251          snapshot-parent domain {snapshot | --current}
6252
6253       Output the name of the parent snapshot, if any, for the given snapshot,
6254       or for the current snapshot with --current.
6255
6256   snapshot-revert
6257       Syntax:
6258
6259          snapshot-revert domain {snapshot | --current} [{--running | --paused}]
6260             [--force] [--reset-nvram]
6261
6262       Revert  the  given  domain to the snapshot specified by snapshot, or to
6263       the current snapshot with --current.  Be aware that this is a  destruc‐
6264       tive  action;  any  changes  in  the domain since the last snapshot was
6265       taken will be lost.  Also note that the state of the domain after snap‐
6266       shot-revert is complete will be the state of the domain at the time the
6267       original snapshot was taken.
6268
6269       Normally, reverting to a snapshot leaves the domain in the state it was
6270       at  the time the snapshot was created, except that a disk snapshot with
6271       no vm state leaves the domain in an inactive state.  Passing either the
6272       --running  or --paused flag will perform additional state changes (such
6273       as booting an inactive domain, or pausing  a  running  domain).   Since
6274       transient  domains  cannot  be  inactive,  it is required to use one of
6275       these flags when reverting to a disk snapshot of a transient domain.
6276
6277       Since libvirt 7.10.0 the VM process is always restarted so the  follow‐
6278       ing  paragraph  is  no longer valid. If the snapshot metadata lacks the
6279       full VM XML it's no longer possible to revert to such snapshot.
6280
6281       There are a number of cases where  a  snapshot  revert  involves  extra
6282       risk, which requires the use of --force to proceed:
6283
6284          • One  is  the case of a snapshot that lacks full domain information
6285            for reverting configuration (such as snapshots  created  prior  to
6286            libvirt  0.9.5);  since libvirt cannot prove that the current con‐
6287            figuration matches what was in use at the time  of  the  snapshot,
6288            supplying  --force assures libvirt that the snapshot is compatible
6289            with the current configuration (and if it is not, the domain  will
6290            likely fail to run).
6291
6292          • Another  is  the case of reverting from a running domain to an ac‐
6293            tive state where a new hypervisor has to be  created  rather  than
6294            reusing the existing hypervisor, because it implies drawbacks such
6295            as breaking any existing VNC or Spice connections; this  condition
6296            happens  with an active snapshot that uses a provably incompatible
6297            configuration, as well as with an inactive snapshot that  is  com‐
6298            bined with the --start or --pause flag.
6299
6300          • Also,  libvirt  will  refuse to restore snapshots of inactive QEMU
6301            domains while there is managed saved state. This is because  those
6302            snapshots  do  not contain memory state and will therefore not re‐
6303            place the existing memory state. This ends up switching a disk un‐
6304            derneath a running system and will likely cause extensive filesys‐
6305            tem corruption or crashes due to swap content mismatches when run.
6306
6307       If --reset-nvram is specified, any existing NVRAM file will be  deleted
6308       and re-initialized from its pristine template.
6309
6310   snapshot-delete
6311       Syntax:
6312
6313          snapshot-delete domain {snapshot | --current}
6314             [--metadata] [{--children | --children-only}]
6315
6316       Delete the snapshot for the domain named snapshot, or the current snap‐
6317       shot with --current.  If this snapshot  has  child  snapshots,  changes
6318       from  this snapshot will be merged into the children.  If --children is
6319       passed, then delete this snapshot and any children  of  this  snapshot.
6320       If  --children-only  is  passed, then delete any children of this snap‐
6321       shot, but leave this snapshot intact.  These two flags are mutually ex‐
6322       clusive.
6323
6324       If  --metadata  is  specified,  then  only delete the snapshot metadata
6325       maintained by libvirt, while leaving the snapshot contents  intact  for
6326       access  by  external  tools; otherwise deleting a snapshot also removes
6327       the data contents from that point in time.
6328

CHECKPOINT COMMANDS

6330       The following  commands  manipulate  domain  checkpoints.   Checkpoints
6331       serve  as a point in time to identify which portions of a guest's disks
6332       have changed after that time, making it possible to perform incremental
6333       and  differential  backups.   Checkpoints  are identified with a unique
6334       name.  See https://libvirt.org/formatcheckpoint.html for  documentation
6335       of the XML format used to represent properties of checkpoints.
6336
6337   checkpoint-create
6338       Syntax:
6339
6340          checkpoint-create domain [xmlfile] { --redefine [--redefine-validate] | [--quiesce]}
6341
6342       Create  a checkpoint for domain domain with the properties specified in
6343       xmlfile describing a <domaincheckpoint> top-level element.  The  format
6344       of  the input XML file will be validated against an internal RNG schema
6345       (identical to using the virt-xml-validate(1) tool). If xmlfile is  com‐
6346       pletely  omitted,  then  libvirt  will  create a checkpoint with a name
6347       based on the current time.
6348
6349       If --redefine is specified, then all XML elements  produced  by  check‐
6350       point-dumpxml are valid; this can be used to migrate checkpoint hierar‐
6351       chy from one machine to another, to recreate hierarchy for the case  of
6352       a  transient domain that goes away and is later recreated with the same
6353       name and UUID, or to make slight alterations in the checkpoint metadata
6354       (such as host-specific aspects of the domain XML embedded in the check‐
6355       point).  When this flag is supplied, the xmlfile argument is mandatory.
6356
6357       If --redefine-validate is specified along with --redefine the  hypervi‐
6358       sor  performs  validation  of  metadata  associated with the checkpoint
6359       stored in places besides the checkpoint XML. Note that some hypervisors
6360       may require that the domain is running to perform validation.
6361
6362       If  --quiesce  is  specified,  libvirt  will  try to use guest agent to
6363       freeze and unfreeze domain's mounted file systems. However,  if  domain
6364       has no guest agent, checkpoint creation will fail.
6365
6366       Existence  of  checkpoint  metadata will prevent attempts to undefine a
6367       persistent guest.  However, for transient domains, checkpoint  metadata
6368       is silently lost when the domain quits running (whether by command such
6369       as destroy or by internal guest action).
6370
6371       For now, it is not possible to create checkpoints in a domain that  has
6372       snapshots,  although  this  restriction  will be lifted in a future re‐
6373       lease.
6374
6375   checkpoint-create-as
6376       Syntax:
6377
6378          checkpoint-create-as domain [--print-xml] [name]
6379             [description] [--quiesce] [--diskspec] diskspec]...
6380
6381       Create a checkpoint for domain domain with the given  <name>  and  <de‐
6382       scription>;  if  either  value is omitted, libvirt will choose a value.
6383       If --print-xml is specified, then XML appropriate for checkpoint-create
6384       is output, rather than actually creating a checkpoint.
6385
6386       The --diskspec option can be used to control which guest disks partici‐
6387       pate in the checkpoint. This option can occur multiple times, according
6388       to the number of <disk> elements in the domain xml.  Each <diskspec> is
6389       in the form disk[,checkpoint=type][,bitmap=name]. A literal  --diskspec
6390       must  precede  each  diskspec unless all three of domain, name, and de‐
6391       scription are also present.  For example,  a  diskspec  of  "vda,check‐
6392       point=bitmap,bitmap=map1" results in the following XML:
6393
6394          <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
6395
6396       If  --quiesce  is  specified,  libvirt  will  try to use guest agent to
6397       freeze and unfreeze domain's mounted file systems. However,  if  domain
6398       has no guest agent, checkpoint creation will fail.
6399
6400       For  now, it is not possible to create checkpoints in a domain that has
6401       snapshots, although this restriction will be lifted  in  a  future  re‐
6402       lease.
6403
6404   checkpoint-edit
6405       Syntax:
6406
6407          checkpoint-edit domain checkpointname
6408
6409       Edit the XML configuration file for checkpointname of a domain.
6410
6411       This is equivalent to:
6412
6413          virsh checkpoint-dumpxml dom name > checkpoint.xml
6414          vi checkpoint.xml (or make changes with your other text editor)
6415          virsh checkpoint-create dom checkpoint.xml --redefine
6416
6417       except  that  it  does  some  error  checking, including that the edits
6418       should not attempt to change the checkpoint name.
6419
6420       The editor used can be supplied by the $VISUAL or  $EDITOR  environment
6421       variables, and defaults to vi.
6422
6423   checkpoint-info
6424       Syntax:
6425
6426          checkpoint-info domain checkpoint
6427
6428       Output basic information about a named <checkpoint>.
6429
6430   checkpoint-list
6431       Syntax:
6432
6433          checkpoint-list domain [{--parent | --roots |
6434             [{--tree | --name}]}] [--topological]
6435             [[--from] checkpoint | [--descendants]]
6436             [--leaves] [--no-leaves]
6437
6438       List  all of the available checkpoints for the given domain, defaulting
6439       to show columns for the checkpoint name and creation time.
6440
6441       Normally, table form output is sorted by checkpoint name; using --topo‐
6442       logical  instead  sorts so that no child is listed before its ancestors
6443       (although there may be more than one possible ordering with this  prop‐
6444       erty).
6445
6446       If  --parent  is specified, add a column to the output table giving the
6447       name of the parent of each checkpoint.  If --roots  is  specified,  the
6448       list  will  be  filtered  to just checkpoints that have no parents.  If
6449       --tree is specified, the output will be in a tree format, listing  just
6450       checkpoint  names.   These  three  options  are  mutually exclusive. If
6451       --name is specified only the checkpoint name is printed. This option is
6452       mutually exclusive with --tree.
6453
6454       If  --from  is provided, filter the list to checkpoints which are chil‐
6455       dren of the given checkpoint.  When used in isolation or with --parent,
6456       the  list  is  limited  to direct children unless --descendants is also
6457       present.  When used with --tree, the use of --descendants  is  implied.
6458       This  option  is  not  compatible with --roots.  Note that the starting
6459       point of --from is not included in the list unless the --tree option is
6460       also present.
6461
6462       If --leaves is specified, the list will be filtered to just checkpoints
6463       that have no children.  Likewise, if --no-leaves is specified, the list
6464       will  be  filtered to just checkpoints with children.  (Note that omit‐
6465       ting both options does no filtering, while providing both options  will
6466       either  produce  the  same  list  or error out depending on whether the
6467       server recognizes the flags).  Filtering  options  are  not  compatible
6468       with --tree.
6469
6470   checkpoint-dumpxml
6471       Syntax:
6472
6473          checkpoint-dumpxml [--security-info] [--no-domain] [--size]
6474                             [--xpath EXPRESSION] [--wrap] domain checkpoint
6475
6476       Output the checkpoint XML for the domain's checkpoint named checkpoint.
6477       Using --security-info will also include security sensitive information.
6478
6479       Using --size will add XML indicating the current size in bytes of guest
6480       data that has changed since the checkpoint was created (although remem‐
6481       ber that guest activity between a size check and  actually  creating  a
6482       backup can result in the backup needing slightly more space). Note that
6483       some hypervisors may require that domain  is  running  when  --size  is
6484       used.
6485
6486       Using  --no-domain will omit the <domain> element from the output for a
6487       more compact view.
6488
6489       If the --xpath argument provides an XPath expression, it will be evalu‐
6490       ated  against  the  output  XML  and  only those matching nodes will be
6491       printed. The default behaviour is to print  each  matching  node  as  a
6492       standalone  document,  however,  for ease of additional processing, the
6493       --wrap argument will cause the matching node to be wrapped in a  common
6494       root node.
6495
6496   checkpoint-parent
6497       Syntax:
6498
6499          checkpoint-parent domain checkpoint
6500
6501       Output  the name of the parent checkpoint, if any, for the given check‐
6502       point.
6503
6504   checkpoint-delete
6505       Syntax:
6506
6507          checkpoint-delete domain checkpoint
6508             [--metadata] [{--children | --children-only}]
6509
6510       Delete the checkpoint for the domain named checkpoint.  The  record  of
6511       which portions of the disk changed since the checkpoint are merged into
6512       the parent checkpoint (if any). If --children is  passed,  then  delete
6513       this  checkpoint  and  any  children  of  this  checkpoint.  If --chil‐
6514       dren-only is passed, then delete any children of this  checkpoint,  but
6515       leave this checkpoint intact. These two flags are mutually exclusive.
6516
6517       If  --metadata  is  specified, then only delete the checkpoint metadata
6518       maintained by libvirt, while leaving the checkpoint contents intact for
6519       access  by external tools; otherwise deleting a checkpoint also removes
6520       the ability to perform an incremental backup from that point in time.
6521

NWFILTER COMMANDS

6523       The following commands manipulate network filters. Network filters  al‐
6524       low  filtering  of the network traffic coming from and going to virtual
6525       machines.  Individual network traffic filters are written  in  XML  and
6526       may  contain references to other network filters, describe traffic fil‐
6527       tering rules, or contain both. Network filters are referenced  by  vir‐
6528       tual machines from within their interface description. A network filter
6529       may be referenced by multiple virtual machines' interfaces.
6530
6531   nwfilter-define
6532       Syntax:
6533
6534          nwfilter-define xmlfile [--validate]
6535
6536       Make a new network filter known to libvirt. If a  network  filter  with
6537       the  same  name  already  exists, it will be replaced with the new XML.
6538       Any running virtual machine referencing this network filter  will  have
6539       its  network traffic rules adapted. If for any reason the network traf‐
6540       fic filtering rules cannot be instantiated by any of the  running  vir‐
6541       tual machines, then the new XML will be rejected.
6542
6543       Optionally,  the  format of the input XML file can be validated against
6544       an internal RNG schema with --validate.
6545
6546   nwfilter-undefine
6547       Syntax:
6548
6549          nwfilter-undefine nwfilter-name
6550
6551       Delete a network filter. The deletion will fail if any running  virtual
6552       machine is currently using this network filter.
6553
6554   nwfilter-list
6555       Syntax:
6556
6557          nwfilter-list
6558
6559       List all of the available network filters.
6560
6561   nwfilter-dumpxml
6562       Syntax:
6563
6564          nwfilter-dumpxml [--xpath EXPRESSION] [--wrap] nwfilter-name
6565
6566       Output the network filter XML.
6567
6568       If the --xpath argument provides an XPath expression, it will be evalu‐
6569       ated against the output XML and  only  those  matching  nodes  will  be
6570       printed.  The  default  behaviour  is  to print each matching node as a
6571       standalone document, however, for ease of  additional  processing,  the
6572       --wrap  argument will cause the matching node to be wrapped in a common
6573       root node.
6574
6575   nwfilter-edit
6576       Syntax:
6577
6578          nwfilter-edit nwfilter-name
6579
6580       Edit the XML of a network filter.
6581
6582       This is equivalent to:
6583
6584          virsh nwfilter-dumpxml myfilter > myfilter.xml
6585          vi myfilter.xml (or make changes with your other text editor)
6586          virsh nwfilter-define myfilter.xml
6587
6588       except that it does some error checking.  The new network filter may be
6589       rejected due to the same reason as mentioned in nwfilter-define.
6590
6591       The  editor  used can be supplied by the $VISUAL or $EDITOR environment
6592       variables, and defaults to vi.
6593

NWFILTER BINDING COMMANDS

6595       The following commands manipulate network filter bindings. Network fil‐
6596       ter bindings track the association between a network port and a network
6597       filter. Generally the bindings are managed automatically by the  hyper‐
6598       visor drivers when adding/removing NICs on a guest.
6599
6600       If  an admin is creating/deleting TAP devices for non-guest usage, how‐
6601       ever, the network filter binding commands provide a way to make use  of
6602       the network filters directly.
6603
6604   nwfilter-binding-create
6605       Syntax:
6606
6607          nwfilter-binding-create xmlfile [--validate]
6608
6609       Associate  a  network  port  with  a network filter. The network filter
6610       backend will immediately attempt to instantiate the filter rules on the
6611       port.  This  command may be used to associate a filter with a currently
6612       running guest that does not have a filter defined for a  specific  net‐
6613       work  port.  Since  the bindings are generally automatically managed by
6614       the hypervisor, using this command to define a  filter  for  a  network
6615       port  and then starting the guest afterwards may prevent the guest from
6616       starting if it attempts to use the network port and finds a filter  al‐
6617       ready defined.
6618
6619       Optionally,  the  format of the input XML file can be validated against
6620       an internal RNG schema with --validate.
6621
6622   nwfilter-binding-delete
6623       Syntax:
6624
6625          nwfilter-binding-delete port-name
6626
6627       Disassociate a network port from a network filter. The  network  filter
6628       backend  will  immediately tear down the filter rules that exist on the
6629       port. This command may be used to remove the network port binding for a
6630       filter  currently in use for the guest while the guest is running with‐
6631       out needing to restart the guest. Restoring the  network  port  binding
6632       filter  for  the  running  guest  would be accomplished by using nwfil‐
6633       ter-binding-create.
6634
6635   nwfilter-binding-list
6636       Syntax:
6637
6638          nwfilter-binding-list
6639
6640       List all of the network ports which have filters associated with them.
6641
6642   nwfilter-binding-dumpxml
6643       Syntax:
6644
6645          nwfilter-binding-dumpxml [--xpath EXPRESSION] [--wrap] port-name
6646
6647       Output the network filter binding XML for  the  network  device  called
6648       port-name.
6649
6650       If the --xpath argument provides an XPath expression, it will be evalu‐
6651       ated against the output XML and  only  those  matching  nodes  will  be
6652       printed.  The  default  behaviour  is  to print each matching node as a
6653       standalone document, however, for ease of  additional  processing,  the
6654       --wrap  argument will cause the matching node to be wrapped in a common
6655       root node.
6656

HYPERVISOR-SPECIFIC COMMANDS

6658       NOTE: Use of the following commands is strongly discouraged.  They  can
6659       cause  libvirt  to become confused and do the wrong thing on subsequent
6660       operations.  Once you have used these commands, please  do  not  report
6661       problems  to  the  libvirt developers; the reports will be ignored.  If
6662       you find that these commands are the only way to accomplish  something,
6663       then it is better to request that the feature be added as a first-class
6664       citizen in the regular libvirt library.
6665
6666   qemu-attach
6667       Syntax:
6668
6669          qemu-attach pid
6670
6671       Attach an externally launched QEMU process to the libvirt QEMU  driver.
6672       The QEMU process must have been created with a monitor connection using
6673       the UNIX driver. Ideally the process will also have had the '-name' ar‐
6674       gument specified.
6675
6676          $ qemu-kvm -cdrom ~/demo.iso \
6677              -monitor unix:/tmp/demo,server,nowait \
6678              -name foo \
6679              -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea  &
6680          $ QEMUPID=$!
6681          $ virsh qemu-attach $QEMUPID
6682
6683       Not  all  functions  of libvirt are expected to work reliably after at‐
6684       taching to an externally launched QEMU process.  There  may  be  issues
6685       with the guest ABI changing upon migration and device hotplug or hotun‐
6686       plug may not work. The attached environment should be  considered  pri‐
6687       marily read-only.
6688
6689   qemu-monitor-command
6690       Syntax:
6691
6692          qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] }
6693              [--pass-fds N,M,...] command...
6694
6695       Send  an arbitrary monitor command command to domain domain through the
6696       QEMU monitor.  The results of the command will be printed on stdout.
6697
6698       If more than one argument is provided for command,  they  are  concate‐
6699       nated  with a space in between before passing the single command to the
6700       monitor.
6701
6702       Note that libvirt uses the QMP to talk to qemu so command must be valid
6703       JSON  in  QMP  format to work properly. If command is not a JSON object
6704       libvirt tries to wrap it as a JSON object to provide convenient  inter‐
6705       face such as the groups of commands with identical handling:
6706
6707          # simple command
6708          $ virsh qemu-monitor-command VM commandname
6709          $ virsh qemu-monitor-command VM '{"execute":"commandname"}'
6710
6711          # with arguments
6712          $ virsh qemu-monitor-command VM commandname '"arg1":123' '"arg2":"test"'
6713          $ virsh qemu-monitor-command VM commandname '{"arg1":123,"arg2":"test"}'
6714          $ virsh qemu-monitor-command VM '{"execute":"commandname", "arguments":{"arg1":123,"arg2":"test"}}'
6715
6716       If --pretty is given the QMP reply is pretty-printed.
6717
6718       If  --return-value is given the 'return' key of the QMP response object
6719       is extracted rather than passing through the full reply from QEMU.
6720
6721       If --hmp is passed, the command is considered to  be  a  human  monitor
6722       command  and libvirt will automatically convert it into QMP and convert
6723       the result back.
6724
6725       If --pass-fds is specified, the argument is a comma separated  list  of
6726       open  file descriptors which should be passed on to qemu along with the
6727       command.
6728
6729   qemu-agent-command
6730       Syntax:
6731
6732          qemu-agent-command domain [--timeout seconds | --async | --block] command...
6733
6734       Send an arbitrary guest agent command command to domain domain  through
6735       QEMU  agent.   --timeout,  --async  and  --block options are exclusive.
6736       --timeout requires timeout seconds seconds and  it  must  be  positive.
6737       When --aysnc is given, the command waits for timeout whether success or
6738       failed. And when --block is  given,  the  command  waits  forever  with
6739       blocking timeout.
6740
6741   qemu-monitor-event
6742       Syntax:
6743
6744          qemu-monitor-event [domain] [--event event-name]
6745            [--loop] [--timeout seconds] [--pretty] [--regex] [--no-case]
6746            [--timestamp]
6747
6748       Wait  for arbitrary QEMU monitor events to occur, and print out the de‐
6749       tails of events as they happen.  The events can optionally be  filtered
6750       by  domain  or  event-name.  The 'query-events' QMP command can be used
6751       via qemu-monitor-command  to  learn  what  events  are  supported.   If
6752       --regex  is used, event-name is a basic regular expression instead of a
6753       literal string.  If --no-case is used, event-name will  match  case-in‐
6754       sensitively.
6755
6756       By default, this command is one-shot, and returns success once an event
6757       occurs; you can send SIGINT (usually via Ctrl-C) to  quit  immediately.
6758       If  --timeout is specified, the command gives up waiting for events af‐
6759       ter seconds have elapsed.  With --loop, the command prints  all  events
6760       until  a  timeout or interrupt key.  If --pretty is specified, any JSON
6761       event details are pretty-printed for better legibility.
6762
6763       When --timestamp is used, a human-readable timestamp  will  be  printed
6764       before  the  event, and the timing information provided by QEMU will be
6765       omitted.
6766
6767   lxc-enter-namespace
6768       Syntax:
6769
6770          lxc-enter-namespace domain [--noseclabel] --
6771             /path/to/binary [arg1, [arg2, ...]]
6772
6773       Enter the namespace of domain and execute the  command  /path/to/binary
6774       passing  the  requested  args.  The binary path is relative to the con‐
6775       tainer root filesystem, not the host root filesystem. The  binary  will
6776       inherit  the environment variables / console visible to virsh. The com‐
6777       mand will be run with the same sVirt context and cgroups  placement  as
6778       processes  within the container. This command only works when connected
6779       to  the  LXC  hypervisor  driver.   This  command  succeeds   only   if
6780       /path/to/binary has 0 exit status.
6781
6782       By  default the new process will run with the security label of the new
6783       parent container. Use the  --noseclabel  option  to  instead  have  the
6784       process keep the same security label as virsh.
6785

ENVIRONMENT

6787       The  following  environment variables can be set to alter the behaviour
6788       of virsh
6789
6790       • VIRSH_DEBUG=<0 to 4>
6791
6792         Turn on verbose debugging of virsh commands. Valid levels are
6793
6794         • VIRSH_DEBUG=0
6795
6796           DEBUG - Messages at ALL levels get logged
6797
6798         • VIRSH_DEBUG=1
6799
6800           INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
6801
6802         • VIRSH_DEBUG=2
6803
6804           NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
6805
6806         • VIRSH_DEBUG=3
6807
6808           WARNING - Logs messages at levels WARNING and ERROR
6809
6810         • VIRSH_DEBUG=4
6811
6812           ERROR - Messages at only ERROR level gets logged.
6813
6814       • VIRSH_LOG_FILE=``LOGFILE``
6815
6816         The file to log virsh debug messages.
6817
6818       • VIRSH_DEFAULT_CONNECT_URI
6819
6820         The hypervisor to connect to by default. Set this to a  URI,  in  the
6821         same format as accepted by the connect option. This environment vari‐
6822         able is deprecated in favour of the global LIBVIRT_DEFAULT_URI  vari‐
6823         able which serves the same purpose.
6824
6825       • LIBVIRT_DEFAULT_URI
6826
6827         The  hypervisor  to  connect to by default. Set this to a URI, in the
6828         same format as accepted by the connect option. This overrides the de‐
6829         fault  URI  set  in  any client config file and prevents libvirt from
6830         probing for drivers.
6831
6832       • VISUAL
6833
6834         The editor to use by the edit and related options.
6835
6836       • EDITOR
6837
6838         The editor to use by the edit and related options, if VISUAL  is  not
6839         set.
6840
6841       • VIRSH_HISTSIZE
6842
6843         The  number of commands to remember in the command  history.  The de‐
6844         fault value is 500.
6845
6846       • LIBVIRT_DEBUG=LEVEL
6847
6848         Turn on verbose debugging of all libvirt API calls. Valid levels are
6849
6850         • LIBVIRT_DEBUG=1
6851
6852           Messages at level DEBUG or above
6853
6854         • LIBVIRT_DEBUG=2
6855
6856           Messages at level INFO or above
6857
6858         • LIBVIRT_DEBUG=3
6859
6860           Messages at level WARNING or above
6861
6862         • LIBVIRT_DEBUG=4
6863
6864           Messages at level ERROR
6865
6866       For   further   information    about    debugging    options    consult
6867       https://libvirt.org/logging.html
6868

BUGS

6870       Please report all bugs you discover.  This should be done via either:
6871
6872       1. the mailing list
6873
6874          https://libvirt.org/contact.html
6875
6876       2. the bug tracker
6877
6878          https://libvirt.org/bugs.html
6879
6880       Alternatively,  you may report bugs to your software distributor / ven‐
6881       dor.
6882

AUTHORS

6884       Please refer to the AUTHORS file distributed with libvirt.
6885
6887       Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed  in
6888       the libvirt AUTHORS file.
6889

LICENSE

6891       virsh is distributed under the terms of the GNU LGPL v2+.  This is free
6892       software; see the source for copying conditions. There is NO  warranty;
6893       not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
6894

SEE ALSO

6896       virt-install(1),    virt-xml-validate(1),    virt-top(1),   virt-df(1),
6897       https://libvirt.org/
6898
6899
6900
6901
6902                                                                      VIRSH(1)
Impressum