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   nodesuspend
354       Syntax:
355
356          nodesuspend [target] [duration]
357
358       Puts  the node (host machine) into a system-wide sleep state and sched‐
359       ule the node's Real-Time-Clock interrupt to resume the node  after  the
360       time duration specified by duration is out.  target specifies the state
361       to which the host will be suspended to, it can  be  "mem"  (suspend  to
362       RAM),  "disk"  (suspend  to disk), or "hybrid" (suspend to both RAM and
363       disk).  duration specifies the time duration in seconds for  which  the
364       host has to be suspended, it should be at least 60 seconds.
365
366   node-memory-tune
367       Syntax:
368
369          node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs] [shm-merge-across-nodes]
370
371       Allows   you   to   display   or   set   the  node  memory  parameters.
372       shm-pages-to-scan can be used to set the number of pages to scan before
373       the  shared  memory  service  goes to sleep; shm-sleep-millisecs can be
374       used to set the number of millisecs the shared  memory  service  should
375       sleep  before next scan; shm-merge-across-nodes specifies if pages from
376       different numa nodes can be merged. When set to  0,  only  pages  which
377       physically  reside  in the memory area of same NUMA node can be merged.
378       When set to 1, pages from all nodes can be merged. Default to 1.
379
380       Note: Currently the "shared memory  service"  only  means  KSM  (Kernel
381       Samepage Merging).
382
383   capabilities
384       Syntax:
385
386          capabilities
387
388       Print  an XML document describing the capabilities of the hypervisor we
389       are currently connected to. This includes a section on the  host  capa‐
390       bilities  in  terms  of  CPU and features, and a set of description for
391       each kind of guest which can be virtualized. For a  more  complete  de‐
392       scription see:
393
394       https://libvirt.org/formatcaps.html
395
396       The XML also show the NUMA topology information if available.
397
398   domcapabilities
399       Syntax:
400
401          domcapabilities [virttype] [emulatorbin] [arch] [machine]
402
403       Print an XML document describing the domain capabilities for the hyper‐
404       visor we are connected to using information either sourced from an  ex‐
405       isting  domain or taken from the virsh capabilities output. This may be
406       useful if you intend to create a new domain and are curious if for  in‐
407       stance  it could make use of VFIO by creating a domain for the hypervi‐
408       sor with a specific emulator and architecture.
409
410       Each hypervisor will have different requirements  regarding  which  op‐
411       tions  are  required  and  which are optional. A hypervisor can support
412       providing a default value for any of the options.
413
414       The virttype option specifies the virtualization type used.  The  value
415       to  be  used  is  either from the 'type' attribute of the <domain/> top
416       level element from the domain XML or the 'type' attribute found  within
417       each  <guest/>  element from the virsh capabilities output.  The emula‐
418       torbin option specifies the path to the emulator. The value to be  used
419       is  either  the <emulator> element in the domain XML or the virsh capa‐
420       bilities output. The arch option specifies the architecture to be  used
421       for  the  domain.  The  value to be used is either the "arch" attribute
422       from the domain's XML <os/>  element  and  <type/>  subelement  or  the
423       "name"  attribute  of  an  <arch/> element from the virsh capabililites
424       output. The machine specifies the machine type for  the  emulator.  The
425       value  to  be  used is either the "machine" attribute from the domain's
426       XML <os/> element and <type/> subelement or one from a list of machines
427       from  the virsh capabilities output for a specific architecture and do‐
428       main type.
429
430       For the QEMU hypervisor, a virttype of either 'qemu' or 'kvm'  must  be
431       supplied along with either the emulatorbin or arch in order to generate
432       output for the default machine.  Supplying a machine value will  gener‐
433       ate output for the specific machine.
434
435   pool-capabilities
436       Syntax:
437
438          pool-capabilities
439
440       Print  an XML document describing the storage pool capabilities for the
441       connected storage driver. This may be useful if you intend to create  a
442       new  storage  pool  and  need to know the available pool types and sup‐
443       ported storage pool source and target volume formats as well as the re‐
444       quired source elements to create the pool.
445
446   inject-nmi
447       Syntax:
448
449          inject-nmi domain
450
451       Inject NMI to the guest.
452
453   list
454       Syntax:
455
456          list [--inactive | --all]
457               [--managed-save] [--title]
458               { [--table] | --name | --uuid | --id }
459               [--persistent] [--transient]
460               [--with-managed-save] [--without-managed-save]
461               [--autostart] [--no-autostart]
462               [--with-snapshot] [--without-snapshot]
463               [--with-checkpoint] [--without-checkpoint]
464               [--state-running] [--state-paused]
465               [--state-shutoff] [--state-other]
466
467       Prints information about existing domains.  If no options are specified
468       it prints out information about running domains.
469
470       Example 1:
471
472       An example format for the list is as follows:
473
474          ``virsh`` list
475            Id    Name                           State
476          ----------------------------------------------------
477            0     Domain-0                       running
478            2     fedora                         paused
479
480       Name is the name of the domain.  ID the domain numeric  id.   State  is
481       the run state (see below).
482
483       STATES
484
485       The  State field lists what state each domain is currently in. A domain
486       can be in one of the following possible states:
487
488running
489
490         The domain is currently running on a CPU
491
492idle
493
494         The domain is idle, and not running or runnable.  This can be  caused
495         because the domain is waiting on IO (a traditional wait state) or has
496         gone to sleep because there was nothing else for it to do.
497
498paused
499
500         The domain has been paused, usually occurring through the administra‐
501         tor  running  virsh  suspend.  When in a paused state the domain will
502         still consume allocated resources like memory, but will not be eligi‐
503         ble for scheduling by the hypervisor.
504
505in shutdown
506
507         The domain is in the process of shutting down, i.e. the guest operat‐
508         ing system has been notified and should be in the process of stopping
509         its operations gracefully.
510
511shut off
512
513         The  domain  is  not  running.  Usually this indicates the domain has
514         been shut down completely, or has not been started.
515
516crashed
517
518         The domain has crashed, which is always a  violent  ending.   Usually
519         this  state  can  only occur if the domain has been configured not to
520         restart on crash.
521
522pmsuspended
523
524         The domain has been suspended by guest power management, e.g. entered
525         into s3 state.
526
527       Normally only active domains are listed. To list inactive domains spec‐
528       ify --inactive or --all to list both active and inactive domains.
529
530       Filtering
531
532       To further filter the list of domains you may specify one  or  more  of
533       filtering  flags supported by the list command. These flags are grouped
534       by function.  Specifying one or more flags from  a  group  enables  the
535       filter  group.  Note  that  some combinations of flags may yield no re‐
536       sults. Supported filtering flags and groups:
537
538   Persistence
539       Flag --persistent is used to include persistent guests in the  returned
540       list. To include transient guests specify --transient.
541
542   Existence of managed save image
543       To  list  domains  having a managed save image specify flag --with-man‐
544       aged-save. For domains that don't have a  managed  save  image  specify
545       --without-managed-save.
546
547   Domain state
548       The  following  filter flags select a domain by its state: --state-run‐
549       ning  for  running  domains,  --state-paused    for   paused   domains,
550       --state-shutoff  for turned off domains and --state-other for all other
551       states as a fallback.
552
553   Autostarting domains
554       To list autostarting domains use the flag --autostart. To list  domains
555       with this feature disabled use --no-autostart.
556
557   Snapshot existence
558       Domains that have snapshot images can be listed using flag --with-snap‐
559       shot, domains without a snapshot --without-snapshot.
560
561   Checkpoint existence
562       Domains that have checkpoints can be listed  using  flag  --with-check‐
563       point, domains without a checkpoint --without-checkpoint.
564
565       When  talking  to older servers, this command is forced to use a series
566       of API calls with an inherent race, where a domain might not be  listed
567       or  might appear more than once if it changed state between calls while
568       the list was being collected.  Newer servers do not have this problem.
569
570       If --managed-save is specified, then domains  that  have  managed  save
571       state  (only possible if they are in the shut off state, so you need to
572       specify --inactive or --all to actually list them) will instead show as
573       saved in the listing. This flag is usable only with the default --table
574       output.  Note that this flag does not filter the list of domains.
575
576       If --name is specified, domain names are printed instead of  the  table
577       formatted  one  per  line.  If  --uuid is specified domain's UUID's are
578       printed instead of names. If --id is specified then domain's  ID's  are
579       printed  indead  of  names.  However, it is possible to combine --name,
580       --uuid and --id to select only desired fields for printing. Flag  --ta‐
581       ble  specifies  that  the legacy table-formatted output should be used,
582       but it is mutually exclusive with --name, --uuid and --id. This is  the
583       default and will be used if neither of --name, --uuid or --id is speci‐
584       fied. If neither --name nor --uuid is specified, but --id is, then only
585       active  domains  are listed, even with the --all parameter as otherwise
586       the output would just contain bunch of lines with just -1.
587
588       If --title is specified, then the short domain description  (title)  is
589       printed  in  an extra column. This flag is usable only with the default
590       --table output.
591
592       Example 2:
593
594          $ virsh list --title
595            Id    Name        State      Title
596           -------------------------------------------
597            0     Domain-0    running    Mailserver 1
598            2     fedora      paused
599
600   freecell
601       Syntax:
602
603          freecell [{ [--cellno] cellno | --all }]
604
605       Prints the available amount of memory on the machine or within  a  NUMA
606       cell.  The freecell command can provide one of three different displays
607       of available memory on the machine depending on the options  specified.
608       With  no  options,  it  displays  the total free memory on the machine.
609       With the --all option, it displays the free memory in each cell and the
610       total  free memory on the machine.  Finally, with a numeric argument or
611       with --cellno plus a cell number it will display the  free  memory  for
612       the specified cell only.
613
614   freepages
615       Syntax:
616
617          freepages [{ [--cellno] cellno [--pagesize] pagesize |     --all }]
618
619       Prints  the available amount of pages within a NUMA cell. cellno refers
620       to the NUMA cell you're interested in. pagesize  is  a  scaled  integer
621       (see  NOTES above).  Alternatively, if --all is used, info on each pos‐
622       sible combination of NUMA cell and page size is printed out.
623
624   allocpages
625       Syntax:
626
627          allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno] cellno] [--add] [--all]
628
629       Change the size of pages pool of pagesize on  the  host.  If  --add  is
630       specified,  then  pagecount  pages are added into the pool. However, if
631       --add wasn't specified, then the pagecount is taken as the new absolute
632       size of the pool (this may be used to free some pages and size the pool
633       down). The cellno modifier can be used to narrow the modification  down
634       to  a  single  host  NUMA cell. On the other end of spectrum lies --all
635       which executes the modification on all NUMA cells.
636
637   cpu-baseline
638       Syntax:
639
640          cpu-baseline FILE [--features] [--migratable]
641
642       Compute baseline CPU which will be supported by all host CPUs given  in
643       <file>.  (See hypervisor-cpu-baseline command to get a CPU which can be
644       provided by a specific hypervisor.) The list of host CPUs is  built  by
645       extracting  all  <cpu>  elements  from the <file>. Thus, the <file> can
646       contain either a set of <cpu> elements separated by new lines or even a
647       set  of  complete  <capabilities> elements printed by capabilities com‐
648       mand.  If --features is specified, then the resulting  XML  description
649       will explicitly include all features that make up the CPU, without this
650       option features that are part of the CPU model will not  be  listed  in
651       the  XML  description.    If  --migratable  is specified, features that
652       block migration will not be included in the resulting CPU.
653
654   cpu-compare
655       Syntax:
656
657          cpu-compare FILE [--error] [--validate]
658
659       Compare CPU definition from XML <file> with  host  CPU.  (See  hypervi‐
660       sor-cpu-compare  command  for comparing the CPU definition with the CPU
661       which a specific hypervisor is able to provide on the  host.)  The  XML
662       <file>  may  contain  either host or guest CPU definition. The host CPU
663       definition is the <cpu> element and its contents as printed by capabil‐
664       ities  command.  The  guest CPU definition is the <cpu> element and its
665       contents from domain XML definition or the CPU definition created  from
666       the  host CPU model found in domain capabilities XML (printed by domca‐
667       pabilities command). In addition to the <cpu> element itself, this com‐
668       mand  accepts full domain XML, capabilities XML, or domain capabilities
669       XML containing the CPU definition. For more information  on  guest  CPU
670       definition  see:  https://libvirt.org/formatdomain.html#elementsCPU. If
671       --error is specified, the command will return an error when  the  given
672       CPU  is incompatible with host CPU and a message providing more details
673       about the incompatibility will be printed out. If --validate is  speci‐
674       fied,  validates the format of the XML document against an internal RNG
675       schema.
676
677   cpu-models
678       Syntax:
679
680          cpu-models arch
681
682       Print the list of CPU models known by libvirt for the specified  archi‐
683       tecture.   Whether  a  specific  hypervisor  is able to create a domain
684       which uses any of the printed CPU models is a separate  question  which
685       can  be  answered by looking at the domain capabilities XML returned by
686       domcapabilities command.  Moreover, for some architectures libvirt does
687       not  know  any CPU models and the usable CPU models are only limited by
688       the hypervisor. This command will print that all  CPU  models  are  ac‐
689       cepted  for  these  architectures  and the actual list of supported CPU
690       models can be checked in the domain capabilities XML.
691
692   echo
693       Syntax:
694
695          echo [--shell] [--xml] [err...] [arg...]
696
697       Echo back each arg, separated by space.  If --shell is specified,  then
698       the  output  will be single-quoted where needed, so that it is suitable
699       for reuse in a shell context.  If --xml is specified, then  the  output
700       will  be escaped for use in XML.  If --err is specified, prefix "error:
701       " and output to stderr instead of stdout.
702
703   hypervisor-cpu-compare
704       Syntax:
705
706          hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine] [--error] [--validate]
707
708       Compare CPU definition from XML <file> with the CPU the  hypervisor  is
709       able  to provide on the host. (This is different from cpu-compare which
710       compares the CPU definition with the host CPU without  considering  any
711       specific hypervisor and its abilities.)
712
713       The  XML  FILE  may  contain either a host or guest CPU definition. The
714       host CPU definition is the <cpu> element and its contents as printed by
715       the capabilities command. The guest CPU definition is the <cpu> element
716       and its contents from the domain XML definition or the  CPU  definition
717       created  from  the  host CPU model found in the domain capabilities XML
718       (printed by the domcapabilities command). In addition to the <cpu> ele‐
719       ment itself, this command accepts full domain XML, capabilities XML, or
720       domain capabilities XML containing the CPU definition. For more  infor‐
721       mation         on        guest        CPU        definition        see:
722       https://libvirt.org/formatdomain.html#elementsCPU.
723
724       The virttype option specifies the virtualization type  (usable  in  the
725       'type'  attribute  of  the  <domain>  top level element from the domain
726       XML). emulator specifies the path to the emulator, arch  specifies  the
727       CPU architecture, and machine specifies the machine type. If --error is
728       specified, the command will return an error when the given CPU  is  in‐
729       compatible with the host CPU and a message providing more details about
730       the incompatibility will be printed out.  If --validate  is  specified,
731       validates  the  format  of  the  XML  document  against an internal RNG
732       schema.
733
734   hypervisor-cpu-baseline
735       Syntax:
736
737          hypervisor-cpu-baseline FILE [virttype] [emulator] [arch] [machine] [--features] [--migratable]
738
739       Compute a baseline CPU which will be compatible with all  CPUs  defined
740       in  an  XML  file and with the CPU the hypervisor is able to provide on
741       the host. (This is different from cpu-baseline which does not  consider
742       any hypervisor abilities when computing the baseline CPU.)
743
744       The  XML FILE may contain either host or guest CPU definitions describ‐
745       ing the host CPU model. The host CPU definition is  the  <cpu>  element
746       and its contents as printed by capabilities command. The guest CPU def‐
747       inition may be created from the host CPU model found in domain capabil‐
748       ities  XML  (printed  by  domcapabilities  command). In addition to the
749       <cpu> elements, this command accepts full capabilities XMLs, or  domain
750       capabilities  XMLs containing the CPU definitions. It is recommended to
751       use only the CPU definitions from domain capabilities, as on  some  ar‐
752       chitectures  using  the  host CPU definition may either fail or provide
753       unexpected results.
754
755       When FILE contains only a single CPU definition, the command will print
756       the  same  CPU with restrictions imposed by the capabilities of the hy‐
757       pervisor.  Specifically, running th virsh hypervisor-cpu-baseline  com‐
758       mand  with no additional options on the result of virsh domcapabilities
759       will transform the host CPU model from domain  capabilities  XML  to  a
760       form directly usable in domain XML.
761
762       The  virttype  option  specifies the virtualization type (usable in the
763       'type' attribute of the <domain> top  level  element  from  the  domain
764       XML).  emulator  specifies the path to the emulator, arch specifies the
765       CPU architecture, and machine specifies the machine type. If --features
766       is  specified,  then  the resulting XML description will explicitly in‐
767       clude all features that make up the CPU, without this  option  features
768       that  are  part of the CPU model will not be listed in the XML descrip‐
769       tion. If --migratable is specified, features that block migration  will
770       not be included in the resulting CPU.
771

DOMAIN COMMANDS

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

DEVICE COMMANDS

3878       The  following  commands manipulate devices associated to domains.  The
3879       domain can be specified as a short integer, a name or a full UUID.   To
3880       better understand the values allowed as options for the command reading
3881       the documentation at https://libvirt.org/formatdomain.html on the  for‐
3882       mat  of  the  device  sections to get the most accurate set of accepted
3883       values.
3884
3885   attach-device
3886       Syntax:
3887
3888          attach-device domain FILE [[[--live] [--config] | [--current]] | [--persistent]]
3889
3890       Attach a device to the domain, using a device definition in an XML file
3891       using  a device definition element such as <disk> or <interface> as the
3892       top-level      element.       See      the       documentation       at
3893       https://libvirt.org/formatdomain.html#elementsDevices  to  learn  about
3894       libvirt XML format for a device.  If --config is specified the  command
3895       alters the persistent guest configuration with the device attach taking
3896       effect the next time libvirt starts the domain.  For cdrom  and  floppy
3897       devices,  this  command  only replaces the media within an existing de‐
3898       vice; consider using update-device for  this  usage.   For  passthrough
3899       host  devices,  see  also nodedev-detach, needed if the PCI device does
3900       not use managed mode.
3901
3902       If --live is specified, affect a running domain.  If --config is speci‐
3903       fied,  affect  the next startup of a persistent guest.  If --current is
3904       specified, it is equivalent to either --live or --config, depending  on
3905       the  current state of the guest.  Both --live and --config flags may be
3906       given, but --current is exclusive. When no flag is specified legacy API
3907       is used whose behavior depends on the hypervisor driver.
3908
3909       For  compatibility  purposes, --persistent behaves like --config for an
3910       offline domain, and like --live --config for a running domain.
3911
3912       Note: using of partial device definition XML files may  lead  to  unex‐
3913       pected  results  as some fields may be autogenerated and thus match de‐
3914       vices other than expected.
3915
3916   attach-disk
3917       Syntax:
3918
3919          attach-disk domain source target [[[--live] [--config] |
3920             [--current]] | [--persistent]] [--targetbus bus]
3921             [--driver driver] [--subdriver subdriver] [--iothread iothread]
3922             [--cache cache] [--io io] [--type type] [--alias alias]
3923             [--mode mode] [--sourcetype sourcetype]
3924             [--source-protocol protocol] [--source-host-name hostname:port]
3925             [--source-host-transport transport] [--source-host-socket socket]
3926             [--serial serial] [--wwn wwn] [--rawio] [--address address]
3927             [--multifunction] [--print-xml]
3928
3929       Attach a new disk device to the domain.  source is path for  the  files
3930       and devices unless --source-protocol is specified, in which case source
3931       is the name of a network disk.  target controls the bus or device under
3932       which  the  disk is exposed to the guest OS. It indicates the "logical"
3933       device name; the optional targetbus attribute  specifies  the  type  of
3934       disk device to emulate; possible values are driver specific, with typi‐
3935       cal values being ide, scsi, virtio, xen, usb, sata, or sd, if  omitted,
3936       the bus type is inferred from the style of the device name (e.g.  a de‐
3937       vice named 'sda' will typically be exported using a SCSI bus).   driver
3938       can be file, tap or phy for the Xen hypervisor depending on the kind of
3939       access; or qemu for the QEMU emulator.  Further details to  the  driver
3940       can  be passed using subdriver. For Xen subdriver can be aio, while for
3941       QEMU subdriver should match the format of the disk source, such as  raw
3942       or  qcow2.   Hypervisor default will be used if subdriver is not speci‐
3943       fied.  However, the default may not be correct, esp. for  QEMU  as  for
3944       security reasons it is configured not to detect disk formats.  type can
3945       indicate lun, cdrom or floppy as alternative to the disk  default,  al‐
3946       though  this  use  only  replaces the media within the existing virtual
3947       cdrom or floppy device; consider using update-device for this usage in‐
3948       stead.   alias  can  set user supplied alias.  mode can specify the two
3949       specific mode readonly or shareable.  sourcetype can indicate the  type
3950       of  source  (block|file|network) cache can be one of "default", "none",
3951       "writethrough", "writeback", "directsync"  or  "unsafe".   io  controls
3952       specific  policies  on I/O; QEMU guests support "threads", "native" and
3953       "io_uring".  iothread is the number within  the  range  of  domain  IO‐
3954       Threads  to which this disk may be attached (QEMU only).  serial is the
3955       serial of disk device. wwn is the wwn of disk device.  rawio  indicates
3956       the disk needs rawio capability.  address is the address of disk device
3957       in the form of pci:domain.bus.slot.function,  scsi:controller.bus.unit,
3958       ide:controller.bus.unit,   usb:bus.port,   sata:controller.bus.unit  or
3959       ccw:cssid.ssid.devno. Virtio-ccw devices must have their cssid  set  to
3960       0xfe.  multifunction indicates specified pci address is a multifunction
3961       pci device address.
3962
3963       There is also support for using a network disk. As specified, the  user
3964       can provide a --source-protocol in which case the source parameter will
3965       be interpreted as the source name. --source-protocol must  be  provided
3966       if  the  user  intends  to  provide a network disk or host information.
3967       Host information can be provided  using  the  tags  --source-host-name,
3968       --source-host-transport,  and  --source-host-socket, which respectively
3969       denote the name of the host,  the  host's  transport  method,  and  the
3970       socket  that the host uses. --source-host-socket and --source-host-name
3971       cannot   both   be   provided,   and   the   user   must   provide    a
3972       --source-host-transport if they want to provide a --source-host-socket.
3973       The --source-host-name parameter supports host:port syntax if the  user
3974       wants to provide a port as well.
3975
3976       If --print-xml is specified, then the XML of the disk that would be at‐
3977       tached is printed instead.
3978
3979       If --live is specified, affect a running domain.  If --config is speci‐
3980       fied,  affect  the next startup of a persistent guest.  If --current is
3981       specified, it is equivalent to either --live or --config, depending  on
3982       the  current state of the guest.  Both --live and --config flags may be
3983       given, but --current is exclusive. When no flag is specified legacy API
3984       is used whose behavior depends on the hypervisor driver.
3985
3986       For  compatibility  purposes, --persistent behaves like --config for an
3987       offline domain, and like --live --config for a running  domain.   Like‐
3988       wise, --shareable is an alias for --mode shareable.
3989
3990   attach-interface
3991       Syntax:
3992
3993          attach-interface domain type source [[[--live]
3994             [--config] | [--current]] | [--persistent]]
3995             [--target target] [--mac mac] [--script script] [--model model]
3996             [--inbound average,peak,burst,floor] [--outbound average,peak,burst]
3997             [--alias alias] [--managed] [--print-xml]
3998
3999       Attach a new network interface to the domain.
4000
4001       type can be one of the:
4002
4003       network to indicate connection via a libvirt virtual network,
4004
4005       bridge to indicate connection via a bridge device on the host,
4006
4007       direct to indicate connection directly to one of the host's network in‐
4008       terfaces or bridges,
4009
4010       hostdev to indicate connection using a passthrough of PCI device on the
4011       host.
4012
4013       source  indicates  the source of the connection.  The source depends on
4014       the type of the interface:
4015
4016       network name of the virtual network,
4017
4018       bridge the name of the bridge device,
4019
4020       direct the name of the host's interface or bridge,
4021
4022       hostdev the PCI address  of  the  host's  interface  formatted  as  do‐
4023       main:bus:slot.function.
4024
4025       --target  is  used to specify the tap/macvtap device to be used to con‐
4026       nect the domain to the source.  Names starting with 'vnet' are  consid‐
4027       ered  as  auto-generated  and are blanked out/regenerated each time the
4028       interface is attached.
4029
4030       --mac specifies the MAC address of the network interface; if a MAC  ad‐
4031       dress  is not given, a new address will be automatically generated (and
4032       stored in the persistent configuration if "--config" is  given  on  the
4033       command line).
4034
4035       --script  is  used  to  specify  a path to a custom script to be called
4036       while attaching to a bridge - this will be called instead  of  the  de‐
4037       fault  script not in addition to it.  This is valid only for interfaces
4038       of bridge type and only for Xen domains.
4039
4040       --model specifies the network device model to be presented to  the  do‐
4041       main.
4042
4043       alias can set user supplied alias.
4044
4045       --inbound  and  --outbound  control the bandwidth of the interface.  At
4046       least one from the average, floor pair must be  specified.   The  other
4047       two  peak  and burst are optional, so "average,peak", "average,,burst",
4048       "average,,,floor", "average" and ",,,floor" are also legal.  Values for
4049       average,  floor  and  peak are expressed in kilobytes per second, while
4050       burst is expressed in kilobytes in a single burst at peak speed as  de‐
4051       scribed      in      the      Network      XML     documentation     at
4052       https://libvirt.org/formatnetwork.html#elementQoS.
4053
4054       --managed is usable only for hostdev type and tells  libvirt  that  the
4055       interface  should  be  managed,  which  means  detached  and reattached
4056       from/to the host by libvirt.
4057
4058       If --print-xml is specified, then the XML of the interface  that  would
4059       be attached is printed instead.
4060
4061       If --live is specified, affect a running domain.  If --config is speci‐
4062       fied, affect the next startup of a persistent guest.  If  --current  is
4063       specified, affect the current domain state, which can either be live or
4064       offline.  Both --live and --config flags may be given, but --current is
4065       exclusive.  When no flag is specified legacy API is used whose behavior
4066       depends on the hypervisor driver.
4067
4068       For compatibility purposes, --persistent behaves like --config  for  an
4069       offline domain, and like --live --config for a running domain.
4070
4071       Note:  the  optional target value is the name of a device to be created
4072       as the back-end on the node.  If not provided a device named "vnetN" or
4073       "vifN" will be created automatically.
4074
4075   detach-device
4076       Syntax:
4077
4078          detach-device domain FILE [[[--live] [--config] |
4079             [--current]] | [--persistent]]
4080
4081       Detach  a  device  from the domain, takes the same kind of XML descrip‐
4082       tions as command attach-device.  For passthrough host devices, see also
4083       nodedev-reattach, needed if the device does not use managed mode.
4084
4085       Note:  The supplied XML description of the device should be as specific
4086       as its definition in the domain XML. The  set  of  attributes  used  to
4087       match  the  device are internal to the drivers. Using a partial defini‐
4088       tion, or attempting to detach a device that is not present in  the  do‐
4089       main XML, but shares some specific attributes with one that is present,
4090       may lead to unexpected results.
4091
4092       Quirk: Device unplug is asynchronous in most cases and  requires  guest
4093       cooperation.  This means that it's up to the discretion of the guest to
4094       disallow or delay the unplug arbitrarily. As the libvirt  API  used  in
4095       this  command was designed as synchronous it returns success after some
4096       timeout even if the device was not unplugged yet to allow  further  in‐
4097       teractions  with  the domain e.g. if the guest is unresponsive. Callers
4098       which need to make sure that the device was unplugged can  use  libvirt
4099       events  (see  virsh  event)  to be notified when the device is removed.
4100       Note that the event may arrive before the command returns.
4101
4102       If --live is specified, affect a running domain.  If --config is speci‐
4103       fied,  affect  the next startup of a persistent guest.  If --current is
4104       specified, it is equivalent to either --live or --config, depending  on
4105       the  current state of the guest.  Both --live and --config flags may be
4106       given, but --current is exclusive. When no flag is specified legacy API
4107       is used whose behavior depends on the hypervisor driver.
4108
4109       For  compatibility  purposes, --persistent behaves like --config for an
4110       offline domain, and like --live --config for a running domain.
4111
4112       Note that older versions of virsh used --config as an alias for  --per‐
4113       sistent.
4114
4115   detach-device-alias
4116       Syntax:
4117
4118          detach-device-alias domain alias [[[--live] [--config] | [--current]]]]
4119
4120       Detach  a device with given alias from the domain. This command returns
4121       successfully after the unplug request was sent to the  hypervisor.  The
4122       actual  removal  of  the  device is notified asynchronously via libvirt
4123       events (see virsh event).
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.
4130
4131   detach-disk
4132       Syntax:
4133
4134          detach-disk domain target [[[--live] [--config] |
4135             [--current]] | [--persistent]] [--print-xml]
4136
4137       Detach a disk device from a domain. The target is the  device  as  seen
4138       from the domain.
4139
4140       If --live is specified, affect a running domain.  If --config is speci‐
4141       fied, affect the next startup of a persistent guest.  If  --current  is
4142       specified,  it is equivalent to either --live or --config, depending on
4143       the current state of the guest.  Both --live and --config flags may  be
4144       given, but --current is exclusive. When no flag is specified legacy API
4145       is used whose behavior depends on the hypervisor driver.
4146
4147       For compatibility purposes, --persistent behaves like --config  for  an
4148       offline domain, and like --live --config for a running domain.
4149
4150       Note  that older versions of virsh used --config as an alias for --per‐
4151       sistent.
4152
4153       If --print-xml is specified, then the XML which would be used to detach
4154       the disk is printed instead.
4155
4156       Please see documentation for detach-device for known quirks.
4157
4158   detach-interface
4159       Syntax:
4160
4161          detach-interface domain type [--mac mac]
4162             [[[--live] [--config] | [--current]] | [--persistent]]
4163
4164       Detach  a  network interface from a domain.  type can be either network
4165       to indicate a physical network device or bridge to indicate a bridge to
4166       a  device.  It  is recommended to use the mac option to distinguish be‐
4167       tween the interfaces if more than one are present on the domain.
4168
4169       If --live is specified, affect a running domain.  If --config is speci‐
4170       fied,  affect  the next startup of a persistent guest.  If --current is
4171       specified, it is equivalent to either --live or --config, depending  on
4172       the  current state of the guest.  Both --live and --config flags may be
4173       given, but --current is exclusive. When no flag is specified legacy API
4174       is used whose behavior depends on the hypervisor driver.
4175
4176       For  compatibility  purposes, --persistent behaves like --config for an
4177       offline domain, and like --live --config for a running domain.
4178
4179       Note that older versions of virsh used --config as an alias for  --per‐
4180       sistent.
4181
4182       Please see documentation for detach-device for known quirks.
4183
4184   update-device
4185       Syntax:
4186
4187          update-device domain file [--force] [[[--live]
4188             [--config] | [--current]] | [--persistent]]
4189
4190       Update the characteristics of a device associated with domain, based on
4191       the device definition in an XML file.  The --force option can  be  used
4192       to  force  device  update,  e.g.,  to  eject  a  CD-ROM  even  if it is
4193       locked/mounted   in   the   domain.   See    the    documentation    at
4194       https://libvirt.org/formatdomain.html#elementsDevices  to  learn  about
4195       libvirt XML format for a device.
4196
4197       If --live is specified, affect a running domain.  If --config is speci‐
4198       fied,  affect  the next startup of a persistent guest.  If --current is
4199       specified, it is equivalent to either --live or --config, depending  on
4200       the  current state of the guest.  Both --live and --config flags may be
4201       given, but --current is exclusive. Not specifying any flag is the  same
4202       as specifying --current.
4203
4204       For  compatibility  purposes, --persistent behaves like --config for an
4205       offline domain, and like --live --config for a running domain.
4206
4207       Note that older versions of virsh used --config as an alias for  --per‐
4208       sistent.
4209
4210       Note:  using  of  partial device definition XML files may lead to unex‐
4211       pected results as some fields may be autogenerated and thus  match  de‐
4212       vices other than expected.
4213
4214   change-media
4215       Syntax:
4216
4217          change-media domain path [--eject] [--insert]
4218             [--update] [source] [--force] [[--live] [--config] |
4219             [--current]] [--print-xml] [--block]
4220
4221       Change  media of CDROM or floppy drive. path can be the fully-qualified
4222       path or the unique target name (<target dev='hdc'>) of the disk device.
4223       source  specifies  the path of the media to be inserted or updated. The
4224       --block flag allows setting the backing type in case a block device  is
4225       used as media for the CDROM or floppy drive instead of a file.
4226
4227       --eject  indicates  the  media will be ejected.  --insert indicates the
4228       media will be inserted. source must be specified.  If  the  device  has
4229       source (e.g. <source file='media'>), and source is not specified, --up‐
4230       date is equal to --eject. If the device has no source,  and  source  is
4231       specified, --update is equal to --insert. If the device has source, and
4232       source is specified, --update behaves like combination of  --eject  and
4233       --insert.   If  none  of  --eject, --insert, and --update is specified,
4234       --update is used by default.  The --force option can be used  to  force
4235       media  changing.   If  --live is specified, alter live configuration of
4236       running guest.  If --config is specified, alter  persistent  configura‐
4237       tion,  effect  observed on next startup of the guest.  --current can be
4238       either or both of live and config, depends on the  hypervisor's  imple‐
4239       mentation.   Both --live and --config flags may be given, but --current
4240       is exclusive. If no flag is specified, behavior is different  depending
4241       on hypervisor.  If --print-xml is specified, the XML that would be used
4242       to change media is printed instead of changing the media.
4243

NODEDEV COMMANDS

4245       The following commands manipulate host devices that are intended to  be
4246       passed  through  to  guest domains via <hostdev> elements in a domain's
4247       <devices> section.  A node device key is generally specified by the bus
4248       name followed by its address, using underscores between all components,
4249       such as  pci_0000_00_02_1,  usb_1_5_3,  or  net_eth1_00_27_13_6a_fe_00.
4250       The  nodedev-list gives the full list of host devices that are known to
4251       libvirt, although this includes devices that cannot be  assigned  to  a
4252       guest  (for  example, attempting to detach the PCI device that controls
4253       the host's hard disk controller where  the  guest's  disk  images  live
4254       could cause the host system to lock up or reboot).
4255
4256       For    more    information    on    node    device    definition   see:
4257       https://libvirt.org/formatnode.html.
4258
4259       Passthrough devices cannot be simultaneously used by the host  and  its
4260       guest domains, nor by multiple active guests at once.  If the <hostdev>
4261       description of a PCI device includes the attribute  managed='yes',  and
4262       the  hypervisor driver supports it, then the device is in managed mode,
4263       and attempts to use that passthrough device in an active guest will au‐
4264       tomatically  behave as if nodedev-detach (guest start, device hot-plug)
4265       and nodedev-reattach (guest stop, device hot-unplug) were called at the
4266       right  points.   If a PCI device is not marked as managed, then it must
4267       manually be detached before guests can use it, and manually  reattached
4268       to  be  returned  to the host.  Also, if a device is manually detached,
4269       then the host does not regain control of the device without a  matching
4270       reattach, even if the guests use the device in managed mode.
4271
4272   nodedev-create
4273       Syntax:
4274
4275          nodedev-create FILE
4276
4277       Create  a  device on the host node that can then be assigned to virtual
4278       machines. Normally, libvirt is able to  automatically  determine  which
4279       host  nodes are available for use, but this allows registration of host
4280       hardware that libvirt did not automatically detect.  file contains  xml
4281       for a top-level <device> description of a node device.
4282
4283   nodedev-destroy
4284       Syntax:
4285
4286          nodedev-destroy device
4287
4288       Destroy  (stop)  a device on the host. device can be either device name
4289       or wwn pair in "wwnn,wwpn" format  (only  works  for  vHBA  currently).
4290       Note  that this makes libvirt quit managing a host device, and may even
4291       make that device unusable by the rest of the physical host until a  re‐
4292       boot.
4293
4294   nodedev-detach
4295       Syntax:
4296
4297          nodedev-detach nodedev [--driver backend_driver]
4298
4299       Detach  nodedev  from the host, so that it can safely be used by guests
4300       via <hostdev> passthrough.  This is reversed with nodedev-reattach, and
4301       is done automatically for managed devices.
4302
4303       Different  backend  drivers  expect the device to be bound to different
4304       dummy devices. For example, QEMU's "kvm" backend driver  (the  default)
4305       expects  the  device  to  be  bound to pci-stub, but its "vfio" backend
4306       driver expects the device to be bound to vfio-pci. The --driver parame‐
4307       ter can be used to specify the desired backend driver.
4308
4309   nodedev-dumpxml
4310       Syntax:
4311
4312          nodedev-dumpxml device
4313
4314       Dump a <device> XML representation for the given node device, including
4315       such information as the device name, which bus  owns  the  device,  the
4316       vendor  and  product  id,  and any capabilities of the device usable by
4317       libvirt (such as whether device reset is supported). device can be  ei‐
4318       ther  device  name  or  wwn  pair in "wwnn,wwpn" format (only works for
4319       HBA).
4320
4321   nodedev-list
4322       Syntax:
4323
4324          nodedev-list cap --tree
4325
4326       List all of the devices available on the node that are  known  by  lib‐
4327       virt.   cap  is  used to filter the list by capability types, the types
4328       must be separated by comma, e.g. --cap pci,scsi. Valid capability types
4329       include  'system',  'pci',  'usb_device',  'usb',  'net',  'scsi_host',
4330       'scsi_target', 'scsi', 'storage', 'fc_host', 'vports',  'scsi_generic',
4331       'drm',  'mdev',  'mdev_types',  'ccw',  'css',  'ap_card',  'ap_queue',
4332       'ap_matrix'.  If --tree is used, the output is formatted in a tree rep‐
4333       resenting parents of each node.  cap and --tree are mutually exclusive.
4334
4335   nodedev-reattach
4336       Syntax:
4337
4338          nodedev-reattach nodedev
4339
4340       Declare  that  nodedev  is no longer in use by any guests, and that the
4341       host can resume normal use of the device.  This is  done  automatically
4342       for  PCI  devices in managed mode and USB devices, but must be done ex‐
4343       plicitly to match any explicit nodedev-detach.
4344
4345   nodedev-reset
4346       Syntax:
4347
4348          nodedev-reset nodedev
4349
4350       Trigger a device reset for nodedev, useful prior to transferring a node
4351       device  between  guest  passthrough or the host.  Libvirt will often do
4352       this action implicitly when required, but this command  allows  an  ex‐
4353       plicit reset when needed.
4354
4355   nodedev-event
4356       Syntax:
4357
4358          nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list}
4359
4360       Wait  for a class of node device events to occur, and print appropriate
4361       details of events as they happen.  The events can  optionally  be  fil‐
4362       tered  by  nodedev.   Using  --list as the only argument will provide a
4363       list of possible event values known by this client, although  the  con‐
4364       nection might not allow registering for all these events.
4365
4366       By default, this command is one-shot, and returns success once an event
4367       occurs; you can send SIGINT (usually via Ctrl-C) to  quit  immediately.
4368       If  --timeout is specified, the command gives up waiting for events af‐
4369       ter seconds have elapsed.   With --loop, the command prints all  events
4370       until a timeout or interrupt key.
4371
4372       When  --timestamp  is  used, a human-readable timestamp will be printed
4373       before the event.
4374

VIRTUAL NETWORK COMMANDS

4376       The following commands manipulate networks. Libvirt has the  capability
4377       to define virtual networks which can then be used by domains and linked
4378       to actual network devices. For more  detailed  information  about  this
4379       feature see the documentation at https://libvirt.org/formatnetwork.html
4380       . Many of the commands for virtual networks are  similar  to  the  ones
4381       used  for  domains,  but the way to name a virtual network is either by
4382       its name or UUID.
4383
4384   net-autostart
4385       Syntax:
4386
4387          net-autostart network [--disable]
4388
4389       Configure a virtual network to be automatically started at  boot.   The
4390       --disable option disable autostarting.
4391
4392   net-create
4393       Syntax:
4394
4395          net-create file
4396
4397       Create a transient (temporary) virtual network from an XML file and in‐
4398       stantiate   (start)   the   network.    See   the   documentation    at
4399       https://libvirt.org/formatnetwork.html  to get a description of the XML
4400       network format used by libvirt.
4401
4402   net-define
4403       Syntax:
4404
4405          net-define file
4406
4407       Define an inactive persistent virtual network  or  modify  an  existing
4408       persistent one from the XML file.
4409
4410   net-destroy
4411       Syntax:
4412
4413          net-destroy network
4414
4415       Destroy  (stop)  a given transient or persistent virtual network speci‐
4416       fied by its name or UUID. This takes effect immediately.
4417
4418   net-dumpxml
4419       Syntax:
4420
4421          net-dumpxml network [--inactive]
4422
4423       Output the virtual network information as an XML dump  to  stdout.   If
4424       --inactive  is specified, then physical functions are not expanded into
4425       their associated virtual functions.
4426
4427   net-edit
4428       Syntax:
4429
4430          net-edit network
4431
4432       Edit the XML configuration file for a network.
4433
4434       This is equivalent to:
4435
4436          virsh net-dumpxml --inactive network > network.xml
4437          vi network.xml (or make changes with your other text editor)
4438          virsh net-define network.xml
4439
4440       except that it does some error checking.
4441
4442       The editor used can be supplied by the $VISUAL or  $EDITOR  environment
4443       variables, and defaults to vi.
4444
4445   net-event
4446       Syntax:
4447
4448          net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list}
4449
4450       Wait  for a class of network events to occur, and print appropriate de‐
4451       tails of events as they happen.  The events can optionally be  filtered
4452       by  network.   Using --list as the only argument will provide a list of
4453       possible event values known by this  client,  although  the  connection
4454       might not allow registering for all these events.
4455
4456       By default, this command is one-shot, and returns success once an event
4457       occurs; you can send SIGINT (usually via Ctrl-C) to  quit  immediately.
4458       If  --timeout is specified, the command gives up waiting for events af‐
4459       ter seconds have elapsed.   With --loop, the command prints all  events
4460       until a timeout or interrupt key.
4461
4462       When  --timestamp  is  used, a human-readable timestamp will be printed
4463       before the event.
4464
4465   net-info
4466       Syntax:
4467
4468          net-info network
4469
4470       Returns basic information about the network object.
4471
4472   net-list
4473       Syntax:
4474
4475          net-list [--inactive | --all]
4476             { [--table] | --name | --uuid }
4477             [--persistent] [<--transient>]
4478             [--autostart] [<--no-autostart>]
4479
4480       Returns the list of active networks, if --all is  specified  this  will
4481       also  include defined but inactive networks, if --inactive is specified
4482       only the inactive ones will be listed. You may also want to filter  the
4483       returned  networks by --persistent to list the persistent ones, --tran‐
4484       sient to list the transient ones, --autostart to list the ones with au‐
4485       tostart  enabled,  and  --no-autostart  to list the ones with autostart
4486       disabled.
4487
4488       If --name is specified, network names are printed instead of the  table
4489       formatted  one  per  line.  If --uuid is specified network's UUID's are
4490       printed instead of names. Flag --table specifies that  the  legacy  ta‐
4491       ble-formatted  output should be used. This is the default. All of these
4492       are mutually exclusive.
4493
4494       NOTE: When talking to older servers, this command is forced  to  use  a
4495       series  of  API  calls with an inherent race, where a pool might not be
4496       listed or might appear more than once if it changed state between calls
4497       while  the  list  was  being collected.  Newer servers do not have this
4498       problem.
4499
4500   net-name
4501       Syntax:
4502
4503          net-name network-UUID
4504
4505       Convert a network UUID to network name.
4506
4507   net-start
4508       Syntax:
4509
4510          net-start network
4511
4512       Start a (previously defined) inactive network.
4513
4514   net-undefine
4515       Syntax:
4516
4517          net-undefine network
4518
4519       Undefine the configuration for a persistent network. If the network  is
4520       active, make it transient.
4521
4522   net-uuid
4523       Syntax:
4524
4525          net-uuid network-name
4526
4527       Convert a network name to network UUID.
4528
4529   net-update
4530       Syntax:
4531
4532          net-update network command section xml
4533             [--parent-index index] [[--live] [--config] | [--current]]
4534
4535       Update  the  given  section of an existing network definition, with the
4536       changes optionally taking effect immediately, without  needing  to  de‐
4537       stroy and re-start the network.
4538
4539       command  is  one  of  "add-first",  "add-last",  "add"  (a  synonym for
4540       add-last), "delete", or "modify".
4541
4542       section  is  one   of   "bridge",   "domain",   "ip",   "ip-dhcp-host",
4543       "ip-dhcp-range",  "forward",  "forward-interface", "forward-pf", "port‐
4544       group", "dns-host", "dns-txt", or "dns-srv", each section  being  named
4545       by  a concatenation of the xml element hierarchy leading to the element
4546       being changed. For example, "ip-dhcp-host" will change a <host> element
4547       that is contained inside a <dhcp> element inside an <ip> element of the
4548       network.
4549
4550       xml is either the text of a complete xml  element  of  the  type  being
4551       changed  (e.g.  "<host  mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the
4552       name of a file that contains a complete xml element. Disambiguation  is
4553       done  by  looking  at the first character of the provided text - if the
4554       first character is "<", it is xml text, if the first character  is  not
4555       "<", it is the name of a file that contains the xml text to be used.
4556
4557       The  --parent-index  option  is used to specify which of several parent
4558       elements the requested element is in (0-based).  For  example,  a  dhcp
4559       <host>  element  could  be  in any one of multiple <ip> elements in the
4560       network; if a parent-index isn't provided, the "most appropriate"  <ip>
4561       element  will  be  selected  (usually  the  only one that already has a
4562       <dhcp> element), but if --parent-index is given,  that  particular  in‐
4563       stance of <ip> will get the modification.
4564
4565       If --live is specified, affect a running network.  If --config is spec‐
4566       ified, affect the next startup of a persistent network.   If  --current
4567       is  specified, it is equivalent to either --live or --config, depending
4568       on the current state of the guest.  Both --live and --config flags  may
4569       be  given,  but  --current is exclusive. Not specifying any flag is the
4570       same as specifying --current.
4571
4572   net-dhcp-leases
4573       Syntax:
4574
4575          net-dhcp-leases network [mac]
4576
4577       Get a list of dhcp leases for all network interfaces connected  to  the
4578       given  virtual  network or limited output just for one interface if mac
4579       is specified.
4580

NETWORK PORT COMMANDS

4582       The following commands manipulate network ports. Libvirt  virtual  net‐
4583       works  have  ports created when a virtual machine has a virtual network
4584       interface added. In general there should be no need to use any  of  the
4585       commands  here, since the hypervisor drivers run these commands are the
4586       right point in a virtual machine's lifecycle. They can  be  useful  for
4587       debugging problems and / or recovering from bugs / stale state.
4588
4589   net-port-list
4590       Syntax:
4591
4592          net-port-list { [--table] | --uuid } network
4593
4594       List all network ports recorded against the network.
4595
4596       If  --uuid  is specified network ports' UUID's are printed instead of a
4597       table. Flag --table specifies that the  legacy  table-formatted  output
4598       should  be used. This is the default.  All of these are mutually exclu‐
4599       sive.
4600
4601   net-port-create
4602       Syntax:
4603
4604          net-port-create network file
4605
4606       Allocate a new network port reserving resources based on the  port  de‐
4607       scription.
4608
4609   net-port-dumpxml
4610       Syntax:
4611
4612          net-port-dumpxml network port
4613
4614       Output the network port information as an XML dump to stdout.
4615
4616   net-port-delete
4617       Syntax:
4618
4619          net-port-delete network port
4620
4621       Delete record of the network port and release its resources
4622

INTERFACE COMMANDS

4624       The  following  commands manipulate host interfaces.  Often, these host
4625       interfaces can then be used by name within domain <interface>  elements
4626       (such  as  a system-created bridge interface), but there is no require‐
4627       ment that host interfaces be tied to any particular guest configuration
4628       XML at all.
4629
4630       Many  of  the commands for host interfaces are similar to the ones used
4631       for domains, and the way to name an interface is either by its name  or
4632       its  MAC  address.   However, using a MAC address for an iface argument
4633       only works when that address is unique (if an interface  and  a  bridge
4634       share  the  same  MAC address, which is often the case, then using that
4635       MAC address results in an error due to ambiguity, and you  must  resort
4636       to a name instead).
4637
4638   iface-bridge
4639       Syntax:
4640
4641          iface-bridge interface bridge [--no-stp] [delay] [--no-start]
4642
4643       Create  a  bridge  device named bridge, and attach the existing network
4644       device interface to the new bridge.  The new bridge defaults to  start‐
4645       ing  immediately, with STP enabled and a delay of 0; these settings can
4646       be altered with --no-stp, --no-start, and an integer number of  seconds
4647       for  delay.  All IP address configuration of interface will be moved to
4648       the new bridge device.
4649
4650       See also iface-unbridge for undoing this operation.
4651
4652   iface-define
4653       Syntax:
4654
4655          iface-define file
4656
4657       Define an inactive persistent physical host interface or modify an  ex‐
4658       isting persistent one from the XML file.
4659
4660   iface-destroy
4661       Syntax:
4662
4663          iface-destroy interface
4664
4665       Destroy  (stop) a given host interface, such as by running "if-down" to
4666       disable that interface from active use. This takes effect immediately.
4667
4668   iface-dumpxml
4669       Syntax:
4670
4671          iface-dumpxml interface [--inactive]
4672
4673       Output the host interface information as an XML  dump  to  stdout.   If
4674       --inactive  is specified, then the output reflects the persistent state
4675       of the interface that will be used the next time it is started.
4676
4677   iface-edit
4678       Syntax:
4679
4680          iface-edit interface
4681
4682       Edit the XML configuration file for a host interface.
4683
4684       This is equivalent to:
4685
4686          virsh iface-dumpxml iface > iface.xml
4687          vi iface.xml (or make changes with your other text editor)
4688          virsh iface-define iface.xml
4689
4690       except that it does some error checking.
4691
4692       The editor used can be supplied by the $VISUAL or  $EDITOR  environment
4693       variables, and defaults to vi.
4694
4695   iface-list
4696       Syntax:
4697
4698          iface-list [--inactive | --all]
4699
4700       Returns the list of active host interfaces.  If --all is specified this
4701       will also include defined but inactive interfaces.   If  --inactive  is
4702       specified only the inactive ones will be listed.
4703
4704   iface-name
4705       Syntax:
4706
4707          iface-name interface
4708
4709       Convert  a  host interface MAC to interface name, if the MAC address is
4710       unique among the host's interfaces.
4711
4712       interface specifies the interface MAC address.
4713
4714   iface-mac
4715       Syntax:
4716
4717          iface-mac interface
4718
4719       Convert a host interface name to MAC address.
4720
4721       interface specifies the interface name.
4722
4723   iface-start
4724       Syntax:
4725
4726          iface-start interface
4727
4728       Start a  (previously  defined)  host  interface,  such  as  by  running
4729       "if-up".
4730
4731   iface-unbridge
4732       Syntax:
4733
4734          iface-unbridge bridge [--no-start]
4735
4736       Tear down a bridge device named bridge, releasing its underlying inter‐
4737       face back to normal usage, and moving all IP address configuration from
4738       the  bridge  device to the underlying device.  The underlying interface
4739       is restarted unless --no-start is present; this  flag  is  present  for
4740       symmetry, but generally not recommended.
4741
4742       See also iface-bridge for creating a bridge.
4743
4744   iface-undefine
4745       Syntax:
4746
4747          iface-undefine interface
4748
4749       Undefine the configuration for an inactive host interface.
4750
4751   iface-begin
4752       Syntax:
4753
4754          iface-begin
4755
4756       Create  a  snapshot of current host interface settings, which can later
4757       be committed (iface-commit) or restored (iface-rollback).  If  a  snap‐
4758       shot  already  exists,  then  this command will fail until the previous
4759       snapshot has been committed or restored.  Undefined behavior results if
4760       any external changes are made to host interfaces outside of the libvirt
4761       API between the beginning of a snapshot  and  its  eventual  commit  or
4762       rollback.
4763
4764   iface-commit
4765       Syntax:
4766
4767          iface-commit
4768
4769       Declare  all  changes since the last iface-begin as working, and delete
4770       the rollback point.  If no interface snapshot has already been started,
4771       then this command will fail.
4772
4773   iface-rollback
4774       Syntax:
4775
4776          iface-rollback
4777
4778       Revert  all  host  interface settings back to the state recorded in the
4779       last iface-begin.  If no interface snapshot has already  been  started,
4780       then  this command will fail.  Rebooting the host also serves as an im‐
4781       plicit rollback point.
4782

STORAGE POOL COMMANDS

4784       The following commands manipulate storage pools. Libvirt has the  capa‐
4785       bility to manage various storage solutions, including files, raw parti‐
4786       tions, and domain-specific formats, used to provide the storage volumes
4787       visible  as devices within virtual machines. For more detailed informa‐
4788       tion    about    this    feature,    see    the    documentation     at
4789       https://libvirt.org/formatstorage.html . Many of the commands for pools
4790       are similar to the ones used for domains.
4791
4792   find-storage-pool-sources
4793       Syntax:
4794
4795          find-storage-pool-sources type [srcSpec]
4796
4797       Returns XML describing all possible available storage pool sources that
4798       could  be  used  to create or define a storage pool of a given type. If
4799       srcSpec is provided, it is a file that contains XML to further restrict
4800       the query for pools.
4801
4802       Not  all  storage  pools support discovery in this manner. Furthermore,
4803       for those that do support discovery, only specific XML elements are re‐
4804       quired in order to return valid data, while other elements and even at‐
4805       tributes of some elements are ignored since they are not  necessary  to
4806       find  the  pool  based  on the search criteria. The following lists the
4807       supported type options and the expected minimal XML  elements  used  to
4808       perform the search.
4809
4810       For  a  "netfs" or "gluster" pool, the minimal expected XML required is
4811       the <host> element with a "name" attribute describing the IP address or
4812       hostname  to be used to find the pool. The "port" attribute will be ig‐
4813       nored as will any other provided XML elements in srcSpec.
4814
4815       For a "logical" pool, the contents of the srcSpec file are ignored, al‐
4816       though if provided the file must at least exist.
4817
4818       For  an "iscsi" or "iscsi-direct" pool, the minimal expect XML required
4819       is the <host> element with a "name" attribute describing the IP address
4820       or hostname to be used to find the pool (the iSCSI server address). Op‐
4821       tionally, the "port" attribute may be provided, although  it  will  de‐
4822       fault to 3260. Optionally, an <initiator> XML element with a "name" at‐
4823       tribute may be provided to further restrict the iSCSI target search  to
4824       a specific initiator for multi-iqn iSCSI storage pools.
4825
4826   find-pool-sources-as
4827       Syntax:
4828
4829          find-storage-pool-sources-as type [host] [port] [initiator]
4830
4831       Rather  than  providing  srcSpec XML file for find-storage-pool-sources
4832       use this command option in order to have virsh generate the  query  XML
4833       file  using  the  optional  arguments. The command will return the same
4834       output XML as find-storage-pool-sources.
4835
4836       Use host to describe a specific host to use for networked storage, such
4837       as netfs, gluster, and iscsi type pools.
4838
4839       Use  port  to  further restrict which networked port to utilize for the
4840       connection if required by the specific storage backend, such as iscsi.
4841
4842       Use initiator to further restrict the iscsi type pool searches to  spe‐
4843       cific target initiators.
4844
4845   pool-autostart
4846       Syntax:
4847
4848          pool-autostart pool-or-uuid [--disable]
4849
4850       Configure whether pool should automatically start at boot.
4851
4852   pool-build
4853       Syntax:
4854
4855          pool-build pool-or-uuid [--overwrite] [--no-overwrite]
4856
4857       Build a given pool.
4858
4859       Options  --overwrite and --no-overwrite can only be used for pool-build
4860       a filesystem, disk, or logical pool.
4861
4862       For a file system pool if neither flag is  specified,  then  pool-build
4863       just  makes the target path directory and no attempt to run mkfs on the
4864       target volume device. If --no-overwrite is specified, it probes to  de‐
4865       termine  if a filesystem already exists on the target device, returning
4866       an error if one exists or using mkfs to format  the  target  device  if
4867       not.   If --overwrite is specified, mkfs is always executed and any ex‐
4868       isting data on the target device is overwritten unconditionally.
4869
4870       For a disk pool, if neither of them is specified or  --no-overwrite  is
4871       specified,  pool-build will check the target volume device for existing
4872       filesystems or partitions before attempting to write a new label on the
4873       target  volume device. If the target volume device already has a label,
4874       the command will fail. If --overwrite is specified, then no check  will
4875       be made on the target volume device prior to writing a new label. Writ‐
4876       ing of the label uses the pool source format type or "dos" if not spec‐
4877       ified.
4878
4879       For  a  logical pool, if neither of them is specified or --no-overwrite
4880       is specified, pool-build will check the target volume devices  for  ex‐
4881       isting  filesystems  or  partitions before attempting to initialize and
4882       format each device for usage by the logical pool. If any target  volume
4883       device  already  has  a label, the command will fail. If --overwrite is
4884       specified, then no check will be made  on  the  target  volume  devices
4885       prior  to  initializing and formatting each device. Once all the target
4886       volume devices are properly formatted via pvcreate,  the  volume  group
4887       will be created using all the devices.
4888
4889   pool-create
4890       Syntax:
4891
4892          pool-create file [--build] [[--overwrite] | [--no-overwrite]]
4893
4894       Create and start a pool object from the XML file.
4895
4896       [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
4897       creation in order to remove the need for a follow-up command  to  build
4898       the  pool.  The  --overwrite  and  --no-overwrite flags follow the same
4899       rules as pool-build. If just --build is provided,  then  pool-build  is
4900       called with no flags.
4901
4902   pool-create-as
4903       Syntax:
4904
4905          pool-create-as name type
4906             [--source-host hostname] [--source-path path] [--source-dev path]
4907             [--source-name name] [--target path] [--source-format format]
4908             [--source-initiator initiator-iqn]
4909             [--auth-type authtype --auth-username username
4910             [--secret-usage usage | --secret-uuid uuid]]
4911             [--source-protocol-ver ver]
4912             [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn]
4913             [--adapter-parent parent |
4914             --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
4915             --adapter-parent-fabric-wwn parent_fabric_wwn]]
4916             [--build] [[--overwrite] | [--no-overwrite]] [--print-xml]
4917
4918       Create  and  start  a  pool  object  name  from the raw parameters.  If
4919       --print-xml is specified, then print the XML of the pool object without
4920       creating  the  pool.   Otherwise, the pool has the specified type. When
4921       using pool-create-as for a pool of type "disk", the existing partitions
4922       found  on the --source-dev path will be used to populate the disk pool.
4923       Therefore, it is suggested to use pool-define-as  and  pool-build  with
4924       the --overwrite in order to properly initialize the disk pool.
4925
4926       [--source-host  hostname] provides the source hostname for pools backed
4927       by storage from a remote server (pool types netfs, iscsi,  rbd,  sheep‐
4928       dog, gluster).
4929
4930       [--source-path  path]  provides  the  source  directory  path for pools
4931       backed by directories (pool type dir).
4932
4933       [--source-dev path] provides the source path for pools backed by physi‐
4934       cal devices (pool types fs, logical, disk, iscsi, zfs).
4935
4936       [--source-name name] provides the source name for pools backed by stor‐
4937       age from a named element (pool types logical, rbd, sheepdog, gluster).
4938
4939       [--target path] is the path for the mapping of the  storage  pool  into
4940       the host file system.
4941
4942       [--source-format  format]  provides information about the format of the
4943       pool (pool types fs, netfs, disk, logical).
4944
4945       [--source-initiator initiator-iqn] provides the initiator iqn for iscsi
4946       connection of the pool (pool type iscsi-direct).
4947
4948       [--auth-type  authtype --auth-username username [--secret-usage usage |
4949       --secret-uuid uuid]] provides the elements required to generate authen‐
4950       tication  credentials for the storage pool. The authtype is either chap
4951       for iscsi type pools or ceph for rbd type pools. Either the secret  us‐
4952       age or uuid value may be provided, but not both.
4953
4954       [--source-protocol-ver  ver]  provides  the NFS protocol version number
4955       used  to  contact  the  server's  NFS  service  via  nfs  mount  option
4956       'nfsvers=n'. It is expect the ver value is an unsigned integer.
4957
4958       [--adapter-name  name]  defines  the scsi_hostN adapter name to be used
4959       for the scsi_host adapter type pool.
4960
4961       [--adapter-wwnn wwnn --adapter-wwpn  wwpn  [--adapter-parent  parent  |
4962       --adapter-parent-wwnn  parent_wwnn  adapter-parent-wwpn  parent_wwpn  |
4963       --adapter-parent-fabric-wwn parent_fabric_wwn]] defines  the  wwnn  and
4964       wwpn  to be used for the fc_host adapter type pool.  Optionally provide
4965       the parent scsi_hostN node device to be used for  the  vHBA  either  by
4966       parent  name,  parent_wwnn  and parent_wwpn, or parent_fabric_wwn.  The
4967       parent name could change between reboots if  the  hardware  environment
4968       changes,  so  providing the parent_wwnn and parent_wwpn ensure usage of
4969       the same physical HBA even if the scsi_hostN node device changes. Usage
4970       of the parent_fabric_wwn allows a bit more flexibility to choose an HBA
4971       on the same storage fabric in order to define the pool.
4972
4973       [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
4974       creation  in  order to remove the need for a follow-up command to build
4975       the pool. The --overwrite and  --no-overwrite  flags  follow  the  same
4976       rules  as  pool-build.  If just --build is provided, then pool-build is
4977       called with no flags.
4978
4979       For  a  "logical"  pool  only  [--name]  needs  to  be  provided.   The
4980       [--source-name]  if  provided must match the Volume Group name.  If not
4981       provided, one will be generated using the  [--name].  If  provided  the
4982       [--target]  is  ignored  and  a  target  source  is generated using the
4983       [--source-name] (or as generated from the [--name]).
4984
4985   pool-define
4986       Syntax:
4987
4988          pool-define file
4989
4990       Define an inactive persistent storage pool or modify an  existing  per‐
4991       sistent one from the XML file.
4992
4993   pool-define-as
4994       Syntax:
4995
4996          pool-define-as name type
4997             [--source-host hostname] [--source-path path] [--source-dev path]
4998             [*--source-name name*] [*--target path*] [*--source-format format*]
4999             [--source-initiator initiator-iqn]
5000             [*--auth-type authtype* *--auth-username username*
5001             [*--secret-usage usage* | *--secret-uuid uuid*]]
5002             [*--source-protocol-ver ver*]
5003             [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*]
5004             [*--adapter-parent parent*]] [*--print-xml*]
5005
5006       Create,  but  do not start, a pool object name from the raw parameters.
5007       If --print-xml is specified, then print the  XML  of  the  pool  object
5008       without defining the pool.  Otherwise, the pool has the specified type.
5009
5010       Use  the  same  arguments  as  pool-create-as,  except for the --build,
5011       --overwrite, and --no-overwrite options.
5012
5013   pool-destroy
5014       Syntax:
5015
5016          pool-destroy pool-or-uuid
5017
5018       Destroy (stop) a given pool object. Libvirt will no longer  manage  the
5019       storage described by the pool object, but the raw data contained in the
5020       pool is not changed, and can be later recovered with pool-create.
5021
5022   pool-delete
5023       Syntax:
5024
5025          pool-delete pool-or-uuid
5026
5027       Destroy the resources used by a given pool object.  This  operation  is
5028       non-recoverable.   The pool object will still exist after this command,
5029       ready for the creation of new storage volumes.
5030
5031   pool-dumpxml
5032       Syntax:
5033
5034          pool-dumpxml [--inactive] pool-or-uuid
5035
5036       Returns the XML information about the pool  object.   --inactive  tells
5037       virsh to dump pool configuration that will be used on next start of the
5038       pool as opposed to the current pool configuration.
5039
5040   pool-edit
5041       Syntax:
5042
5043          pool-edit pool-or-uuid
5044
5045       Edit the XML configuration file for a storage pool.
5046
5047       This is equivalent to:
5048
5049          virsh pool-dumpxml pool > pool.xml
5050          vi pool.xml (or make changes with your other text editor)
5051          virsh pool-define pool.xml
5052
5053       except that it does some error checking.
5054
5055       The editor used can be supplied by the $VISUAL or  $EDITOR  environment
5056       variables, and defaults to vi.
5057
5058   pool-info
5059       Syntax:
5060
5061          pool-info [--bytes] pool-or-uuid
5062
5063       Returns  basic  information about the pool object. If --bytes is speci‐
5064       fied the sizes of basic info are not converted to human friendly units.
5065
5066   pool-list
5067       Syntax:
5068
5069          pool-list [--inactive] [--all]
5070             [--persistent] [--transient]
5071             [--autostart] [--no-autostart]
5072             [[--details] [--uuid]
5073             [--name] [<type>]
5074
5075       List pool objects known to libvirt.  By default, only active pools  are
5076       listed;  --inactive  lists just the inactive pools, and --all lists all
5077       pools.
5078
5079       In addition, there are several sets of filtering flags. --persistent is
5080       to  list  the  persistent  pools,  --transient is to list the transient
5081       pools.  --autostart lists the autostarting pools, --no-autostart  lists
5082       the  pools  with  autostarting  disabled.  If  --uuid is specified only
5083       pool's UUIDs are printed.  If --name is specified only pool's names are
5084       printed. If both --name and --uuid are specified, pool's UUID and names
5085       are printed side by side without any header. Option --details is  mutu‐
5086       ally exclusive with options --uuid and --name.
5087
5088       You  may  also  want to list pools with specified types using type, the
5089       pool types must be separated by comma, e.g. --type dir,disk. The  valid
5090       pool  types  include  'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi',
5091       'scsi', 'mpath', 'rbd', 'sheepdog', 'gluster',  'zfs',  'vstorage'  and
5092       'iscsi-direct'.
5093
5094       The  --details option instructs virsh to additionally display pool per‐
5095       sistence and capacity related information where available.
5096
5097       NOTE: When talking to older servers, this command is forced  to  use  a
5098       series  of  API  calls with an inherent race, where a pool might not be
5099       listed or might appear more than once if it changed state between calls
5100       while  the  list  was  being collected.  Newer servers do not have this
5101       problem.
5102
5103   pool-name
5104       Syntax:
5105
5106          pool-name uuid
5107
5108       Convert the uuid to a pool name.
5109
5110   pool-refresh
5111       Syntax:
5112
5113          pool-refresh pool-or-uuid
5114
5115       Refresh the list of volumes contained in pool.
5116
5117   pool-start
5118       Syntax:
5119
5120          pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]
5121
5122       Start the storage pool, which is previously defined but inactive.
5123
5124       [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build prior
5125       to  pool-start  to  ensure the pool environment is in an expected state
5126       rather than needing to run the build  command  prior  to  startup.  The
5127       --overwrite   and   --no-overwrite  flags  follow  the  same  rules  as
5128       pool-build. If just --build is provided, then pool-build is called with
5129       no flags.
5130
5131       Note: A storage pool that relies on remote resources such as an "iscsi"
5132       or a (v)HBA backed "scsi" pool may need to be refreshed multiple  times
5133       in  order to have all the volumes detected (see pool-refresh).  This is
5134       because the corresponding volume devices may  not  be  present  in  the
5135       host's  filesystem  during  the initial pool startup or the current re‐
5136       fresh attempt. The number of refresh retries is dependent upon the net‐
5137       work connection and the time the host takes to export the corresponding
5138       devices.
5139
5140   pool-undefine
5141       Syntax:
5142
5143          pool-undefine pool-or-uuid
5144
5145       Undefine the configuration for an inactive pool.
5146
5147   pool-uuid
5148       Syntax:
5149
5150          pool-uuid pool
5151
5152       Returns the UUID of the named pool.
5153
5154   pool-event
5155       Syntax:
5156
5157          pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list}
5158
5159       Wait for a class of storage pool events to occur, and print appropriate
5160       details  of  events  as they happen.  The events can optionally be fil‐
5161       tered by pool.  Using --list as the only argument will provide  a  list
5162       of  possible event values known by this client, although the connection
5163       might not allow registering for all these events.
5164
5165       By default, this command is one-shot, and returns success once an event
5166       occurs;  you  can send SIGINT (usually via Ctrl-C) to quit immediately.
5167       If --timeout is specified, the command gives up waiting for events  af‐
5168       ter  seconds have elapsed.   With --loop, the command prints all events
5169       until a timeout or interrupt key.
5170
5171       When --timestamp is used, a human-readable timestamp  will  be  printed
5172       before the event.
5173

VOLUME COMMANDS

5175   vol-create
5176       Syntax:
5177
5178          vol-create pool-or-uuid FILE [--prealloc-metadata]
5179
5180       Create a volume from an XML <file>.
5181
5182       pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5183       ume in.
5184
5185       FILE is the XML <file> with the volume definition. An easy way to  cre‐
5186       ate the XML <file> is to use the vol-dumpxml command to obtain the def‐
5187       inition of a pre-existing volume.
5188
5189       [--prealloc-metadata] preallocate  metadata  (for  qcow2  images  which
5190       don't support full allocation). This option creates a sparse image file
5191       with metadata, resulting in higher performance compared to images  with
5192       no preallocation and only slightly higher initial disk space usage.
5193
5194       Example:
5195
5196          virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
5197          vi newvolume.xml (or make changes with your other text editor)
5198          virsh vol-create differentstoragepool newvolume.xml
5199
5200   vol-create-from
5201       Syntax:
5202
5203          vol-create-from pool-or-uuid FILE vol-name-or-key-or-path
5204             [--inputpool pool-or-uuid]  [--prealloc-metadata] [--reflink]
5205
5206       Create a volume, using another volume as input.
5207
5208       pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5209       ume in.
5210
5211       FILE is the XML <file> with the volume definition.
5212
5213       vol-name-or-key-or-path is the name or key or path of the  source  vol‐
5214       ume.
5215
5216       --inputpool  pool-or-uuid  is  the name or uuid of the storage pool the
5217       source volume is in.
5218
5219       [--prealloc-metadata] preallocate  metadata  (for  qcow2  images  which
5220       don't support full allocation). This option creates a sparse image file
5221       with metadata, resulting in higher performance compared to images  with
5222       no preallocation and only slightly higher initial disk space usage.
5223
5224       When  --reflink is specified, perform a COW lightweight copy, where the
5225       data blocks are copied only when modified.  If this  is  not  possible,
5226       the copy fails.
5227
5228   vol-create-as
5229       Syntax:
5230
5231          vol-create-as pool-or-uuid name capacity [--allocation size] [--format string]
5232             [--backing-vol vol-name-or-key-or-path]
5233             [--backing-vol-format string] [--prealloc-metadata] [--print-xml]
5234
5235       Create  a  volume  from a set of arguments unless --print-xml is speci‐
5236       fied, in which case just the XML of the volume object  is  printed  out
5237       without any actual object creation.
5238
5239       pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5240       ume in.
5241
5242       name is the name of the new volume. For a disk pool,  this  must  match
5243       the partition name as determined from the pool's source device path and
5244       the next available partition. For example,  a  source  device  path  of
5245       /dev/sdb and there are no partitions on the disk, then the name must be
5246       sdb1 with the next name being sdb2 and so on.
5247
5248       capacity is the size of the volume to be created, as a  scaled  integer
5249       (see NOTES above), defaulting to bytes if there is no suffix.
5250
5251       --allocation  size  is  the initial size to be allocated in the volume,
5252       also as a scaled integer defaulting to bytes.
5253
5254       --format string is used in file based storage pools to specify the vol‐
5255       ume  file  format  to  use; raw, bochs, qcow, qcow2, vmdk, qed. Use ex‐
5256       tended for disk storage pools in order to create an extended  partition
5257       (other  values  are validity checked but not preserved when libvirtd is
5258       restarted or the pool is refreshed).
5259
5260       --backing-vol vol-name-or-key-or-path is the source backing  volume  to
5261       be used if taking a snapshot of an existing volume.
5262
5263       --backing-vol-format  string is the format of the snapshot backing vol‐
5264       ume; raw, bochs, qcow, qcow2, qed, vmdk, host_device. These  are,  how‐
5265       ever, meant for file based storage pools.
5266
5267       [--prealloc-metadata]  preallocate  metadata  (for  qcow2  images which
5268       don't support full allocation). This option creates a sparse image file
5269       with  metadata, resulting in higher performance compared to images with
5270       no preallocation and only slightly higher initial disk space usage.
5271
5272   vol-clone
5273       Syntax:
5274
5275          vol-clone vol-name-or-key-or-path name
5276             [--pool pool-or-uuid] [--prealloc-metadata] [--reflink]
5277
5278       Clone an existing volume within the parent pool.   Less  powerful,  but
5279       easier to type, version of vol-create-from.
5280
5281       vol-name-or-key-or-path  is  the name or key or path of the source vol‐
5282       ume.
5283
5284       name is the name of the new volume.
5285
5286       --pool pool-or-uuid is the name or UUID of the storage pool  that  con‐
5287       tains the source volume and will contain the new volume.  If the source
5288       volume name is provided instead of the key or path, then providing  the
5289       pool is necessary to find the volume to be cloned; otherwise, the first
5290       volume found by the key or path will be used.
5291
5292       [--prealloc-metadata] preallocate  metadata  (for  qcow2  images  which
5293       don't support full allocation). This option creates a sparse image file
5294       with metadata, resulting in higher performance compared to images  with
5295       no preallocation and only slightly higher initial disk space usage.
5296
5297       When  --reflink is specified, perform a COW lightweight copy, where the
5298       data blocks are copied only when modified.  If this  is  not  possible,
5299       the copy fails.
5300
5301   vol-delete
5302       Syntax:
5303
5304          vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots]
5305
5306       Delete a given volume.
5307
5308       vol-name-or-key-or-path is the volume name or key or path of the volume
5309       to delete.
5310
5311       [--pool pool-or-uuid] is the name or UUID of the storage pool the  vol‐
5312       ume  is  in. If the volume name is provided instead of the key or path,
5313       then providing the pool is necessary to find the volume to be  deleted;
5314       otherwise, the first volume found by the key or path will be used.
5315
5316       The  --delete-snapshots  flag  specifies  that any snapshots associated
5317       with the storage volume should be deleted  as  well.  Not  all  storage
5318       drivers support this option, presently only rbd.
5319
5320   vol-upload
5321       Syntax:
5322
5323          vol-upload vol-name-or-key-or-path local-file
5324             [--pool pool-or-uuid] [--offset bytes]
5325             [--length bytes] [--sparse]
5326
5327       Upload the contents of local-file to a storage volume.
5328
5329       vol-name-or-key-or-path  is the name or key or path of the volume where
5330       the local-file will be uploaded.
5331
5332       --pool pool-or-uuid is the name or UUID of the storage pool the  volume
5333       is  in. If the volume name is provided instead of the key or path, then
5334       providing the pool is necessary to find the volume to be uploaded into;
5335       otherwise, the first volume found by the key or path will be used.
5336
5337       --offset  is the position in the storage volume at which to start writ‐
5338       ing the data. The value must be 0 or larger.
5339
5340       --length is an upper bound of the amount of data  to  be  uploaded.   A
5341       negative  value is interpreted as an unsigned long long value to essen‐
5342       tially include everything from the offset to the end of the volume.
5343
5344       If --sparse is specified, this command will preserve volume sparseness.
5345
5346       An error will occur if the local-file is  greater  than  the  specified
5347       length.
5348
5349       See the description for the libvirt virStorageVolUpload API for details
5350       regarding possible target volume and pool changes as a  result  of  the
5351       pool refresh when the upload is attempted.
5352
5353   vol-download
5354       Syntax:
5355
5356          vol-download vol-name-or-key-or-path local-file
5357             [--pool pool-or-uuid] [--offset bytes] [--length bytes]
5358             [--sparse]
5359
5360       Download the contents of a storage volume to local-file.
5361
5362       vol-name-or-key-or-path  is  the  name  or key or path of the volume to
5363       download into local-file.
5364
5365       --pool pool-or-uuid is the name or UUID of the storage pool the  volume
5366       is  in. If the volume name is provided instead of the key or path, then
5367       providing the pool is necessary to find the volume to be uploaded into;
5368       otherwise, the first volume found by the key or path will be used.
5369
5370       --offset  is the position in the storage volume at which to start read‐
5371       ing the data. The value must be 0 or larger.
5372
5373       --length is an upper bound of the amount of data to be  downloaded.   A
5374       negative  value is interpreted as an unsigned long long value to essen‐
5375       tially include everything from the offset to the end of the volume.
5376
5377       If --sparse is specified, this command will preserve volume sparseness.
5378
5379   vol-wipe
5380       Syntax:
5381
5382          vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm]
5383
5384       Wipe a volume, ensure data previously on the volume is  not  accessible
5385       to future reads.
5386
5387       vol-name-or-key-or-path  is  the  name  or key or path of the volume to
5388       wipe.  It is possible to choose different wiping algorithms instead  of
5389       re-writing volume with zeroes.
5390
5391       --pool  pool-or-uuid is the name or UUID of the storage pool the volume
5392       is in. If the volume name is provided instead of the key or path,  then
5393       providing  the pool is necessary to find the volume to be wiped; other‐
5394       wise, the first volume found by the key or path will be used.
5395
5396       Use the --algorithm switch choosing from the list of the following  al‐
5397       gorithms in order to define which algorithm to use for the wipe.
5398
5399       Supported algorithms
5400
5401       • zero       - 1-pass all zeroes
5402
5403       • nnsa        -  4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for sani‐
5404         tizing removable and non-removable hard disks: random x2, 0x00,  ver‐
5405         ify.
5406
5407       • dod         -  4-pass DoD 5220.22-M section 8-306 procedure for sani‐
5408         tizing removable and non-removable rigid disks: random,  0x00,  0xff,
5409         verify.
5410
5411       • bsi         - 9-pass method recommended by the German Center of Secu‐
5412         rity in  Information  Technologies  (https://www.bsi.bund.de):  0xff,
5413         0xfe, 0xfd, 0xfb, 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
5414
5415       • gutmann     -  The  canonical 35-pass sequence described in Gutmann's
5416         paper.
5417
5418       • schneier   - 7-pass method described by Bruce  Schneier  in  "Applied
5419         Cryptography" (1996): 0x00, 0xff, random x5.
5420
5421       • pfitzner7  - Roy Pfitzner's 7-random-pass method: random x7.
5422
5423       • pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
5424
5425       • random     - 1-pass pattern: random.
5426
5427       • trim       - 1-pass trimming the volume using TRIM or DISCARD
5428
5429       Note: The scrub binary will be used to handle the 'nnsa', 'dod', 'bsi',
5430       'gutmann', 'schneier', 'pfitzner7' and  'pfitzner33'  algorithms.   The
5431       availability  of  the  algorithms  may be limited by the version of the
5432       scrub binary installed on the host. The 'zero' algorithm will write ze‐
5433       roes to the entire volume. For some volumes, such as sparse or rbd vol‐
5434       umes, this may result in completely filling the volume with zeroes mak‐
5435       ing  it appear to be completely full. As an alternative, the 'trim' al‐
5436       gorithm does not overwrite all the data in a volume, rather it  expects
5437       the  storage  driver to be able to discard all bytes in a volume. It is
5438       up to the storage driver to handle how the discarding occurs.  Not  all
5439       storage drivers or volume types can support 'trim'.
5440
5441   vol-dumpxml
5442       Syntax:
5443
5444          vol-dumpxml vol-name-or-key-or-path [--pool pool-or-uuid]
5445
5446       Output the volume information as an XML dump to stdout.
5447
5448       vol-name-or-key-or-path  is  the  name  or key or path of the volume to
5449       output the XML.
5450
5451       --pool pool-or-uuid is the name or UUID of the storage pool the  volume
5452       is  in. If the volume name is provided instead of the key or path, then
5453       providing the pool is necessary to find the volume to be uploaded into;
5454       otherwise, the first volume found by the key or path will be used.
5455
5456   vol-info
5457       Syntax:
5458
5459          vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical]
5460
5461       Returns basic information about the given storage volume.
5462
5463       vol-name-or-key-or-path is the name or key or path of the volume to re‐
5464       turn information for.
5465
5466       --pool pool-or-uuid is the name or UUID of the storage pool the  volume
5467       is  in. If the volume name is provided instead of the key or path, then
5468       providing the pool is necessary to find the volume to be uploaded into;
5469       otherwise, the first volume found by the key or path will be used.
5470
5471       If  --bytes  is specified the sizes are not converted to human friendly
5472       units.
5473
5474       If --physical is specified, then the host physical size is returned and
5475       displayed  instead of the allocation value. The physical value for some
5476       file types, such as qcow2 may have a different (larger) physical  value
5477       than  is shown for allocation. Additionally sparse files will have dif‐
5478       ferent physical and allocation values.
5479
5480   vol-list
5481       Syntax:
5482
5483          vol-list [--pool pool-or-uuid] [--details]
5484
5485       Return the list of volumes in the given storage pool.
5486
5487       --pool pool-or-uuid is the name or UUID of the storage pool.
5488
5489       The --details option instructs virsh  to  additionally  display  volume
5490       type and capacity related information where available.
5491
5492   vol-pool
5493       Syntax:
5494
5495          vol-pool vol-key-or-path [--uuid]
5496
5497       Return  the  pool name or UUID for a given volume. By default, the pool
5498       name is returned.
5499
5500       vol-key-or-path is the key or path of the volume to return the pool in‐
5501       formation.
5502
5503       If the --uuid option is given, the pool UUID is returned instead.
5504
5505   vol-path
5506       Syntax:
5507
5508          vol-path vol-name-or-key [--pool pool-or-uuid]
5509
5510       Return the path for a given volume.
5511
5512       vol-name-or-key is the name or key of the volume to return the path.
5513
5514       --pool  pool-or-uuid is the name or UUID of the storage pool the volume
5515       is in. If the volume name is provided instead of the key, then  provid‐
5516       ing  the pool is necessary to find the volume to be uploaded into; oth‐
5517       erwise, the first volume found by the key will be used.
5518
5519   vol-name
5520       Syntax:
5521
5522          vol-name vol-key-or-path
5523
5524       Return the name for a given volume.
5525
5526       vol-key-or-path is the key or path of the volume to return the name.
5527
5528   vol-key
5529       Syntax:
5530
5531          vol-key vol-name-or-path [--pool pool-or-uuid]
5532
5533       Return the volume key for a given volume.
5534
5535       vol-name-or-path is the name or path of the volume to return the volume
5536       key.
5537
5538       --pool  pool-or-uuid is the name or UUID of the storage pool the volume
5539       is in. If the volume name is provided instead of the path, then provid‐
5540       ing  the pool is necessary to find the volume to be uploaded into; oth‐
5541       erwise, the first volume found by the path will be used.
5542
5543   vol-resize
5544       Syntax:
5545
5546          vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink]
5547
5548       Resize the capacity of the given volume, in bytes.
5549
5550       vol-name-or-key-or-path is the name or key or path of the volume to re‐
5551       size.
5552
5553       capacity  is  a  scaled integer (see NOTES above) for the volume, which
5554       defaults to bytes if there is no suffix.
5555
5556       --pool pool-or-uuid is the name or UUID of the storage pool the  volume
5557       is  in. If the volume name is provided instead of the key or path, then
5558       providing the pool is necessary to find the volume to be uploaded into;
5559       otherwise, the first volume found by the key or path will be used.
5560
5561       The new capacity might be sparse unless --allocate is specified.
5562
5563       Normally,  capacity is the new size, but if --delta is present, then it
5564       is added to the existing size.
5565
5566       Attempts to shrink the volume will fail  unless  --shrink  is  present.
5567       The capacity cannot be negative unless --shrink is provided, but a neg‐
5568       ative sign is not necessary.
5569
5570       This command is only safe for storage volumes not in use by  an  active
5571       guest; see also blockresize for live resizing.
5572

SECRET COMMANDS

5574       The   following   commands   manipulate   "secrets"   (e.g.  passwords,
5575       passphrases and encryption keys).  Libvirt can store  secrets  indepen‐
5576       dently  from their use, and other objects (e.g. volumes or domains) can
5577       refer to the secrets for encryption or possibly  other  uses.   Secrets
5578       are identified using a UUID.  See https://libvirt.org/formatsecret.html
5579       for documentation of the XML format used to represent properties of se‐
5580       crets.
5581
5582   secret-define
5583       Syntax:
5584
5585          secret-define file
5586
5587       Create  a secret with the properties specified in file, with no associ‐
5588       ated secret value.  If file does not specify a UUID, choose  one  auto‐
5589       matically.  If file specifies a UUID of an existing secret, replace its
5590       properties by properties defined in file, without affecting the  secret
5591       value.
5592
5593   secret-dumpxml
5594       Syntax:
5595
5596          secret-dumpxml secret
5597
5598       Output  properties  of secret (specified by its UUID) as an XML dump to
5599       stdout.
5600
5601   secret-event
5602       Syntax:
5603
5604          secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list}
5605
5606       Wait for a class of secret events to occur, and print  appropriate  de‐
5607       tails  of events as they happen.  The events can optionally be filtered
5608       by secret.  Using --list as the only argument will provide  a  list  of
5609       possible  event  values  known  by this client, although the connection
5610       might not allow registering for all these events.
5611
5612       By default, this command is one-shot, and returns success once an event
5613       occurs;  you  can send SIGINT (usually via Ctrl-C) to quit immediately.
5614       If --timeout is specified, the command gives up waiting for events  af‐
5615       ter  seconds have elapsed.   With --loop, the command prints all events
5616       until a timeout or interrupt key.
5617
5618       When --timestamp is used, a human-readable timestamp  will  be  printed
5619       before the event.
5620
5621   secret-set-value
5622       Syntax:
5623
5624          secret-set-value secret (--file filename [--plain] | --interactive | base64)
5625
5626       Set  the  value  associated  with secret (specified by its UUID) to the
5627       value Base64-encoded value base64 or Base-64-encoded contents  of  file
5628       named  filename.  Using the --plain flag is together with --file allows
5629       one to use the file contents directly as the secret value.
5630
5631       If --interactive flag is used the secret value is read  as  a  password
5632       from the terminal.
5633
5634       Note  that --file, --interactive and base64 options are mutually exclu‐
5635       sive.
5636
5637       Passing secrets via the base64 option on command line is  INSECURE  and
5638       deprecated. Use the --file option instead.
5639
5640   secret-get-value
5641       Syntax:
5642
5643          secret-get-value [--plain] secret
5644
5645       Output the value associated with secret (specified by its UUID) to std‐
5646       out, encoded using Base64.
5647
5648       If the --plain flag is used the value is not base64 encoded, but rather
5649       printed raw. Note that unless virsh is started in quiet mode (virsh -q)
5650       it prints a newline at the end of the command. This newline is not part
5651       of the secret.
5652
5653   secret-undefine
5654       Syntax:
5655
5656          secret-undefine secret
5657
5658       Delete  a  secret  (specified  by  its  UUID), including the associated
5659       value, if any.
5660
5661   secret-list
5662       Syntax:
5663
5664          secret-list [--ephemeral] [--no-ephemeral]
5665             [--private] [--no-private]
5666
5667       Returns the list of secrets. You may also want to filter  the  returned
5668       secrets  by  --ephemeral  to list the ephemeral ones, --no-ephemeral to
5669       list the non-ephemeral ones, --private to list the  private  ones,  and
5670       --no-private to list the non-private ones.
5671

SNAPSHOT COMMANDS

5673       The following commands manipulate domain snapshots.  Snapshots take the
5674       disk, memory, and device state of a domain at a point-of-time, and save
5675       it  for future use.  They have many uses, from saving a "clean" copy of
5676       an OS image to saving a domain's state before a potentially destructive
5677       operation.    Snapshots   are  identified  with  a  unique  name.   See
5678       https://libvirt.org/formatsnapshot.html for documentation  of  the  XML
5679       format used to represent properties of snapshots.
5680
5681   snapshot-create
5682       Syntax:
5683
5684          snapshot-create domain [xmlfile] {[--redefine [--current]] |
5685             [--no-metadata] [--halt] [--disk-only] [--reuse-external]
5686             [--quiesce] [--atomic] [--live]} [--validate]
5687
5688       Create  a  snapshot  for domain domain with the properties specified in
5689       xmlfile.   Optionally, the --validate option can be passed to  validate
5690       the  format of the input XML file against an internal RNG schema (iden‐
5691       tical to using the virt-xml-validate(1) tool). Normally, the only prop‐
5692       erties  settable for a domain snapshot are the <name> and <description>
5693       elements, as well as <disks> if --disk-only is given; the rest  of  the
5694       fields are ignored, and automatically filled in by libvirt.  If xmlfile
5695       is completely omitted, then libvirt will choose a value for all fields.
5696       The new snapshot will become current, as listed by snapshot-current.
5697
5698       If  --halt  is  specified, the domain will be left in an inactive state
5699       after the snapshot is created.
5700
5701       If --disk-only is specified, the snapshot will only include  disk  con‐
5702       tent  rather  than  the usual full system snapshot with vm state.  Disk
5703       snapshots are captured faster than full system snapshots, but reverting
5704       to  a  disk  snapshot  may require fsck or journal replays, since it is
5705       like the disk state at the  point  when  the  power  cord  is  abruptly
5706       pulled;  and  mixing --halt and --disk-only loses any data that was not
5707       flushed to disk at the time.
5708
5709       If --redefine is specified, then all XML  elements  produced  by  snap‐
5710       shot-dumpxml  are valid; this can be used to migrate snapshot hierarchy
5711       from one machine to another, to recreate hierarchy for the  case  of  a
5712       transient  domain  that  goes away and is later recreated with the same
5713       name and UUID, or to make slight alterations in the  snapshot  metadata
5714       (such  as host-specific aspects of the domain XML embedded in the snap‐
5715       shot).  When this flag is supplied, the xmlfile argument is  mandatory,
5716       and the domain's current snapshot will not be altered unless the --cur‐
5717       rent flag is also given.
5718
5719       If --no-metadata is specified, then the snapshot data is  created,  but
5720       any  metadata is immediately discarded (that is, libvirt does not treat
5721       the snapshot as current, and cannot revert to the snapshot unless --re‐
5722       define is later used to teach libvirt about the metadata again).
5723
5724       If  --reuse-external is specified, and the snapshot XML requests an ex‐
5725       ternal snapshot with a destination of an existing file, then the desti‐
5726       nation  must exist and be pre-created with correct format and metadata.
5727       The file is then reused; otherwise, a snapshot is refused to avoid los‐
5728       ing contents of the existing files.
5729
5730       If  --quiesce  is  specified,  libvirt  will  try to use guest agent to
5731       freeze and unfreeze domain's mounted file systems. However,  if  domain
5732       has  no  guest agent, snapshot creation will fail.  Currently, this re‐
5733       quires --disk-only to be passed as well.
5734
5735       If --atomic is specified, libvirt will guarantee that the snapshot  ei‐
5736       ther  succeeds,  or  fails with no changes; not all hypervisors support
5737       this.  If this flag is not specified, then some  hypervisors  may  fail
5738       after  partially performing the action, and dumpxml must be used to see
5739       whether any partial changes occurred.
5740
5741       If --live is specified, libvirt takes the snapshot while the  guest  is
5742       running.  Both disk snapshot and domain memory snapshot are taken. This
5743       increases the size of the memory image of the external  snapshot.  This
5744       is currently supported only for full system external snapshots.
5745
5746       Existence of snapshot metadata will prevent attempts to undefine a per‐
5747       sistent guest.  However, for transient domains,  snapshot  metadata  is
5748       silently lost when the domain quits running (whether by command such as
5749       destroy or by internal guest action).
5750
5751       For now, it is not possible to create snapshots in a  domain  that  has
5752       checkpoints,  although  this restriction will be lifted in a future re‐
5753       lease.
5754
5755   snapshot-create-as
5756       Syntax:
5757
5758          snapshot-create-as domain {[--print-xml] [--no-metadata]
5759             [--halt] [--reuse-external]} [name]
5760             [description] [--disk-only [--quiesce]] [--atomic] [--validate]
5761             [[--live] [--memspec memspec]] [--diskspec] diskspec]...
5762
5763       Create a snapshot for domain domain with the given <name> and <descrip‐
5764       tion>;  if  either  value  is omitted, libvirt will choose a value.  If
5765       --print-xml is specified, then XML appropriate for  snapshot-create  is
5766       output, rather than actually creating a snapshot.  Otherwise, if --halt
5767       is specified, the domain will be left in an inactive  state  after  the
5768       snapshot is created, and if --disk-only is specified, the snapshot will
5769       not include vm state.
5770
5771       The --memspec option can be used to control whether a full system snap‐
5772       shot  is  internal  or external.  The --memspec flag is mandatory, fol‐
5773       lowed by a memspec of the form [file=]name[,snapshot=type], where  type
5774       can  be  no,  internal,  or  external.   To  include a literal comma in
5775       file=name, escape it with a second comma. --memspec cannot be used  to‐
5776       gether with --disk-only.
5777
5778       The --diskspec option can be used to control how --disk-only and exter‐
5779       nal full system snapshots create external files.  This option can occur
5780       multiple  times,  according to the number of <disk> elements in the do‐
5781       main   xml.    Each   <diskspec>   is   in   the    form    disk[,snap‐
5782       shot=type][,driver=type][,stype=type][,file=name].   A diskspec must be
5783       provided for disks backed by block devices as libvirt doesn't auto-gen‐
5784       erate file names for those.  The optional stype parameter allows one to
5785       control the type of the source file. Supported values are  'file'  (de‐
5786       fault)  and  'block'.  To  exclude a disk from an external snapshot use
5787       --diskspec disk,snapshot=no.
5788
5789       To include a literal comma in disk or in file=name, escape  it  with  a
5790       second  comma.   A literal --diskspec must precede each diskspec unless
5791       all three of domain, name, and description are also present.  For exam‐
5792       ple,  a  diskspec of "vda,snapshot=external,file=/path/to,,new" results
5793       in the following XML:
5794
5795          <disk name='vda' snapshot='external'>
5796            <source file='/path/to,new'/>
5797          </disk>
5798
5799       If --reuse-external is specified, and the domain XML or diskspec option
5800       requests  an  external snapshot with a destination of an existing file,
5801       then the destination must exist and be pre-created with correct  format
5802       and metadata. The file is then reused; otherwise, a snapshot is refused
5803       to avoid losing contents of the existing files.
5804
5805       If --quiesce is specified, libvirt will  try  to  use  guest  agent  to
5806       freeze  and  unfreeze domain's mounted file systems. However, if domain
5807       has no guest agent, snapshot creation will fail.  Currently,  this  re‐
5808       quires --disk-only to be passed as well.
5809
5810       If  --no-metadata  is specified, then the snapshot data is created, but
5811       any metadata is immediately discarded (that is, libvirt does not  treat
5812       the snapshot as current, and cannot revert to the snapshot unless snap‐
5813       shot-create is later used to teach libvirt about the metadata again).
5814
5815       If --atomic is specified, libvirt will guarantee that the snapshot  ei‐
5816       ther  succeeds,  or  fails with no changes; not all hypervisors support
5817       this.  If this flag is not specified, then some  hypervisors  may  fail
5818       after  partially performing the action, and dumpxml must be used to see
5819       whether any partial changes occurred.
5820
5821       If --live is specified, libvirt takes the snapshot while the  guest  is
5822       running.  This  increases  the size of the memory image of the external
5823       snapshot. This is currently supported only  for  external  full  system
5824       snapshots.
5825
5826       For  now,  it  is not possible to create snapshots in a domain that has
5827       checkpoints, although this restriction will be lifted in a  future  re‐
5828       lease.
5829
5830       Optionally,  the  --validate option can be passed to validate XML docu‐
5831       ment which is internally generated by this command against the internal
5832       RNG schema.
5833
5834   snapshot-current
5835       Syntax:
5836
5837          snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
5838
5839       Without  snapshotname,  this  will  output the snapshot XML for the do‐
5840       main's current snapshot (if any).  If --name  is  specified,  just  the
5841       current  snapshot name instead of the full xml.  Otherwise, using --se‐
5842       curity-info will also include security  sensitive  information  in  the
5843       XML.
5844
5845       With  snapshotname,  this is a request to make the existing named snap‐
5846       shot become the current snapshot, without reverting the domain.
5847
5848   snapshot-edit
5849       Syntax:
5850
5851          snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]}
5852
5853       Edit the XML configuration file for snapshotname of a domain.  If  both
5854       snapshotname  and  --current are specified, also force the edited snap‐
5855       shot to become the current snapshot.  If snapshotname is omitted,  then
5856       --current must be supplied, to edit the current snapshot.
5857
5858       This is equivalent to:
5859
5860          virsh snapshot-dumpxml dom name > snapshot.xml
5861          vi snapshot.xml (or make changes with your other text editor)
5862          virsh snapshot-create dom snapshot.xml --redefine [--current]
5863
5864       except that it does some error checking.
5865
5866       The  editor  used can be supplied by the $VISUAL or $EDITOR environment
5867       variables, and defaults to vi.
5868
5869       If --rename is specified, then the edits can change the snapshot  name.
5870       If  --clone is specified, then changing the snapshot name will create a
5871       clone of the snapshot metadata.  If neither is specified, then the  ed‐
5872       its  must  not change the snapshot name.  Note that changing a snapshot
5873       name must be done with care, since the contents of some snapshots, such
5874       as  internal  snapshots within a single qcow2 file, are accessible only
5875       from the original name.
5876
5877   snapshot-info
5878       Syntax:
5879
5880          snapshot-info domain {snapshot | --current}
5881
5882       Output basic information about a named <snapshot>, or the current snap‐
5883       shot with --current.
5884
5885   snapshot-list
5886       Syntax:
5887
5888          snapshot-list domain [--metadata] [--no-metadata]
5889             [{--parent | --roots | [{--tree | --name}]}] [--topological]
5890             [{[--from] snapshot | --current} [--descendants]]
5891             [--leaves] [--no-leaves] [--inactive] [--active]
5892             [--disk-only] [--internal] [--external]
5893
5894       List all of the available snapshots for the given domain, defaulting to
5895       show columns for the snapshot name, creation time, and domain state.
5896
5897       Normally, table form output is sorted by snapshot name;  using  --topo‐
5898       logical  instead  sorts so that no child is listed before its ancestors
5899       (although there may be more than one possible ordering with this  prop‐
5900       erty).
5901
5902       If  --parent  is specified, add a column to the output table giving the
5903       name of the parent of each snapshot.  If --roots is specified, the list
5904       will  be filtered to just snapshots that have no parents.  If --tree is
5905       specified, the output will be in a tree format, listing  just  snapshot
5906       names.  These three options are mutually exclusive. If --name is speci‐
5907       fied only the snapshot name is printed. This option is mutually  exclu‐
5908       sive with --tree.
5909
5910       If  --from is provided, filter the list to snapshots which are children
5911       of the given snapshot; or if --current is provided, start at  the  cur‐
5912       rent  snapshot.   When  used in isolation or with --parent, the list is
5913       limited to direct children unless --descendants is also present.   When
5914       used  with --tree, the use of --descendants is implied.  This option is
5915       not compatible with --roots.  Note that the starting point of --from or
5916       --current  is not included in the list unless the --tree option is also
5917       present.
5918
5919       If --leaves is specified, the list will be filtered to  just  snapshots
5920       that have no children.  Likewise, if --no-leaves is specified, the list
5921       will be filtered to just snapshots with children.  (Note that  omitting
5922       both  options  does no filtering, while providing both options will ei‐
5923       ther produce the same list or error out depending on whether the server
5924       recognizes  the  flags).   Filtering  options  are  not compatible with
5925       --tree.
5926
5927       If --metadata is specified, the list will be filtered to just snapshots
5928       that  involve  libvirt  metadata,  and thus would prevent undefine of a
5929       persistent guest, or be lost on destroy of a transient  domain.   Like‐
5930       wise,  if --no-metadata is specified, the list will be filtered to just
5931       snapshots that exist without the need for libvirt metadata.
5932
5933       If --inactive is specified, the list will be filtered to snapshots that
5934       were taken when the domain was shut off.  If --active is specified, the
5935       list will be filtered to snapshots that were taken when the domain  was
5936       running,  and where the snapshot includes the memory state to revert to
5937       that running state.  If --disk-only is specified, the list will be fil‐
5938       tered  to  snapshots  that  were taken when the domain was running, but
5939       where the snapshot includes only disk state.
5940
5941       If --internal is specified, the list will be filtered to snapshots that
5942       use  internal storage of existing disk images.  If --external is speci‐
5943       fied, the list will be filtered to snapshots that  use  external  files
5944       for disk images or memory state.
5945
5946   snapshot-dumpxml
5947       Syntax:
5948
5949          snapshot-dumpxml domain snapshot [--security-info]
5950
5951       Output  the snapshot XML for the domain's snapshot named snapshot.  Us‐
5952       ing --security-info will also include security  sensitive  information.
5953       Use snapshot-current to easily access the XML of the current snapshot.
5954
5955   snapshot-parent
5956       Syntax:
5957
5958          snapshot-parent domain {snapshot | --current}
5959
5960       Output the name of the parent snapshot, if any, for the given snapshot,
5961       or for the current snapshot with --current.
5962
5963   snapshot-revert
5964       Syntax:
5965
5966          snapshot-revert domain {snapshot | --current} [{--running | --paused}] [--force]
5967
5968       Revert the given domain to the snapshot specified by  snapshot,  or  to
5969       the  current snapshot with --current.  Be aware that this is a destruc‐
5970       tive action; any changes in the domain  since  the  last  snapshot  was
5971       taken will be lost.  Also note that the state of the domain after snap‐
5972       shot-revert is complete will be the state of the domain at the time the
5973       original snapshot was taken.
5974
5975       Normally, reverting to a snapshot leaves the domain in the state it was
5976       at the time the snapshot was created, except that a disk snapshot  with
5977       no vm state leaves the domain in an inactive state.  Passing either the
5978       --running or --paused flag will perform additional state changes  (such
5979       as  booting  an  inactive  domain, or pausing a running domain).  Since
5980       transient domains cannot be inactive, it is  required  to  use  one  of
5981       these flags when reverting to a disk snapshot of a transient domain.
5982
5983       There  are  a  number  of  cases where a snapshot revert involves extra
5984       risk, which requires the use of --force to proceed:
5985
5986          • One is the case of a snapshot that lacks full  domain  information
5987            for  reverting  configuration  (such as snapshots created prior to
5988            libvirt 0.9.5); since libvirt cannot prove that the  current  con‐
5989            figuration  matches  what  was in use at the time of the snapshot,
5990            supplying --force assures libvirt that the snapshot is  compatible
5991            with  the current configuration (and if it is not, the domain will
5992            likely fail to run).
5993
5994          • Another is the case of reverting from a running domain to  an  ac‐
5995            tive  state  where  a new hypervisor has to be created rather than
5996            reusing the existing hypervisor, because it implies drawbacks such
5997            as  breaking any existing VNC or Spice connections; this condition
5998            happens with an active snapshot that uses a provably  incompatible
5999            configuration,  as  well as with an inactive snapshot that is com‐
6000            bined with the --start or --pause flag.
6001
6002          • Also, libvirt will refuse to restore snapshots  of  inactive  QEMU
6003            domains  while there is managed saved state. This is because those
6004            snapshots do not contain memory state and will therefore  not  re‐
6005            place the existing memory state. This ends up switching a disk un‐
6006            derneath a running system and will likely cause extensive filesys‐
6007            tem corruption or crashes due to swap content mismatches when run.
6008
6009   snapshot-delete
6010       Syntax:
6011
6012          snapshot-delete domain {snapshot | --current}
6013             [--metadata] [{--children | --children-only}]
6014
6015       Delete the snapshot for the domain named snapshot, or the current snap‐
6016       shot with --current.  If this snapshot  has  child  snapshots,  changes
6017       from  this snapshot will be merged into the children.  If --children is
6018       passed, then delete this snapshot and any children  of  this  snapshot.
6019       If  --children-only  is  passed, then delete any children of this snap‐
6020       shot, but leave this snapshot intact.  These two flags are mutually ex‐
6021       clusive.
6022
6023       If  --metadata  is  specified,  then  only delete the snapshot metadata
6024       maintained by libvirt, while leaving the snapshot contents  intact  for
6025       access  by  external  tools; otherwise deleting a snapshot also removes
6026       the data contents from that point in time.
6027

CHECKPOINT COMMANDS

6029       The following  commands  manipulate  domain  checkpoints.   Checkpoints
6030       serve  as a point in time to identify which portions of a guest's disks
6031       have changed after that time, making it possible to perform incremental
6032       and  differential  backups.   Checkpoints  are identified with a unique
6033       name.  See https://libvirt.org/formatcheckpoint.html for  documentation
6034       of the XML format used to represent properties of checkpoints.
6035
6036   checkpoint-create
6037       Syntax:
6038
6039          checkpoint-create domain [xmlfile] { --redefine [--redefine-validate] | [--quiesce]}
6040
6041       Create  a checkpoint for domain domain with the properties specified in
6042       xmlfile describing a <domaincheckpoint> top-level element.  The  format
6043       of  the input XML file will be validated against an internal RNG schema
6044       (identical to using the virt-xml-validate(1) tool). If xmlfile is  com‐
6045       pletely  omitted,  then  libvirt  will  create a checkpoint with a name
6046       based on the current time.
6047
6048       If --redefine is specified, then all XML elements  produced  by  check‐
6049       point-dumpxml are valid; this can be used to migrate checkpoint hierar‐
6050       chy from one machine to another, to recreate hierarchy for the case  of
6051       a  transient domain that goes away and is later recreated with the same
6052       name and UUID, or to make slight alterations in the checkpoint metadata
6053       (such as host-specific aspects of the domain XML embedded in the check‐
6054       point).  When this flag is supplied, the xmlfile argument is mandatory.
6055
6056       If --redefine-validate is specified along with --redefine the  hypervi‐
6057       sor  performs  validation  of  metadata  associated with the checkpoint
6058       stored in places besides the checkpoint XML. Note that some hypervisors
6059       may require that the domain is running to perform validation.
6060
6061       If  --quiesce  is  specified,  libvirt  will  try to use guest agent to
6062       freeze and unfreeze domain's mounted file systems. However,  if  domain
6063       has no guest agent, checkpoint creation will fail.
6064
6065       Existence  of  checkpoint  metadata will prevent attempts to undefine a
6066       persistent guest.  However, for transient domains, checkpoint  metadata
6067       is silently lost when the domain quits running (whether by command such
6068       as destroy or by internal guest action).
6069
6070       For now, it is not possible to create checkpoints in a domain that  has
6071       snapshots,  although  this  restriction  will be lifted in a future re‐
6072       lease.
6073
6074   checkpoint-create-as
6075       Syntax:
6076
6077          checkpoint-create-as domain [--print-xml] [name]
6078             [description] [--quiesce] [--diskspec] diskspec]...
6079
6080       Create a checkpoint for domain domain with the given  <name>  and  <de‐
6081       scription>;  if  either  value is omitted, libvirt will choose a value.
6082       If --print-xml is specified, then XML appropriate for checkpoint-create
6083       is output, rather than actually creating a checkpoint.
6084
6085       The --diskspec option can be used to control which guest disks partici‐
6086       pate in the checkpoint. This option can occur multiple times, according
6087       to the number of <disk> elements in the domain xml.  Each <diskspec> is
6088       in the form disk[,checkpoint=type][,bitmap=name]. A literal  --diskspec
6089       must  precede  each  diskspec unless all three of domain, name, and de‐
6090       scription are also present.  For example,  a  diskspec  of  "vda,check‐
6091       point=bitmap,bitmap=map1" results in the following XML:
6092
6093          <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
6094
6095       If  --quiesce  is  specified,  libvirt  will  try to use guest agent to
6096       freeze and unfreeze domain's mounted file systems. However,  if  domain
6097       has no guest agent, checkpoint creation will fail.
6098
6099       For  now, it is not possible to create checkpoints in a domain that has
6100       snapshots, although this restriction will be lifted  in  a  future  re‐
6101       lease.
6102
6103   checkpoint-edit
6104       Syntax:
6105
6106          checkpoint-edit domain checkpointname
6107
6108       Edit the XML configuration file for checkpointname of a domain.
6109
6110       This is equivalent to:
6111
6112          virsh checkpoint-dumpxml dom name > checkpoint.xml
6113          vi checkpoint.xml (or make changes with your other text editor)
6114          virsh checkpoint-create dom checkpoint.xml --redefine
6115
6116       except  that  it  does  some  error  checking, including that the edits
6117       should not attempt to change the checkpoint name.
6118
6119       The editor used can be supplied by the $VISUAL or  $EDITOR  environment
6120       variables, and defaults to vi.
6121
6122   checkpoint-info
6123       Syntax:
6124
6125          checkpoint-info domain checkpoint
6126
6127       Output basic information about a named <checkpoint>.
6128
6129   checkpoint-list
6130       Syntax:
6131
6132          checkpoint-list domain [{--parent | --roots |
6133             [{--tree | --name}]}] [--topological]
6134             [[--from] checkpoint | [--descendants]]
6135             [--leaves] [--no-leaves]
6136
6137       List  all of the available checkpoints for the given domain, defaulting
6138       to show columns for the checkpoint name and creation time.
6139
6140       Normally, table form output is sorted by checkpoint name; using --topo‐
6141       logical  instead  sorts so that no child is listed before its ancestors
6142       (although there may be more than one possible ordering with this  prop‐
6143       erty).
6144
6145       If  --parent  is specified, add a column to the output table giving the
6146       name of the parent of each checkpoint.  If --roots  is  specified,  the
6147       list  will  be  filtered  to just checkpoints that have no parents.  If
6148       --tree is specified, the output will be in a tree format, listing  just
6149       checkpoint  names.   These  three  options  are  mutually exclusive. If
6150       --name is specified only the checkpoint name is printed. This option is
6151       mutually exclusive with --tree.
6152
6153       If  --from  is provided, filter the list to checkpoints which are chil‐
6154       dren of the given checkpoint.  When used in isolation or with --parent,
6155       the  list  is  limited  to direct children unless --descendants is also
6156       present.  When used with --tree, the use of --descendants  is  implied.
6157       This  option  is  not  compatible with --roots.  Note that the starting
6158       point of --from is not included in the list unless the --tree option is
6159       also present.
6160
6161       If --leaves is specified, the list will be filtered to just checkpoints
6162       that have no children.  Likewise, if --no-leaves is specified, the list
6163       will  be  filtered to just checkpoints with children.  (Note that omit‐
6164       ting both options does no filtering, while providing both options  will
6165       either  produce  the  same  list  or error out depending on whether the
6166       server recognizes the flags).  Filtering  options  are  not  compatible
6167       with --tree.
6168
6169   checkpoint-dumpxml
6170       Syntax:
6171
6172          checkpoint-dumpxml domain checkpoint [--security-info] [--no-domain] [--size]
6173
6174       Output the checkpoint XML for the domain's checkpoint named checkpoint.
6175       Using --security-info will also include security sensitive information.
6176
6177       Using --size will add XML indicating the current size in bytes of guest
6178       data that has changed since the checkpoint was created (although remem‐
6179       ber that guest activity between a size check and  actually  creating  a
6180       backup can result in the backup needing slightly more space). Note that
6181       some hypervisors may require that domain  is  running  when  --size  is
6182       used.
6183
6184       Using  --no-domain will omit the <domain> element from the output for a
6185       more compact view.
6186
6187   checkpoint-parent
6188       Syntax:
6189
6190          checkpoint-parent domain checkpoint
6191
6192       Output the name of the parent checkpoint, if any, for the given  check‐
6193       point.
6194
6195   checkpoint-delete
6196       Syntax:
6197
6198          checkpoint-delete domain checkpoint
6199             [--metadata] [{--children | --children-only}]
6200
6201       Delete  the  checkpoint for the domain named checkpoint.  The record of
6202       which portions of the disk changed since the checkpoint are merged into
6203       the  parent  checkpoint  (if any). If --children is passed, then delete
6204       this checkpoint and  any  children  of  this  checkpoint.   If  --chil‐
6205       dren-only  is  passed, then delete any children of this checkpoint, but
6206       leave this checkpoint intact. These two flags are mutually exclusive.
6207
6208       If --metadata is specified, then only delete  the  checkpoint  metadata
6209       maintained by libvirt, while leaving the checkpoint contents intact for
6210       access by external tools; otherwise deleting a checkpoint also  removes
6211       the ability to perform an incremental backup from that point in time.
6212

NWFILTER COMMANDS

6214       The  following commands manipulate network filters. Network filters al‐
6215       low filtering of the network traffic coming from and going  to  virtual
6216       machines.   Individual  network  traffic filters are written in XML and
6217       may contain references to other network filters, describe traffic  fil‐
6218       tering  rules,  or contain both. Network filters are referenced by vir‐
6219       tual machines from within their interface description. A network filter
6220       may be referenced by multiple virtual machines' interfaces.
6221
6222   nwfilter-define
6223       Syntax:
6224
6225          nwfilter-define xmlfile
6226
6227       Make  a  new  network filter known to libvirt. If a network filter with
6228       the same name already exists, it will be replaced  with  the  new  XML.
6229       Any  running  virtual machine referencing this network filter will have
6230       its network traffic rules adapted. If for any reason the network  traf‐
6231       fic  filtering  rules cannot be instantiated by any of the running vir‐
6232       tual machines, then the new XML will be rejected.
6233
6234   nwfilter-undefine
6235       Syntax:
6236
6237          nwfilter-undefine nwfilter-name
6238
6239       Delete a network filter. The deletion will fail if any running  virtual
6240       machine is currently using this network filter.
6241
6242   nwfilter-list
6243       Syntax:
6244
6245          nwfilter-list
6246
6247       List all of the available network filters.
6248
6249   nwfilter-dumpxml
6250       Syntax:
6251
6252          nwfilter-dumpxml nwfilter-name
6253
6254       Output the network filter XML.
6255
6256   nwfilter-edit
6257       Syntax:
6258
6259          nwfilter-edit nwfilter-name
6260
6261       Edit the XML of a network filter.
6262
6263       This is equivalent to:
6264
6265          virsh nwfilter-dumpxml myfilter > myfilter.xml
6266          vi myfilter.xml (or make changes with your other text editor)
6267          virsh nwfilter-define myfilter.xml
6268
6269       except that it does some error checking.  The new network filter may be
6270       rejected due to the same reason as mentioned in nwfilter-define.
6271
6272       The editor used can be supplied by the $VISUAL or  $EDITOR  environment
6273       variables, and defaults to vi.
6274

NWFILTER BINDING COMMANDS

6276       The following commands manipulate network filter bindings. Network fil‐
6277       ter bindings track the association between a network port and a network
6278       filter.  Generally the bindings are managed automatically by the hyper‐
6279       visor drivers when adding/removing NICs on a guest.
6280
6281       If an admin is creating/deleting TAP devices for non-guest usage,  how‐
6282       ever,  the network filter binding commands provide a way to make use of
6283       the network filters directly.
6284
6285   nwfilter-binding-create
6286       Syntax:
6287
6288          nwfilter-binding-create xmlfile
6289
6290       Associate a network port with a  network  filter.  The  network  filter
6291       backend will immediately attempt to instantiate the filter rules on the
6292       port. This command may be used to associate a filter with  a  currently
6293       running  guest  that does not have a filter defined for a specific net‐
6294       work port. Since the bindings are generally  automatically  managed  by
6295       the  hypervisor,  using  this  command to define a filter for a network
6296       port and then starting the guest afterwards may prevent the guest  from
6297       starting  if it attempts to use the network port and finds a filter al‐
6298       ready defined.
6299
6300   nwfilter-binding-delete
6301       Syntax:
6302
6303          nwfilter-binding-delete port-name
6304
6305       Disassociate a network port from a network filter. The  network  filter
6306       backend  will  immediately tear down the filter rules that exist on the
6307       port. This command may be used to remove the network port binding for a
6308       filter  currently in use for the guest while the guest is running with‐
6309       out needing to restart the guest. Restoring the  network  port  binding
6310       filter  for  the  running  guest  would be accomplished by using nwfil‐
6311       ter-binding-create.
6312
6313   nwfilter-binding-list
6314       Syntax:
6315
6316          nwfilter-binding-list
6317
6318       List all of the network ports which have filters associated with them.
6319
6320   nwfilter-binding-dumpxml
6321       Syntax:
6322
6323          nwfilter-binding-dumpxml port-name
6324
6325       Output the network filter binding XML for  the  network  device  called
6326       port-name.
6327

HYPERVISOR-SPECIFIC COMMANDS

6329       NOTE:  Use of the following commands is strongly discouraged.  They can
6330       cause libvirt to become confused and do the wrong thing  on  subsequent
6331       operations.   Once  you  have used these commands, please do not report
6332       problems to the libvirt developers; the reports will  be  ignored.   If
6333       you  find that these commands are the only way to accomplish something,
6334       then it is better to request that the feature be added as a first-class
6335       citizen in the regular libvirt library.
6336
6337   qemu-attach
6338       Syntax:
6339
6340          qemu-attach pid
6341
6342       Attach  an externally launched QEMU process to the libvirt QEMU driver.
6343       The QEMU process must have been created with a monitor connection using
6344       the UNIX driver. Ideally the process will also have had the '-name' ar‐
6345       gument specified.
6346
6347          $ qemu-kvm -cdrom ~/demo.iso \
6348              -monitor unix:/tmp/demo,server,nowait \
6349              -name foo \
6350              -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea  &
6351          $ QEMUPID=$!
6352          $ virsh qemu-attach $QEMUPID
6353
6354       Not all functions of libvirt are expected to work  reliably  after  at‐
6355       taching  to  an  externally  launched QEMU process. There may be issues
6356       with the guest ABI changing upon migration and device hotplug or hotun‐
6357       plug  may  not work. The attached environment should be considered pri‐
6358       marily read-only.
6359
6360   qemu-monitor-command
6361       Syntax:
6362
6363          qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] } command...
6364
6365       Send an arbitrary monitor command command to domain domain through  the
6366       QEMU monitor.  The results of the command will be printed on stdout.
6367
6368       If  more  than  one argument is provided for command, they are concate‐
6369       nated with a space in between before passing the single command to  the
6370       monitor.
6371
6372       Note that libvirt uses the QMP to talk to qemu so command must be valid
6373       JSON in QMP format to work properly.
6374
6375       If --pretty is given the QMP reply is pretty-printed.
6376
6377       If --return-value is given the 'return' key of the QMP response  object
6378       is extracted rather than passing through the full reply from QEMU.
6379
6380       If  --hmp  is  passed,  the command is considered to be a human monitor
6381       command and libvirt will automatically convert it into QMP and  convert
6382       the result back.
6383
6384   qemu-agent-command
6385       Syntax:
6386
6387          qemu-agent-command domain [--timeout seconds | --async | --block] command...
6388
6389       Send  an arbitrary guest agent command command to domain domain through
6390       QEMU agent.  --timeout, --async  and  --block  options  are  exclusive.
6391       --timeout  requires  timeout  seconds  seconds and it must be positive.
6392       When --aysnc is given, the command waits for timeout whether success or
6393       failed.  And  when  --block  is  given,  the command waits forever with
6394       blocking timeout.
6395
6396   qemu-monitor-event
6397       Syntax:
6398
6399          qemu-monitor-event [domain] [--event event-name]
6400            [--loop] [--timeout seconds] [--pretty] [--regex] [--no-case]
6401            [--timestamp]
6402
6403       Wait for arbitrary QEMU monitor events to occur, and print out the  de‐
6404       tails  of events as they happen.  The events can optionally be filtered
6405       by domain or event-name.  The 'query-events' QMP command  can  be  used
6406       via  qemu-monitor-command  to  learn  what  events  are  supported.  If
6407       --regex is used, event-name is a basic regular expression instead of  a
6408       literal  string.   If --no-case is used, event-name will match case-in‐
6409       sensitively.
6410
6411       By default, this command is one-shot, and returns success once an event
6412       occurs;  you  can send SIGINT (usually via Ctrl-C) to quit immediately.
6413       If --timeout is specified, the command gives up waiting for events  af‐
6414       ter  seconds  have elapsed.  With --loop, the command prints all events
6415       until a timeout or interrupt key.  If --pretty is specified,  any  JSON
6416       event details are pretty-printed for better legibility.
6417
6418       When  --timestamp  is  used, a human-readable timestamp will be printed
6419       before the event, and the timing information provided by QEMU  will  be
6420       omitted.
6421
6422   lxc-enter-namespace
6423       Syntax:
6424
6425          lxc-enter-namespace domain [--noseclabel] --
6426             /path/to/binary [arg1, [arg2, ...]]
6427
6428       Enter  the  namespace of domain and execute the command /path/to/binary
6429       passing the requested args. The binary path is  relative  to  the  con‐
6430       tainer  root  filesystem, not the host root filesystem. The binary will
6431       inherit the environment variables / console visible to virsh. The  com‐
6432       mand  will  be run with the same sVirt context and cgroups placement as
6433       processes within the container. This command only works when  connected
6434       to   the   LXC  hypervisor  driver.   This  command  succeeds  only  if
6435       /path/to/binary has 0 exit status.
6436
6437       By default the new process will run with the security label of the  new
6438       parent  container.  Use  the  --noseclabel  option  to instead have the
6439       process keep the same security label as virsh.
6440

ENVIRONMENT

6442       The following environment variables can be set to alter  the  behaviour
6443       of virsh
6444
6445       • VIRSH_DEBUG=<0 to 4>
6446
6447         Turn on verbose debugging of virsh commands. Valid levels are
6448
6449         • VIRSH_DEBUG=0
6450
6451           DEBUG - Messages at ALL levels get logged
6452
6453         • VIRSH_DEBUG=1
6454
6455           INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
6456
6457         • VIRSH_DEBUG=2
6458
6459           NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
6460
6461         • VIRSH_DEBUG=3
6462
6463           WARNING - Logs messages at levels WARNING and ERROR
6464
6465         • VIRSH_DEBUG=4
6466
6467           ERROR - Messages at only ERROR level gets logged.
6468
6469       • VIRSH_LOG_FILE=``LOGFILE``
6470
6471         The file to log virsh debug messages.
6472
6473       • VIRSH_DEFAULT_CONNECT_URI
6474
6475         The  hypervisor  to  connect to by default. Set this to a URI, in the
6476         same format as accepted by the connect option. This environment vari‐
6477         able  is deprecated in favour of the global LIBVIRT_DEFAULT_URI vari‐
6478         able which serves the same purpose.
6479
6480       • LIBVIRT_DEFAULT_URI
6481
6482         The hypervisor to connect to by default. Set this to a  URI,  in  the
6483         same format as accepted by the connect option. This overrides the de‐
6484         fault URI set in any client config file  and  prevents  libvirt  from
6485         probing for drivers.
6486
6487       • VISUAL
6488
6489         The editor to use by the edit and related options.
6490
6491       • EDITOR
6492
6493         The  editor  to use by the edit and related options, if VISUAL is not
6494         set.
6495
6496       • VIRSH_HISTSIZE
6497
6498         The number of commands to remember in the command  history.  The  de‐
6499         fault value is 500.
6500
6501       • LIBVIRT_DEBUG=LEVEL
6502
6503         Turn on verbose debugging of all libvirt API calls. Valid levels are
6504
6505         • LIBVIRT_DEBUG=1
6506
6507           Messages at level DEBUG or above
6508
6509         • LIBVIRT_DEBUG=2
6510
6511           Messages at level INFO or above
6512
6513         • LIBVIRT_DEBUG=3
6514
6515           Messages at level WARNING or above
6516
6517         • LIBVIRT_DEBUG=4
6518
6519           Messages at level ERROR
6520
6521       For    further    information    about    debugging   options   consult
6522       https://libvirt.org/logging.html
6523

BUGS

6525       Please report all bugs you discover.  This should be done via either:
6526
6527       1. the mailing list
6528
6529          https://libvirt.org/contact.html
6530
6531       2. the bug tracker
6532
6533          https://libvirt.org/bugs.html
6534
6535       Alternatively, you may report bugs to your software distributor /  ven‐
6536       dor.
6537

AUTHORS

6539       Please refer to the AUTHORS file distributed with libvirt.
6540
6542       Copyright  (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in
6543       the libvirt AUTHORS file.
6544

LICENSE

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

SEE ALSO

6551       virt-install(1),   virt-xml-validate(1),    virt-top(1),    virt-df(1),
6552       https://libvirt.org/
6553
6554
6555
6556
6557                                                                      VIRSH(1)
Impressum