1VIRSH(1) Virtualization Support VIRSH(1)
2
6 virsh - management user interface
7
9 virsh [OPTION]... [COMMAND_STRING]
10 virsh [OPTION]... COMMAND [ARG]...
12
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 The basic structure of most virsh usage is:
27 virsh [OPTION]... <command> <domain> [ARG]...
29 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 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 The virsh program understands the following OPTIONS.
56 -c, --connect URI
58 Connect to the specified URI, as if by the connect command, instead of
60 the default connection.
61 -d, --debug LEVEL
63 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 • -e, --escape string
69 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 • -h, --help
75 Ignore all other arguments, and behave as if the help command were
77 given instead.
78 • -k, --keepalive-interval INTERVAL
80 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 • -K, --keepalive-count COUNT
86 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 • -l, --log FILE
92 Output logging details to FILE.
94 • -q, --quiet
96 Avoid extra informational messages.
98 • -r, --readonly
100 Make the initial connection read-only, as if by the --readonly option
102 of the connect command.
103 • -t, --timing
105 Output elapsed time information for each command.
107 • -v, --version[=short]
109 Ignore all other arguments, and prints the version of the libvirt li‐
111 brary virsh is coming from
112 • -V, --version=long
114 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
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 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 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 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 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 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
160 The following commands are generic i.e. not specific to a domain.
161 help
163 Syntax:
164 help [command-or-group]
166 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 To display only commands for a specific group, give the keyword for
172 that group as an option. For example:
173 Example 1:
175 virsh # help host
177 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 To display detailed information for a specific command, give its name
191 as the option instead. For example:
192 Example 2:
194 virsh # help list
196 NAME
197 list - list domains
198 SYNOPSIS
200 list [--inactive] [--all]
201 DESCRIPTION
203 Returns list of domains.
204 OPTIONS
206 --inactive list inactive domains
207 --all list inactive & active domains
208 quit, exit
210 Syntax:
211 quit
213 exit
214 quit this interactive terminal
216 version
218 Syntax:
219 version [--daemon]
221 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 Example:
227 $ 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 $ 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 cd
242 Syntax:
243 cd [directory]
245 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 This command is only available in interactive mode.
251 pwd
253 Syntax:
254 pwd
256 Will print the current directory.
258 connect
260 Syntax:
261 connect [URI] [--readonly]
263 (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 • xen:///system
271 this is used to connect to the local Xen hypervisor
273 • qemu:///system
275 connect locally as root to the daemon supervising QEMU and KVM do‐
277 mains
278 • qemu:///session
280 connect locally as a normal user to his own set of QEMU and KVM do‐
282 mains
283 • lxc:///system
285 connect to a local linux container
287 To find the currently used URI, check the uri command documented below.
289 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 uri
294 Syntax:
295 uri
297 Prints the hypervisor canonical URI, can be useful in shell mode.
299 hostname
301 Syntax:
302 hostname
304 Print the hypervisor hostname.
306 sysinfo
308 Syntax:
309 sysinfo
311 Print the XML representation of the hypervisor sysinfo, if available.
313 nodeinfo
315 Syntax:
316 nodeinfo
318 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 nodecpumap
326 Syntax:
327 nodecpumap [--pretty]
329 Displays the node's total number of CPUs, the number of online CPUs and
331 the list of online CPUs.
332 With --pretty the online CPUs are printed as a range instead of a list.
334 nodecpustats
336 Syntax:
337 nodecpustats [cpu] [--percent]
339 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 nodememstats
346 Syntax:
347 nodememstats [cell]
349 Returns memory stats of the node. If cell is specified, this will
351 print the specified cell statistics only.
352 nodesevinfo
354 Syntax:
355 nodesevinfo
357 Reports information about the AMD SEV launch security features for the
359 node, if any. Some of this information is also reported in the domain
360 capabilities XML document.
361 nodesuspend
363 Syntax:
364 nodesuspend [target] [duration]
366 Puts the node (host machine) into a system-wide sleep state and sched‐
368 ule the node's Real-Time-Clock interrupt to resume the node after the
369 time duration specified by duration is out. target specifies the state
370 to which the host will be suspended to, it can be "mem" (suspend to
371 RAM), "disk" (suspend to disk), or "hybrid" (suspend to both RAM and
372 disk). duration specifies the time duration in seconds for which the
373 host has to be suspended, it should be at least 60 seconds.
374 node-memory-tune
376 Syntax:
377 node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs] [shm-merge-across-nodes]
379 Allows you to display or set the node memory parameters.
381 shm-pages-to-scan can be used to set the number of pages to scan before
382 the shared memory service goes to sleep; shm-sleep-millisecs can be
383 used to set the number of millisecs the shared memory service should
384 sleep before next scan; shm-merge-across-nodes specifies if pages from
385 different numa nodes can be merged. When set to 0, only pages which
386 physically reside in the memory area of same NUMA node can be merged.
387 When set to 1, pages from all nodes can be merged. Default to 1.
388 Note: Currently the "shared memory service" only means KSM (Kernel
390 Samepage Merging).
391 capabilities
393 Syntax:
394 capabilities
396 Print an XML document describing the capabilities of the hypervisor we
398 are currently connected to. This includes a section on the host capa‐
399 bilities in terms of CPU and features, and a set of description for
400 each kind of guest which can be virtualized. For a more complete de‐
401 scription see:
402 https://libvirt.org/formatcaps.html
404 The XML also show the NUMA topology information if available.
406 domcapabilities
408 Syntax:
409 domcapabilities [virttype] [emulatorbin] [arch] [machine]
411 Print an XML document describing the domain capabilities for the hyper‐
413 visor we are connected to using information either sourced from an ex‐
414 isting domain or taken from the virsh capabilities output. This may be
415 useful if you intend to create a new domain and are curious if for in‐
416 stance it could make use of VFIO by creating a domain for the hypervi‐
417 sor with a specific emulator and architecture.
418 Each hypervisor will have different requirements regarding which op‐
420 tions are required and which are optional. A hypervisor can support
421 providing a default value for any of the options.
422 The virttype option specifies the virtualization type used. The value
424 to be used is either from the 'type' attribute of the <domain/> top
425 level element from the domain XML or the 'type' attribute found within
426 each <guest/> element from the virsh capabilities output. The emula‐
427 torbin option specifies the path to the emulator. The value to be used
428 is either the <emulator> element in the domain XML or the virsh capa‐
429 bilities output. The arch option specifies the architecture to be used
430 for the domain. The value to be used is either the "arch" attribute
431 from the domain's XML <os/> element and <type/> subelement or the
432 "name" attribute of an <arch/> element from the virsh capabililites
433 output. The machine specifies the machine type for the emulator. The
434 value to be used is either the "machine" attribute from the domain's
435 XML <os/> element and <type/> subelement or one from a list of machines
436 from the virsh capabilities output for a specific architecture and do‐
437 main type.
438 For the QEMU hypervisor, a virttype of either 'qemu' or 'kvm' must be
440 supplied along with either the emulatorbin or arch in order to generate
441 output for the default machine. Supplying a machine value will gener‐
442 ate output for the specific machine.
443 pool-capabilities
445 Syntax:
446 pool-capabilities
448 Print an XML document describing the storage pool capabilities for the
450 connected storage driver. This may be useful if you intend to create a
451 new storage pool and need to know the available pool types and sup‐
452 ported storage pool source and target volume formats as well as the re‐
453 quired source elements to create the pool.
454 inject-nmi
456 Syntax:
457 inject-nmi domain
459 Inject NMI to the guest.
461 list
463 Syntax:
464 list [--inactive | --all]
466 [--managed-save] [--title]
467 { [--table] | --name | --uuid | --id }
468 [--persistent] [--transient]
469 [--with-managed-save] [--without-managed-save]
470 [--autostart] [--no-autostart]
471 [--with-snapshot] [--without-snapshot]
472 [--with-checkpoint] [--without-checkpoint]
473 [--state-running] [--state-paused]
474 [--state-shutoff] [--state-other]
475 Prints information about existing domains. If no options are specified
477 it prints out information about running domains.
478 Example 1:
480 An example format for the list is as follows:
482 ``virsh`` list
484 Id Name State
485 ----------------------------------------------------
486 0 Domain-0 running
487 2 fedora paused
488 Name is the name of the domain. ID the domain numeric id. State is
490 the run state (see below).
491 STATES
493 The State field lists what state each domain is currently in. A domain
495 can be in one of the following possible states:
496 • running
498 The domain is currently running on a CPU
500 • idle
502 The domain is idle, and not running or runnable. This can be caused
504 because the domain is waiting on IO (a traditional wait state) or has
505 gone to sleep because there was nothing else for it to do.
506 • paused
508 The domain has been paused, usually occurring through the administra‐
510 tor running virsh suspend. When in a paused state the domain will
511 still consume allocated resources like memory, but will not be eligi‐
512 ble for scheduling by the hypervisor.
513 • in shutdown
515 The domain is in the process of shutting down, i.e. the guest operat‐
517 ing system has been notified and should be in the process of stopping
518 its operations gracefully.
519 • shut off
521 The domain is not running. Usually this indicates the domain has
523 been shut down completely, or has not been started.
524 • crashed
526 The domain has crashed, which is always a violent ending. Usually
528 this state can only occur if the domain has been configured not to
529 restart on crash.
530 • pmsuspended
532 The domain has been suspended by guest power management, e.g. entered
534 into s3 state.
535 Normally only active domains are listed. To list inactive domains spec‐
537 ify --inactive or --all to list both active and inactive domains.
538 Filtering
540 To further filter the list of domains you may specify one or more of
542 filtering flags supported by the list command. These flags are grouped
543 by function. Specifying one or more flags from a group enables the
544 filter group. Note that some combinations of flags may yield no re‐
545 sults. Supported filtering flags and groups:
546 Persistence
548 Flag --persistent is used to include persistent guests in the returned
549 list. To include transient guests specify --transient.
550 Existence of managed save image
552 To list domains having a managed save image specify flag --with-man‐
553 aged-save. For domains that don't have a managed save image specify
554 --without-managed-save.
555 Domain state
557 The following filter flags select a domain by its state: --state-run‐
558 ning for running domains, --state-paused for paused domains,
559 --state-shutoff for turned off domains and --state-other for all other
560 states as a fallback.
561 Autostarting domains
563 To list autostarting domains use the flag --autostart. To list domains
564 with this feature disabled use --no-autostart.
565 Snapshot existence
567 Domains that have snapshot images can be listed using flag --with-snap‐
568 shot, domains without a snapshot --without-snapshot.
569 Checkpoint existence
571 Domains that have checkpoints can be listed using flag --with-check‐
572 point, domains without a checkpoint --without-checkpoint.
573 When talking to older servers, this command is forced to use a series
575 of API calls with an inherent race, where a domain might not be listed
576 or might appear more than once if it changed state between calls while
577 the list was being collected. Newer servers do not have this problem.
578 If --managed-save is specified, then domains that have managed save
580 state (only possible if they are in the shut off state, so you need to
581 specify --inactive or --all to actually list them) will instead show as
582 saved in the listing. This flag is usable only with the default --table
583 output. Note that this flag does not filter the list of domains.
584 If --name is specified, domain names are printed instead of the table
586 formatted one per line. If --uuid is specified domain's UUID's are
587 printed instead of names. If --id is specified then domain's ID's are
588 printed indead of names. However, it is possible to combine --name,
589 --uuid and --id to select only desired fields for printing. Flag --ta‐
590 ble specifies that the legacy table-formatted output should be used,
591 but it is mutually exclusive with --name, --uuid and --id. This is the
592 default and will be used if neither of --name, --uuid or --id is speci‐
593 fied. If neither --name nor --uuid is specified, but --id is, then only
594 active domains are listed, even with the --all parameter as otherwise
595 the output would just contain bunch of lines with just -1.
596 If --title is specified, then the short domain description (title) is
598 printed in an extra column. This flag is usable only with the default
599 --table output.
600 Example 2:
602 $ virsh list --title
604 Id Name State Title
605 -------------------------------------------
606 0 Domain-0 running Mailserver 1
607 2 fedora paused
608 freecell
610 Syntax:
611 freecell [{ [--cellno] cellno | --all }]
613 Prints the available amount of memory on the machine or within a NUMA
615 cell. The freecell command can provide one of three different displays
616 of available memory on the machine depending on the options specified.
617 With no options, it displays the total free memory on the machine.
618 With the --all option, it displays the free memory in each cell and the
619 total free memory on the machine. Finally, with a numeric argument or
620 with --cellno plus a cell number it will display the free memory for
621 the specified cell only.
622 freepages
624 Syntax:
625 freepages [{ [--cellno] cellno [--pagesize] pagesize | --all }]
627 Prints the available amount of pages within a NUMA cell. cellno refers
629 to the NUMA cell you're interested in. pagesize is a scaled integer
630 (see NOTES above). Alternatively, if --all is used, info on each pos‐
631 sible combination of NUMA cell and page size is printed out.
632 allocpages
634 Syntax:
635 allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno] cellno] [--add] [--all]
637 Change the size of pages pool of pagesize on the host. If --add is
639 specified, then pagecount pages are added into the pool. However, if
640 --add wasn't specified, then the pagecount is taken as the new absolute
641 size of the pool (this may be used to free some pages and size the pool
642 down). The cellno modifier can be used to narrow the modification down
643 to a single host NUMA cell. On the other end of spectrum lies --all
644 which executes the modification on all NUMA cells.
645 cpu-baseline
647 Syntax:
648 cpu-baseline FILE [--features] [--migratable]
650 Compute baseline CPU which will be supported by all host CPUs given in
652 <file>. (See hypervisor-cpu-baseline command to get a CPU which can be
653 provided by a specific hypervisor.) The list of host CPUs is built by
654 extracting all <cpu> elements from the <file>. Thus, the <file> can
655 contain either a set of <cpu> elements separated by new lines or even a
656 set of complete <capabilities> elements printed by capabilities com‐
657 mand. If --features is specified, then the resulting XML description
658 will explicitly include all features that make up the CPU, without this
659 option features that are part of the CPU model will not be listed in
660 the XML description. If --migratable is specified, features that
661 block migration will not be included in the resulting CPU.
662 cpu-compare
664 Syntax:
665 cpu-compare FILE [--error] [--validate]
667 Compare CPU definition from XML <file> with host CPU. (See hypervi‐
669 sor-cpu-compare command for comparing the CPU definition with the CPU
670 which a specific hypervisor is able to provide on the host.) The XML
671 <file> may contain either host or guest CPU definition. The host CPU
672 definition is the <cpu> element and its contents as printed by capabil‐
673 ities command. The guest CPU definition is the <cpu> element and its
674 contents from domain XML definition or the CPU definition created from
675 the host CPU model found in domain capabilities XML (printed by domca‐
676 pabilities command). In addition to the <cpu> element itself, this com‐
677 mand accepts full domain XML, capabilities XML, or domain capabilities
678 XML containing the CPU definition. For more information on guest CPU
679 definition see: https://libvirt.org/formatdomain.html#elementsCPU. If
680 --error is specified, the command will return an error when the given
681 CPU is incompatible with host CPU and a message providing more details
682 about the incompatibility will be printed out. If --validate is speci‐
683 fied, validates the format of the XML document against an internal RNG
684 schema.
685 cpu-models
687 Syntax:
688 cpu-models arch
690 Print the list of CPU models known by libvirt for the specified archi‐
692 tecture. Whether a specific hypervisor is able to create a domain
693 which uses any of the printed CPU models is a separate question which
694 can be answered by looking at the domain capabilities XML returned by
695 domcapabilities command. Moreover, for some architectures libvirt does
696 not know any CPU models and the usable CPU models are only limited by
697 the hypervisor. This command will print that all CPU models are ac‐
698 cepted for these architectures and the actual list of supported CPU
699 models can be checked in the domain capabilities XML.
700 hypervisor-cpu-compare
702 Syntax:
703 hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine] [--error] [--validate]
705 Compare CPU definition from XML <file> with the CPU the hypervisor is
707 able to provide on the host. (This is different from cpu-compare which
708 compares the CPU definition with the host CPU without considering any
709 specific hypervisor and its abilities.)
710 The XML FILE may contain either a host or guest CPU definition. The
712 host CPU definition is the <cpu> element and its contents as printed by
713 the capabilities command. The guest CPU definition is the <cpu> element
714 and its contents from the domain XML definition or the CPU definition
715 created from the host CPU model found in the domain capabilities XML
716 (printed by the domcapabilities command). In addition to the <cpu> ele‐
717 ment itself, this command accepts full domain XML, capabilities XML, or
718 domain capabilities XML containing the CPU definition. For more infor‐
719 mation on guest CPU definition see:
720 https://libvirt.org/formatdomain.html#elementsCPU.
721 The virttype option specifies the virtualization type (usable in the
723 'type' attribute of the <domain> top level element from the domain
724 XML). emulator specifies the path to the emulator, arch specifies the
725 CPU architecture, and machine specifies the machine type. If --error is
726 specified, the command will return an error when the given CPU is in‐
727 compatible with the host CPU and a message providing more details about
728 the incompatibility will be printed out. If --validate is specified,
729 validates the format of the XML document against an internal RNG
730 schema.
731 hypervisor-cpu-baseline
733 Syntax:
734 hypervisor-cpu-baseline FILE [virttype] [emulator] [arch] [machine] [--features] [--migratable]
736 Compute a baseline CPU which will be compatible with all CPUs defined
738 in an XML file and with the CPU the hypervisor is able to provide on
739 the host. (This is different from cpu-baseline which does not consider
740 any hypervisor abilities when computing the baseline CPU.)
741 The XML FILE may contain either host or guest CPU definitions describ‐
743 ing the host CPU model. The host CPU definition is the <cpu> element
744 and its contents as printed by capabilities command. The guest CPU def‐
745 inition may be created from the host CPU model found in domain capabil‐
746 ities XML (printed by domcapabilities command). In addition to the
747 <cpu> elements, this command accepts full capabilities XMLs, or domain
748 capabilities XMLs containing the CPU definitions. It is recommended to
749 use only the CPU definitions from domain capabilities, as on some ar‐
750 chitectures using the host CPU definition may either fail or provide
751 unexpected results.
752 When FILE contains only a single CPU definition, the command will print
754 the same CPU with restrictions imposed by the capabilities of the hy‐
755 pervisor. Specifically, running th virsh hypervisor-cpu-baseline com‐
756 mand with no additional options on the result of virsh domcapabilities
757 will transform the host CPU model from domain capabilities XML to a
758 form directly usable in domain XML.
759 The virttype option specifies the virtualization type (usable in the
761 'type' attribute of the <domain> top level element from the domain
762 XML). emulator specifies the path to the emulator, arch specifies the
763 CPU architecture, and machine specifies the machine type. If --features
764 is specified, then the resulting XML description will explicitly in‐
765 clude all features that make up the CPU, without this option features
766 that are part of the CPU model will not be listed in the XML descrip‐
767 tion. If --migratable is specified, features that block migration will
768 not be included in the resulting CPU.
769
771 The following commands manipulate domains directly, as stated previ‐
772 ously most commands take domain as the first parameter. The domain can
773 be specified as a short integer, a name or a full UUID.
774 autostart
776 Syntax:
777 autostart [--disable] domain
779 Configure a domain to be automatically started at boot.
781 The option --disable disables autostarting.
783 blkdeviotune
785 Syntax:
786 blkdeviotune domain device [[--config] [--live] | [--current]]
788 [[total-bytes-sec] | [read-bytes-sec] [write-bytes-sec]]
789 [[total-iops-sec] | [read-iops-sec] [write-iops-sec]]
790 [[total-bytes-sec-max] | [read-bytes-sec-max] [write-bytes-sec-max]]
791 [[total-iops-sec-max] | [read-iops-sec-max] [write-iops-sec-max]]
792 [[total-bytes-sec-max-length] |
793 [read-bytes-sec-max-length] [write-bytes-sec-max-length]]
794 [[total-iops-sec-max-length] |
795 [read-iops-sec-max-length] [write-iops-sec-max-length]]
796 [size-iops-sec] [group-name]
797 Set or query the block disk io parameters for a block device of domain.
799 device specifies a unique target name (<target dev='name'/>) or source
800 file (<source file='name'/>) for one of the disk devices attached to
801 domain (see also domblklist for listing these names).
802 If no limit is specified, it will query current I/O limits setting.
804 Otherwise, alter the limits with these flags: --total-bytes-sec speci‐
805 fies total throughput limit as a scaled integer, the default being
806 bytes per second if no suffix is specified. --read-bytes-sec specifies
807 read throughput limit as a scaled integer, the default being bytes per
808 second if no suffix is specified. --write-bytes-sec specifies write
809 throughput limit as a scaled integer, the default being bytes per sec‐
810 ond if no suffix is specified. --total-iops-sec specifies total I/O
811 operations limit per second. --read-iops-sec specifies read I/O opera‐
812 tions limit per second. --write-iops-sec specifies write I/O opera‐
813 tions limit per second. --total-bytes-sec-max specifies maximum total
814 throughput limit as a scaled integer, the default being bytes per sec‐
815 ond if no suffix is specified --read-bytes-sec-max specifies maximum
816 read throughput limit as a scaled integer, the default being bytes per
817 second if no suffix is specified. --write-bytes-sec-max specifies max‐
818 imum write throughput limit as a scaled integer, the default being
819 bytes per second if no suffix is specified. --total-iops-sec-max spec‐
820 ifies maximum total I/O operations limit per second.
821 --read-iops-sec-max specifies maximum read I/O operations limit per
822 second. --write-iops-sec-max specifies maximum write I/O operations
823 limit per second. --total-bytes-sec-max-length specifies duration in
824 seconds to allow maximum total throughput limit.
825 --read-bytes-sec-max-length specifies duration in seconds to allow max‐
826 imum read throughput limit. --write-bytes-sec-max-length specifies du‐
827 ration in seconds to allow maximum write throughput limit. --to‐
828 tal-iops-sec-max-length specifies duration in seconds to allow maximum
829 total I/O operations limit. --read-iops-sec-max-length specifies dura‐
830 tion in seconds to allow maximum read I/O operations limit.
831 --write-iops-sec-max-length specifies duration in seconds to allow max‐
832 imum write I/O operations limit. --size-iops-sec specifies size I/O
833 operations limit per second. --group-name specifies group name to
834 share I/O quota between multiple drives. For a QEMU domain, if no name
835 is provided, then the default is to have a single group for each de‐
836 vice.
837 Older versions of virsh only accepted these options with underscore in‐
839 stead of dash, as in --total_bytes_sec.
840 Bytes and iops values are independent, but setting only one value (such
842 as --read-bytes-sec) resets the other two in that category to unlim‐
843 ited. An explicit 0 also clears any limit. A non-zero value for a
844 given total cannot be mixed with non-zero values for read or write.
845 It is up to the hypervisor to determine how to handle the length val‐
847 ues. For the QEMU hypervisor, if an I/O limit value or maximum value
848 is set, then the default value of 1 second will be displayed. Supplying
849 a 0 will reset the value back to the default.
850 If --live is specified, affect a running guest. If --config is speci‐
852 fied, affect the next start of a persistent guest. If --current is
853 specified, it is equivalent to either --live or --config, depending on
854 the current state of the guest. When setting the disk io parameters
855 both --live and --config flags may be given, but --current is exclu‐
856 sive. For querying only one of --live, --config or --current can be
857 specified. If no flag is specified, behavior is different depending on
858 hypervisor.
859 blkiotune
861 Syntax:
862 blkiotune domain [--weight weight] [--device-weights device-weights]
864 [--device-read-iops-sec device-read-iops-sec]
865 [--device-write-iops-sec device-write-iops-sec]
866 [--device-read-bytes-sec device-read-bytes-sec]
867 [--device-write-bytes-sec device-write-bytes-sec]
868 [[--config] [--live] | [--current]]
869 Display or set the blkio parameters. QEMU/KVM supports --weight.
871 --weight is in range [100, 1000]. After kernel 2.6.39, the value could
872 be in the range [10, 1000].
873 device-weights is a single string listing one or more device/weight
875 pairs, in the format of /path/to/device,weight,/path/to/device,weight.
876 Each weight is in the range [100, 1000], [10, 1000] after kernel
877 2.6.39, or the value 0 to remove that device from per-device listings.
878 Only the devices listed in the string are modified; any existing
879 per-device weights for other devices remain unchanged.
880 device-read-iops-sec is a single string listing one or more de‐
882 vice/read_iops_sec pairs, int the format of /path/to/de‐
883 vice,read_iops_sec,/path/to/device,read_iops_sec. Each read_iops_sec
884 is a number which type is unsigned int, value 0 to remove that device
885 from per-device listing. Only the devices listed in the string are
886 modified; any existing per-device read_iops_sec for other devices re‐
887 main unchanged.
888 device-write-iops-sec is a single string listing one or more de‐
890 vice/write_iops_sec pairs, int the format of /path/to/de‐
891 vice,write_iops_sec,/path/to/device,write_iops_sec. Each
892 write_iops_sec is a number which type is unsigned int, value 0 to re‐
893 move that device from per-device listing. Only the devices listed in
894 the string are modified; any existing per-device write_iops_sec for
895 other devices remain unchanged.
896 device-read-bytes-sec is a single string listing one or more de‐
898 vice/read_bytes_sec pairs, int the format of /path/to/de‐
899 vice,read_bytes_sec,/path/to/device,read_bytes_sec. Each
900 read_bytes_sec is a number which type is unsigned long long, value 0 to
901 remove that device from per-device listing. Only the devices listed in
902 the string are modified; any existing per-device read_bytes_sec for
903 other devices remain unchanged.
904 device-write-bytes-sec is a single string listing one or more de‐
906 vice/write_bytes_sec pairs, int the format of /path/to/de‐
907 vice,write_bytes_sec,/path/to/device,write_bytes_sec. Each
908 write_bytes_sec is a number which type is unsigned long long, value 0
909 to remove that device from per-device listing. Only the devices listed
910 in the string are modified; any existing per-device write_bytes_sec for
911 other devices remain unchanged.
912 If --live is specified, affect a running guest. If --config is speci‐
914 fied, affect the next start of a persistent guest. If --current is
915 specified, it is equivalent to either --live or --config, depending on
916 the current state of the guest. Both --live and --config flags may be
917 given, but --current is exclusive. If no flag is specified, behavior is
918 different depending on hypervisor.
919 blockcommit
921 Syntax:
922 blockcommit domain path [bandwidth] [--bytes] [base]
924 [--shallow] [top] [--delete] [--keep-relative]
925 [--wait [--async] [--verbose]] [--timeout seconds]
926 [--active] [{--pivot | --keep-overlay}]
927 Reduce the length of a backing image chain, by committing changes at
929 the top of the chain (snapshot or delta files) into backing images. By
930 default, this command attempts to flatten the entire chain. If base
931 and/or top are specified as files within the backing chain, then the
932 operation is constrained to committing just that portion of the chain;
933 --shallow can be used instead of base to specify the immediate backing
934 file of the resulting top image to be committed. The files being com‐
935 mitted are rendered invalid, possibly as soon as the operation starts;
936 using the --delete flag will attempt to remove these invalidated files
937 at the successful completion of the commit operation. When the
938 --keep-relative flag is used, the backing file paths will be kept rela‐
939 tive.
940 When top is omitted or specified as the active image, it is also possi‐
942 ble to specify --active to trigger a two-phase active commit. In the
943 first phase, top is copied into base and the job can only be canceled,
944 with top still containing data not yet in base. In the second phase,
945 top and base remain identical until a call to blockjob with the --abort
946 flag (keeping top as the active image that tracks changes from that
947 point in time) or the --pivot flag (making base the new active image
948 and invalidating top).
949 By default, this command returns as soon as possible, and data for the
951 entire disk is committed in the background; the progress of the opera‐
952 tion can be checked with blockjob. However, if --wait is specified,
953 then this command will block until the operation completes (or for
954 --active, enters the second phase), or until the operation is canceled
955 because the optional timeout in seconds elapses or SIGINT is sent (usu‐
956 ally with Ctrl-C). Using --verbose along with --wait will produce pe‐
957 riodic status updates. If job cancellation is triggered, --async will
958 return control to the user as fast as possible, otherwise the command
959 may continue to block a little while longer until the job is done
960 cleaning up. Using --pivot is shorthand for combining --active --wait
961 with an automatic blockjob --pivot; and using --keep-overlay is short‐
962 hand for combining --active --wait with an automatic blockjob --abort.
963 path specifies fully-qualified path of the disk; it corresponds to a
965 unique target name (<target dev='name'/>) or source file (<source
966 file='name'/>) for one of the disk devices attached to domain (see also
967 domblklist for listing these names). bandwidth specifies copying band‐
968 width limit in MiB/s, although for QEMU, it may be non-zero only for an
969 online domain. For further information on the bandwidth argument see
970 the corresponding section for the blockjob command.
971 blockcopy
973 Syntax:
974 blockcopy domain path { dest [format] [--blockdev] | --xml file }
976 [--shallow] [--reuse-external] [bandwidth]
977 [--wait [--async] [--verbose]] [{--pivot | --finish}]
978 [--timeout seconds] [granularity] [buf-size] [--bytes]
979 [--transient-job] [--synchronous-writes]
980 Copy a disk backing image chain to a destination. Either dest as the
982 destination file name, or --xml with the name of an XML file containing
983 a top-level <disk> element describing the destination, must be present.
984 Additionally, if dest is given, format should be specified to declare
985 the format of the destination (if format is omitted, then libvirt will
986 reuse the format of the source, or with --reuse-external will be forced
987 to probe the destination format, which could be a potential security
988 hole). The command supports --raw as a boolean flag synonym for --for‐
989 mat=raw. When using dest, the destination is treated as a regular file
990 unless --blockdev is used to signal that it is a block device. By de‐
991 fault, this command flattens the entire chain; but if --shallow is
992 specified, the copy shares the backing chain.
993 If --reuse-external is specified, then the destination must exist and
995 have sufficient space to hold the copy. If --shallow is used in con‐
996 junction with --reuse-external then the pre-created image must have
997 guest visible contents identical to guest visible contents of the back‐
998 ing file of the original image. This may be used to modify the backing
999 file names on the destination.
1000 By default, the copy job runs in the background, and consists of two
1002 phases. Initially, the job must copy all data from the source, and
1003 during this phase, the job can only be canceled to revert back to the
1004 source disk, with no guarantees about the destination. After this
1005 phase completes, both the source and the destination remain mirrored
1006 until a call to blockjob with the --abort and --pivot flags pivots over
1007 to the copy, or a call without --pivot leaves the destination as a
1008 faithful copy of that point in time. However, if --wait is specified,
1009 then this command will block until the mirroring phase begins, or can‐
1010 cel the operation if the optional timeout in seconds elapses or SIGINT
1011 is sent (usually with Ctrl-C). Using --verbose along with --wait will
1012 produce periodic status updates. Using --pivot (similar to blockjob
1013 --pivot) or --finish (similar to blockjob --abort) implies --wait, and
1014 will additionally end the job cleanly rather than leaving things in the
1015 mirroring phase. If job cancellation is triggered by timeout or by
1016 --finish, --async will return control to the user as fast as possible,
1017 otherwise the command may continue to block a little while longer until
1018 the job has actually cancelled.
1019 path specifies fully-qualified path of the disk. bandwidth specifies
1021 copying bandwidth limit in MiB/s. Specifying a negative value is inter‐
1022 preted as an unsigned long long value that might be essentially unlim‐
1023 ited, but more likely would overflow; it is safer to use 0 for that
1024 purpose. For further information on the bandwidth argument see the cor‐
1025 responding section for the blockjob command. Specifying granularity
1026 allows fine-tuning of the granularity that will be copied when a dirty
1027 region is detected; larger values trigger less I/O overhead but may end
1028 up copying more data overall (the default value is usually correct);
1029 hypervisors may restrict this to be a power of two or fall within a
1030 certain range. Specifying buf-size will control how much data can be
1031 simultaneously in-flight during the copy; larger values use more memory
1032 but may allow faster completion (the default value is usually correct).
1033 --transient-job allows specifying that the user does not require the
1035 job to be recovered if the VM crashes or is turned off before the job
1036 completes. This flag removes the restriction of copy jobs to transient
1037 domains if that restriction is applied by the hypervisor.
1038 If --synchronous-writes is specified the block job will wait for guest
1040 writes to be propagated both to the original image and to the destina‐
1041 tion of the copy so that it's guaranteed that the job converges if the
1042 destination storage is slower. This may impact performance of writes
1043 while the blockjob is running.
1044 blockjob
1046 Syntax:
1047 blockjob domain path { [--abort] [--async] [--pivot] |
1049 [--info] [--raw] [--bytes] | [bandwidth] }
1050 Manage active block operations. There are three mutually-exclusive
1052 modes: --info, bandwidth, and --abort. --async and --pivot imply abort
1053 mode; --raw implies info mode; and if no mode was given, --info mode is
1054 assumed.
1055 path specifies fully-qualified path of the disk; it corresponds to a
1057 unique target name (<target dev='name'/>) or source file (<source
1058 file='name'/>) for one of the disk devices attached to domain (see also
1059 domblklist for listing these names).
1060 In --abort mode, the active job on the specified disk will be aborted.
1062 If --async is also specified, this command will return immediately,
1063 rather than waiting for the cancellation to complete. If --pivot is
1064 specified, this requests that an active copy or active commit job be
1065 pivoted over to the new image.
1066 In --info mode, the active job information on the specified disk will
1068 be printed. By default, the output is a single human-readable summary
1069 line; this format may change in future versions. Adding --raw lists
1070 each field of the struct, in a stable format. If the --bytes flag is
1071 set, then the command errors out if the server could not supply bytes/s
1072 resolution; when omitting the flag, raw output is listed in MiB/s and
1073 human-readable output automatically selects the best resolution sup‐
1074 ported by the server.
1075 bandwidth can be used to set bandwidth limit for the active job in
1077 MiB/s. If --bytes is specified then the bandwidth value is interpreted
1078 in bytes/s. Specifying a negative value is interpreted as an unsigned
1079 long value or essentially unlimited. The hypervisor can choose whether
1080 to reject the value or convert it to the maximum value allowed. Option‐
1081 ally a scaled positive number may be used as bandwidth (see NOTES
1082 above). Using --bytes with a scaled value permits a finer granularity
1083 to be selected. A scaled value used without --bytes will be rounded
1084 down to MiB/s. Note that the --bytes may be unsupported by the hypervi‐
1085 sor.
1086 Note that the progress reported for blockjobs corresponding to a
1088 pull-mode backup don't report progress of the backup but rather usage
1089 of temporary space required for the backup.
1090 blockpull
1092 Syntax:
1093 blockpull domain path [bandwidth] [--bytes] [base]
1095 [--wait [--verbose] [--timeout seconds] [--async]]
1096 [--keep-relative]
1097 Populate a disk from its backing image chain. By default, this command
1099 flattens the entire chain; but if base is specified, containing the
1100 name of one of the backing files in the chain, then that file becomes
1101 the new backing file and only the intermediate portion of the chain is
1102 pulled. Once all requested data from the backing image chain has been
1103 pulled, the disk no longer depends on that portion of the backing
1104 chain.
1105 By default, this command returns as soon as possible, and data for the
1107 entire disk is pulled in the background; the progress of the operation
1108 can be checked with blockjob. However, if --wait is specified, then
1109 this command will block until the operation completes, or cancel the
1110 operation if the optional timeout in seconds elapses or SIGINT is sent
1111 (usually with Ctrl-C). Using --verbose along with --wait will produce
1112 periodic status updates. If job cancellation is triggered, --async
1113 will return control to the user as fast as possible, otherwise the com‐
1114 mand may continue to block a little while longer until the job is done
1115 cleaning up.
1116 Using the --keep-relative flag will keep the backing chain names rela‐
1118 tive.
1119 path specifies fully-qualified path of the disk; it corresponds to a
1121 unique target name (<target dev='name'/>) or source file (<source
1122 file='name'/>) for one of the disk devices attached to domain (see also
1123 domblklist for listing these names). bandwidth specifies copying band‐
1124 width limit in MiB/s. For further information on the bandwidth argument
1125 see the corresponding section for the blockjob command.
1126 blockresize
1128 Syntax:
1129 blockresize domain path size
1131 Resize a block device of domain while the domain is running, path spec‐
1133 ifies the absolute path of the block device; it corresponds to a unique
1134 target name (<target dev='name'/>) or source file (<source
1135 file='name'/>) for one of the disk devices attached to domain (see also
1136 domblklist for listing these names).
1137 size is a scaled integer (see NOTES above) which defaults to KiB
1139 (blocks of 1024 bytes) if there is no suffix. You must use a suffix of
1140 "B" to get bytes (note that for historical reasons, this differs from
1141 vol-resize which defaults to bytes without a suffix).
1142 console
1144 Syntax:
1145 console domain [devname] [--safe] [--force]
1147 Connect the virtual serial console for the guest. The optional devname
1149 parameter refers to the device alias of an alternate console, serial or
1150 parallel device configured for the guest. If omitted, the primary con‐
1151 sole will be opened.
1152 If the flag --safe is specified, the connection is only attempted if
1154 the driver supports safe console handling. This flag specifies that the
1155 server has to ensure exclusive access to console devices. Optionally
1156 the --force flag may be specified, requesting to disconnect any exist‐
1157 ing sessions, such as in a case of a broken connection.
1158 cpu-stats
1160 Syntax:
1161 cpu-stats domain [--total] [start] [count]
1163 Provide cpu statistics information of a domain. The domain should be
1165 running. Default it shows stats for all CPUs, and a total. Use --total
1166 for only the total stats, start for only the per-cpu stats of the CPUs
1167 from start, count for only count CPUs' stats.
1168 create
1170 Syntax:
1171 create FILE [--console] [--paused] [--autodestroy]
1173 [--pass-fds N,M,...] [--validate] [--reset-nvram]
1174 Create a domain from an XML <file>. Optionally, --validate option can
1176 be passed to validate the format of the input XML file against an in‐
1177 ternal RNG schema (identical to using virt-xml-validate(1) tool). Do‐
1178 mains created using this command are going to be either transient (tem‐
1179 porary ones that will vanish once destroyed) or existing persistent
1180 guests that will run with one-time use configuration, leaving the per‐
1181 sistent XML untouched (this can come handy during an automated testing
1182 of various configurations all based on the original XML). See the ex‐
1183 ample below for usage demonstration.
1184 The domain will be paused if the --paused option is used and supported
1186 by the driver; otherwise it will be running. If --console is requested,
1187 attach to the console after creation. If --autodestroy is requested,
1188 then the guest will be automatically destroyed when virsh closes its
1189 connection to libvirt, or otherwise exits.
1190 If --pass-fds is specified, the argument is a comma separated list of
1192 open file descriptors which should be pass on into the guest. The file
1193 descriptors will be re-numbered in the guest, starting from 3. This is
1194 only supported with container based virtualization.
1195 If --reset-nvram is specified, any existing NVRAM file will be deleted
1197 and re-initialized from its pristine template.
1198 Example:
1200 1. prepare a template from an existing domain (skip directly to 3a if
1202 writing one from scratch)
1203 # virsh dumpxml <domain> > domain.xml
1205 2. edit the template using an editor of your choice and:
1207 a. DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or
1209 b. DON'T CHANGE! either <name> or <uuid>
1211 # $EDITOR domain.xml
1213 3. create a domain from domain.xml, depending on whether following 2a
1215 or 2b respectively:
1216 a. the domain is going to be transient
1218 b. an existing persistent guest will run with a modified one-time
1220 configuration
1221 # virsh create domain.xml
1223 define
1225 Syntax:
1226 define FILE [--validate]
1228 Define a domain from an XML <file>. Optionally, the format of the input
1230 XML file can be validated against an internal RNG schema with --vali‐
1231 date (identical to using virt-xml-validate(1) tool). The domain defini‐
1232 tion is registered but not started. If domain is already running, the
1233 changes will take effect on the next boot.
1234 desc
1236 Syntax:
1237 desc domain [[--live] [--config] |
1239 [--current]] [--title] [--edit] [--new-desc
1240 New description or title message]
1241 Show or modify description and title of a domain. These values are user
1243 fields that allow storing arbitrary textual data to allow easy identi‐
1244 fication of domains. Title should be short, although it's not enforced.
1245 (See also metadata that works with XML based domain metadata.)
1246 Flags --live or --config select whether this command works on live or
1248 persistent definitions of the domain. If both --live and --config are
1249 specified, the --config option takes precedence on getting the current
1250 description and both live configuration and config are updated while
1251 setting the description. --current is exclusive and implied if none of
1252 these was specified.
1253 Flag --edit specifies that an editor with the contents of current de‐
1255 scription or title should be opened and the contents saved back after‐
1256 wards.
1257 Flag --title selects operation on the title field instead of descrip‐
1259 tion.
1260 If neither of --edit and --new-desc are specified the note or descrip‐
1262 tion is displayed instead of being modified.
1263 destroy
1265 Syntax:
1266 destroy domain [--graceful]
1268 Immediately terminate the domain domain. This doesn't give the domain
1270 OS any chance to react, and it's the equivalent of ripping the power
1271 cord out on a physical machine. In most cases you will want to use the
1272 shutdown command instead. However, this does not delete any storage
1273 volumes used by the guest, and if the domain is persistent, it can be
1274 restarted later.
1275 If domain is transient, then the metadata of any snapshots will be lost
1277 once the guest stops running, but the snapshot contents still exist,
1278 and a new domain with the same name and UUID can restore the snapshot
1279 metadata with snapshot-create. Similarly, the metadata of any check‐
1280 points will be lost, but can be restored with checkpoint-create.
1281 If --graceful is specified, don't resort to extreme measures (e.g.
1283 SIGKILL) when the guest doesn't stop after a reasonable timeout; return
1284 an error instead.
1285 domblkerror
1287 Syntax:
1288 domblkerror domain
1290 Show errors on block devices. This command usually comes handy when
1292 domstate command says that a domain was paused due to I/O error. The
1293 domblkerror command lists all block devices in error state and the er‐
1294 ror seen on each of them.
1295 domblkinfo
1297 Syntax:
1298 domblkinfo domain [block-device --all] [--human]
1300 Get block device size info for a domain. A block-device corresponds to
1302 a unique target name (<target dev='name'/>) or source file (<source
1303 file='name'/>) for one of the disk devices attached to domain (see also
1304 domblklist for listing these names). If --human is set, the output will
1305 have a human readable output. If --all is set, the output will be a
1306 table showing all block devices size info associated with domain. The
1307 --all option takes precedence of the others.
1308 domblklist
1310 Syntax:
1311 domblklist domain [--inactive] [--details]
1313 Print a table showing the brief information of all block devices asso‐
1315 ciated with domain. If --inactive is specified, query the block devices
1316 that will be used on the next boot, rather than those currently in use
1317 by a running domain. If --details is specified, disk type and device
1318 value will also be printed. Other contexts that require a block device
1319 name (such as domblkinfo or snapshot-create for disk snapshots) will
1320 accept either target or unique source names printed by this command.
1321 domblkstat
1323 Syntax:
1324 domblkstat domain [block-device] [--human]
1326 Get device block stats for a running domain. A block-device corre‐
1328 sponds to a unique target name (<target dev='name'/>) or source file
1329 (<source file='name'/>) for one of the disk devices attached to domain
1330 (see also domblklist for listing these names). On a LXC or QEMU domain,
1331 omitting the block-device yields device block stats summarily for the
1332 entire domain.
1333 Use --human for a more human readable output.
1335 Availability of these fields depends on hypervisor. Unsupported fields
1337 are missing from the output. Other fields may appear if communicating
1338 with a newer version of libvirtd.
1339 Explanation of fields (fields appear in the following order):
1341 • rd_req - count of read operations
1343 • rd_bytes - count of read bytes
1345 • wr_req - count of write operations
1347 • wr_bytes - count of written bytes
1349 • errs - error count
1351 • flush_operations - count of flush operations
1353 • rd_total_times - total time read operations took (ns)
1355 • wr_total_times - total time write operations took (ns)
1357 • flush_total_times - total time flush operations took (ns)
1359 • <-- other fields provided by hypervisor -->
1361 domblkthreshold
1363 Syntax:
1364 domblkthreshold domain dev threshold
1366 Set the threshold value for delivering the block-threshold event. dev
1368 specifies the disk device target or backing chain element of given de‐
1369 vice using the 'target[1]' syntax. threshold is a scaled value of the
1370 offset. If the block device should write beyond that offset the event
1371 will be delivered.
1372 domcontrol
1374 Syntax:
1375 domcontrol domain
1377 Returns state of an interface to VMM used to control a domain. For
1379 states other than "ok" or "error" the command also prints number of
1380 seconds elapsed since the control interface entered its current state.
1381 domdirtyrate-calc
1383 Syntax:
1384 domdirtyrate-calc <domain> [--seconds <sec>]
1386 --mode=[page-sampling | dirty-bitmap | dirty-ring]
1387 Calculate an active domain's memory dirty rate which may be expected by
1389 user in order to decide whether it's proper to be migrated out or not.
1390 The seconds parameter can be used to calculate dirty rate in a specific
1391 time which allows 60s at most now and would be default to 1s if miss‐
1392 ing. These three page-sampling, dirty-bitmap, dirty-ring modes are mu‐
1393 tually exclusive and alternative when specify calculation mode,
1394 page-sampling is the default mode if missing. The calculated dirty rate
1395 information is available by calling 'domstats --dirtyrate'.
1396 domdisplay
1398 Syntax:
1399 domdisplay domain [--include-password] [[--type] type] [--all]
1401 Output a URI which can be used to connect to the graphical display of
1403 the domain via VNC, SPICE or RDP. The particular graphical display
1404 type can be selected using the type parameter (e.g. "vnc", "spice",
1405 "rdp"). If --include-password is specified, the SPICE channel password
1406 will be included in the URI. If --all is specified, then all show all
1407 possible graphical displays, for a VM could have more than one graphi‐
1408 cal displays.
1409 domfsfreeze
1411 Syntax:
1412 domfsfreeze domain [[--mountpoint] mountpoint...]
1414 Freeze mounted filesystems within a running domain to prepare for con‐
1416 sistent snapshots.
1417 The --mountpoint option takes a parameter mountpoint, which is a mount
1419 point path of the filesystem to be frozen. This option can occur multi‐
1420 ple times. If this is not specified, every mounted filesystem is
1421 frozen.
1422 Note: snapshot-create command has a --quiesce option to freeze and thaw
1424 the filesystems automatically to keep snapshots consistent. domfs‐
1425 freeze command is only needed when a user wants to utilize the native
1426 snapshot features of storage devices not supported by libvirt.
1427 domfsinfo
1429 Syntax:
1430 domfsinfo domain
1432 Show a list of mounted filesystems within the running domain. The list
1434 contains mountpoints, names of a mounted device in the guest, filesys‐
1435 tem types, and unique target names used in the domain XML (<target
1436 dev='name'/>).
1437 Note that this command requires a guest agent configured and running in
1439 the domain's guest OS.
1440 domfsthaw
1442 Syntax:
1443 domfsthaw domain [[--mountpoint] mountpoint...]
1445 Thaw mounted filesystems within a running domain, which have been
1447 frozen by domfsfreeze command.
1448 The --mountpoint option takes a parameter mountpoint, which is a mount
1450 point path of the filesystem to be thawed. This option can occur multi‐
1451 ple times. If this is not specified, every mounted filesystem is
1452 thawed.
1453 domfstrim
1455 Syntax:
1456 domfstrim domain [--minimum bytes] [--mountpoint mountPoint]
1458 Issue a fstrim command on all mounted filesystems within a running do‐
1460 main. It discards blocks which are not in use by the filesystem. If
1461 --minimum bytes is specified, it tells guest kernel length of contigu‐
1462 ous free range. Smaller than this may be ignored (this is a hint and
1463 the guest may not respect it). By increasing this value, the fstrim op‐
1464 eration will complete more quickly for filesystems with badly frag‐
1465 mented free space, although not all blocks will be discarded. The de‐
1466 fault value is zero, meaning "discard every free block". Moreover, if a
1467 user wants to trim only one mount point, it can be specified via op‐
1468 tional --mountpoint parameter.
1469 domhostname
1471 Syntax:
1472 domhostname domain [--source lease|agent]
1474 Returns the hostname of a domain, if the hypervisor makes it available.
1476 The --source argument specifies what data source to use for the host‐
1478 names, currently 'lease' to read DHCP leases or 'agent' to query the
1479 guest OS via an agent. If unspecified, driver returns the default
1480 method available (some drivers support only one type of source).
1481 domid
1483 Syntax:
1484 domid domain-name-or-uuid
1486 Convert a domain name (or UUID) to a domain id
1488 domif-getlink
1490 Syntax:
1491 domif-getlink domain interface-device [--config]
1493 Query link state of the domain's virtual interface. If --config is
1495 specified, query the persistent configuration, for compatibility pur‐
1496 poses, --persistent is alias of --config.
1497 interface-device can be the interface's target name or the MAC address.
1499 domif-setlink
1501 Syntax:
1502 domif-setlink domain interface-device state [--config]
1504 Modify link state of the domain's virtual interface. Possible values
1506 for state are "up" and "down". If --config is specified, only the per‐
1507 sistent configuration of the domain is modified, for compatibility pur‐
1508 poses, --persistent is alias of --config. interface-device can be the
1509 interface's target name or the MAC address.
1510 domifaddr
1512 Syntax:
1513 domifaddr domain [interface] [--full]
1515 [--source lease|agent|arp]
1516 Get a list of interfaces of a running domain along with their IP and
1518 MAC addresses, or limited output just for one interface if interface is
1519 specified. Note that interface can be driver dependent, it can be the
1520 name within guest OS or the name you would see in domain XML. Moreover,
1521 the whole command may require a guest agent to be configured for the
1522 queried domain under some hypervisors, notably QEMU.
1523 If --full is specified, the interface name and MAC address is always
1525 displayed when the interface has multiple IP addresses or aliases; oth‐
1526 erwise, only the interface name and MAC address is displayed for the
1527 first name and MAC address with "-" for the others using the same name
1528 and MAC address.
1529 The --source argument specifies what data source to use for the ad‐
1531 dresses, currently 'lease' to read DHCP leases, 'agent' to query the
1532 guest OS via an agent, or 'arp' to get IP from host's arp tables. If
1533 unspecified, 'lease' is the default.
1534 backup-begin
1536 Syntax:
1537 backup-begin domain [backupxml] [checkpointxml] [--reuse-external]
1539 Begin a new backup job. If backupxml is omitted, this defaults to a
1541 full backup using a push model to filenames generated by libvirt; sup‐
1542 plying XML allows fine-tuning such as requesting an incremental backup
1543 relative to an earlier checkpoint, controlling which disks participate
1544 or which filenames are involved, or requesting the use of a pull model
1545 backup. The backup-dumpxml command shows any resulting values assigned
1546 by libvirt. For more information on backup XML, see:
1547 https://libvirt.org/formatbackup.html
1548 If --reuse-external is used it instructs libvirt to reuse temporary and
1550 output files provided by the user in backupxml.
1551 If checkpointxml is specified, a second file with a top-level element
1553 of domaincheckpoint is used to create a simultaneous checkpoint, for
1554 doing a later incremental backup relative to the time the backup was
1555 created. See checkpoint-create for more details on checkpoints.
1556 This command returns as soon as possible, and the backup job runs in
1558 the background; the progress of a push model backup can be checked with
1559 domjobinfo or by waiting for an event with event (the progress of a
1560 pull model backup is under the control of whatever third party connects
1561 to the NBD export). The job is ended with domjobabort.
1562 backup-dumpxml
1564 Syntax:
1565 backup-dumpxml domain
1567 Output XML describing the current backup job.
1569 domiflist
1571 Syntax:
1572 domiflist domain [--inactive]
1574 Print a table showing the brief information of all virtual interfaces
1576 associated with domain. If --inactive is specified, query the virtual
1577 interfaces that will be used on the next boot, rather than those cur‐
1578 rently in use by a running domain. Other contexts that require a MAC
1579 address of virtual interface (such as detach-interface or
1580 domif-setlink) will accept the MAC address printed by this command.
1581 domifstat
1583 Syntax:
1584 domifstat domain interface-device
1586 Get network interface stats for a running domain. The network interface
1588 stats are only available for interfaces that have a physical source in‐
1589 terface. This does not include, for example, a 'user' interface type
1590 since it is a virtual LAN with NAT to the outside world. interface-de‐
1591 vice can be the interface target by name or MAC address.
1592 domiftune
1594 Syntax:
1595 domiftune domain interface-device [[--config] [--live] | [--current]]
1597 [*--inbound average,peak,burst,floor*]
1598 [*--outbound average,peak,burst*]
1599 Set or query the domain's network interface's bandwidth parameters.
1601 interface-device can be the interface's target name (<target
1602 dev='name'/>), or the MAC address.
1603 If no --inbound or --outbound is specified, this command will query and
1605 show the bandwidth settings. Otherwise, it will set the inbound or out‐
1606 bound bandwidth. average,peak,burst,floor is the same as in command at‐
1607 tach-interface. Values for average, peak and floor are expressed in
1608 kilobytes per second, while burst is expressed in kilobytes in a single
1609 burst at peak speed as described in the Network XML documentation at
1610 https://libvirt.org/formatnetwork.html#elementQoS.
1611 To clear inbound or outbound settings, use --inbound or --outbound re‐
1613 spectfully with average value of zero.
1614 If --live is specified, affect a running guest. If --config is speci‐
1616 fied, affect the next start of a persistent guest. If --current is
1617 specified, it is equivalent to either --live or --config, depending on
1618 the current state of the guest. Both --live and --config flags may be
1619 given, but --current is exclusive. If no flag is specified, behavior is
1620 different depending on hypervisor.
1621 dominfo
1623 Syntax:
1624 dominfo domain
1626 Returns basic information about the domain.
1628 domjobabort
1630 Syntax:
1631 domjobabort domain
1633 Abort the currently running domain job.
1635 domjobinfo
1637 Syntax:
1638 domjobinfo domain [--completed [--keep-completed]] [--anystats] [--rawstats]
1640 Returns information about jobs running on a domain. --completed tells
1642 virsh to return information about a recently finished job. Statistics
1643 of a completed job are automatically destroyed once read (unless
1644 --keep-completed is used) or when libvirtd is restarted.
1645 Normally only statistics for running and successful completed jobs are
1647 printed. --anystats can be used to also display statistics for failed
1648 jobs.
1649 In case --rawstats is used, all fields are printed as received from the
1651 server without any attempts to interpret the data. The "Job type:"
1652 field is special, since it's reported by the API and not part of stats.
1653 Note that time information returned for completed migrations may be
1655 completely irrelevant unless both source and destination hosts have
1656 synchronized time (i.e., NTP daemon is running on both of them).
1657 domlaunchsecinfo
1659 Syntax:
1660 domlaunchsecinfo domain
1662 Returns information about the launch security parameters associated
1664 with a running domain.
1665 The set of parameters reported will vary depending on which type of
1667 launch security protection is active. If none is active, no parameters
1668 will be reported.
1669 domsetlaunchsecstate
1671 Syntax:
1672 domsetlaunchsecstate domain --secrethdr hdr-filename
1674 --secret secret-filename [--set-address address]
1675 Set a launch security secret in the guest's memory. The guest must have
1677 a launchSecurity type enabled in its configuration and be in a paused
1678 state. On success, the guest can be transitioned to a running state.
1679 On failure, the guest should be destroyed.
1680 --secrethdr specifies a filename containing the base64-encoded secret
1682 header. The header includes artifacts needed by the hypervisor
1683 firmware to recover the plain text of the launch secret. --secret spec‐
1684 ifies the filename containing the base64-encoded encrypted launch se‐
1685 cret.
1686 The --set-address option can be used to specify a physical address
1688 within the guest's memory to set the secret. If not specified, the ad‐
1689 dress will be determined by the hypervisor.
1690 dommemstat
1692 Syntax:
1693 dommemstat domain [--period seconds] [[--config] [--live] | [--current]]
1695 Get memory stats for a running domain.
1697 Availability of these fields depends on hypervisor. Unsupported fields
1699 are missing from the output. Other fields may appear if communicating
1700 with a newer version of libvirtd.
1701 Explanation of fields:
1703 • swap_in - The amount of data read from swap space (in KiB)
1705 • swap_out - The amount of memory written out to swap space
1707 (in KiB)
1708 • major_fault - The number of page faults where disk IO was re‐
1710 quired
1711 • minor_fault - The number of other page faults
1713 • unused - The amount of memory left unused by the system
1715 (in KiB)
1716 • available - The amount of usable memory as seen by the domain
1718 (in KiB)
1719 • actual - Current balloon value (in KiB)
1721 • rss - Resident Set Size of the running domain's process
1723 (in KiB)
1724 • usable - The amount of memory which can be reclaimed by
1726 balloon without causing host swapping (in KiB)
1727 • last-update - Timestamp of the last update of statistics (in
1729 seconds)
1730 • disk_caches - The amount of memory that can be reclaimed with‐
1732 out additional I/O, typically disk caches (in KiB)
1733 • hugetlb_pgalloc - The number of successful huge page allocations
1735 initiated from within the domain
1736 • hugetlb_pgfail - The number of failed huge page allocations initi‐
1738 ated from within the domain
1739 For QEMU/KVM with a memory balloon, setting the optional --period to a
1741 value larger than 0 in seconds will allow the balloon driver to return
1742 additional statistics which will be displayed by subsequent dommemstat
1743 commands. Setting the --period to 0 will stop the balloon driver col‐
1744 lection, but does not clear the statistics in the balloon driver. Re‐
1745 quires at least QEMU/KVM 1.5 to be running on the host.
1746 The --live, --config, and --current flags are only valid when using the
1748 --period option in order to set the collection period for the balloon
1749 driver. If --live is specified, only the running guest collection pe‐
1750 riod is affected. If --config is specified, affect the next start of a
1751 persistent guest. If --current is specified, it is equivalent to either
1752 --live or --config, depending on the current state of the guest.
1753 Both --live and --config flags may be given, but --current is exclu‐
1755 sive. If no flag is specified, behavior is different depending on the
1756 guest state.
1757 domname
1759 Syntax:
1760 domname domain-id-or-uuid
1762 Convert a domain Id (or UUID) to domain name
1764 dompmsuspend
1766 Syntax:
1767 dompmsuspend domain target [--duration]
1769 Suspend a running domain into one of these states (possible target val‐
1771 ues):
1772 • mem - equivalent of S3 ACPI state
1774 • disk - equivalent of S4 ACPI state
1776 • hybrid - RAM is saved to disk but not powered off
1778 The --duration argument specifies number of seconds before the domain
1780 is woken up after it was suspended (see also dompmwakeup). Default is 0
1781 for unlimited suspend time. (This feature isn't currently supported by
1782 any hypervisor driver and 0 should be used.).
1783 Note that this command requires a guest agent configured and running in
1785 the domain's guest OS.
1786 Beware that at least for QEMU, the domain's process will be terminated
1788 when target disk is used and a new process will be launched when lib‐
1789 virt is asked to wake up the domain. As a result of this, any runtime
1790 changes, such as device hotplug or memory settings, are lost unless
1791 such changes were made with --config flag.
1792 dompmwakeup
1794 Syntax:
1795 dompmwakeup domain
1797 Wakeup a domain from pmsuspended state (either suspended by dompmsus‐
1799 pend or from the guest itself). Injects a wakeup into the guest that is
1800 in pmsuspended state, rather than waiting for the previously requested
1801 duration (if any) to elapse. This operation does not necessarily fail
1802 if the domain is running.
1803 domrename
1805 Syntax:
1806 domrename domain new-name
1808 Rename a domain. This command changes current domain name to the new
1810 name specified in the second argument.
1811 Note: Domain must be inactive.
1813 domstate
1815 Syntax:
1816 domstate domain [--reason]
1818 Returns state about a domain. --reason tells virsh to also print rea‐
1820 son for the state.
1821 domstats
1823 Syntax:
1824 domstats [--raw] [--enforce] [--backing] [--nowait] [--state]
1826 [--cpu-total] [--balloon] [--vcpu] [--interface]
1827 [--block] [--perf] [--iothread] [--memory] [--dirtyrate]
1828 [[--list-active] [--list-inactive]
1829 [--list-persistent] [--list-transient] [--list-running]y
1830 [--list-paused] [--list-shutoff] [--list-other]] | [domain ...]
1831 Get statistics for multiple or all domains. Without any argument this
1833 command prints all available statistics for all domains.
1834 The list of domains to gather stats for can be either limited by list‐
1836 ing the domains as a space separated list, or by specifying one of the
1837 filtering flags --list-NNN. (The approaches can't be combined.)
1838 By default some of the returned fields may be converted to more human
1840 friendly values by a set of pretty-printers. To suppress this behavior
1841 use the --raw flag.
1842 The individual statistics groups are selectable via specific flags. By
1844 default all supported statistics groups are returned. Supported statis‐
1845 tics groups flags are: --state, --cpu-total, --balloon, --vcpu, --in‐
1846 terface, --block, --perf, --iothread, --memory, --dirtyrate.
1847 Note that - depending on the hypervisor type and version or the domain
1849 state - not all of the following statistics may be returned.
1850 When selecting the --state group the following fields are returned:
1852 • state.state - state of the VM, returned as number from virDomainState
1854 enum
1855 • state.reason - reason for entering given state, returned as int from
1857 virDomain*Reason enum corresponding to given state
1858 --cpu-total returns:
1860 • cpu.time - total cpu time spent for this domain in nanoseconds
1862 • cpu.user - user cpu time spent in nanoseconds
1864 • cpu.system - system cpu time spent in nanoseconds
1866 • cpu.haltpoll.success.time - cpu halt polling success time spent in
1868 nanoseconds
1869 • cpu.haltpoll.fail.time - cpu halt polling fail time spent in nanosec‐
1871 onds
1872 • cpu.cache.monitor.count - the number of cache monitors for this do‐
1874 main
1875 • cpu.cache.monitor.<num>.name - the name of cache monitor <num>
1877 • cpu.cache.monitor.<num>.vcpus - vcpu list of cache monitor <num>
1879 • cpu.cache.monitor.<num>.bank.count - the number of cache banks in
1881 cache monitor <num>
1882 • cpu.cache.monitor.<num>.bank.<index>.id - host allocated cache id for
1884 bank <index> in cache monitor <num>
1885 • cpu.cache.monitor.<num>.bank.<index>.bytes - the number of bytes of
1887 last level cache that the domain is using on cache bank <index>
1888 --balloon returns:
1890 • balloon.current - the memory in KiB currently used
1892 • balloon.maximum - the maximum memory in KiB allowed
1894 • balloon.swap_in - the amount of data read from swap space (in KiB)
1896 • balloon.swap_out - the amount of memory written out to swap space (in
1898 KiB)
1899 • balloon.major_fault - the number of page faults when disk IO was re‐
1901 quired
1902 • balloon.minor_fault - the number of other page faults
1904 • balloon.unused - the amount of memory left unused by the system (in
1906 KiB)
1907 • balloon.available - the amount of usable memory as seen by the domain
1909 (in KiB)
1910 • balloon.rss - Resident Set Size of running domain's process (in KiB)
1912 • balloon.usable - the amount of memory which can be reclaimed by bal‐
1914 loon without causing host swapping (in KiB)
1915 • balloon.last-update - timestamp of the last update of statistics (in
1917 seconds)
1918 • balloon.disk_caches - the amount of memory that can be reclaimed
1920 without additional I/O, typically disk (in KiB)
1921 • balloon.hugetlb_pgalloc - the number of successful huge page alloca‐
1923 tions from inside the domain via virtio balloon
1924 • balloon.hugetlb_pgfail - the number of failed huge page allocations
1926 from inside the domain via virtio balloon
1927 --vcpu returns:
1929 • vcpu.current - current number of online virtual CPUs
1931 • vcpu.maximum - maximum number of online virtual CPUs
1933 • vcpu.<num>.state - state of the virtual CPU <num>, as number from
1935 virVcpuState enum
1936 • vcpu.<num>.time - virtual cpu time spent by virtual CPU <num> (in mi‐
1938 croseconds)
1939 • vcpu.<num>.wait - virtual cpu time spent by virtual CPU <num> waiting
1941 on I/O (in microseconds)
1942 • vcpu.<num>.halted - virtual CPU <num> is halted: yes or no (may indi‐
1944 cate the processor is idle or even disabled, depending on the archi‐
1945 tecture)
1946 • vcpu.<num>.delay - time the vCPU <num> thread was enqueued by the
1948 host scheduler, but was waiting in the queue instead of running. Ex‐
1949 posed to the VM as a steal time.
1950 --interface returns:
1952 • net.count - number of network interfaces on this domain
1954 • net.<num>.name - name of the interface <num>
1956 • net.<num>.rx.bytes - number of bytes received
1958 • net.<num>.rx.pkts - number of packets received
1960 • net.<num>.rx.errs - number of receive errors
1962 • net.<num>.rx.drop - number of receive packets dropped
1964 • net.<num>.tx.bytes - number of bytes transmitted
1966 • net.<num>.tx.pkts - number of packets transmitted
1968 • net.<num>.tx.errs - number of transmission errors
1970 • net.<num>.tx.drop - number of transmit packets dropped
1972 --perf returns the statistics of all enabled perf events:
1974 • perf.cmt - the cache usage in Byte currently used
1976 • perf.mbmt - total system bandwidth from one level of cache
1978 • perf.mbml - bandwidth of memory traffic for a memory controller
1980 • perf.cpu_cycles - the count of cpu cycles (total/elapsed)
1982 • perf.instructions - the count of instructions
1984 • perf.cache_references - the count of cache hits
1986 • perf.cache_misses - the count of caches misses
1988 • perf.branch_instructions - the count of branch instructions
1990 • perf.branch_misses - the count of branch misses
1992 • perf.bus_cycles - the count of bus cycles
1994 • perf.stalled_cycles_frontend - the count of stalled frontend cpu cy‐
1996 cles
1997 • perf.stalled_cycles_backend - the count of stalled backend cpu cycles
1999 • perf.ref_cpu_cycles - the count of ref cpu cycles
2001 • perf.cpu_clock - the count of cpu clock time
2003 • perf.task_clock - the count of task clock time
2005 • perf.page_faults - the count of page faults
2007 • perf.context_switches - the count of context switches
2009 • perf.cpu_migrations - the count of cpu migrations
2011 • perf.page_faults_min - the count of minor page faults
2013 • perf.page_faults_maj - the count of major page faults
2015 • perf.alignment_faults - the count of alignment faults
2017 • perf.emulation_faults - the count of emulation faults
2019 See the perf command for more details about each event.
2021 --block returns information about disks associated with each domain.
2023 Using the --backing flag extends this information to cover all re‐
2024 sources in the backing chain, rather than the default of limiting in‐
2025 formation to the active layer for each guest disk. Information listed
2026 includes:
2027 • block.count - number of block devices being listed
2029 • block.<num>.name - name of the target of the block device <num> (the
2031 same name for multiple entries if --backing is present)
2032 • block.<num>.backingIndex - when --backing is present, matches up with
2034 the <backingStore> index listed in domain XML for backing files
2035 • block.<num>.path - file source of block device <num>, if it is a lo‐
2037 cal file or block device
2038 • block.<num>.rd.reqs - number of read requests
2040 • block.<num>.rd.bytes - number of read bytes
2042 • block.<num>.rd.times - total time (ns) spent on reads
2044 • block.<num>.wr.reqs - number of write requests
2046 • block.<num>.wr.bytes - number of written bytes
2048 • block.<num>.wr.times - total time (ns) spent on writes
2050 • block.<num>.fl.reqs - total flush requests
2052 • block.<num>.fl.times - total time (ns) spent on cache flushing
2054 • block.<num>.errors - Xen only: the 'oo_req' value
2056 • block.<num>.allocation - offset of highest written sector in bytes
2058 • block.<num>.capacity - logical size of source file in bytes
2060 • block.<num>.physical - physical size of source file in bytes
2062 • block.<num>.threshold - threshold (in bytes) for delivering the
2064 VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event. See domblkthreshold.
2065 --iothread returns information about IOThreads on the running guest if
2067 supported by the hypervisor.
2068 The "poll-max-ns" for each thread is the maximum nanoseconds to allow
2070 each polling interval to occur. A polling interval is a period of time
2071 allowed for a thread to process data before being the guest gives up
2072 its CPU quantum back to the host. A value set too small will not allow
2073 the IOThread to run long enough on a CPU to process data. A value set
2074 too high will consume too much CPU time per IOThread failing to allow
2075 other threads running on the CPU to get time. The polling interval is
2076 not available for statistical purposes.
2077 •
2079 iothread.count - maximum number of IOThreads in the subsequent list
2081 as unsigned int. Each IOThread in the list will will use it's
2082 iothread_id value as the <id>. There may be fewer <id> entries
2083 than the iothread.count value if the polling values are not
2084 supported.
2085 • iothread.<id>.poll-max-ns - maximum polling time in nanoseconds used
2087 by the <id> IOThread. A value of 0 (zero) indicates polling is dis‐
2088 abled.
2089 • iothread.<id>.poll-grow - polling time grow value. A value of 0
2091 (zero) growth is managed by the hypervisor.
2092 • iothread.<id>.poll-shrink - polling time shrink value. A value of
2094 (zero) indicates shrink is managed by hypervisor.
2095 --memory returns:
2097 • memory.bandwidth.monitor.count - the number of memory bandwidth moni‐
2099 tors for this domain
2100 • memory.bandwidth.monitor.<num>.name - the name of monitor <num>
2102 • memory.bandwidth.monitor.<num>.vcpus - the vcpu list of monitor <num>
2104 •
2106 memory.bandwidth.monitor.<num>.node.count - the number of memory
2108 controller in monitor <num>
2109 • memory.bandwidth.monitor.<num>.node.<index>.id - host allocated mem‐
2111 ory controller id for controller <index> of monitor <num>
2112 • memory.bandwidth.monitor.<num>.node.<index>.bytes.local - the accumu‐
2114 lative bytes consumed by @vcpus that passing through the memory con‐
2115 troller in the same processor that the scheduled host CPU belongs to.
2116 • memory.bandwidth.monitor.<num>.node.<index>.bytes.total - the total
2118 bytes consumed by @vcpus that passing through all memory controllers,
2119 either local or remote controller.
2120 --dirtyrate returns:
2122 • dirtyrate.calc_status - the status of last memory dirty rate calcula‐
2124 tion, returned as number from virDomainDirtyRateStatus enum.
2125 • dirtyrate.calc_start_time - the start time of last memory dirty rate
2127 calculation.
2128 • dirtyrate.calc_period - the period of last memory dirty rate calcula‐
2130 tion.
2131 • dirtyrate.megabytes_per_second - the calculated memory dirty rate in
2133 MiB/s.
2134 Selecting a specific statistics groups doesn't guarantee that the dae‐
2136 mon supports the selected group of stats. Flag --enforce forces the
2137 command to fail if the daemon doesn't support the selected group.
2138 When collecting stats libvirtd may wait for some time if there's al‐
2140 ready another job running on given domain for it to finish. This may
2141 cause unnecessary delay in delivering stats. Using --nowait suppresses
2142 this behaviour. On the other hand some statistics might be missing for
2143 such domain.
2144 domtime
2146 Syntax:
2147 domtime domain { [--now] [--pretty] [--sync] [--time time] }
2149 Gets or sets the domain's system time. When run without any arguments
2151 (but domain), the current domain's system time is printed out. The
2152 --pretty modifier can be used to print the time in more human readable
2153 form.
2154 When --time time is specified, the domain's time is not gotten but set
2156 instead. The --now modifier acts like if it was an alias for --time
2157 $now, which means it sets the time that is currently on the host virsh
2158 is running at. In both cases (setting and getting), time is in seconds
2159 relative to Epoch of 1970-01-01 in UTC. The --sync modifies the set
2160 behavior a bit: The time passed is ignored, but the time to set is read
2161 from domain's RTC instead. Please note, that some hypervisors may re‐
2162 quire a guest agent to be configured in order to get or set the guest
2163 time.
2164 domuuid
2166 Syntax:
2167 domuuid domain-name-or-id
2169 Convert a domain name or id to domain UUID
2171 domxml-from-native
2173 Syntax:
2174 domxml-from-native format config
2176 Convert the file config in the native guest configuration format named
2178 by format to a domain XML format. For QEMU/KVM hypervisor, the format
2179 argument must be qemu-argv. For Xen hypervisor, the format argument may
2180 be xen-xm, xen-xl, or xen-sxpr. For LXC hypervisor, the format argument
2181 must be lxc-tools. For VMware/ESX hypervisor, the format argument must
2182 be vmware-vmx. For the Bhyve hypervisor, the format argument must be
2183 bhyve-argv.
2184 domxml-to-native
2186 Syntax:
2187 domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-uuid }
2189 Convert the file xml into domain XML format or convert an existing
2191 --domain to the native guest configuration format named by format. The
2192 xml and --domain arguments are mutually exclusive. For the types of
2193 format argument, refer to domxml-from-native.
2194 dump
2196 Syntax:
2197 dump domain corefilepath [--bypass-cache]
2199 { [--live] | [--crash] | [--reset] }
2200 [--verbose] [--memory-only] [--format string]
2201 Dumps the core of a domain to a file for analysis. If --live is speci‐
2203 fied, the domain continues to run until the core dump is complete,
2204 rather than pausing up front. If --crash is specified, the domain is
2205 halted with a crashed status, rather than merely left in a paused
2206 state. If --reset is specified, the domain is reset after successful
2207 dump. Note, these three switches are mutually exclusive. If --by‐
2208 pass-cache is specified, the save will avoid the file system cache, al‐
2209 though this may slow down the operation. If --memory-only is speci‐
2210 fied, the file is elf file, and will only include domain's memory and
2211 cpu common register value. It is very useful if the domain uses host
2212 devices directly. --format string is used to specify the format of
2213 'memory-only' dump, and string can be one of: elf,
2214 kdump-zlib(kdump-compressed format with zlib-compressed),
2215 kdump-lzo(kdump-compressed format with lzo-compressed),
2216 kdump-snappy(kdump-compressed format with snappy-compressed),
2217 win-dmp(Windows full crashdump format).
2218 The progress may be monitored using domjobinfo virsh command and can‐
2220 celed with domjobabort command (sent by another virsh instance). An‐
2221 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2222 process running dump command. --verbose displays the progress of dump.
2223 NOTE: Some hypervisors may require the user to manually ensure proper
2225 permissions on file and path specified by argument corefilepath.
2226 NOTE: Crash dump in a old kvmdump format is being obsolete and cannot
2228 be loaded and processed by crash utility since its version 6.1.0. A
2229 --memory-only option is required in order to produce valid ELF file
2230 which can be later processed by the crash utility.
2231 dumpxml
2233 Syntax:
2234 dumpxml domain [--inactive] [--security-info] [--update-cpu] [--migratable]
2236 Output the domain information as an XML dump to stdout, this format can
2238 be used by the create command. Additional options affecting the XML
2239 dump may be used. --inactive tells virsh to dump domain configuration
2240 that will be used on next start of the domain as opposed to the current
2241 domain configuration. Using --security-info will also include security
2242 sensitive information in the XML dump. --update-cpu updates domain CPU
2243 requirements according to host CPU. With --migratable one can request
2244 an XML that is suitable for migrations, i.e., compatible with older
2245 libvirt releases and possibly amended with internal run-time options.
2246 This option may automatically enable other options (--update-cpu, --se‐
2247 curity-info, ...) as necessary.
2248 edit
2250 Syntax:
2251 edit domain
2253 Edit the XML configuration file for a domain, which will affect the
2255 next boot of the guest.
2256 This is equivalent to:
2258 virsh dumpxml --inactive --security-info domain > domain.xml
2260 vi domain.xml (or make changes with your other text editor)
2261 virsh define domain.xml
2262 except that it does some error checking.
2264 The editor used can be supplied by the $VISUAL or $EDITOR environment
2266 variables, and defaults to vi.
2267 emulatorpin
2269 Syntax:
2270 emulatorpin domain [cpulist] [[--live] [--config] | [--current]]
2272 Query or change the pinning of domain's emulator threads to host physi‐
2274 cal CPUs.
2275 See vcpupin for cpulist.
2277 If --live is specified, affect a running guest. If --config is speci‐
2279 fied, affect the next start of a persistent guest. If --current is
2280 specified, it is equivalent to either --live or --config, depending on
2281 the current state of the guest. Both --live and --config flags may be
2282 given if cpulist is present, but --current is exclusive. If no flag is
2283 specified, behavior is different depending on hypervisor.
2284 event
2286 Syntax:
2287 event {[domain] { event | --all } [--loop] [--timeout seconds] [--timestamp] | --list}
2289 Wait for a class of domain events to occur, and print appropriate de‐
2291 tails of events as they happen. The events can optionally be filtered
2292 by domain. Using --list as the only argument will provide a list of
2293 possible event values known by this client, although the connection
2294 might not allow registering for all these events. It is also possible
2295 to use --all instead of event to register for all possible event types
2296 at once.
2297 By default, this command is one-shot, and returns success once an event
2299 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
2300 If --timeout is specified, the command gives up waiting for events af‐
2301 ter seconds have elapsed. With --loop, the command prints all events
2302 until a timeout or interrupt key.
2303 When --timestamp is used, a human-readable timestamp will be printed
2305 before the event.
2306 get-user-sshkeys
2308 Syntax:
2309 get-user-sshkeys domain user
2311 Print SSH authorized keys for given user in the guest domain. Please
2313 note, that an entry in the file has internal structure as defined by
2314 sshd(8) and virsh/libvirt does handle keys as opaque strings, i.e. does
2315 not interpret them.
2316 guest-agent-timeout
2318 Syntax:
2319 guest-agent-timeout domain [--timeout value]
2321 Set how long to wait for a response from guest agent commands. By de‐
2323 fault, agent commands block forever waiting for a response. value must
2324 be a positive value (wait for given amount of seconds) or one of the
2325 following values:
2326 • -2 - block forever waiting for a result (used when --timeout is omit‐
2328 ted),
2329 • -1 - reset timeout to the default value (currently defined as 5 sec‐
2331 onds in libvirt daemon),
2332 • 0 - do not wait at all,
2334 guestinfo
2336 Syntax:
2337 guestinfo domain [--user] [--os] [--timezone] [--hostname] [--filesystem]
2339 [--disk] [--interface]
2340 Print information about the guest from the point of view of the guest
2342 agent. Note that this command requires a guest agent to be configured
2343 and running in the domain's guest OS.
2344 When run without any arguments, this command prints all information
2346 types that are supported by the guest agent at that point, omitting un‐
2347 available ones. Success is always reported in this case.
2348 You can limit the types of information that are returned by specifying
2350 one or more flags. Available information types flags are --user, --os,
2351 --timezone, --hostname, --filesystem, --disk and --interface. If an
2352 explicitly requested information type is not supported by the guest
2353 agent at that point, the processes will provide an exit code of 1.
2354 Note that depending on the hypervisor type and the version of the guest
2356 agent running within the domain, not all of the following information
2357 may be returned.
2358 When selecting the --user information type, the following fields may be
2360 returned:
2361 • user.count - the number of active users on this domain
2363 • user.<num>.name - username of user <num>
2365 • user.<num>.domain - domain of the user <num> (may only be present on
2367 certain guets types)
2368 • user.<num>.login-time - the login time of user <num> in milliseconds
2370 since the epoch
2371 --os returns:
2373 • os.id - a string identifying the operating system
2375 • os.name - the name of the operating system
2377 • os.pretty-name - a pretty name for the operating system
2379 • os.version - the version of the operating system
2381 • os.version-id - the version id of the operating system
2383 • os.kernel-release - the release of the operating system kernel
2385 • os.kernel-version - the version of the operating system kernel
2387 • os.machine - the machine hardware name
2389 • os.variant - a specific variant or edition of the operating system
2391 • os.variant-id - the id for a specific variant or edition of the oper‐
2393 ating system
2394 --timezone returns:
2396 • timezone.name - the name of the timezone
2398 • timezone.offset - the offset to UTC in seconds
2400 --hostname returns:
2402 • hostname - the hostname of the domain
2404 --filesystem returns:
2406 • fs.count - the number of filesystems defined on this domain
2408 • fs.<num>.mountpoint - the path to the mount point for filesystem
2410 <num>
2411 • fs.<num>.name - device name in the guest (e.g. sda1) for filesystem
2413 <num>
2414 • fs.<num>.fstype - the type of filesystem <num>
2416 • fs.<num>.total-bytes - the total size of filesystem <num>
2418 • fs.<num>.used-bytes - the number of bytes used in filesystem <num>
2420 • fs.<num>.disk.count - the number of disks targeted by filesystem
2422 <num>
2423 • fs.<num>.disk.<num>.alias - the device alias of disk <num> (e.g. sda)
2425 • fs.<num>.disk.<num>.serial - the serial number of disk <num>
2427 • fs.<num>.disk.<num>.device - the device node of disk <num>
2429 --disk returns:
2431 • disk.count - the number of disks defined on this domain
2433 • disk.<num>.name - device node (Linux) or device UNC (Windows)
2435 • disk.<num>.partition - whether this is a partition or disk
2437 • disk.<num>.dependency.count - the number of device dependencies
2439 • disk.<num>.dependency.<num>.name - a dependency name
2441 • disk.<num>.serial - optional disk serial number
2443 • disk.<num>.alias - the device alias of the disk (e.g. sda)
2445 • disk.<num>.guest_alias - optional alias assigned to the disk
2447 --interface returns: * if.count - the number of interfaces defined on
2449 this domain * if.<num>.name - name in the guest (e.g. eth0) for inter‐
2450 face <num> * if.<num>.hwaddr - hardware address in the guest for inter‐
2451 face <num> * if.<num>.addr.count - the number of IP addresses of inter‐
2452 face <num> * if.<num>.addr.<num1>.type - the IP address type of addr
2453 <num1> (e.g. ipv4) * if.<num>.addr.<num1>.addr - the IP address of addr
2454 <num1> * if.<num>.addr.<num1>.prefix - the prefix of IP address of addr
2455 <num1>
2456 guestvcpus
2458 Syntax:
2459 guestvcpus domain [[--enable] | [--disable]] [cpulist]
2461 Query or change state of vCPUs from guest's point of view using the
2463 guest agent. When invoked without cpulist the guest is queried for
2464 available guest vCPUs, their state and possibility to be offlined.
2465 If cpulist is provided then one of --enable or --disable must be pro‐
2467 vided too. The desired operation is then executed on the domain.
2468 See vcpupin for information on cpulist.
2470 iothreadadd
2472 Syntax:
2473 iothreadadd domain iothread_id [[--config] [--live] | [--current]]
2475 Add a new IOThread to the domain using the specified iothread_id. If
2477 the iothread_id already exists, the command will fail. The iothread_id
2478 must be greater than zero.
2479 If --live is specified, affect a running guest. If the guest is not
2481 running an error is returned. If --config is specified, affect the
2482 next start of a persistent guest. If --current is specified, it is
2483 equivalent to either --live or --config, depending on the current state
2484 of the guest.
2485 iothreaddel
2487 Syntax:
2488 iothreaddel domain iothread_id [[--config] [--live] | [--current]]
2490 Delete an IOThread from the domain using the specified iothread_id. If
2492 an IOThread is currently assigned to a disk resource such as via the
2493 attach-disk command, then the attempt to remove the IOThread will fail.
2494 If the iothread_id does not exist an error will occur.
2495 If --live is specified, affect a running guest. If the guest is not
2497 running an error is returned. If --config is specified, affect the
2498 next start of a persistent guest. If --current is specified, it is
2499 equivalent to either --live or --config, depending on the current state
2500 of the guest.
2501 iothreadinfo
2503 Syntax:
2504 iothreadinfo domain [[--live] [--config] | [--current]]
2506 Display basic domain IOThreads information including the IOThread ID
2508 and the CPU Affinity for each IOThread.
2509 If --live is specified, get the IOThreads data from the running guest.
2511 If the guest is not running, an error is returned. If --config is
2512 specified, get the IOThreads data from the next start of a persistent
2513 guest. If --current is specified or --live and --config are not speci‐
2514 fied, then get the IOThread data based on the current guest state,
2515 which can either be live or offline.
2516 iothreadpin
2518 Syntax:
2519 iothreadpin domain iothread cpulist [[--live] [--config] | [--current]]
2521 Change the pinning of a domain IOThread to host physical CPUs. In order
2523 to retrieve a list of all IOThreads, use iothreadinfo. To pin an io‐
2524 thread specify the cpulist desired for the IOThread ID as listed in the
2525 iothreadinfo output.
2526 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
2528 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
2529 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
2530 clusive. If you want to reset iothreadpin setting, that is, to pin an
2531 iothread to all physical cpus, simply specify 'r' as a cpulist.
2532 If --live is specified, affect a running guest. If the guest is not
2534 running, an error is returned. If --config is specified, affect the
2535 next start of a persistent guest. If --current is specified, it is
2536 equivalent to either --live or --config, depending on the current state
2537 of the guest. Both --live and --config flags may be given if cpulist
2538 is present, but --current is exclusive. If no flag is specified, be‐
2539 havior is different depending on hypervisor.
2540 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
2542 cal to "9-14,0-7,15" but not identical to "^8,0-15".
2543 iothreadset
2545 Syntax:
2546 iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor]
2548 [--poll-shrink divisor]]
2549 [[--config] [--live] | [--current]]
2550 Modifies an existing iothread of the domain using the specified io‐
2552 thread_id. The --poll-max-ns provides the maximum polling interval to
2553 be allowed for an IOThread in ns. If a 0 (zero) is provided, then
2554 polling for the IOThread is disabled. The --poll-grow is the factor by
2555 which the current polling time will be adjusted in order to reach the
2556 maximum polling time. If a 0 (zero) is provided, then the default fac‐
2557 tor will be used. The --poll-shrink is the quotient by which the cur‐
2558 rent polling time will be reduced in order to get below the maximum
2559 polling interval. If a 0 (zero) is provided, then the default quotient
2560 will be used. The polling values are purely dynamic for a running
2561 guest. Saving, destroying, stopping, etc. the guest will result in the
2562 polling values returning to hypervisor defaults at the next start, re‐
2563 store, etc.
2564 If --live is specified, affect a running guest. If the guest is not
2566 running an error is returned. If --current is specified or --live is
2567 not specified, then handle as if --live was specified. (Where "cur‐
2568 rent" here means whatever the present guest state is: live or offline.)
2569 managedsave
2571 Syntax:
2572 managedsave domain [--bypass-cache] [{--running | --paused}] [--verbose]
2574 Save and destroy (stop) a running domain, so it can be restarted from
2576 the same state at a later time. When the virsh start command is next
2577 run for the domain, it will automatically be started from this saved
2578 state. If --bypass-cache is specified, the save will avoid the file
2579 system cache, although this may slow down the operation.
2580 The progress may be monitored using domjobinfo virsh command and can‐
2582 celed with domjobabort command (sent by another virsh instance). An‐
2583 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2584 process running managedsave command. --verbose displays the progress of
2585 save.
2586 Normally, starting a managed save will decide between running or paused
2588 based on the state the domain was in when the save was done; passing
2589 either the --running or --paused flag will allow overriding which state
2590 the start should use.
2591 The dominfo command can be used to query whether a domain currently has
2593 any managed save image.
2594 managedsave-define
2596 Syntax:
2597 managedsave-define domain xml [{--running | --paused}]
2599 Update the domain XML that will be used when domain is later started.
2601 The xml argument must be a file name containing the alternative XML,
2602 with changes only in the host-specific portions of the domain XML. For
2603 example, it can be used to change disk file paths.
2604 The managed save image records whether the domain should be started to
2606 a running or paused state. Normally, this command does not alter the
2607 recorded state; passing either the --running or --paused flag will al‐
2608 low overriding which state the start should use.
2609 managedsave-dumpxml
2611 Syntax:
2612 managedsave-dumpxml domain [--security-info]
2614 Extract the domain XML that was in effect at the time the saved state
2616 file file was created with the managedsave command. Using --secu‐
2617 rity-info will also include security sensitive information.
2618 managedsave-edit
2620 Syntax:
2621 managedsave-edit domain [{--running | --paused}]
2623 Edit the XML configuration associated with a saved state file of a do‐
2625 main was created by the managedsave command.
2626 The managed save image records whether the domain should be started to
2628 a running or paused state. Normally, this command does not alter the
2629 recorded state; passing either the --running or --paused flag will al‐
2630 low overriding which state the restore should use.
2631 This is equivalent to:
2633 virsh managedsave-dumpxml domain-name > state-file.xml
2635 vi state-file.xml (or make changes with your other text editor)
2636 virsh managedsave-define domain-name state-file-xml
2637 except that it does some error checking.
2639 The editor used can be supplied by the $VISUAL or $EDITOR environment
2641 variables, and defaults to vi.
2642 managedsave-remove
2644 Syntax:
2645 managedsave-remove domain
2647 Remove the managedsave state file for a domain, if it exists. This en‐
2649 sures the domain will do a full boot the next time it is started.
2650 maxvcpus
2652 Syntax:
2653 maxvcpus [type]
2655 Provide the maximum number of virtual CPUs supported for a guest VM on
2657 this connection. If provided, the type parameter must be a valid type
2658 attribute for the <domain> element of XML.
2659 memtune
2661 Syntax:
2662 memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-limit size]
2664 [--min-guarantee size] [[--config] [--live] | [--current]]
2665 Allows you to display or set the domain memory parameters. Without
2667 flags, the current settings are displayed; with a flag, the appropriate
2668 limit is adjusted if supported by the hypervisor. LXC and QEMU/KVM
2669 support --hard-limit, --soft-limit, and --swap-hard-limit. --min-guar‐
2670 antee is supported only by ESX hypervisor. Each of these limits are
2671 scaled integers (see NOTES above), with a default of kibibytes (blocks
2672 of 1024 bytes) if no suffix is present. Libvirt rounds up to the near‐
2673 est kibibyte. Some hypervisors require a larger granularity than KiB,
2674 and requests that are not an even multiple will be rounded up. For ex‐
2675 ample, vSphere/ESX rounds the parameter up to mebibytes (1024
2676 kibibytes).
2677 If --live is specified, affect a running guest. If --config is speci‐
2679 fied, affect the next start of a persistent guest. If --current is
2680 specified, it is equivalent to either --live or --config, depending on
2681 the current state of the guest. Both --live and --config flags may be
2682 given, but --current is exclusive. If no flag is specified, behavior is
2683 different depending on hypervisor.
2684 For QEMU/KVM, the parameters are applied to the QEMU process as a
2686 whole. Thus, when counting them, one needs to add up guest RAM, guest
2687 video RAM, and some memory overhead of QEMU itself. The last piece is
2688 hard to determine so one needs guess and try.
2689 For LXC, the displayed hard_limit value is the current memory setting
2691 from the XML or the results from a virsh setmem command.
2692 • --hard-limit
2694 The maximum memory the guest can use.
2696 • --soft-limit
2698 The memory limit to enforce during memory contention.
2700 • --swap-hard-limit
2702 The maximum memory plus swap the guest can use. This has to be more
2704 than hard-limit value provided.
2705 • --min-guarantee
2707 The guaranteed minimum memory allocation for the guest.
2709 Specifying -1 as a value for these limits is interpreted as unlimited.
2711 metadata
2713 Syntax:
2714 metadata domain [[--live] [--config] | [--current]]
2716 [--edit] [uri] [key] [set] [--remove]
2717 Show or modify custom XML metadata of a domain. The metadata is a user
2719 defined XML that allows storing arbitrary XML data in the domain defi‐
2720 nition. Multiple separate custom metadata pieces can be stored in the
2721 domain XML. The pieces are identified by a private XML namespace pro‐
2722 vided via the uri argument. (See also desc that works with textual
2723 metadata of a domain.)
2724 Flags --live or --config select whether this command works on live or
2726 persistent definitions of the domain. If both --live and --config are
2727 specified, the --config option takes precedence on getting the current
2728 description and both live configuration and config are updated while
2729 setting the description. --current is exclusive and implied if none of
2730 these was specified.
2731 Flag --remove specifies that the metadata element specified by the uri
2733 argument should be removed rather than updated.
2734 Flag --edit specifies that an editor with the metadata identified by
2736 the uri argument should be opened and the contents saved back after‐
2737 wards. Otherwise the new contents can be provided via the set argu‐
2738 ment.
2739 When setting metadata via --edit or set the key argument must be speci‐
2741 fied and is used to prefix the custom elements to bind them to the pri‐
2742 vate namespace.
2743 If neither of --edit and set are specified the XML metadata correspond‐
2745 ing to the uri namespace is displayed instead of being modified.
2746 migrate
2748 Syntax:
2749 migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]]
2751 [--persistent] [--undefinesource] [--suspend] [--copy-storage-all]
2752 [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose]
2753 [--rdma-pin-all] [--abort-on-error] [--postcopy] [--postcopy-after-precopy]
2754 domain desturi [migrateuri] [graphicsuri] [listen-address] [dname]
2755 [--timeout seconds [--timeout-suspend | --timeout-postcopy]]
2756 [--xml file] [--migrate-disks disk-list] [--disks-port port]
2757 [--compressed] [--comp-methods method-list]
2758 [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads]
2759 [--comp-xbzrle-cache] [--auto-converge] [auto-converge-initial]
2760 [auto-converge-increment] [--persistent-xml file] [--tls]
2761 [--postcopy-bandwidth bandwidth]
2762 [--parallel [--parallel-connections connections]]
2763 [--bandwidth bandwidth] [--tls-destination hostname]
2764 [--disks-uri URI] [--copy-storage-synchronous-writes]
2765 Migrate domain to another host. Add --live for live migration; <--p2p>
2767 for peer-2-peer migration; --direct for direct migration; or --tun‐
2768 nelled for tunnelled migration. --offline migrates domain definition
2769 without starting the domain on destination and without stopping it on
2770 source host. Offline migration may be used with inactive domains and
2771 it must be used with --persistent option.
2772 --persistent leaves the domain persistent on destination host, --unde‐
2774 finesource undefines the domain on the source host, and --suspend
2775 leaves the domain paused on the destination host.
2776 --copy-storage-all indicates migration with non-shared storage with
2778 full disk copy, --copy-storage-inc indicates migration with non-shared
2779 storage with incremental copy (same base image shared between source
2780 and destination). In both cases the disk images have to exist on des‐
2781 tination host, the --copy-storage-... options only tell libvirt to
2782 transfer data from the images on source host to the images found at the
2783 same place on the destination host. By default only non-shared
2784 non-readonly images are transferred. Use --migrate-disks to explicitly
2785 specify a list of disk targets to transfer via the comma separated
2786 disk-list argument. With --copy-storage-synchronous-writes flag used
2787 the disk data migration will synchronously handle guest disk writes to
2788 both the original source and the destination to ensure that the disk
2789 migration converges at the price of possibly decreased burst perfor‐
2790 mance.
2791 --change-protection enforces that no incompatible configuration changes
2793 will be made to the domain while the migration is underway; this flag
2794 is implicitly enabled when supported by the hypervisor, but can be ex‐
2795 plicitly used to reject the migration if the hypervisor lacks change
2796 protection support.
2797 --verbose displays the progress of migration.
2799 --abort-on-error cancels the migration if a soft error (for example I/O
2801 error) happens during the migration.
2802 --postcopy enables post-copy logic in migration, but does not actually
2804 start post-copy, i.e., migration is started in pre-copy mode. Once mi‐
2805 gration is running, the user may switch to post-copy using the mi‐
2806 grate-postcopy command sent from another virsh instance or use --post‐
2807 copy-after-precopy along with --postcopy to let libvirt automatically
2808 switch to post-copy after the first pass of pre-copy is finished. The
2809 maximum bandwidth consumed during the post-copy phase may be limited
2810 using --postcopy-bandwidth. The maximum bandwidth consumed during the
2811 pre-copy phase may be limited using --bandwidth.
2812 --auto-converge forces convergence during live migration. The initial
2814 guest CPU throttling rate can be set with auto-converge-initial. If the
2815 initial throttling rate is not enough to ensure convergence, the rate
2816 is periodically increased by auto-converge-increment.
2817 --rdma-pin-all can be used with RDMA migration (i.e., when migrateuri
2819 starts with rdma://) to tell the hypervisor to pin all domain's memory
2820 at once before migration starts rather than letting it pin memory pages
2821 as needed. For QEMU/KVM this requires hard_limit memory tuning element
2822 (in the domain XML) to be used and set to the maximum memory configured
2823 for the domain plus any memory consumed by the QEMU process itself. Be‐
2824 ware of setting the memory limit too high (and thus allowing the domain
2825 to lock most of the host's memory). Doing so may be dangerous to both
2826 the domain and the host itself since the host's kernel may run out of
2827 memory.
2828 Note: Individual hypervisors usually do not support all possible types
2830 of migration. For example, QEMU does not support direct migration.
2831 In some cases libvirt may refuse to migrate the domain because doing so
2833 may lead to potential problems such as data corruption, and thus the
2834 migration is considered unsafe. For QEMU domain, this may happen if the
2835 domain uses disks without explicitly setting cache mode to "none". Mi‐
2836 grating such domains is unsafe unless the disk images are stored on co‐
2837 herent clustered filesystem, such as GFS2 or GPFS. If you are sure the
2838 migration is safe or you just do not care, use --unsafe to force the
2839 migration.
2840 dname is used for renaming the domain to new name during migration,
2842 which also usually can be omitted. Likewise, --xml file is usually
2843 omitted, but can be used to supply an alternative XML file for use on
2844 the destination to supply a larger set of changes to any host-specific
2845 portions of the domain XML, such as accounting for naming differences
2846 between source and destination in accessing underlying storage. If
2847 --persistent is enabled, --persistent-xml file can be used to supply an
2848 alternative XML file which will be used as the persistent guest defini‐
2849 tion on the destination host.
2850 --timeout seconds tells virsh to run a specified action when live mi‐
2852 gration exceeds that many seconds. It can only be used with --live.
2853 If --timeout-suspend is specified, the domain will be suspended after
2854 the timeout and the migration will complete offline; this is the de‐
2855 fault if no --timeout-\`` option is specified on the command line.
2856 When *--timeout-postcopy is used, virsh will switch migration from
2857 pre-copy to post-copy upon timeout; migration has to be started with
2858 --postcopy option for this to work.
2859 --compressed activates compression, the compression method is chosen
2861 with --comp-methods. Supported methods are "mt" and "xbzrle" and can be
2862 used in any combination. When no methods are specified, a hypervisor
2863 default methods will be used. QEMU defaults to "xbzrle". Compression
2864 methods can be tuned further. --comp-mt-level sets compression level.
2865 Values are in range from 0 to 9, where 1 is maximum speed and 9 is max‐
2866 imum compression. --comp-mt-threads and --comp-mt-dthreads set the num‐
2867 ber of compress threads on source and the number of decompress threads
2868 on target respectively. --comp-xbzrle-cache sets size of page cache in
2869 bytes.
2870 Providing --tls causes the migration to use the host configured TLS
2872 setup (see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in or‐
2873 der to perform the migration of the domain. Usage requires proper TLS
2874 setup for both source and target. Normally the TLS certificate from the
2875 destination host must match the host's name for TLS verification to
2876 succeed. When the certificate does not match the destination hostname
2877 and the expected certificate's hostname is known, --tls-destination can
2878 be used to pass the expected hostname when starting the migration.
2879 --parallel option will cause migration data to be sent over multiple
2881 parallel connections. The number of such connections can be set using
2882 --parallel-connections. Parallel connections may help with saturating
2883 the network link between the source and the target and thus speeding up
2884 the migration.
2885 Running migration can be canceled by interrupting virsh (usually using
2887 Ctrl-C) or by domjobabort command sent from another virsh instance.
2888 The desturi and migrateuri parameters can be used to control which des‐
2890 tination the migration uses. desturi is important for managed migra‐
2891 tion, but unused for direct migration; migrateuri is required for di‐
2892 rect migration, but can usually be automatically determined for managed
2893 migration.
2894 Note: The desturi parameter for normal migration and peer2peer migra‐
2896 tion has different semantics:
2897 • normal migration: the desturi is an address of the target host as
2899 seen from the client machine.
2900 • peer2peer migration: the desturi is an address of the target host as
2902 seen from the source machine.
2903 In a special circumstance where you require a complete control of the
2905 connection and/or libvirt does not have network access to the remote
2906 side you can use a UNIX transport in the URI and specify a socket path
2907 in the query, for example with the qemu driver you could use this:
2908 qemu+unix:///system?socket=/path/to/socket
2910 When migrateuri is not specified, libvirt will automatically determine
2912 the hypervisor specific URI. Some hypervisors, including QEMU, have an
2913 optional "migration_host" configuration parameter (useful when the host
2914 has multiple network interfaces). If this is unspecified, libvirt de‐
2915 termines a name by looking up the target host's configured hostname.
2916 There are a few scenarios where specifying migrateuri may help:
2918 • The configured hostname is incorrect, or DNS is broken. If a host
2920 has a hostname which will not resolve to match one of its public IP
2921 addresses, then libvirt will generate an incorrect URI. In this case
2922 migrateuri should be explicitly specified, using an IP address, or a
2923 correct hostname.
2924 • The host has multiple network interfaces. If a host has multiple
2926 network interfaces, it might be desirable for the migration data
2927 stream to be sent over a specific interface for either security or
2928 performance reasons. In this case migrateuri should be explicitly
2929 specified, using an IP address associated with the network to be
2930 used.
2931 • The firewall restricts what ports are available. When libvirt gener‐
2933 ates a migration URI, it will pick a port number using hypervisor
2934 specific rules. Some hypervisors only require a single port to be
2935 open in the firewalls, while others require a whole range of port
2936 numbers. In the latter case migrateuri might be specified to choose
2937 a specific port number outside the default range in order to comply
2938 with local firewall policies.
2939 • The desturi uses UNIX transport method. In this advanced case lib‐
2941 virt should not guess a migrateuri and it should be specified using
2942 UNIX socket path URI:
2943 unix:///path/to/socket
2945 See https://libvirt.org/migration.html#uris for more details on migra‐
2947 tion URIs.
2948 Optional graphicsuri overrides connection parameters used for automati‐
2950 cally reconnecting a graphical clients at the end of migration. If
2951 omitted, libvirt will compute the parameters based on target host IP
2952 address. In case the client does not have a direct access to the net‐
2953 work virtualization hosts are connected to and needs to connect through
2954 a proxy, graphicsuri may be used to specify the address the client
2955 should connect to. The URI is formed as follows:
2956 protocol://hostname[:port]/[?parameters]
2958 where protocol is either "spice" or "vnc" and parameters is a list of
2960 protocol specific parameters separated by '&'. Currently recognized pa‐
2961 rameters are "tlsPort" and "tlsSubject". For example,
2962 spice://target.host.com:1234/?tlsPort=4567
2964 Optional listen-address sets the listen address that hypervisor on the
2966 destination side should bind to for incoming migration. Both IPv4 and
2967 IPv6 addresses are accepted as well as hostnames (the resolving is done
2968 on destination). Some hypervisors do not support specifying the listen
2969 address and will return an error if this parameter is used. This param‐
2970 eter cannot be used if desturi uses UNIX transport method.
2971 Optional disks-port sets the port that hypervisor on destination side
2973 should bind to for incoming disks traffic. Currently it is supported
2974 only by QEMU.
2975 Optional disks-uri can also be specified (mutually exclusive with
2977 disks-port) to specify what the remote hypervisor should bind/connect
2978 to when migrating disks. This can be tcp://address:port to specify a
2979 listen address (which overrides --migrate-uri and --listen-address for
2980 the disk migration) and a port or unix:///path/to/socket in case you
2981 need the disk migration to happen over a UNIX socket with that speci‐
2982 fied path. In this case you need to make sure the same socket path is
2983 accessible to both source and destination hypervisors and connecting to
2984 the socket on the source (after hypervisor creates it on the destina‐
2985 tion) will actually connect to the destination. If you are using
2986 SELinux (at least on the source host) you need to make sure the socket
2987 on the source is accessible to libvirtd/QEMU for connection. Libvirt
2988 cannot change the context of the existing socket because it is differ‐
2989 ent from the file representation of the socket and the context is cho‐
2990 sen by its creator (usually by using setsockcreatecon{,_raw}() func‐
2991 tions).
2992 migrate-compcache
2994 Syntax:
2995 migrate-compcache domain [--size bytes]
2997 Sets and/or gets size of the cache (in bytes) used for compressing re‐
2999 peatedly transferred memory pages during live migration. When called
3000 without size, the command just prints current size of the compression
3001 cache. When size is specified, the hypervisor is asked to change com‐
3002 pression cache to size bytes and then the current size is printed (the
3003 result may differ from the requested size due to rounding done by the
3004 hypervisor). The size option is supposed to be used while the domain is
3005 being live-migrated as a reaction to migration progress and increasing
3006 number of compression cache misses obtained from domjobinfo.
3007 migrate-getmaxdowntime
3009 Syntax:
3010 migrate-getmaxdowntime domain
3012 Get the maximum tolerable downtime for a domain which is being live-mi‐
3014 grated to another host. This is the number of milliseconds the guest
3015 is allowed to be down at the end of live migration.
3016 migrate-getspeed
3018 Syntax:
3019 migrate-getspeed domain [--postcopy]
3021 Get the maximum migration bandwidth (in MiB/s) for a domain. If the
3023 --postcopy option is specified, the command will get the maximum band‐
3024 width allowed during a post-copy migration phase.
3025 migrate-postcopy
3027 Syntax:
3028 migrate-postcopy domain
3030 Switch the current migration from pre-copy to post-copy. This is only
3032 supported for a migration started with --postcopy option.
3033 migrate-setmaxdowntime
3035 Syntax:
3036 migrate-setmaxdowntime domain downtime
3038 Set maximum tolerable downtime for a domain which is being live-mi‐
3040 grated to another host. The downtime is a number of milliseconds the
3041 guest is allowed to be down at the end of live migration.
3042 migrate-setspeed
3044 Syntax:
3045 migrate-setspeed domain bandwidth [--postcopy]
3047 Set the maximum migration bandwidth (in MiB/s) for a domain which is
3049 being migrated to another host. bandwidth is interpreted as an unsigned
3050 long long value. Specifying a negative value results in an essentially
3051 unlimited value being provided to the hypervisor. The hypervisor can
3052 choose whether to reject the value or convert it to the maximum value
3053 allowed. If the --postcopy option is specified, the command will set
3054 the maximum bandwidth allowed during a post-copy migration phase.
3055 numatune
3057 Syntax:
3058 numatune domain [--mode mode] [--nodeset nodeset]
3060 [[--config] [--live] | [--current]]
3061 Set or get a domain's numa parameters, corresponding to the <numatune>
3063 element of domain XML. Without flags, the current settings are dis‐
3064 played.
3065 mode can be one of `strict', `interleave', `preferred' and 'restric‐
3067 tive' or any valid number from the virDomainNumatuneMemMode enum in
3068 case the daemon supports it. For a running domain, the mode can't be
3069 changed, and the nodeset can be changed only if the domain was started
3070 with `restrictive' mode.
3071 nodeset is a list of numa nodes used by the host for running the do‐
3073 main. Its syntax is a comma separated list, with '-' for ranges and
3074 '^' for excluding a node.
3075 If --live is specified, set scheduler information of a running guest.
3077 If --config is specified, affect the next start of a persistent guest.
3078 If --current is specified, it is equivalent to either --live or --con‐
3079 fig, depending on the current state of the guest.
3080 For running guests in Linux hosts, the changes made in the domain's
3082 numa parameters does not imply that the guest memory will be moved to a
3083 different nodeset immediately. The memory migration depends on the
3084 guest activity, and the memory of an idle guest will remain in its pre‐
3085 vious nodeset for longer. The presence of VFIO devices will also lock
3086 parts of the guest memory in the same nodeset used to start the guest,
3087 regardless of nodeset changes.
3088 perf
3090 Syntax:
3091 perf domain [--enable eventSpec] [--disable eventSpec]
3093 [[--config] [--live] | [--current]]
3094 Get the current perf events setting or enable/disable specific perf
3096 events for a guest domain.
3097 Perf is a performance analyzing tool in Linux, and it can instrument
3099 CPU performance counters, tracepoints, kprobes, and uprobes (dynamic
3100 tracing). Perf supports a list of measurable events, and can measure
3101 events coming from different sources. For instance, some event are pure
3102 kernel counters, in this case they are called software events, includ‐
3103 ing context-switches, minor-faults, etc.. Now dozens of events from
3104 different sources can be supported by perf.
3105 Currently only QEMU/KVM supports this command. The --enable and --dis‐
3107 able option combined with eventSpec can be used to enable or disable
3108 specific performance event. eventSpec is a string list of one or more
3109 events separated by commas. Valid event names are as follows:
3110 Valid perf event names
3112 • cmt - A PQos (Platform Qos) feature to monitor the usage of cache by
3114 applications running on the platform.
3115 • mbmt - Provides a way to monitor the total system memory bandwidth
3117 between one level of cache and another.
3118 • mbml - Provides a way to limit the amount of data (bytes/s) send
3120 through the memory controller on the socket.
3121 • cache_misses - Provides the count of cache misses by applications
3123 running on the platform.
3124 • cache_references - Provides the count of cache hits by applications
3126 running on th e platform.
3127 • instructions - Provides the count of instructions executed by appli‐
3129 cations running on the platform.
3130 • cpu_cycles - Provides the count of cpu cycles (total/elapsed). May be
3132 used with instructions in order to get a cycles per instruction.
3133 • branch_instructions - Provides the count of branch instructions exe‐
3135 cuted by applications running on the platform.
3136 • branch_misses - Provides the count of branch misses executed by ap‐
3138 plications running on the platform.
3139 • bus_cycles - Provides the count of bus cycles executed by applica‐
3141 tions running on the platform.
3142 • stalled_cycles_frontend - Provides the count of stalled cpu cycles in
3144 the frontend of the instruction processor pipeline by applications
3145 running on the platform.
3146 • stalled_cycles_backend - Provides the count of stalled cpu cycles in
3148 the backend of the instruction processor pipeline by applications
3149 running on the platform.
3150 • ref_cpu_cycles - Provides the count of total cpu cycles not affected
3152 by CPU frequency scaling by applications running on the platform.
3153 • cpu_clock - Provides the cpu clock time consumed by applications run‐
3155 ning on the platform.
3156 • task_clock - Provides the task clock time consumed by applications
3158 running on the platform.
3159 • page_faults - Provides the count of page faults by applications run‐
3161 ning on the platform.
3162 • context_switches - Provides the count of context switches by applica‐
3164 tions running on the platform.
3165 • cpu_migrations - Provides the count cpu migrations by applications
3167 running on the platform.
3168 • page_faults_min - Provides the count minor page faults by applica‐
3170 tions running on the platform.
3171 • page_faults_maj - Provides the count major page faults by applica‐
3173 tions running on the platform.
3174 • alignment_faults - Provides the count alignment faults by applica‐
3176 tions running on the platform.
3177 • emulation_faults - Provides the count emulation faults by applica‐
3179 tions running on the platform.
3180 Note: The statistics can be retrieved using the domstats command using
3182 the --perf flag.
3183 If --live is specified, affect a running guest. If --config is speci‐
3185 fied, affect the next start of a persistent guest. If --current is
3186 specified, it is equivalent to either --live or --config, depending on
3187 the current state of the guest. Both --live and --config flags may be
3188 given, but --current is exclusive. If no flag is specified, behavior is
3189 different depending on hypervisor.
3190 reboot
3192 Syntax:
3193 reboot domain [--mode MODE-LIST]
3195 Reboot a domain. This acts just as if the domain had the reboot com‐
3197 mand run from the console. The command returns as soon as it has exe‐
3198 cuted the reboot action, which may be significantly before the domain
3199 actually reboots.
3200 The exact behavior of a domain when it reboots is set by the on_reboot
3202 parameter in the domain's XML definition.
3203 By default the hypervisor will try to pick a suitable shutdown method.
3205 To specify an alternative method, the --mode parameter can specify a
3206 comma separated list which includes acpi, agent, initctl, signal and
3207 paravirt. The order in which drivers will try each mode is undefined,
3208 and not related to the order specified to virsh. For strict control
3209 over ordering, use a single mode at a time and repeat the command.
3210 reset
3212 Syntax:
3213 reset domain
3215 Reset a domain immediately without any guest shutdown. reset emulates
3217 the power reset button on a machine, where all guest hardware sees the
3218 RST line set and reinitializes internal state.
3219 Note: Reset without any guest OS shutdown risks data loss.
3221 restore
3223 Syntax:
3224 restore state-file [--bypass-cache] [--xml file]
3226 [{--running | --paused}] [--reset-nvram]
3227 Restores a domain from a virsh save state file. See save for more info.
3229 If --bypass-cache is specified, the restore will avoid the file system
3231 cache, although this may slow down the operation.
3232 --xml file is usually omitted, but can be used to supply an alternative
3234 XML file for use on the restored guest with changes only in the
3235 host-specific portions of the domain XML. For example, it can be used
3236 to account for file naming differences in underlying storage due to
3237 disk snapshots taken after the guest was saved.
3238 Normally, restoring a saved image will use the state recorded in the
3240 save image to decide between running or paused; passing either the
3241 --running or --paused flag will allow overriding which state the domain
3242 should be started in.
3243 If --reset-nvram is specified, any existing NVRAM file will be deleted
3245 and re-initialized from its pristine template.
3246 Note: To avoid corrupting file system contents within the domain, you
3248 should not reuse the saved state file for a second restore unless you
3249 have also reverted all storage volumes back to the same contents as
3250 when the state file was created.
3251 resume
3253 Syntax:
3254 resume domain
3256 Moves a domain out of the suspended state. This will allow a previ‐
3258 ously suspended domain to now be eligible for scheduling by the under‐
3259 lying hypervisor.
3260 save
3262 Syntax:
3263 save domain state-file [--bypass-cache] [--xml file]
3265 [{--running | --paused}] [--verbose]
3266 Saves a running domain (RAM, but not disk state) to a state file so
3268 that it can be restored later. Once saved, the domain will no longer
3269 be running on the system, thus the memory allocated for the domain will
3270 be free for other domains to use. virsh restore restores from this
3271 state file. If --bypass-cache is specified, the save will avoid the
3272 file system cache, although this may slow down the operation.
3273 The progress may be monitored using domjobinfo virsh command and can‐
3275 celed with domjobabort command (sent by another virsh instance). An‐
3276 other option is to send SIGINT (usually with Ctrl-C) to the virsh
3277 process running save command. --verbose displays the progress of save.
3278 This is roughly equivalent to doing a hibernate on a running computer,
3280 with all the same limitations. Open network connections may be severed
3281 upon restore, as TCP timeouts may have expired.
3282 --xml file is usually omitted, but can be used to supply an alternative
3284 XML file for use on the restored guest with changes only in the
3285 host-specific portions of the domain XML. For example, it can be used
3286 to account for file naming differences that are planned to be made via
3287 disk snapshots of underlying storage after the guest is saved.
3288 Normally, restoring a saved image will decide between running or paused
3290 based on the state the domain was in when the save was done; passing
3291 either the --running or --paused flag will allow overriding which state
3292 the restore should use.
3293 Domain saved state files assume that disk images will be unchanged be‐
3295 tween the creation and restore point. For a more complete system re‐
3296 store point, where the disk state is saved alongside the memory state,
3297 see the snapshot family of commands.
3298 save-image-define
3300 Syntax:
3301 save-image-define file xml [{--running | --paused}]
3303 Update the domain XML that will be used when file is later used in the
3305 restore command. The xml argument must be a file name containing the
3306 alternative XML, with changes only in the host-specific portions of the
3307 domain XML. For example, it can be used to account for file naming
3308 differences resulting from creating disk snapshots of underlying stor‐
3309 age after the guest was saved.
3310 The save image records whether the domain should be restored to a run‐
3312 ning or paused state. Normally, this command does not alter the
3313 recorded state; passing either the --running or --paused flag will al‐
3314 low overriding which state the restore should use.
3315 save-image-dumpxml
3317 Syntax:
3318 save-image-dumpxml file [--security-info]
3320 Extract the domain XML that was in effect at the time the saved state
3322 file file was created with the save command. Using --security-info
3323 will also include security sensitive information.
3324 save-image-edit
3326 Syntax:
3327 save-image-edit file [{--running | --paused}]
3329 Edit the XML configuration associated with a saved state file file cre‐
3331 ated by the save command.
3332 The save image records whether the domain should be restored to a run‐
3334 ning or paused state. Normally, this command does not alter the
3335 recorded state; passing either the --running or --paused flag will al‐
3336 low overriding which state the restore should use.
3337 This is equivalent to:
3339 virsh save-image-dumpxml state-file > state-file.xml
3341 vi state-file.xml (or make changes with your other text editor)
3342 virsh save-image-define state-file state-file-xml
3343 except that it does some error checking.
3345 The editor used can be supplied by the $VISUAL or $EDITOR environment
3347 variables, and defaults to vi.
3348 schedinfo
3350 Syntax:
3351 schedinfo domain [[--config] [--live] | [--current]] [[--set] parameter=value]...
3353 schedinfo [--weight number] [--cap number] domain
3354 Allows you to show (and set) the domain scheduler parameters. The pa‐
3356 rameters available for each hypervisor are:
3357 LXC (posix scheduler) : cpu_shares, vcpu_period, vcpu_quota
3359 QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota, emula‐
3361 tor_period, emulator_quota, global_period, global_quota, iothread_pe‐
3362 riod, iothread_quota
3363 Xen (credit scheduler): weight, cap
3365 ESX (allocation scheduler): reservation, limit, shares
3367 If --live is specified, set scheduler information of a running guest.
3369 If --config is specified, affect the next start of a persistent guest.
3370 If --current is specified, it is equivalent to either --live or --con‐
3371 fig, depending on the current state of the guest.
3372 Note: The cpu_shares parameter has a valid value range of 2-262144.
3374 Note: The weight and cap parameters are defined only for the XEN_CREDIT
3376 scheduler.
3377 Note: The vcpu_period, emulator_period, and iothread_period parameters
3379 have a valid value range of 1000-1000000 or 0, and the vcpu_quota, emu‐
3380 lator_quota, and iothread_quota parameters have a valid value range of
3381 1000-17592186044415 or less than 0. The value 0 for either parameter is
3382 the same as not specifying that parameter.
3383 screenshot
3385 Syntax:
3386 screenshot domain [imagefilepath] [--screen screenID]
3388 Takes a screenshot of a current domain console and stores it into a
3390 file. Optionally, if the hypervisor supports more displays for a do‐
3391 main, screenID allows specifying which screen will be captured. It is
3392 the sequential number of screen. In case of multiple graphics cards,
3393 heads are enumerated before devices, e.g. having two graphics cards,
3394 both with four heads, screen ID 5 addresses the second head on the sec‐
3395 ond card.
3396 send-key
3398 Syntax:
3399 send-key domain [--codeset codeset] [--holdtime holdtime] keycode...
3401 Parse the keycode sequence as keystrokes to send to domain. Each key‐
3403 code can either be a numeric value or a symbolic name from the corre‐
3404 sponding codeset. If --holdtime is given, each keystroke will be held
3405 for that many milliseconds. The default codeset is linux, but use of
3406 the --codeset option allows other codesets to be chosen.
3407 If multiple keycodes are specified, they are all sent simultaneously to
3409 the guest, and they may be received in random order. If you need dis‐
3410 tinct keypresses, you must use multiple send-key invocations.
3411 • linux
3413 The numeric values are those defined by the Linux generic input event
3415 subsystem. The symbolic names match the corresponding Linux key con‐
3416 stant macro names.
3417 See virkeycode-linux(7) and virkeyname-linux(7)
3419 • xt
3421 The numeric values are those defined by the original XT keyboard con‐
3423 troller. No symbolic names are provided
3424 See virkeycode-xt(7)
3426 • atset1
3428 The numeric values are those defined by the AT keyboard controller,
3430 set 1 (aka XT compatible set). Extended keycoes from atset1 may dif‐
3431 fer from extended keycodes in the xt codeset. No symbolic names are
3432 provided
3433 See virkeycode-atset1(7)
3435 • atset2
3437 The numeric values are those defined by the AT keyboard controller,
3439 set 2. No symbolic names are provided
3440 See virkeycode-atset2(7)
3442 • atset3
3444 The numeric values are those defined by the AT keyboard controller,
3446 set 3 (aka PS/2 compatible set). No symbolic names are provided
3447 See virkeycode-atset3(7)
3449 • os_x
3451 The numeric values are those defined by the macOS keyboard input sub‐
3453 system. The symbolic names match the corresponding macOS key constant
3454 macro names
3455 See virkeycode-osx(7) and virkeyname-osx(7)
3457 • xt_kbd
3459 The numeric values are those defined by the Linux KBD device. These
3461 are a variant on the original XT codeset, but often with different
3462 encoding for extended keycodes. No symbolic names are provided.
3463 See virkeycode-xtkbd(7)
3465 • win32
3467 The numeric values are those defined by the Win32 keyboard input sub‐
3469 system. The symbolic names match the corresponding Win32 key constant
3470 macro names
3471 See virkeycode-win32(7) and virkeyname-win32(7)
3473 • usb
3475 The numeric values are those defined by the USB HID specification for
3477 keyboard input. No symbolic names are provided
3478 See virkeycode-usb(7)
3480 • qnum
3482 The numeric values are those defined by the QNUM extension for send‐
3484 ing raw keycodes. These are a variant on the XT codeset, but extended
3485 keycodes have the low bit of the second byte set, instead of the high
3486 bit of the first byte. No symbolic names are provided.
3487 See virkeycode-qnum(7)
3489 Examples:
3491 # send three strokes 'k', 'e', 'y', using xt codeset. these
3493 # are all pressed simultaneously and may be received by the guest
3494 # in random order
3495 virsh send-key dom --codeset xt 37 18 21
3496 # send one stroke 'right-ctrl+C'
3498 virsh send-key dom KEY_RIGHTCTRL KEY_C
3499 # send a tab, held for 1 second
3501 virsh send-key --holdtime 1000 0xf
3502 send-process-signal
3504 Syntax:
3505 send-process-signal domain-id pid signame
3507 Send a signal signame to the process identified by pid running in the
3509 virtual domain domain-id. The pid is a process ID in the virtual domain
3510 namespace.
3511 The signame argument may be either an integer signal constant number,
3513 or one of the symbolic names:
3514 "nop", "hup", "int", "quit", "ill",
3516 "trap", "abrt", "bus", "fpe", "kill",
3517 "usr1", "segv", "usr2", "pipe", "alrm",
3518 "term", "stkflt", "chld", "cont", "stop",
3519 "tstp", "ttin", "ttou", "urg", "xcpu",
3520 "xfsz", "vtalrm", "prof", "winch", "poll",
3521 "pwr", "sys", "rt0", "rt1", "rt2", "rt3",
3522 "rt4", "rt5", "rt6", "rt7", "rt8", "rt9",
3523 "rt10", "rt11", "rt12", "rt13", "rt14", "rt15",
3524 "rt16", "rt17", "rt18", "rt19", "rt20", "rt21",
3525 "rt22", "rt23", "rt24", "rt25", "rt26", "rt27",
3526 "rt28", "rt29", "rt30", "rt31", "rt32"
3527 The symbol name may optionally be prefixed with sig or sig_ and may be
3529 in uppercase or lowercase.
3530 Examples:
3532 virsh send-process-signal myguest 1 15
3534 virsh send-process-signal myguest 1 term
3535 virsh send-process-signal myguest 1 sigterm
3536 virsh send-process-signal myguest 1 SIG_HUP
3537 set-lifecycle-action
3539 Syntax:
3540 set-lifecycle-action domain type action
3542 [[--config] [--live] | [--current]]
3543 Set the lifecycle action for specified lifecycle type. The valid types
3545 are "poweroff", "reboot" and "crash", and for each of them valid action
3546 is one of "destroy", "restart", "rename-restart", "preserve". For type
3547 "crash", additional actions "coredump-destroy" and "coredump-restart"
3548 are supported.
3549 set-user-password
3551 Syntax:
3552 set-user-password domain user password [--encrypted]
3554 Set the password for the user account in the guest domain.
3556 If --encrypted is specified, the password is assumed to be already en‐
3558 crypted by the method required by the guest OS.
3559 For QEMU/KVM, this requires the guest agent to be configured and run‐
3561 ning.
3562 set-user-sshkeys
3564 Syntax:
3565 set-user-sshkeys domain user [--file FILE] [{--reset | --remove}]
3567 Append keys read from FILE into user's SSH authorized keys file in the
3569 guest domain. In the FILE keys must be on separate lines and each line
3570 must follow authorized keys format as defined by sshd(8).
3571 If --reset is specified, then the guest authorized keys file content is
3573 removed before appending new keys. As a special case, if --reset is
3574 provided and no FILE was provided then no new keys are added and the
3575 authorized keys file is cleared out.
3576 If --remove is specified, then instead of adding any new keys then keys
3578 read from FILE are removed from the authorized keys file. It is not
3579 considered an error if the key does not exist in the file.
3580 setmaxmem
3582 Syntax:
3583 setmaxmem domain size [[--config] [--live] | [--current]]
3585 Change the maximum memory allocation limit for a guest domain. If
3587 --live is specified, affect a running guest. If --config is specified,
3588 affect the next start of a persistent guest. If --current is speci‐
3589 fied, it is equivalent to either --live or --config, depending on the
3590 current state of the guest. Both --live and --config flags may be
3591 given, but --current is exclusive. If no flag is specified, behavior is
3592 different depending on hypervisor.
3593 Some hypervisors such as QEMU/KVM don't support live changes (espe‐
3595 cially increasing) of the maximum memory limit. Even persistent con‐
3596 figuration changes might not be performed with some hypervisors/config‐
3597 uration (e.g. on NUMA enabled domains on QEMU). For complex configura‐
3598 tion changes use command edit instead).
3599 size is a scaled integer (see NOTES above); it defaults to kibibytes
3601 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3602 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3603 rounds up to the nearest kibibyte. Some hypervisors require a larger
3604 granularity than KiB, and requests that are not an even multiple will
3605 be rounded up. For example, vSphere/ESX rounds the parameter up to
3606 mebibytes (1024 kibibytes).
3607 setmem
3609 Syntax:
3610 setmem domain size [[--config] [--live] | [--current]]
3612 Change the memory allocation for a guest domain. If --live is speci‐
3614 fied, perform a memory balloon of a running guest. If --config is
3615 specified, affect the next start of a persistent guest. If --current
3616 is specified, it is equivalent to either --live or --config, depending
3617 on the current state of the guest. Both --live and --config flags may
3618 be given, but --current is exclusive. If no flag is specified, behavior
3619 is different depending on hypervisor.
3620 size is a scaled integer (see NOTES above); it defaults to kibibytes
3622 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3623 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3624 rounds up to the nearest kibibyte. Some hypervisors require a larger
3625 granularity than KiB, and requests that are not an even multiple will
3626 be rounded up. For example, vSphere/ESX rounds the parameter up to
3627 mebibytes (1024 kibibytes).
3628 For Xen, you can only adjust the memory of a running domain if the do‐
3630 main is paravirtualized or running the PV balloon driver.
3631 For LXC, the value being set is the cgroups value for limit_in_bytes or
3633 the maximum amount of user memory (including file cache). When viewing
3634 memory inside the container, this is the /proc/meminfo "MemTotal"
3635 value. When viewing the value from the host, use the virsh memtune com‐
3636 mand. In order to view the current memory in use and the maximum value
3637 allowed to set memory, use the virsh dominfo command.
3638 setvcpus
3640 Syntax:
3641 setvcpus domain count [--maximum] [[--config] [--live] | [--current]] [--guest] [--hotpluggable]
3643 Change the number of virtual CPUs active in a guest domain. By de‐
3645 fault, this command works on active guest domains. To change the set‐
3646 tings for an inactive guest domain, use the --config flag.
3647 The count value may be limited by host, hypervisor, or a limit coming
3649 from the original description of the guest domain. For Xen, you can
3650 only adjust the virtual CPUs of a running domain if the domain is par‐
3651 avirtualized.
3652 If the --config flag is specified, the change is made to the stored XML
3654 configuration for the guest domain, and will only take effect when the
3655 guest domain is next started.
3656 If --live is specified, the guest domain must be active, and the change
3658 takes place immediately. Both the --config and --live flags may be
3659 specified together if supported by the hypervisor. If this command is
3660 run before the guest has finished booting, the guest may fail to
3661 process the change.
3662 If --current is specified, it is equivalent to either --live or --con‐
3664 fig, depending on the current state of the guest.
3665 When no flags are given, the --live flag is assumed and the guest do‐
3667 main must be active. In this situation it is up to the hypervisor
3668 whether the --config flag is also assumed, and therefore whether the
3669 XML configuration is adjusted to make the change persistent.
3670 If --guest is specified, then the count of cpus is modified in the
3672 guest instead of the hypervisor. This flag is usable only for live do‐
3673 mains and may require guest agent to be configured in the guest.
3674 To allow adding vcpus to persistent definitions that can be later ho‐
3676 tunplugged after the domain is booted it is necessary to specify the
3677 --hotpluggable flag. Vcpus added to live domains supporting vcpu unplug
3678 are automatically marked as hotpluggable.
3679 The --maximum flag controls the maximum number of virtual cpus that can
3681 be hot-plugged the next time the domain is booted. As such, it must
3682 only be used with the --config flag, and not with the --live or the
3683 --current flag. Note that it may not be possible to change the maximum
3684 vcpu count if the processor topology is specified for the guest.
3685 setvcpu
3687 Syntax:
3688 setvcpu domain vcpulist [--enable] | [--disable]
3690 [[--live] [--config] | [--current]]
3691 Change state of individual vCPUs using hot(un)plug mechanism.
3693 See vcpupin for information on format of vcpulist. Hypervisor drivers
3695 may require that vcpulist contains exactly vCPUs belonging to one hot‐
3696 pluggable entity. This is usually just a single vCPU but certain archi‐
3697 tectures such as ppc64 require a full core to be specified at once.
3698 Note that hypervisors may refuse to disable certain vcpus such as vcpu
3700 0 or others.
3701 If --live is specified, affect a running domain. If --config is speci‐
3703 fied, affect the next startup of a persistent guest. If --current is
3704 specified, it is equivalent to either --live or --config, depending on
3705 the current state of the guest. This is the default. Both --live and
3706 --config flags may be given, but --current is exclusive.
3707 shutdown
3709 Syntax:
3710 shutdown domain [--mode MODE-LIST]
3712 Gracefully shuts down a domain. This coordinates with the domain OS to
3714 perform graceful shutdown, so there is no guarantee that it will suc‐
3715 ceed, and may take a variable length of time depending on what services
3716 must be shutdown in the domain.
3717 The exact behavior of a domain when it shuts down is set by the
3719 on_poweroff parameter in the domain's XML definition.
3720 If domain is transient, then the metadata of any snapshots and check‐
3722 points will be lost once the guest stops running, but the underlying
3723 contents still exist, and a new domain with the same name and UUID can
3724 restore the snapshot metadata with snapshot-create, and the checkpoint
3725 metadata with checkpoint-create.
3726 By default the hypervisor will try to pick a suitable shutdown method.
3728 To specify an alternative method, the --mode parameter can specify a
3729 comma separated list which includes acpi, agent, initctl, signal and
3730 paravirt. The order in which drivers will try each mode is undefined,
3731 and not related to the order specified to virsh. For strict control
3732 over ordering, use a single mode at a time and repeat the command.
3733 start
3735 Syntax:
3736 start domain-name-or-uuid [--console] [--paused]
3738 [--autodestroy] [--bypass-cache] [--force-boot]
3739 [--pass-fds N,M,...] [--reset-nvram]
3740 Start a (previously defined) inactive domain, either from the last man‐
3742 agedsave state, or via a fresh boot if no managedsave state is present.
3743 The domain will be paused if the --paused option is used and supported
3744 by the driver; otherwise it will be running. If --console is re‐
3745 quested, attach to the console after creation. If --autodestroy is re‐
3746 quested, then the guest will be automatically destroyed when virsh
3747 closes its connection to libvirt, or otherwise exits. If --by‐
3748 pass-cache is specified, and managedsave state exists, the restore will
3749 avoid the file system cache, although this may slow down the operation.
3750 If --force-boot is specified, then any managedsave state is discarded
3751 and a fresh boot occurs.
3752 If --pass-fds is specified, the argument is a comma separated list of
3754 open file descriptors which should be pass on into the guest. The file
3755 descriptors will be re-numbered in the guest, starting from 3. This is
3756 only supported with container based virtualization.
3757 If --reset-nvram is specified, any existing NVRAM file will be deleted
3759 and re-initialized from its pristine template.
3760 suspend
3762 Syntax:
3763 suspend domain
3765 Suspend a running domain. It is kept in memory but won't be scheduled
3767 anymore.
3768 ttyconsole
3770 Syntax:
3771 ttyconsole domain
3773 Output the device used for the TTY console of the domain. If the infor‐
3775 mation is not available the processes will provide an exit code of 1.
3776 undefine
3778 Syntax:
3779 undefine domain [--managed-save] [--snapshots-metadata]
3781 [--checkpoints-metadata] [--nvram] [--keep-nvram]
3782 [ {--storage volumes | --remove-all-storage
3783 [--delete-storage-volume-snapshots]} --wipe-storage]
3784 Undefine a domain. If the domain is running, this converts it to a
3786 transient domain, without stopping it. If the domain is inactive, the
3787 domain configuration is removed.
3788 The --managed-save flag guarantees that any managed save image (see the
3790 managedsave command) is also cleaned up. Without the flag, attempts to
3791 undefine a domain with a managed save image will fail.
3792 The --snapshots-metadata flag guarantees that any snapshots (see the
3794 snapshot-list command) are also cleaned up when undefining an inactive
3795 domain. Without the flag, attempts to undefine an inactive domain with
3796 snapshot metadata will fail. If the domain is active, this flag is ig‐
3797 nored.
3798 The --checkpoints-metadata flag guarantees that any checkpoints (see
3800 the checkpoint-list command) are also cleaned up when undefining an in‐
3801 active domain. Without the flag, attempts to undefine an inactive do‐
3802 main with checkpoint metadata will fail. If the domain is active, this
3803 flag is ignored.
3804 --nvram and --keep-nvram specify accordingly to delete or keep nvram
3806 (/domain/os/nvram/) file. If the domain has an nvram file and the flags
3807 are omitted, the undefine will fail.
3808 The --storage flag takes a parameter volumes, which is a comma sepa‐
3810 rated list of volume target names or source paths of storage volumes to
3811 be removed along with the undefined domain. Volumes can be undefined
3812 and thus removed only on inactive domains. Volume deletion is only at‐
3813 tempted after the domain is undefined; if not all of the requested vol‐
3814 umes could be deleted, the error message indicates what still remains
3815 behind. If a volume path is not found in the domain definition, it's
3816 treated as if the volume was successfully deleted. Only volumes managed
3817 by libvirt in storage pools can be removed this way. (See domblklist
3818 for list of target names associated to a domain). Example: --storage
3819 vda,/path/to/storage.img
3820 The --remove-all-storage flag specifies that all of the domain's stor‐
3822 age volumes should be deleted.
3823 The --delete-storage-volume-snapshots (previously --delete-snapshots)
3825 flag specifies that any snapshots associated with the storage volume
3826 should be deleted as well. Requires the --remove-all-storage flag to be
3827 provided. Not all storage drivers support this option, presently only
3828 rbd. Using this when also removing volumes handled by a storage driver
3829 which does not support the flag will result in failure.
3830 The flag --wipe-storage specifies that the storage volumes should be
3832 wiped before removal.
3833 NOTE: For an inactive domain, the domain name or UUID must be used as
3835 the domain.
3836 vcpucount
3838 Syntax:
3839 vcpucount domain [{--maximum | --active}
3841 {--config | --live | --current}] [--guest]
3842 Print information about the virtual cpu counts of the given domain. If
3844 no flags are specified, all possible counts are listed in a table; oth‐
3845 erwise, the output is limited to just the numeric value requested. For
3846 historical reasons, the table lists the label "current" on the rows
3847 that can be queried in isolation via the --active flag, rather than re‐
3848 lating to the --current flag.
3849 --maximum requests information on the maximum cap of vcpus that a do‐
3851 main can add via setvcpus, while --active shows the current usage;
3852 these two flags cannot both be specified. --config requires a persis‐
3853 tent guest and requests information regarding the next time the domain
3854 will be booted, --live requires a running domain and lists current val‐
3855 ues, and --current queries according to the current state of the domain
3856 (corresponding to --live if running, or --config if inactive); these
3857 three flags are mutually exclusive.
3858 If --guest is specified, then the count of cpus is reported from the
3860 perspective of the guest. This flag is usable only for live domains and
3861 may require guest agent to be configured in the guest.
3862 vcpuinfo
3864 Syntax:
3865 vcpuinfo domain [--pretty]
3867 Returns basic information about the domain virtual CPUs, like the num‐
3869 ber of vCPUs, the running time, the affinity to physical processors.
3870 With --pretty, cpu affinities are shown as ranges.
3872 Example:
3874 $ virsh vcpuinfo fedora
3876 VCPU: 0
3877 CPU: 0
3878 State: running
3879 CPU time: 7,0s
3880 CPU Affinity: yyyy
3881 VCPU: 1
3883 CPU: 1
3884 State: running
3885 CPU time: 0,7s
3886 CPU Affinity: yyyy
3887 STATES
3889 The State field displays the current operating state of a virtual CPU
3891 • offline
3893 The virtual CPU is offline and not usable by the domain. This state
3895 is not supported by all hypervisors.
3896 • running
3898 The virtual CPU is available to the domain and is operating.
3900 • blocked
3902 The virtual CPU is available to the domain but is waiting for a re‐
3904 source. This state is not supported by all hypervisors, in which
3905 case running may be reported instead.
3906 • no state
3908 The virtual CPU state could not be determined. This could happen if
3910 the hypervisor is newer than virsh.
3911 • N/A
3913 There's no information about the virtual CPU state available. This
3915 can be the case if the domain is not running or the hypervisor does
3916 not report the virtual CPU state.
3917 vcpupin
3919 Syntax:
3920 vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]]
3922 Query or change the pinning of domain VCPUs to host physical CPUs. To
3924 pin a single vcpu, specify cpulist; otherwise, you can query one vcpu
3925 or omit vcpu to list all at once.
3926 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
3928 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
3929 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
3930 clusive. For pinning the vcpu to all physical cpus specify 'r' as a
3931 cpulist. If --live is specified, affect a running guest. If --config
3932 is specified, affect the next start of a persistent guest. If --cur‐
3933 rent is specified, it is equivalent to either --live or --config, de‐
3934 pending on the current state of the guest. Both --live and --config
3935 flags may be given if cpulist is present, but --current is exclusive.
3936 If no flag is specified, behavior is different depending on hypervisor.
3937 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
3939 cal to "9-14,0-7,15" but not identical to "^8,0-15".
3940 vncdisplay
3942 Syntax:
3943 vncdisplay domain
3945 Output the IP address and port number for the VNC display. If the in‐
3947 formation is not available the processes will provide an exit code of
3948 1.
3949
3951 The following commands manipulate devices associated to domains. The
3952 domain can be specified as a short integer, a name or a full UUID. To
3953 better understand the values allowed as options for the command reading
3954 the documentation at https://libvirt.org/formatdomain.html on the for‐
3955 mat of the device sections to get the most accurate set of accepted
3956 values.
3957 attach-device
3959 Syntax:
3960 attach-device domain FILE [[[--live] [--config] | [--current]] | [--persistent]]
3962 Attach a device to the domain, using a device definition in an XML file
3964 using a device definition element such as <disk> or <interface> as the
3965 top-level element. See the documentation at
3966 https://libvirt.org/formatdomain.html#elementsDevices to learn about
3967 libvirt XML format for a device. If --config is specified the command
3968 alters the persistent guest configuration with the device attach taking
3969 effect the next time libvirt starts the domain. For cdrom and floppy
3970 devices, this command only replaces the media within an existing de‐
3971 vice; consider using update-device for this usage. For passthrough
3972 host devices, see also nodedev-detach, needed if the PCI device does
3973 not use managed mode.
3974 If --live is specified, affect a running domain. If --config is speci‐
3976 fied, affect the next startup of a persistent guest. If --current is
3977 specified, it is equivalent to either --live or --config, depending on
3978 the current state of the guest. Both --live and --config flags may be
3979 given, but --current is exclusive. When no flag is specified legacy API
3980 is used whose behavior depends on the hypervisor driver.
3981 For compatibility purposes, --persistent behaves like --config for an
3983 offline domain, and like --live --config for a running domain.
3984 Note: using of partial device definition XML files may lead to unex‐
3986 pected results as some fields may be autogenerated and thus match de‐
3987 vices other than expected.
3988 attach-disk
3990 Syntax:
3991 attach-disk domain source target [[[--live] [--config] |
3993 [--current]] | [--persistent]] [--targetbus bus]
3994 [--driver driver] [--subdriver subdriver] [--iothread iothread]
3995 [--cache cache] [--io io] [--type type] [--alias alias]
3996 [--mode mode] [--sourcetype sourcetype]
3997 [--source-protocol protocol] [--source-host-name hostname:port]
3998 [--source-host-transport transport] [--source-host-socket socket]
3999 [--serial serial] [--wwn wwn] [--rawio] [--address address]
4000 [--multifunction] [--print-xml]
4001 Attach a new disk device to the domain. source is path for the files
4003 and devices unless --source-protocol is specified, in which case source
4004 is the name of a network disk. target controls the bus or device under
4005 which the disk is exposed to the guest OS. It indicates the "logical"
4006 device name; the optional targetbus attribute specifies the type of
4007 disk device to emulate; possible values are driver specific, with typi‐
4008 cal values being ide, scsi, virtio, xen, usb, sata, or sd, if omitted,
4009 the bus type is inferred from the style of the device name (e.g. a de‐
4010 vice named 'sda' will typically be exported using a SCSI bus). driver
4011 can be file, tap or phy for the Xen hypervisor depending on the kind of
4012 access; or qemu for the QEMU emulator. Further details to the driver
4013 can be passed using subdriver. For Xen subdriver can be aio, while for
4014 QEMU subdriver should match the format of the disk source, such as raw
4015 or qcow2. Hypervisor default will be used if subdriver is not speci‐
4016 fied. However, the default may not be correct, esp. for QEMU as for
4017 security reasons it is configured not to detect disk formats. type can
4018 indicate lun, cdrom or floppy as alternative to the disk default, al‐
4019 though this use only replaces the media within the existing virtual
4020 cdrom or floppy device; consider using update-device for this usage in‐
4021 stead. alias can set user supplied alias. mode can specify the two
4022 specific mode readonly or shareable. sourcetype can indicate the type
4023 of source (block|file|network) cache can be one of "default", "none",
4024 "writethrough", "writeback", "directsync" or "unsafe". io controls
4025 specific policies on I/O; QEMU guests support "threads", "native" and
4026 "io_uring". iothread is the number within the range of domain IO‐
4027 Threads to which this disk may be attached (QEMU only). serial is the
4028 serial of disk device. wwn is the wwn of disk device. rawio indicates
4029 the disk needs rawio capability. address is the address of disk device
4030 in the form of pci:domain.bus.slot.function, scsi:controller.bus.unit,
4031 ide:controller.bus.unit, usb:bus.port, sata:controller.bus.unit or
4032 ccw:cssid.ssid.devno. Virtio-ccw devices must have their cssid set to
4033 0xfe. multifunction indicates specified pci address is a multifunction
4034 pci device address.
4035 There is also support for using a network disk. As specified, the user
4037 can provide a --source-protocol in which case the source parameter will
4038 be interpreted as the source name. --source-protocol must be provided
4039 if the user intends to provide a network disk or host information.
4040 Host information can be provided using the tags --source-host-name,
4041 --source-host-transport, and --source-host-socket, which respectively
4042 denote the name of the host, the host's transport method, and the
4043 socket that the host uses. --source-host-socket and --source-host-name
4044 cannot both be provided, and the user must provide a
4045 --source-host-transport if they want to provide a --source-host-socket.
4046 The --source-host-name parameter supports host:port syntax if the user
4047 wants to provide a port as well.
4048 If --print-xml is specified, then the XML of the disk that would be at‐
4050 tached is printed instead.
4051 If --live is specified, affect a running domain. If --config is speci‐
4053 fied, affect the next startup of a persistent guest. If --current is
4054 specified, it is equivalent to either --live or --config, depending on
4055 the current state of the guest. Both --live and --config flags may be
4056 given, but --current is exclusive. When no flag is specified legacy API
4057 is used whose behavior depends on the hypervisor driver.
4058 For compatibility purposes, --persistent behaves like --config for an
4060 offline domain, and like --live --config for a running domain. Like‐
4061 wise, --shareable is an alias for --mode shareable.
4062 attach-interface
4064 Syntax:
4065 attach-interface domain type source [[[--live]
4067 [--config] | [--current]] | [--persistent]]
4068 [--target target] [--mac mac] [--script script] [--model model]
4069 [--inbound average,peak,burst,floor] [--outbound average,peak,burst]
4070 [--alias alias] [--managed] [--print-xml]
4071 [--source-mode mode]
4072 Attach a new network interface to the domain.
4074 type can be one of the:
4076 network to indicate connection via a libvirt virtual network,
4078 bridge to indicate connection via a bridge device on the host,
4080 direct to indicate connection directly to one of the host's network in‐
4082 terfaces or bridges,
4083 hostdev to indicate connection using a passthrough of PCI device on the
4085 host,
4086 vhostuser to indicate connection using a virtio transport protocol.
4088 source indicates the source of the connection. The source depends on
4090 the type of the interface:
4091 network name of the virtual network,
4093 bridge the name of the bridge device,
4095 direct the name of the host's interface or bridge,
4097 hostdev the PCI address of the host's interface formatted as do‐
4099 main:bus:slot.function.
4100 vhostuser the path to UNIX socket (control plane)
4102 --target is used to specify the tap/macvtap device to be used to con‐
4104 nect the domain to the source. Names starting with 'vnet' are consid‐
4105 ered as auto-generated and are blanked out/regenerated each time the
4106 interface is attached.
4107 --mac specifies the MAC address of the network interface; if a MAC ad‐
4109 dress is not given, a new address will be automatically generated (and
4110 stored in the persistent configuration if "--config" is given on the
4111 command line).
4112 --script is used to specify a path to a custom script to be called
4114 while attaching to a bridge - this will be called instead of the de‐
4115 fault script not in addition to it. This is valid only for interfaces
4116 of bridge type and only for Xen domains.
4117 --model specifies the network device model to be presented to the do‐
4119 main.
4120 alias can set user supplied alias.
4122 --inbound and --outbound control the bandwidth of the interface. At
4124 least one from the average, floor pair must be specified. The other
4125 two peak and burst are optional, so "average,peak", "average,,burst",
4126 "average,,,floor", "average" and ",,,floor" are also legal. Values for
4127 average, floor and peak are expressed in kilobytes per second, while
4128 burst is expressed in kilobytes in a single burst at peak speed as de‐
4129 scribed in the Network XML documentation at
4130 https://libvirt.org/formatnetwork.html#elementQoS.
4131 --managed is usable only for hostdev type and tells libvirt that the
4133 interface should be managed, which means detached and reattached
4134 from/to the host by libvirt.
4135 --source-mode is mandatory for vhostuser interface and accepts values
4137 server and client that control whether hypervisor waits for the other
4138 process to connect, or initiates connection, respectively.
4139 If --print-xml is specified, then the XML of the interface that would
4141 be attached is printed instead.
4142 If --live is specified, affect a running domain. If --config is speci‐
4144 fied, affect the next startup of a persistent guest. If --current is
4145 specified, affect the current domain state, which can either be live or
4146 offline. Both --live and --config flags may be given, but --current is
4147 exclusive. When no flag is specified legacy API is used whose behavior
4148 depends on the hypervisor driver.
4149 For compatibility purposes, --persistent behaves like --config for an
4151 offline domain, and like --live --config for a running domain.
4152 Note: the optional target value is the name of a device to be created
4154 as the back-end on the node. If not provided a device named "vnetN" or
4155 "vifN" will be created automatically.
4156 detach-device
4158 Syntax:
4159 detach-device domain FILE [[[--live] [--config] |
4161 [--current]] | [--persistent]]
4162 Detach a device from the domain, takes the same kind of XML descrip‐
4164 tions as command attach-device. For passthrough host devices, see also
4165 nodedev-reattach, needed if the device does not use managed mode.
4166 Note: The supplied XML description of the device should be as specific
4168 as its definition in the domain XML. The set of attributes used to
4169 match the device are internal to the drivers. Using a partial defini‐
4170 tion, or attempting to detach a device that is not present in the do‐
4171 main XML, but shares some specific attributes with one that is present,
4172 may lead to unexpected results.
4173 Quirk: Device unplug is asynchronous in most cases and requires guest
4175 cooperation. This means that it's up to the discretion of the guest to
4176 disallow or delay the unplug arbitrarily. As the libvirt API used in
4177 this command was designed as synchronous it returns success after some
4178 timeout even if the device was not unplugged yet to allow further in‐
4179 teractions with the domain e.g. if the guest is unresponsive. Callers
4180 which need to make sure that the device was unplugged can use libvirt
4181 events (see virsh event) to be notified when the device is removed.
4182 Note that the event may arrive before the command returns.
4183 If --live is specified, affect a running domain. If --config is speci‐
4185 fied, affect the next startup of a persistent guest. If --current is
4186 specified, it is equivalent to either --live or --config, depending on
4187 the current state of the guest. Both --live and --config flags may be
4188 given, but --current is exclusive. When no flag is specified legacy API
4189 is used whose behavior depends on the hypervisor driver.
4190 For compatibility purposes, --persistent behaves like --config for an
4192 offline domain, and like --live --config for a running domain.
4193 Note that older versions of virsh used --config as an alias for --per‐
4195 sistent.
4196 detach-device-alias
4198 Syntax:
4199 detach-device-alias domain alias [[[--live] [--config] | [--current]]]]
4201 Detach a device with given alias from the domain. This command returns
4203 successfully after the unplug request was sent to the hypervisor. The
4204 actual removal of the device is notified asynchronously via libvirt
4205 events (see virsh event).
4206 If --live is specified, affect a running domain. If --config is speci‐
4208 fied, affect the next startup of a persistent guest. If --current is
4209 specified, it is equivalent to either --live or --config, depending on
4210 the current state of the guest. Both --live and --config flags may be
4211 given, but --current is exclusive.
4212 detach-disk
4214 Syntax:
4215 detach-disk domain target [[[--live] [--config] |
4217 [--current]] | [--persistent]] [--print-xml]
4218 Detach a disk device from a domain. The target is the device as seen
4220 from the domain.
4221 If --live is specified, affect a running domain. If --config is speci‐
4223 fied, affect the next startup of a persistent guest. If --current is
4224 specified, it is equivalent to either --live or --config, depending on
4225 the current state of the guest. Both --live and --config flags may be
4226 given, but --current is exclusive. When no flag is specified legacy API
4227 is used whose behavior depends on the hypervisor driver.
4228 For compatibility purposes, --persistent behaves like --config for an
4230 offline domain, and like --live --config for a running domain.
4231 Note that older versions of virsh used --config as an alias for --per‐
4233 sistent.
4234 If --print-xml is specified, then the XML which would be used to detach
4236 the disk is printed instead.
4237 Please see documentation for detach-device for known quirks.
4239 detach-interface
4241 Syntax:
4242 detach-interface domain type [--mac mac]
4244 [[[--live] [--config] | [--current]] | [--persistent]]
4245 Detach a network interface from a domain. type can be either network
4247 to indicate a physical network device or bridge to indicate a bridge to
4248 a device. It is recommended to use the mac option to distinguish be‐
4249 tween the interfaces if more than one are present on the domain.
4250 If --live is specified, affect a running domain. If --config is speci‐
4252 fied, affect the next startup of a persistent guest. If --current is
4253 specified, it is equivalent to either --live or --config, depending on
4254 the current state of the guest. Both --live and --config flags may be
4255 given, but --current is exclusive. When no flag is specified legacy API
4256 is used whose behavior depends on the hypervisor driver.
4257 For compatibility purposes, --persistent behaves like --config for an
4259 offline domain, and like --live --config for a running domain.
4260 Note that older versions of virsh used --config as an alias for --per‐
4262 sistent.
4263 Please see documentation for detach-device for known quirks.
4265 update-device
4267 Syntax:
4268 update-device domain file [--force] [[[--live]
4270 [--config] | [--current]] | [--persistent]]
4271 Update the characteristics of a device associated with domain, based on
4273 the device definition in an XML file. The --force option can be used
4274 to force device update, e.g., to eject a CD-ROM even if it is
4275 locked/mounted in the domain. See the documentation at
4276 https://libvirt.org/formatdomain.html#elementsDevices to learn about
4277 libvirt XML format for a device.
4278 If --live is specified, affect a running domain. If --config is speci‐
4280 fied, affect the next startup of a persistent guest. If --current is
4281 specified, it is equivalent to either --live or --config, depending on
4282 the current state of the guest. Both --live and --config flags may be
4283 given, but --current is exclusive. Not specifying any flag is the same
4284 as specifying --current.
4285 For compatibility purposes, --persistent behaves like --config for an
4287 offline domain, and like --live --config for a running domain.
4288 Note that older versions of virsh used --config as an alias for --per‐
4290 sistent.
4291 Note: using of partial device definition XML files may lead to unex‐
4293 pected results as some fields may be autogenerated and thus match de‐
4294 vices other than expected.
4295 update-memory-device
4297 Syntax:
4298 update-memory-device domain [--print-xml] [[--alias alias] | [--node node]]
4300 [[--live] [--config] | [--current]]
4301 [--requested-size size]
4302 This command finds <memory/> device inside given domain, changes re‐
4304 quested values and passes updated device XML to daemon. If --print-xml
4305 is specified then the device is not changed, but the updated device XML
4306 is printed to stdout. If there are more than one <memory/> devices in
4307 domain use --alias or --node to select the desired one.
4308 If --live is specified, affect a running domain. If --config is speci‐
4310 fied, affect the next startup of a persistent guest. If --current is
4311 specified, it is equivalent to either --live or --config, depending on
4312 the current state of the guest. Both --live and --config flags may be
4313 given, but --current is exclusive. Not specifying any flag is the same
4314 as specifying --current.
4315 If --requested-size is specified then <requested/> under memory target
4317 is changed to requested size (as scaled integer, see NOTES above). It
4318 defaults to kibibytes if no suffix is provided. The option is valid
4319 only for virtio-mem memory device model.
4320 change-media
4322 Syntax:
4323 change-media domain path [--eject] [--insert]
4325 [--update] [source] [--force] [[--live] [--config] |
4326 [--current]] [--print-xml] [--block]
4327 Change media of CDROM or floppy drive. path can be the fully-qualified
4329 path or the unique target name (<target dev='hdc'>) of the disk device.
4330 source specifies the path of the media to be inserted or updated. The
4331 --block flag allows setting the backing type in case a block device is
4332 used as media for the CDROM or floppy drive instead of a file.
4333 --eject indicates the media will be ejected. --insert indicates the
4335 media will be inserted. source must be specified. If the device has
4336 source (e.g. <source file='media'>), and source is not specified, --up‐
4337 date is equal to --eject. If the device has no source, and source is
4338 specified, --update is equal to --insert. If the device has source, and
4339 source is specified, --update behaves like combination of --eject and
4340 --insert. If none of --eject, --insert, and --update is specified,
4341 --update is used by default. The --force option can be used to force
4342 media changing. If --live is specified, alter live configuration of
4343 running guest. If --config is specified, alter persistent configura‐
4344 tion, effect observed on next startup of the guest. --current can be
4345 either or both of live and config, depends on the hypervisor's imple‐
4346 mentation. Both --live and --config flags may be given, but --current
4347 is exclusive. If no flag is specified, behavior is different depending
4348 on hypervisor. If --print-xml is specified, the XML that would be used
4349 to change media is printed instead of changing the media.
4350
4352 The following commands manipulate host devices that are intended to be
4353 passed through to guest domains via <hostdev> elements in a domain's
4354 <devices> section. A node device key is generally specified by the bus
4355 name followed by its address, using underscores between all components,
4356 such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
4357 The nodedev-list gives the full list of host devices that are known to
4358 libvirt, although this includes devices that cannot be assigned to a
4359 guest (for example, attempting to detach the PCI device that controls
4360 the host's hard disk controller where the guest's disk images live
4361 could cause the host system to lock up or reboot).
4362 For more information on node device definition see:
4364 https://libvirt.org/formatnode.html.
4365 Passthrough devices cannot be simultaneously used by the host and its
4367 guest domains, nor by multiple active guests at once. If the <hostdev>
4368 description of a PCI device includes the attribute managed='yes', and
4369 the hypervisor driver supports it, then the device is in managed mode,
4370 and attempts to use that passthrough device in an active guest will au‐
4371 tomatically behave as if nodedev-detach (guest start, device hot-plug)
4372 and nodedev-reattach (guest stop, device hot-unplug) were called at the
4373 right points. If a PCI device is not marked as managed, then it must
4374 manually be detached before guests can use it, and manually reattached
4375 to be returned to the host. Also, if a device is manually detached,
4376 then the host does not regain control of the device without a matching
4377 reattach, even if the guests use the device in managed mode.
4378 nodedev-create
4380 Syntax:
4381 nodedev-create FILE
4383 Create a device on the host node that can then be assigned to virtual
4385 machines. Normally, libvirt is able to automatically determine which
4386 host nodes are available for use, but this allows registration of host
4387 hardware that libvirt did not automatically detect. file contains xml
4388 for a top-level <device> description of a node device.
4389 nodedev-destroy
4391 Syntax:
4392 nodedev-destroy device
4394 Destroy (stop) a device on the host. device can be either device name
4396 or wwn pair in "wwnn,wwpn" format (only works for vHBA currently).
4397 Note that this makes libvirt quit managing a host device, and may even
4398 make that device unusable by the rest of the physical host until a re‐
4399 boot.
4400 nodedev-define
4402 Syntax:
4403 nodedev-define FILE
4405 Define an inactive persistent device or modify an existing persistent
4407 one from the XML FILE.
4408 nodedev-undefine
4410 Syntax:
4411 nodedev-undefine device
4413 Undefine the configuration for a persistent device. If the device is
4415 active, make it transient.
4416 nodedev-start
4418 Syntax:
4419 nodedev-start device
4421 Start a (previously defined) inactive device.
4423 nodedev-detach
4425 Syntax:
4426 nodedev-detach nodedev [--driver backend_driver]
4428 Detach nodedev from the host, so that it can safely be used by guests
4430 via <hostdev> passthrough. This is reversed with nodedev-reattach, and
4431 is done automatically for managed devices.
4432 Different backend drivers expect the device to be bound to different
4434 dummy devices. For example, QEMU's "kvm" backend driver (the default)
4435 expects the device to be bound to pci-stub, but its "vfio" backend
4436 driver expects the device to be bound to vfio-pci. The --driver parame‐
4437 ter can be used to specify the desired backend driver.
4438 nodedev-dumpxml
4440 Syntax:
4441 nodedev-dumpxml device
4443 Dump a <device> XML representation for the given node device, including
4445 such information as the device name, which bus owns the device, the
4446 vendor and product id, and any capabilities of the device usable by
4447 libvirt (such as whether device reset is supported). device can be ei‐
4448 ther device name or wwn pair in "wwnn,wwpn" format (only works for
4449 HBA).
4450 nodedev-info
4452 Syntax:
4453 nodedev-info device
4455 Returns basic information about the device object.
4457 nodedev-list
4459 Syntax:
4460 nodedev-list [--cap capability] [--tree] [--inactive | --all]
4462 List all of the devices available on the node that are known by lib‐
4464 virt. cap is used to filter the list by capability types, the types
4465 must be separated by comma, e.g. --cap pci,scsi. Valid capability types
4466 include 'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host',
4467 'scsi_target', 'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic',
4468 'drm', 'mdev', 'mdev_types', 'ccw', 'css', 'ap_card', 'ap_queue',
4469 'ap_matrix'. By default, only active devices are listed. --inactive is
4470 used to list only inactive devices, and -all is used to list both ac‐
4471 tive and inactive devices. If --tree is used, the output is formatted
4472 in a tree representing parents of each node. --tree is mutually exclu‐
4473 sive with all other options.
4474 nodedev-reattach
4476 Syntax:
4477 nodedev-reattach nodedev
4479 Declare that nodedev is no longer in use by any guests, and that the
4481 host can resume normal use of the device. This is done automatically
4482 for PCI devices in managed mode and USB devices, but must be done ex‐
4483 plicitly to match any explicit nodedev-detach.
4484 nodedev-reset
4486 Syntax:
4487 nodedev-reset nodedev
4489 Trigger a device reset for nodedev, useful prior to transferring a node
4491 device between guest passthrough or the host. Libvirt will often do
4492 this action implicitly when required, but this command allows an ex‐
4493 plicit reset when needed.
4494 nodedev-event
4496 Syntax:
4497 nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list}
4499 Wait for a class of node device events to occur, and print appropriate
4501 details of events as they happen. The events can optionally be fil‐
4502 tered by nodedev. Using --list as the only argument will provide a
4503 list of possible event values known by this client, although the con‐
4504 nection might not allow registering for all these events.
4505 By default, this command is one-shot, and returns success once an event
4507 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4508 If --timeout is specified, the command gives up waiting for events af‐
4509 ter seconds have elapsed. With --loop, the command prints all events
4510 until a timeout or interrupt key.
4511 When --timestamp is used, a human-readable timestamp will be printed
4513 before the event.
4514 nodedev-autostart
4516 Syntax:
4517 nodedev-autostart [--disable] device
4519 Configure a device to be automatically started when the host machine
4521 boots or the parent device becomes available. With --disable, the de‐
4522 vice will be set to manual mode and will no longer be automatically
4523 started by the host. This command is only supported for persis‐
4524 tently-defined mediated devices.
4525
4527 The following commands manipulate networks. Libvirt has the capability
4528 to define virtual networks which can then be used by domains and linked
4529 to actual network devices. For more detailed information about this
4530 feature see the documentation at https://libvirt.org/formatnetwork.html
4531 . Many of the commands for virtual networks are similar to the ones
4532 used for domains, but the way to name a virtual network is either by
4533 its name or UUID.
4534 net-autostart
4536 Syntax:
4537 net-autostart network [--disable]
4539 Configure a virtual network to be automatically started at boot. The
4541 --disable option disable autostarting.
4542 net-create
4544 Syntax:
4545 net-create file [--validate]
4547 Create a transient (temporary) virtual network from an XML file and in‐
4549 stantiate (start) the network. See the documentation at
4550 https://libvirt.org/formatnetwork.html to get a description of the XML
4551 network format used by libvirt.
4552 Optionally, the format of the input XML file can be validated against
4554 an internal RNG schema with --validate.
4555 net-define
4557 Syntax:
4558 net-define file [--validate]
4560 Define an inactive persistent virtual network or modify an existing
4562 persistent one from the XML file. Optionally, the format of the input
4563 XML file can be validated against an internal RNG schema with --vali‐
4564 date.
4565 net-destroy
4567 Syntax:
4568 net-destroy network
4570 Destroy (stop) a given transient or persistent virtual network speci‐
4572 fied by its name or UUID. This takes effect immediately.
4573 net-dumpxml
4575 Syntax:
4576 net-dumpxml network [--inactive]
4578 Output the virtual network information as an XML dump to stdout. If
4580 --inactive is specified, then physical functions are not expanded into
4581 their associated virtual functions.
4582 net-edit
4584 Syntax:
4585 net-edit network
4587 Edit the XML configuration file for a network.
4589 This is equivalent to:
4591 virsh net-dumpxml --inactive network > network.xml
4593 vi network.xml (or make changes with your other text editor)
4594 virsh net-define network.xml
4595 except that it does some error checking.
4597 The editor used can be supplied by the $VISUAL or $EDITOR environment
4599 variables, and defaults to vi.
4600 net-event
4602 Syntax:
4603 net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list}
4605 Wait for a class of network events to occur, and print appropriate de‐
4607 tails of events as they happen. The events can optionally be filtered
4608 by network. Using --list as the only argument will provide a list of
4609 possible event values known by this client, although the connection
4610 might not allow registering for all these events.
4611 By default, this command is one-shot, and returns success once an event
4613 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4614 If --timeout is specified, the command gives up waiting for events af‐
4615 ter seconds have elapsed. With --loop, the command prints all events
4616 until a timeout or interrupt key.
4617 When --timestamp is used, a human-readable timestamp will be printed
4619 before the event.
4620 net-info
4622 Syntax:
4623 net-info network
4625 Returns basic information about the network object.
4627 net-list
4629 Syntax:
4630 net-list [--inactive | --all]
4632 { [--table] | --name | --uuid }
4633 [--persistent] [<--transient>]
4634 [--autostart] [<--no-autostart>]
4635 Returns the list of active networks, if --all is specified this will
4637 also include defined but inactive networks, if --inactive is specified
4638 only the inactive ones will be listed. You may also want to filter the
4639 returned networks by --persistent to list the persistent ones, --tran‐
4640 sient to list the transient ones, --autostart to list the ones with au‐
4641 tostart enabled, and --no-autostart to list the ones with autostart
4642 disabled.
4643 If --name is specified, network names are printed instead of the table
4645 formatted one per line. If --uuid is specified network's UUID's are
4646 printed instead of names. Flag --table specifies that the legacy ta‐
4647 ble-formatted output should be used. This is the default. All of these
4648 are mutually exclusive.
4649 NOTE: When talking to older servers, this command is forced to use a
4651 series of API calls with an inherent race, where a pool might not be
4652 listed or might appear more than once if it changed state between calls
4653 while the list was being collected. Newer servers do not have this
4654 problem.
4655 net-name
4657 Syntax:
4658 net-name network-UUID
4660 Convert a network UUID to network name.
4662 net-start
4664 Syntax:
4665 net-start network
4667 Start a (previously defined) inactive network.
4669 net-undefine
4671 Syntax:
4672 net-undefine network
4674 Undefine the configuration for a persistent network. If the network is
4676 active, make it transient.
4677 net-uuid
4679 Syntax:
4680 net-uuid network-name
4682 Convert a network name to network UUID.
4684 net-update
4686 Syntax:
4687 net-update network command section xml
4689 [--parent-index index] [[--live] [--config] | [--current]]
4690 Update the given section of an existing network definition, with the
4692 changes optionally taking effect immediately, without needing to de‐
4693 stroy and re-start the network.
4694 command is one of "add-first", "add-last", "add" (a synonym for
4696 add-last), "delete", or "modify".
4697 section is one of "bridge", "domain", "ip", "ip-dhcp-host",
4699 "ip-dhcp-range", "forward", "forward-interface", "forward-pf", "port‐
4700 group", "dns-host", "dns-txt", or "dns-srv", each section being named
4701 by a concatenation of the xml element hierarchy leading to the element
4702 being changed. For example, "ip-dhcp-host" will change a <host> element
4703 that is contained inside a <dhcp> element inside an <ip> element of the
4704 network.
4705 xml is either the text of a complete xml element of the type being
4707 changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the
4708 name of a file that contains a complete xml element. Disambiguation is
4709 done by looking at the first character of the provided text - if the
4710 first character is "<", it is xml text, if the first character is not
4711 "<", it is the name of a file that contains the xml text to be used.
4712 The --parent-index option is used to specify which of several parent
4714 elements the requested element is in (0-based). For example, a dhcp
4715 <host> element could be in any one of multiple <ip> elements in the
4716 network; if a parent-index isn't provided, the "most appropriate" <ip>
4717 element will be selected (usually the only one that already has a
4718 <dhcp> element), but if --parent-index is given, that particular in‐
4719 stance of <ip> will get the modification.
4720 If --live is specified, affect a running network. If --config is spec‐
4722 ified, affect the next startup of a persistent network. If --current
4723 is specified, it is equivalent to either --live or --config, depending
4724 on the current state of the guest. Both --live and --config flags may
4725 be given, but --current is exclusive. Not specifying any flag is the
4726 same as specifying --current.
4727 net-dhcp-leases
4729 Syntax:
4730 net-dhcp-leases network [mac]
4732 Get a list of dhcp leases for all network interfaces connected to the
4734 given virtual network or limited output just for one interface if mac
4735 is specified.
4736
4738 The following commands manipulate network ports. Libvirt virtual net‐
4739 works have ports created when a virtual machine has a virtual network
4740 interface added. In general there should be no need to use any of the
4741 commands here, since the hypervisor drivers run these commands are the
4742 right point in a virtual machine's lifecycle. They can be useful for
4743 debugging problems and / or recovering from bugs / stale state.
4744 net-port-list
4746 Syntax:
4747 net-port-list { [--table] | --uuid } network
4749 List all network ports recorded against the network.
4751 If --uuid is specified network ports' UUID's are printed instead of a
4753 table. Flag --table specifies that the legacy table-formatted output
4754 should be used. This is the default. All of these are mutually exclu‐
4755 sive.
4756 net-port-create
4758 Syntax:
4759 net-port-create network file [--validate]
4761 Allocate a new network port reserving resources based on the port de‐
4763 scription. Optionally, the format of the input XML file can be vali‐
4764 dated against an internal RNG schema with --validate.
4765 net-port-dumpxml
4767 Syntax:
4768 net-port-dumpxml network port
4770 Output the network port information as an XML dump to stdout.
4772 net-port-delete
4774 Syntax:
4775 net-port-delete network port
4777 Delete record of the network port and release its resources
4779
4781 The following commands manipulate host interfaces. Often, these host
4782 interfaces can then be used by name within domain <interface> elements
4783 (such as a system-created bridge interface), but there is no require‐
4784 ment that host interfaces be tied to any particular guest configuration
4785 XML at all.
4786 Many of the commands for host interfaces are similar to the ones used
4788 for domains, and the way to name an interface is either by its name or
4789 its MAC address. However, using a MAC address for an iface argument
4790 only works when that address is unique (if an interface and a bridge
4791 share the same MAC address, which is often the case, then using that
4792 MAC address results in an error due to ambiguity, and you must resort
4793 to a name instead).
4794 iface-bridge
4796 Syntax:
4797 iface-bridge interface bridge [--no-stp] [delay] [--no-start]
4799 Create a bridge device named bridge, and attach the existing network
4801 device interface to the new bridge. The new bridge defaults to start‐
4802 ing immediately, with STP enabled and a delay of 0; these settings can
4803 be altered with --no-stp, --no-start, and an integer number of seconds
4804 for delay. All IP address configuration of interface will be moved to
4805 the new bridge device.
4806 See also iface-unbridge for undoing this operation.
4808 iface-define
4810 Syntax:
4811 iface-define file [--validate]
4813 Define an inactive persistent physical host interface or modify an ex‐
4815 isting persistent one from the XML file. Optionally, the format of the
4816 input XML file can be validated against an internal RNG schema with
4817 --validate.
4818 iface-destroy
4820 Syntax:
4821 iface-destroy interface
4823 Destroy (stop) a given host interface, such as by running "if-down" to
4825 disable that interface from active use. This takes effect immediately.
4826 iface-dumpxml
4828 Syntax:
4829 iface-dumpxml interface [--inactive]
4831 Output the host interface information as an XML dump to stdout. If
4833 --inactive is specified, then the output reflects the persistent state
4834 of the interface that will be used the next time it is started.
4835 iface-edit
4837 Syntax:
4838 iface-edit interface
4840 Edit the XML configuration file for a host interface.
4842 This is equivalent to:
4844 virsh iface-dumpxml iface > iface.xml
4846 vi iface.xml (or make changes with your other text editor)
4847 virsh iface-define iface.xml
4848 except that it does some error checking.
4850 The editor used can be supplied by the $VISUAL or $EDITOR environment
4852 variables, and defaults to vi.
4853 iface-list
4855 Syntax:
4856 iface-list [--inactive | --all]
4858 Returns the list of active host interfaces. If --all is specified this
4860 will also include defined but inactive interfaces. If --inactive is
4861 specified only the inactive ones will be listed.
4862 iface-name
4864 Syntax:
4865 iface-name interface
4867 Convert a host interface MAC to interface name, if the MAC address is
4869 unique among the host's interfaces.
4870 interface specifies the interface MAC address.
4872 iface-mac
4874 Syntax:
4875 iface-mac interface
4877 Convert a host interface name to MAC address.
4879 interface specifies the interface name.
4881 iface-start
4883 Syntax:
4884 iface-start interface
4886 Start a (previously defined) host interface, such as by running
4888 "if-up".
4889 iface-unbridge
4891 Syntax:
4892 iface-unbridge bridge [--no-start]
4894 Tear down a bridge device named bridge, releasing its underlying inter‐
4896 face back to normal usage, and moving all IP address configuration from
4897 the bridge device to the underlying device. The underlying interface
4898 is restarted unless --no-start is present; this flag is present for
4899 symmetry, but generally not recommended.
4900 See also iface-bridge for creating a bridge.
4902 iface-undefine
4904 Syntax:
4905 iface-undefine interface
4907 Undefine the configuration for an inactive host interface.
4909 iface-begin
4911 Syntax:
4912 iface-begin
4914 Create a snapshot of current host interface settings, which can later
4916 be committed (iface-commit) or restored (iface-rollback). If a snap‐
4917 shot already exists, then this command will fail until the previous
4918 snapshot has been committed or restored. Undefined behavior results if
4919 any external changes are made to host interfaces outside of the libvirt
4920 API between the beginning of a snapshot and its eventual commit or
4921 rollback.
4922 iface-commit
4924 Syntax:
4925 iface-commit
4927 Declare all changes since the last iface-begin as working, and delete
4929 the rollback point. If no interface snapshot has already been started,
4930 then this command will fail.
4931 iface-rollback
4933 Syntax:
4934 iface-rollback
4936 Revert all host interface settings back to the state recorded in the
4938 last iface-begin. If no interface snapshot has already been started,
4939 then this command will fail. Rebooting the host also serves as an im‐
4940 plicit rollback point.
4941
4943 The following commands manipulate storage pools. Libvirt has the capa‐
4944 bility to manage various storage solutions, including files, raw parti‐
4945 tions, and domain-specific formats, used to provide the storage volumes
4946 visible as devices within virtual machines. For more detailed informa‐
4947 tion about this feature, see the documentation at
4948 https://libvirt.org/formatstorage.html . Many of the commands for pools
4949 are similar to the ones used for domains.
4950 find-storage-pool-sources
4952 Syntax:
4953 find-storage-pool-sources type [srcSpec]
4955 Returns XML describing all possible available storage pool sources that
4957 could be used to create or define a storage pool of a given type. If
4958 srcSpec is provided, it is a file that contains XML to further restrict
4959 the query for pools.
4960 Not all storage pools support discovery in this manner. Furthermore,
4962 for those that do support discovery, only specific XML elements are re‐
4963 quired in order to return valid data, while other elements and even at‐
4964 tributes of some elements are ignored since they are not necessary to
4965 find the pool based on the search criteria. The following lists the
4966 supported type options and the expected minimal XML elements used to
4967 perform the search.
4968 For a "netfs" or "gluster" pool, the minimal expected XML required is
4970 the <host> element with a "name" attribute describing the IP address or
4971 hostname to be used to find the pool. The "port" attribute will be ig‐
4972 nored as will any other provided XML elements in srcSpec.
4973 For a "logical" pool, the contents of the srcSpec file are ignored, al‐
4975 though if provided the file must at least exist.
4976 For an "iscsi" or "iscsi-direct" pool, the minimal expect XML required
4978 is the <host> element with a "name" attribute describing the IP address
4979 or hostname to be used to find the pool (the iSCSI server address). Op‐
4980 tionally, the "port" attribute may be provided, although it will de‐
4981 fault to 3260. Optionally, an <initiator> XML element with a "name" at‐
4982 tribute may be provided to further restrict the iSCSI target search to
4983 a specific initiator for multi-iqn iSCSI storage pools.
4984 find-pool-sources-as
4986 Syntax:
4987 find-storage-pool-sources-as type [host] [port] [initiator]
4989 Rather than providing srcSpec XML file for find-storage-pool-sources
4991 use this command option in order to have virsh generate the query XML
4992 file using the optional arguments. The command will return the same
4993 output XML as find-storage-pool-sources.
4994 Use host to describe a specific host to use for networked storage, such
4996 as netfs, gluster, and iscsi type pools.
4997 Use port to further restrict which networked port to utilize for the
4999 connection if required by the specific storage backend, such as iscsi.
5000 Use initiator to further restrict the iscsi type pool searches to spe‐
5002 cific target initiators.
5003 pool-autostart
5005 Syntax:
5006 pool-autostart pool-or-uuid [--disable]
5008 Configure whether pool should automatically start at boot.
5010 pool-build
5012 Syntax:
5013 pool-build pool-or-uuid [--overwrite] [--no-overwrite]
5015 Build a given pool.
5017 Options --overwrite and --no-overwrite can only be used for pool-build
5019 a filesystem, disk, or logical pool.
5020 For a file system pool if neither flag is specified, then pool-build
5022 just makes the target path directory and no attempt to run mkfs on the
5023 target volume device. If --no-overwrite is specified, it probes to de‐
5024 termine if a filesystem already exists on the target device, returning
5025 an error if one exists or using mkfs to format the target device if
5026 not. If --overwrite is specified, mkfs is always executed and any ex‐
5027 isting data on the target device is overwritten unconditionally.
5028 For a disk pool, if neither of them is specified or --no-overwrite is
5030 specified, pool-build will check the target volume device for existing
5031 filesystems or partitions before attempting to write a new label on the
5032 target volume device. If the target volume device already has a label,
5033 the command will fail. If --overwrite is specified, then no check will
5034 be made on the target volume device prior to writing a new label. Writ‐
5035 ing of the label uses the pool source format type or "dos" if not spec‐
5036 ified.
5037 For a logical pool, if neither of them is specified or --no-overwrite
5039 is specified, pool-build will check the target volume devices for ex‐
5040 isting filesystems or partitions before attempting to initialize and
5041 format each device for usage by the logical pool. If any target volume
5042 device already has a label, the command will fail. If --overwrite is
5043 specified, then no check will be made on the target volume devices
5044 prior to initializing and formatting each device. Once all the target
5045 volume devices are properly formatted via pvcreate, the volume group
5046 will be created using all the devices.
5047 pool-create
5049 Syntax:
5050 pool-create file [--build] [[--overwrite] | [--no-overwrite]]
5052 Create and start a pool object from the XML file.
5054 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
5056 creation in order to remove the need for a follow-up command to build
5057 the pool. The --overwrite and --no-overwrite flags follow the same
5058 rules as pool-build. If just --build is provided, then pool-build is
5059 called with no flags.
5060 pool-create-as
5062 Syntax:
5063 pool-create-as name type
5065 [--source-host hostname] [--source-path path] [--source-dev path]
5066 [--source-name name] [--target path] [--source-format format]
5067 [--source-initiator initiator-iqn]
5068 [--auth-type authtype --auth-username username
5069 [--secret-usage usage | --secret-uuid uuid]]
5070 [--source-protocol-ver ver]
5071 [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn]
5072 [--adapter-parent parent |
5073 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
5074 --adapter-parent-fabric-wwn parent_fabric_wwn]]
5075 [--build] [[--overwrite] | [--no-overwrite]] [--print-xml]
5076 Create and start a pool object name from the raw parameters. If
5078 --print-xml is specified, then print the XML of the pool object without
5079 creating the pool. Otherwise, the pool has the specified type. When
5080 using pool-create-as for a pool of type "disk", the existing partitions
5081 found on the --source-dev path will be used to populate the disk pool.
5082 Therefore, it is suggested to use pool-define-as and pool-build with
5083 the --overwrite in order to properly initialize the disk pool.
5084 [--source-host hostname] provides the source hostname for pools backed
5086 by storage from a remote server (pool types netfs, iscsi, rbd, sheep‐
5087 dog, gluster).
5088 [--source-path path] provides the source directory path for pools
5090 backed by directories (pool type dir).
5091 [--source-dev path] provides the source path for pools backed by physi‐
5093 cal devices (pool types fs, logical, disk, iscsi, zfs).
5094 [--source-name name] provides the source name for pools backed by stor‐
5096 age from a named element (pool types logical, rbd, sheepdog, gluster).
5097 [--target path] is the path for the mapping of the storage pool into
5099 the host file system.
5100 [--source-format format] provides information about the format of the
5102 pool (pool types fs, netfs, disk, logical).
5103 [--source-initiator initiator-iqn] provides the initiator iqn for iscsi
5105 connection of the pool (pool type iscsi-direct).
5106 [--auth-type authtype --auth-username username [--secret-usage usage |
5108 --secret-uuid uuid]] provides the elements required to generate authen‐
5109 tication credentials for the storage pool. The authtype is either chap
5110 for iscsi type pools or ceph for rbd type pools. Either the secret us‐
5111 age or uuid value may be provided, but not both.
5112 [--source-protocol-ver ver] provides the NFS protocol version number
5114 used to contact the server's NFS service via nfs mount option
5115 'nfsvers=n'. It is expect the ver value is an unsigned integer.
5116 [--adapter-name name] defines the scsi_hostN adapter name to be used
5118 for the scsi_host adapter type pool.
5119 [--adapter-wwnn wwnn --adapter-wwpn wwpn [--adapter-parent parent |
5121 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
5122 --adapter-parent-fabric-wwn parent_fabric_wwn]] defines the wwnn and
5123 wwpn to be used for the fc_host adapter type pool. Optionally provide
5124 the parent scsi_hostN node device to be used for the vHBA either by
5125 parent name, parent_wwnn and parent_wwpn, or parent_fabric_wwn. The
5126 parent name could change between reboots if the hardware environment
5127 changes, so providing the parent_wwnn and parent_wwpn ensure usage of
5128 the same physical HBA even if the scsi_hostN node device changes. Usage
5129 of the parent_fabric_wwn allows a bit more flexibility to choose an HBA
5130 on the same storage fabric in order to define the pool.
5131 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
5133 creation in order to remove the need for a follow-up command to build
5134 the pool. The --overwrite and --no-overwrite flags follow the same
5135 rules as pool-build. If just --build is provided, then pool-build is
5136 called with no flags.
5137 For a "logical" pool only [--name] needs to be provided. The
5139 [--source-name] if provided must match the Volume Group name. If not
5140 provided, one will be generated using the [--name]. If provided the
5141 [--target] is ignored and a target source is generated using the
5142 [--source-name] (or as generated from the [--name]).
5143 pool-define
5145 Syntax:
5146 pool-define file [--validate]
5148 Define an inactive persistent storage pool or modify an existing per‐
5150 sistent one from the XML file. Optionally, the format of the input XML
5151 file can be validated against an internal RNG schema with --validate.
5152 pool-define-as
5154 Syntax:
5155 pool-define-as name type
5157 [--source-host hostname] [--source-path path] [--source-dev path]
5158 [*--source-name name*] [*--target path*] [*--source-format format*]
5159 [--source-initiator initiator-iqn]
5160 [*--auth-type authtype* *--auth-username username*
5161 [*--secret-usage usage* | *--secret-uuid uuid*]]
5162 [*--source-protocol-ver ver*]
5163 [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*]
5164 [*--adapter-parent parent*]] [*--print-xml*]
5165 Create, but do not start, a pool object name from the raw parameters.
5167 If --print-xml is specified, then print the XML of the pool object
5168 without defining the pool. Otherwise, the pool has the specified type.
5169 Use the same arguments as pool-create-as, except for the --build,
5171 --overwrite, and --no-overwrite options.
5172 pool-destroy
5174 Syntax:
5175 pool-destroy pool-or-uuid
5177 Destroy (stop) a given pool object. Libvirt will no longer manage the
5179 storage described by the pool object, but the raw data contained in the
5180 pool is not changed, and can be later recovered with pool-create.
5181 pool-delete
5183 Syntax:
5184 pool-delete pool-or-uuid
5186 Destroy the resources used by a given pool object. This operation is
5188 non-recoverable. The pool object will still exist after this command,
5189 ready for the creation of new storage volumes.
5190 pool-dumpxml
5192 Syntax:
5193 pool-dumpxml [--inactive] pool-or-uuid
5195 Returns the XML information about the pool object. --inactive tells
5197 virsh to dump pool configuration that will be used on next start of the
5198 pool as opposed to the current pool configuration.
5199 pool-edit
5201 Syntax:
5202 pool-edit pool-or-uuid
5204 Edit the XML configuration file for a storage pool.
5206 This is equivalent to:
5208 virsh pool-dumpxml pool > pool.xml
5210 vi pool.xml (or make changes with your other text editor)
5211 virsh pool-define pool.xml
5212 except that it does some error checking.
5214 The editor used can be supplied by the $VISUAL or $EDITOR environment
5216 variables, and defaults to vi.
5217 pool-info
5219 Syntax:
5220 pool-info [--bytes] pool-or-uuid
5222 Returns basic information about the pool object. If --bytes is speci‐
5224 fied the sizes of basic info are not converted to human friendly units.
5225 pool-list
5227 Syntax:
5228 pool-list [--inactive] [--all]
5230 [--persistent] [--transient]
5231 [--autostart] [--no-autostart]
5232 [[--details] [--uuid]
5233 [--name] [<type>]
5234 List pool objects known to libvirt. By default, only active pools are
5236 listed; --inactive lists just the inactive pools, and --all lists all
5237 pools.
5238 In addition, there are several sets of filtering flags. --persistent is
5240 to list the persistent pools, --transient is to list the transient
5241 pools. --autostart lists the autostarting pools, --no-autostart lists
5242 the pools with autostarting disabled. If --uuid is specified only
5243 pool's UUIDs are printed. If --name is specified only pool's names are
5244 printed. If both --name and --uuid are specified, pool's UUID and names
5245 are printed side by side without any header. Option --details is mutu‐
5246 ally exclusive with options --uuid and --name.
5247 You may also want to list pools with specified types using type, the
5249 pool types must be separated by comma, e.g. --type dir,disk. The valid
5250 pool types include 'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi',
5251 'scsi', 'mpath', 'rbd', 'sheepdog', 'gluster', 'zfs', 'vstorage' and
5252 'iscsi-direct'.
5253 The --details option instructs virsh to additionally display pool per‐
5255 sistence and capacity related information where available.
5256 NOTE: When talking to older servers, this command is forced to use a
5258 series of API calls with an inherent race, where a pool might not be
5259 listed or might appear more than once if it changed state between calls
5260 while the list was being collected. Newer servers do not have this
5261 problem.
5262 pool-name
5264 Syntax:
5265 pool-name uuid
5267 Convert the uuid to a pool name.
5269 pool-refresh
5271 Syntax:
5272 pool-refresh pool-or-uuid
5274 Refresh the list of volumes contained in pool.
5276 pool-start
5278 Syntax:
5279 pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]
5281 Start the storage pool, which is previously defined but inactive.
5283 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build prior
5285 to pool-start to ensure the pool environment is in an expected state
5286 rather than needing to run the build command prior to startup. The
5287 --overwrite and --no-overwrite flags follow the same rules as
5288 pool-build. If just --build is provided, then pool-build is called with
5289 no flags.
5290 Note: A storage pool that relies on remote resources such as an "iscsi"
5292 or a (v)HBA backed "scsi" pool may need to be refreshed multiple times
5293 in order to have all the volumes detected (see pool-refresh). This is
5294 because the corresponding volume devices may not be present in the
5295 host's filesystem during the initial pool startup or the current re‐
5296 fresh attempt. The number of refresh retries is dependent upon the net‐
5297 work connection and the time the host takes to export the corresponding
5298 devices.
5299 pool-undefine
5301 Syntax:
5302 pool-undefine pool-or-uuid
5304 Undefine the configuration for an inactive pool.
5306 pool-uuid
5308 Syntax:
5309 pool-uuid pool
5311 Returns the UUID of the named pool.
5313 pool-event
5315 Syntax:
5316 pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list}
5318 Wait for a class of storage pool events to occur, and print appropriate
5320 details of events as they happen. The events can optionally be fil‐
5321 tered by pool. Using --list as the only argument will provide a list
5322 of possible event values known by this client, although the connection
5323 might not allow registering for all these events.
5324 By default, this command is one-shot, and returns success once an event
5326 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
5327 If --timeout is specified, the command gives up waiting for events af‐
5328 ter seconds have elapsed. With --loop, the command prints all events
5329 until a timeout or interrupt key.
5330 When --timestamp is used, a human-readable timestamp will be printed
5332 before the event.
5333
5335 vol-create
5336 Syntax:
5337 vol-create pool-or-uuid FILE [--prealloc-metadata]
5339 Create a volume from an XML <file>.
5341 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5343 ume in.
5344 FILE is the XML <file> with the volume definition. An easy way to cre‐
5346 ate the XML <file> is to use the vol-dumpxml command to obtain the def‐
5347 inition of a pre-existing volume.
5348 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5350 don't support full allocation). This option creates a sparse image file
5351 with metadata, resulting in higher performance compared to images with
5352 no preallocation and only slightly higher initial disk space usage.
5353 Example:
5355 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
5357 vi newvolume.xml (or make changes with your other text editor)
5358 virsh vol-create differentstoragepool newvolume.xml
5359 vol-create-from
5361 Syntax:
5362 vol-create-from pool-or-uuid FILE vol-name-or-key-or-path
5364 [--inputpool pool-or-uuid] [--prealloc-metadata] [--reflink]
5365 Create a volume, using another volume as input.
5367 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5369 ume in.
5370 FILE is the XML <file> with the volume definition.
5372 vol-name-or-key-or-path is the name or key or path of the source vol‐
5374 ume.
5375 --inputpool pool-or-uuid is the name or uuid of the storage pool the
5377 source volume is in.
5378 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5380 don't support full allocation). This option creates a sparse image file
5381 with metadata, resulting in higher performance compared to images with
5382 no preallocation and only slightly higher initial disk space usage.
5383 When --reflink is specified, perform a COW lightweight copy, where the
5385 data blocks are copied only when modified. If this is not possible,
5386 the copy fails.
5387 vol-create-as
5389 Syntax:
5390 vol-create-as pool-or-uuid name capacity [--allocation size] [--format string]
5392 [--backing-vol vol-name-or-key-or-path]
5393 [--backing-vol-format string] [--prealloc-metadata] [--print-xml]
5394 Create a volume from a set of arguments unless --print-xml is speci‐
5396 fied, in which case just the XML of the volume object is printed out
5397 without any actual object creation.
5398 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5400 ume in.
5401 name is the name of the new volume. For a disk pool, this must match
5403 the partition name as determined from the pool's source device path and
5404 the next available partition. For example, a source device path of
5405 /dev/sdb and there are no partitions on the disk, then the name must be
5406 sdb1 with the next name being sdb2 and so on.
5407 capacity is the size of the volume to be created, as a scaled integer
5409 (see NOTES above), defaulting to bytes if there is no suffix.
5410 --allocation size is the initial size to be allocated in the volume,
5412 also as a scaled integer defaulting to bytes.
5413 --format string is used in file based storage pools to specify the vol‐
5415 ume file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use ex‐
5416 tended for disk storage pools in order to create an extended partition
5417 (other values are validity checked but not preserved when libvirtd is
5418 restarted or the pool is refreshed).
5419 --backing-vol vol-name-or-key-or-path is the source backing volume to
5421 be used if taking a snapshot of an existing volume.
5422 --backing-vol-format string is the format of the snapshot backing vol‐
5424 ume; raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, how‐
5425 ever, meant for file based storage pools.
5426 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5428 don't support full allocation). This option creates a sparse image file
5429 with metadata, resulting in higher performance compared to images with
5430 no preallocation and only slightly higher initial disk space usage.
5431 vol-clone
5433 Syntax:
5434 vol-clone vol-name-or-key-or-path name
5436 [--pool pool-or-uuid] [--prealloc-metadata] [--reflink]
5437 Clone an existing volume within the parent pool. Less powerful, but
5439 easier to type, version of vol-create-from.
5440 vol-name-or-key-or-path is the name or key or path of the source vol‐
5442 ume.
5443 name is the name of the new volume.
5445 --pool pool-or-uuid is the name or UUID of the storage pool that con‐
5447 tains the source volume and will contain the new volume. If the source
5448 volume name is provided instead of the key or path, then providing the
5449 pool is necessary to find the volume to be cloned; otherwise, the first
5450 volume found by the key or path will be used.
5451 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5453 don't support full allocation). This option creates a sparse image file
5454 with metadata, resulting in higher performance compared to images with
5455 no preallocation and only slightly higher initial disk space usage.
5456 When --reflink is specified, perform a COW lightweight copy, where the
5458 data blocks are copied only when modified. If this is not possible,
5459 the copy fails.
5460 vol-delete
5462 Syntax:
5463 vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots]
5465 Delete a given volume.
5467 vol-name-or-key-or-path is the volume name or key or path of the volume
5469 to delete.
5470 [--pool pool-or-uuid] is the name or UUID of the storage pool the vol‐
5472 ume is in. If the volume name is provided instead of the key or path,
5473 then providing the pool is necessary to find the volume to be deleted;
5474 otherwise, the first volume found by the key or path will be used.
5475 The --delete-snapshots flag specifies that any snapshots associated
5477 with the storage volume should be deleted as well. Not all storage
5478 drivers support this option, presently only rbd.
5479 vol-upload
5481 Syntax:
5482 vol-upload vol-name-or-key-or-path local-file
5484 [--pool pool-or-uuid] [--offset bytes]
5485 [--length bytes] [--sparse]
5486 Upload the contents of local-file to a storage volume.
5488 vol-name-or-key-or-path is the name or key or path of the volume where
5490 the local-file will be uploaded.
5491 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5493 is in. If the volume name is provided instead of the key or path, then
5494 providing the pool is necessary to find the volume to be uploaded into;
5495 otherwise, the first volume found by the key or path will be used.
5496 --offset is the position in the storage volume at which to start writ‐
5498 ing the data. The value must be 0 or larger.
5499 --length is an upper bound of the amount of data to be uploaded. A
5501 negative value is interpreted as an unsigned long long value to essen‐
5502 tially include everything from the offset to the end of the volume.
5503 If --sparse is specified, this command will preserve volume sparseness.
5505 An error will occur if the local-file is greater than the specified
5507 length.
5508 See the description for the libvirt virStorageVolUpload API for details
5510 regarding possible target volume and pool changes as a result of the
5511 pool refresh when the upload is attempted.
5512 vol-download
5514 Syntax:
5515 vol-download vol-name-or-key-or-path local-file
5517 [--pool pool-or-uuid] [--offset bytes] [--length bytes]
5518 [--sparse]
5519 Download the contents of a storage volume to local-file.
5521 vol-name-or-key-or-path is the name or key or path of the volume to
5523 download into local-file.
5524 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5526 is in. If the volume name is provided instead of the key or path, then
5527 providing the pool is necessary to find the volume to be uploaded into;
5528 otherwise, the first volume found by the key or path will be used.
5529 --offset is the position in the storage volume at which to start read‐
5531 ing the data. The value must be 0 or larger.
5532 --length is an upper bound of the amount of data to be downloaded. A
5534 negative value is interpreted as an unsigned long long value to essen‐
5535 tially include everything from the offset to the end of the volume.
5536 If --sparse is specified, this command will preserve volume sparseness.
5538 vol-wipe
5540 Syntax:
5541 vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm]
5543 Wipe a volume, ensure data previously on the volume is not accessible
5545 to future reads.
5546 vol-name-or-key-or-path is the name or key or path of the volume to
5548 wipe. It is possible to choose different wiping algorithms instead of
5549 re-writing volume with zeroes.
5550 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5552 is in. If the volume name is provided instead of the key or path, then
5553 providing the pool is necessary to find the volume to be wiped; other‐
5554 wise, the first volume found by the key or path will be used.
5555 Use the --algorithm switch choosing from the list of the following al‐
5557 gorithms in order to define which algorithm to use for the wipe.
5558 Supported algorithms
5560 • zero - 1-pass all zeroes
5562 • nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for sani‐
5564 tizing removable and non-removable hard disks: random x2, 0x00, ver‐
5565 ify.
5566 • dod - 4-pass DoD 5220.22-M section 8-306 procedure for sani‐
5568 tizing removable and non-removable rigid disks: random, 0x00, 0xff,
5569 verify.
5570 • bsi - 9-pass method recommended by the German Center of Secu‐
5572 rity in Information Technologies (https://www.bsi.bund.de): 0xff,
5573 0xfe, 0xfd, 0xfb, 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
5574 • gutmann - The canonical 35-pass sequence described in Gutmann's
5576 paper.
5577 • schneier - 7-pass method described by Bruce Schneier in "Applied
5579 Cryptography" (1996): 0x00, 0xff, random x5.
5580 • pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7.
5582 • pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
5584 • random - 1-pass pattern: random.
5586 • trim - 1-pass trimming the volume using TRIM or DISCARD
5588 Note: The scrub binary will be used to handle the 'nnsa', 'dod', 'bsi',
5590 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33' algorithms. The
5591 availability of the algorithms may be limited by the version of the
5592 scrub binary installed on the host. The 'zero' algorithm will write ze‐
5593 roes to the entire volume. For some volumes, such as sparse or rbd vol‐
5594 umes, this may result in completely filling the volume with zeroes mak‐
5595 ing it appear to be completely full. As an alternative, the 'trim' al‐
5596 gorithm does not overwrite all the data in a volume, rather it expects
5597 the storage driver to be able to discard all bytes in a volume. It is
5598 up to the storage driver to handle how the discarding occurs. Not all
5599 storage drivers or volume types can support 'trim'.
5600 vol-dumpxml
5602 Syntax:
5603 vol-dumpxml vol-name-or-key-or-path [--pool pool-or-uuid]
5605 Output the volume information as an XML dump to stdout.
5607 vol-name-or-key-or-path is the name or key or path of the volume to
5609 output the XML.
5610 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5612 is in. If the volume name is provided instead of the key or path, then
5613 providing the pool is necessary to find the volume to be uploaded into;
5614 otherwise, the first volume found by the key or path will be used.
5615 vol-info
5617 Syntax:
5618 vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical]
5620 Returns basic information about the given storage volume.
5622 vol-name-or-key-or-path is the name or key or path of the volume to re‐
5624 turn information for.
5625 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5627 is in. If the volume name is provided instead of the key or path, then
5628 providing the pool is necessary to find the volume to be uploaded into;
5629 otherwise, the first volume found by the key or path will be used.
5630 If --bytes is specified the sizes are not converted to human friendly
5632 units.
5633 If --physical is specified, then the host physical size is returned and
5635 displayed instead of the allocation value. The physical value for some
5636 file types, such as qcow2 may have a different (larger) physical value
5637 than is shown for allocation. Additionally sparse files will have dif‐
5638 ferent physical and allocation values.
5639 vol-list
5641 Syntax:
5642 vol-list [--pool pool-or-uuid] [--details]
5644 Return the list of volumes in the given storage pool.
5646 --pool pool-or-uuid is the name or UUID of the storage pool.
5648 The --details option instructs virsh to additionally display volume
5650 type and capacity related information where available.
5651 vol-pool
5653 Syntax:
5654 vol-pool vol-key-or-path [--uuid]
5656 Return the pool name or UUID for a given volume. By default, the pool
5658 name is returned.
5659 vol-key-or-path is the key or path of the volume to return the pool in‐
5661 formation.
5662 If the --uuid option is given, the pool UUID is returned instead.
5664 vol-path
5666 Syntax:
5667 vol-path vol-name-or-key [--pool pool-or-uuid]
5669 Return the path for a given volume.
5671 vol-name-or-key is the name or key of the volume to return the path.
5673 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5675 is in. If the volume name is provided instead of the key, then provid‐
5676 ing the pool is necessary to find the volume to be uploaded into; oth‐
5677 erwise, the first volume found by the key will be used.
5678 vol-name
5680 Syntax:
5681 vol-name vol-key-or-path
5683 Return the name for a given volume.
5685 vol-key-or-path is the key or path of the volume to return the name.
5687 vol-key
5689 Syntax:
5690 vol-key vol-name-or-path [--pool pool-or-uuid]
5692 Return the volume key for a given volume.
5694 vol-name-or-path is the name or path of the volume to return the volume
5696 key.
5697 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5699 is in. If the volume name is provided instead of the path, then provid‐
5700 ing the pool is necessary to find the volume to be uploaded into; oth‐
5701 erwise, the first volume found by the path will be used.
5702 vol-resize
5704 Syntax:
5705 vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink]
5707 Resize the capacity of the given volume, in bytes.
5709 vol-name-or-key-or-path is the name or key or path of the volume to re‐
5711 size.
5712 capacity is a scaled integer (see NOTES above) for the volume, which
5714 defaults to bytes if there is no suffix.
5715 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5717 is in. If the volume name is provided instead of the key or path, then
5718 providing the pool is necessary to find the volume to be uploaded into;
5719 otherwise, the first volume found by the key or path will be used.
5720 The new capacity might be sparse unless --allocate is specified.
5722 Normally, capacity is the new size, but if --delta is present, then it
5724 is added to the existing size.
5725 Attempts to shrink the volume will fail unless --shrink is present.
5727 The capacity cannot be negative unless --shrink is provided, but a neg‐
5728 ative sign is not necessary.
5729 This command is only safe for storage volumes not in use by an active
5731 guest; see also blockresize for live resizing.
5732
5734 The following commands manipulate "secrets" (e.g. passwords,
5735 passphrases and encryption keys). Libvirt can store secrets indepen‐
5736 dently from their use, and other objects (e.g. volumes or domains) can
5737 refer to the secrets for encryption or possibly other uses. Secrets
5738 are identified using a UUID. See https://libvirt.org/formatsecret.html
5739 for documentation of the XML format used to represent properties of se‐
5740 crets.
5741 secret-define
5743 Syntax:
5744 secret-define file [--validate]
5746 Create a secret with the properties specified in file, with no associ‐
5748 ated secret value. If file does not specify a UUID, choose one auto‐
5749 matically. If file specifies a UUID of an existing secret, replace its
5750 properties by properties defined in file, without affecting the secret
5751 value.
5752 Optionally, the format of the input XML file can be validated against
5754 an internal RNG schema with --validate.
5755 secret-dumpxml
5757 Syntax:
5758 secret-dumpxml secret
5760 Output properties of secret (specified by its UUID) as an XML dump to
5762 stdout.
5763 secret-event
5765 Syntax:
5766 secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list}
5768 Wait for a class of secret events to occur, and print appropriate de‐
5770 tails of events as they happen. The events can optionally be filtered
5771 by secret. Using --list as the only argument will provide a list of
5772 possible event values known by this client, although the connection
5773 might not allow registering for all these events.
5774 By default, this command is one-shot, and returns success once an event
5776 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
5777 If --timeout is specified, the command gives up waiting for events af‐
5778 ter seconds have elapsed. With --loop, the command prints all events
5779 until a timeout or interrupt key.
5780 When --timestamp is used, a human-readable timestamp will be printed
5782 before the event.
5783 secret-set-value
5785 Syntax:
5786 secret-set-value secret (--file filename [--plain] | --interactive | base64)
5788 Set the value associated with secret (specified by its UUID) to the
5790 value Base64-encoded value base64 or Base-64-encoded contents of file
5791 named filename. Using the --plain flag is together with --file allows
5792 one to use the file contents directly as the secret value.
5793 If --interactive flag is used the secret value is read as a password
5795 from the terminal.
5796 Note that --file, --interactive and base64 options are mutually exclu‐
5798 sive.
5799 Passing secrets via the base64 option on command line is INSECURE and
5801 deprecated. Use the --file option instead.
5802 secret-get-value
5804 Syntax:
5805 secret-get-value [--plain] secret
5807 Output the value associated with secret (specified by its UUID) to std‐
5809 out, encoded using Base64.
5810 If the --plain flag is used the value is not base64 encoded, but rather
5812 printed raw. Note that unless virsh is started in quiet mode (virsh -q)
5813 it prints a newline at the end of the command. This newline is not part
5814 of the secret.
5815 secret-undefine
5817 Syntax:
5818 secret-undefine secret
5820 Delete a secret (specified by its UUID), including the associated
5822 value, if any.
5823 secret-list
5825 Syntax:
5826 secret-list [--ephemeral] [--no-ephemeral]
5828 [--private] [--no-private]
5829 Returns the list of secrets. You may also want to filter the returned
5831 secrets by --ephemeral to list the ephemeral ones, --no-ephemeral to
5832 list the non-ephemeral ones, --private to list the private ones, and
5833 --no-private to list the non-private ones.
5834
5836 The following commands manipulate domain snapshots. Snapshots take the
5837 disk, memory, and device state of a domain at a point-of-time, and save
5838 it for future use. They have many uses, from saving a "clean" copy of
5839 an OS image to saving a domain's state before a potentially destructive
5840 operation. Snapshots are identified with a unique name. See
5841 https://libvirt.org/formatsnapshot.html for documentation of the XML
5842 format used to represent properties of snapshots.
5843 snapshot-create
5845 Syntax:
5846 snapshot-create domain [xmlfile] {[--redefine [--current]] |
5848 [--no-metadata] [--halt] [--disk-only] [--reuse-external]
5849 [--quiesce] [--atomic] [--live]} [--validate]
5850 Create a snapshot for domain domain with the properties specified in
5852 xmlfile. Optionally, the --validate option can be passed to validate
5853 the format of the input XML file against an internal RNG schema (iden‐
5854 tical to using the virt-xml-validate(1) tool). Normally, the only prop‐
5855 erties settable for a domain snapshot are the <name> and <description>
5856 elements, as well as <disks> if --disk-only is given; the rest of the
5857 fields are ignored, and automatically filled in by libvirt. If xmlfile
5858 is completely omitted, then libvirt will choose a value for all fields.
5859 The new snapshot will become current, as listed by snapshot-current.
5860 If --halt is specified, the domain will be left in an inactive state
5862 after the snapshot is created.
5863 If --disk-only is specified, the snapshot will only include disk con‐
5865 tent rather than the usual full system snapshot with vm state. Disk
5866 snapshots are captured faster than full system snapshots, but reverting
5867 to a disk snapshot may require fsck or journal replays, since it is
5868 like the disk state at the point when the power cord is abruptly
5869 pulled; and mixing --halt and --disk-only loses any data that was not
5870 flushed to disk at the time.
5871 If --redefine is specified, then all XML elements produced by snap‐
5873 shot-dumpxml are valid; this can be used to migrate snapshot hierarchy
5874 from one machine to another, to recreate hierarchy for the case of a
5875 transient domain that goes away and is later recreated with the same
5876 name and UUID, or to make slight alterations in the snapshot metadata
5877 (such as host-specific aspects of the domain XML embedded in the snap‐
5878 shot). When this flag is supplied, the xmlfile argument is mandatory,
5879 and the domain's current snapshot will not be altered unless the --cur‐
5880 rent flag is also given.
5881 If --no-metadata is specified, then the snapshot data is created, but
5883 any metadata is immediately discarded (that is, libvirt does not treat
5884 the snapshot as current, and cannot revert to the snapshot unless --re‐
5885 define is later used to teach libvirt about the metadata again).
5886 If --reuse-external is specified, and the snapshot XML requests an ex‐
5888 ternal snapshot with a destination of an existing file, then the desti‐
5889 nation must exist and be pre-created with correct format and metadata.
5890 The file is then reused; otherwise, a snapshot is refused to avoid los‐
5891 ing contents of the existing files.
5892 If --quiesce is specified, libvirt will try to use guest agent to
5894 freeze and unfreeze domain's mounted file systems. However, if domain
5895 has no guest agent, snapshot creation will fail. Currently, this re‐
5896 quires --disk-only to be passed as well.
5897 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
5899 ther succeeds, or fails with no changes; not all hypervisors support
5900 this. If this flag is not specified, then some hypervisors may fail
5901 after partially performing the action, and dumpxml must be used to see
5902 whether any partial changes occurred.
5903 If --live is specified, libvirt takes the snapshot while the guest is
5905 running. Both disk snapshot and domain memory snapshot are taken. This
5906 increases the size of the memory image of the external snapshot. This
5907 is currently supported only for full system external snapshots.
5908 Existence of snapshot metadata will prevent attempts to undefine a per‐
5910 sistent guest. However, for transient domains, snapshot metadata is
5911 silently lost when the domain quits running (whether by command such as
5912 destroy or by internal guest action).
5913 For now, it is not possible to create snapshots in a domain that has
5915 checkpoints, although this restriction will be lifted in a future re‐
5916 lease.
5917 snapshot-create-as
5919 Syntax:
5920 snapshot-create-as domain {[--print-xml] [--no-metadata]
5922 [--halt] [--reuse-external]} [name]
5923 [description] [--disk-only [--quiesce]] [--atomic] [--validate]
5924 [[--live] [--memspec memspec]] [--diskspec] diskspec]...
5925 Create a snapshot for domain domain with the given <name> and <descrip‐
5927 tion>; if either value is omitted, libvirt will choose a value. If
5928 --print-xml is specified, then XML appropriate for snapshot-create is
5929 output, rather than actually creating a snapshot. Otherwise, if --halt
5930 is specified, the domain will be left in an inactive state after the
5931 snapshot is created, and if --disk-only is specified, the snapshot will
5932 not include vm state.
5933 The --memspec option can be used to control whether a full system snap‐
5935 shot is internal or external. The --memspec flag is mandatory, fol‐
5936 lowed by a memspec of the form [file=]name[,snapshot=type], where type
5937 can be no, internal, or external. To include a literal comma in
5938 file=name, escape it with a second comma. --memspec cannot be used to‐
5939 gether with --disk-only.
5940 The --diskspec option can be used to control how --disk-only and exter‐
5942 nal full system snapshots create external files. This option can occur
5943 multiple times, according to the number of <disk> elements in the do‐
5944 main xml. Each <diskspec> is in the form disk[,snap‐
5945 shot=type][,driver=type][,stype=type][,file=name]. A diskspec must be
5946 provided for disks backed by block devices as libvirt doesn't auto-gen‐
5947 erate file names for those. The optional stype parameter allows one to
5948 control the type of the source file. Supported values are 'file' (de‐
5949 fault) and 'block'. To exclude a disk from an external snapshot use
5950 --diskspec disk,snapshot=no.
5951 To include a literal comma in disk or in file=name, escape it with a
5953 second comma. A literal --diskspec must precede each diskspec unless
5954 all three of domain, name, and description are also present. For exam‐
5955 ple, a diskspec of "vda,snapshot=external,file=/path/to,,new" results
5956 in the following XML:
5957 <disk name='vda' snapshot='external'>
5959 <source file='/path/to,new'/>
5960 </disk>
5961 If --reuse-external is specified, and the domain XML or diskspec option
5963 requests an external snapshot with a destination of an existing file,
5964 then the destination must exist and be pre-created with correct format
5965 and metadata. The file is then reused; otherwise, a snapshot is refused
5966 to avoid losing contents of the existing files.
5967 If --quiesce is specified, libvirt will try to use guest agent to
5969 freeze and unfreeze domain's mounted file systems. However, if domain
5970 has no guest agent, snapshot creation will fail. Currently, this re‐
5971 quires --disk-only to be passed as well.
5972 If --no-metadata is specified, then the snapshot data is created, but
5974 any metadata is immediately discarded (that is, libvirt does not treat
5975 the snapshot as current, and cannot revert to the snapshot unless snap‐
5976 shot-create is later used to teach libvirt about the metadata again).
5977 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
5979 ther succeeds, or fails with no changes; not all hypervisors support
5980 this. If this flag is not specified, then some hypervisors may fail
5981 after partially performing the action, and dumpxml must be used to see
5982 whether any partial changes occurred.
5983 If --live is specified, libvirt takes the snapshot while the guest is
5985 running. This increases the size of the memory image of the external
5986 snapshot. This is currently supported only for external full system
5987 snapshots.
5988 For now, it is not possible to create snapshots in a domain that has
5990 checkpoints, although this restriction will be lifted in a future re‐
5991 lease.
5992 Optionally, the --validate option can be passed to validate XML docu‐
5994 ment which is internally generated by this command against the internal
5995 RNG schema.
5996 snapshot-current
5998 Syntax:
5999 snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
6001 Without snapshotname, this will output the snapshot XML for the do‐
6003 main's current snapshot (if any). If --name is specified, just the
6004 current snapshot name instead of the full xml. Otherwise, using --se‐
6005 curity-info will also include security sensitive information in the
6006 XML.
6007 With snapshotname, this is a request to make the existing named snap‐
6009 shot become the current snapshot, without reverting the domain.
6010 snapshot-edit
6012 Syntax:
6013 snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]}
6015 Edit the XML configuration file for snapshotname of a domain. If both
6017 snapshotname and --current are specified, also force the edited snap‐
6018 shot to become the current snapshot. If snapshotname is omitted, then
6019 --current must be supplied, to edit the current snapshot.
6020 This is equivalent to:
6022 virsh snapshot-dumpxml dom name > snapshot.xml
6024 vi snapshot.xml (or make changes with your other text editor)
6025 virsh snapshot-create dom snapshot.xml --redefine [--current]
6026 except that it does some error checking.
6028 The editor used can be supplied by the $VISUAL or $EDITOR environment
6030 variables, and defaults to vi.
6031 If --rename is specified, then the edits can change the snapshot name.
6033 If --clone is specified, then changing the snapshot name will create a
6034 clone of the snapshot metadata. If neither is specified, then the ed‐
6035 its must not change the snapshot name. Note that changing a snapshot
6036 name must be done with care, since the contents of some snapshots, such
6037 as internal snapshots within a single qcow2 file, are accessible only
6038 from the original name.
6039 snapshot-info
6041 Syntax:
6042 snapshot-info domain {snapshot | --current}
6044 Output basic information about a named <snapshot>, or the current snap‐
6046 shot with --current.
6047 snapshot-list
6049 Syntax:
6050 snapshot-list domain [--metadata] [--no-metadata]
6052 [{--parent | --roots | [{--tree | --name}]}] [--topological]
6053 [{[--from] snapshot | --current} [--descendants]]
6054 [--leaves] [--no-leaves] [--inactive] [--active]
6055 [--disk-only] [--internal] [--external]
6056 List all of the available snapshots for the given domain, defaulting to
6058 show columns for the snapshot name, creation time, and domain state.
6059 Normally, table form output is sorted by snapshot name; using --topo‐
6061 logical instead sorts so that no child is listed before its ancestors
6062 (although there may be more than one possible ordering with this prop‐
6063 erty).
6064 If --parent is specified, add a column to the output table giving the
6066 name of the parent of each snapshot. If --roots is specified, the list
6067 will be filtered to just snapshots that have no parents. If --tree is
6068 specified, the output will be in a tree format, listing just snapshot
6069 names. These three options are mutually exclusive. If --name is speci‐
6070 fied only the snapshot name is printed. This option is mutually exclu‐
6071 sive with --tree.
6072 If --from is provided, filter the list to snapshots which are children
6074 of the given snapshot; or if --current is provided, start at the cur‐
6075 rent snapshot. When used in isolation or with --parent, the list is
6076 limited to direct children unless --descendants is also present. When
6077 used with --tree, the use of --descendants is implied. This option is
6078 not compatible with --roots. Note that the starting point of --from or
6079 --current is not included in the list unless the --tree option is also
6080 present.
6081 If --leaves is specified, the list will be filtered to just snapshots
6083 that have no children. Likewise, if --no-leaves is specified, the list
6084 will be filtered to just snapshots with children. (Note that omitting
6085 both options does no filtering, while providing both options will ei‐
6086 ther produce the same list or error out depending on whether the server
6087 recognizes the flags). Filtering options are not compatible with
6088 --tree.
6089 If --metadata is specified, the list will be filtered to just snapshots
6091 that involve libvirt metadata, and thus would prevent undefine of a
6092 persistent guest, or be lost on destroy of a transient domain. Like‐
6093 wise, if --no-metadata is specified, the list will be filtered to just
6094 snapshots that exist without the need for libvirt metadata.
6095 If --inactive is specified, the list will be filtered to snapshots that
6097 were taken when the domain was shut off. If --active is specified, the
6098 list will be filtered to snapshots that were taken when the domain was
6099 running, and where the snapshot includes the memory state to revert to
6100 that running state. If --disk-only is specified, the list will be fil‐
6101 tered to snapshots that were taken when the domain was running, but
6102 where the snapshot includes only disk state.
6103 If --internal is specified, the list will be filtered to snapshots that
6105 use internal storage of existing disk images. If --external is speci‐
6106 fied, the list will be filtered to snapshots that use external files
6107 for disk images or memory state.
6108 snapshot-dumpxml
6110 Syntax:
6111 snapshot-dumpxml domain snapshot [--security-info]
6113 Output the snapshot XML for the domain's snapshot named snapshot. Us‐
6115 ing --security-info will also include security sensitive information.
6116 Use snapshot-current to easily access the XML of the current snapshot.
6117 snapshot-parent
6119 Syntax:
6120 snapshot-parent domain {snapshot | --current}
6122 Output the name of the parent snapshot, if any, for the given snapshot,
6124 or for the current snapshot with --current.
6125 snapshot-revert
6127 Syntax:
6128 snapshot-revert domain {snapshot | --current} [{--running | --paused}]
6130 [--force] [--reset-nvram]
6131 Revert the given domain to the snapshot specified by snapshot, or to
6133 the current snapshot with --current. Be aware that this is a destruc‐
6134 tive action; any changes in the domain since the last snapshot was
6135 taken will be lost. Also note that the state of the domain after snap‐
6136 shot-revert is complete will be the state of the domain at the time the
6137 original snapshot was taken.
6138 Normally, reverting to a snapshot leaves the domain in the state it was
6140 at the time the snapshot was created, except that a disk snapshot with
6141 no vm state leaves the domain in an inactive state. Passing either the
6142 --running or --paused flag will perform additional state changes (such
6143 as booting an inactive domain, or pausing a running domain). Since
6144 transient domains cannot be inactive, it is required to use one of
6145 these flags when reverting to a disk snapshot of a transient domain.
6146 Since libvirt 7.10.0 the VM process is always restarted so the follow‐
6148 ing paragraph is no longer valid. If the snapshot metadata lacks the
6149 full VM XML it's no longer possible to revert to such snapshot.
6150 There are a number of cases where a snapshot revert involves extra
6152 risk, which requires the use of --force to proceed:
6153 • One is the case of a snapshot that lacks full domain information
6155 for reverting configuration (such as snapshots created prior to
6156 libvirt 0.9.5); since libvirt cannot prove that the current con‐
6157 figuration matches what was in use at the time of the snapshot,
6158 supplying --force assures libvirt that the snapshot is compatible
6159 with the current configuration (and if it is not, the domain will
6160 likely fail to run).
6161 • Another is the case of reverting from a running domain to an ac‐
6163 tive state where a new hypervisor has to be created rather than
6164 reusing the existing hypervisor, because it implies drawbacks such
6165 as breaking any existing VNC or Spice connections; this condition
6166 happens with an active snapshot that uses a provably incompatible
6167 configuration, as well as with an inactive snapshot that is com‐
6168 bined with the --start or --pause flag.
6169 • Also, libvirt will refuse to restore snapshots of inactive QEMU
6171 domains while there is managed saved state. This is because those
6172 snapshots do not contain memory state and will therefore not re‐
6173 place the existing memory state. This ends up switching a disk un‐
6174 derneath a running system and will likely cause extensive filesys‐
6175 tem corruption or crashes due to swap content mismatches when run.
6176 If --reset-nvram is specified, any existing NVRAM file will be deleted
6178 and re-initialized from its pristine template.
6179 snapshot-delete
6181 Syntax:
6182 snapshot-delete domain {snapshot | --current}
6184 [--metadata] [{--children | --children-only}]
6185 Delete the snapshot for the domain named snapshot, or the current snap‐
6187 shot with --current. If this snapshot has child snapshots, changes
6188 from this snapshot will be merged into the children. If --children is
6189 passed, then delete this snapshot and any children of this snapshot.
6190 If --children-only is passed, then delete any children of this snap‐
6191 shot, but leave this snapshot intact. These two flags are mutually ex‐
6192 clusive.
6193 If --metadata is specified, then only delete the snapshot metadata
6195 maintained by libvirt, while leaving the snapshot contents intact for
6196 access by external tools; otherwise deleting a snapshot also removes
6197 the data contents from that point in time.
6198
6200 The following commands manipulate domain checkpoints. Checkpoints
6201 serve as a point in time to identify which portions of a guest's disks
6202 have changed after that time, making it possible to perform incremental
6203 and differential backups. Checkpoints are identified with a unique
6204 name. See https://libvirt.org/formatcheckpoint.html for documentation
6205 of the XML format used to represent properties of checkpoints.
6206 checkpoint-create
6208 Syntax:
6209 checkpoint-create domain [xmlfile] { --redefine [--redefine-validate] | [--quiesce]}
6211 Create a checkpoint for domain domain with the properties specified in
6213 xmlfile describing a <domaincheckpoint> top-level element. The format
6214 of the input XML file will be validated against an internal RNG schema
6215 (identical to using the virt-xml-validate(1) tool). If xmlfile is com‐
6216 pletely omitted, then libvirt will create a checkpoint with a name
6217 based on the current time.
6218 If --redefine is specified, then all XML elements produced by check‐
6220 point-dumpxml are valid; this can be used to migrate checkpoint hierar‐
6221 chy from one machine to another, to recreate hierarchy for the case of
6222 a transient domain that goes away and is later recreated with the same
6223 name and UUID, or to make slight alterations in the checkpoint metadata
6224 (such as host-specific aspects of the domain XML embedded in the check‐
6225 point). When this flag is supplied, the xmlfile argument is mandatory.
6226 If --redefine-validate is specified along with --redefine the hypervi‐
6228 sor performs validation of metadata associated with the checkpoint
6229 stored in places besides the checkpoint XML. Note that some hypervisors
6230 may require that the domain is running to perform validation.
6231 If --quiesce is specified, libvirt will try to use guest agent to
6233 freeze and unfreeze domain's mounted file systems. However, if domain
6234 has no guest agent, checkpoint creation will fail.
6235 Existence of checkpoint metadata will prevent attempts to undefine a
6237 persistent guest. However, for transient domains, checkpoint metadata
6238 is silently lost when the domain quits running (whether by command such
6239 as destroy or by internal guest action).
6240 For now, it is not possible to create checkpoints in a domain that has
6242 snapshots, although this restriction will be lifted in a future re‐
6243 lease.
6244 checkpoint-create-as
6246 Syntax:
6247 checkpoint-create-as domain [--print-xml] [name]
6249 [description] [--quiesce] [--diskspec] diskspec]...
6250 Create a checkpoint for domain domain with the given <name> and <de‐
6252 scription>; if either value is omitted, libvirt will choose a value.
6253 If --print-xml is specified, then XML appropriate for checkpoint-create
6254 is output, rather than actually creating a checkpoint.
6255 The --diskspec option can be used to control which guest disks partici‐
6257 pate in the checkpoint. This option can occur multiple times, according
6258 to the number of <disk> elements in the domain xml. Each <diskspec> is
6259 in the form disk[,checkpoint=type][,bitmap=name]. A literal --diskspec
6260 must precede each diskspec unless all three of domain, name, and de‐
6261 scription are also present. For example, a diskspec of "vda,check‐
6262 point=bitmap,bitmap=map1" results in the following XML:
6263 <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
6265 If --quiesce is specified, libvirt will try to use guest agent to
6267 freeze and unfreeze domain's mounted file systems. However, if domain
6268 has no guest agent, checkpoint creation will fail.
6269 For now, it is not possible to create checkpoints in a domain that has
6271 snapshots, although this restriction will be lifted in a future re‐
6272 lease.
6273 checkpoint-edit
6275 Syntax:
6276 checkpoint-edit domain checkpointname
6278 Edit the XML configuration file for checkpointname of a domain.
6280 This is equivalent to:
6282 virsh checkpoint-dumpxml dom name > checkpoint.xml
6284 vi checkpoint.xml (or make changes with your other text editor)
6285 virsh checkpoint-create dom checkpoint.xml --redefine
6286 except that it does some error checking, including that the edits
6288 should not attempt to change the checkpoint name.
6289 The editor used can be supplied by the $VISUAL or $EDITOR environment
6291 variables, and defaults to vi.
6292 checkpoint-info
6294 Syntax:
6295 checkpoint-info domain checkpoint
6297 Output basic information about a named <checkpoint>.
6299 checkpoint-list
6301 Syntax:
6302 checkpoint-list domain [{--parent | --roots |
6304 [{--tree | --name}]}] [--topological]
6305 [[--from] checkpoint | [--descendants]]
6306 [--leaves] [--no-leaves]
6307 List all of the available checkpoints for the given domain, defaulting
6309 to show columns for the checkpoint name and creation time.
6310 Normally, table form output is sorted by checkpoint name; using --topo‐
6312 logical instead sorts so that no child is listed before its ancestors
6313 (although there may be more than one possible ordering with this prop‐
6314 erty).
6315 If --parent is specified, add a column to the output table giving the
6317 name of the parent of each checkpoint. If --roots is specified, the
6318 list will be filtered to just checkpoints that have no parents. If
6319 --tree is specified, the output will be in a tree format, listing just
6320 checkpoint names. These three options are mutually exclusive. If
6321 --name is specified only the checkpoint name is printed. This option is
6322 mutually exclusive with --tree.
6323 If --from is provided, filter the list to checkpoints which are chil‐
6325 dren of the given checkpoint. When used in isolation or with --parent,
6326 the list is limited to direct children unless --descendants is also
6327 present. When used with --tree, the use of --descendants is implied.
6328 This option is not compatible with --roots. Note that the starting
6329 point of --from is not included in the list unless the --tree option is
6330 also present.
6331 If --leaves is specified, the list will be filtered to just checkpoints
6333 that have no children. Likewise, if --no-leaves is specified, the list
6334 will be filtered to just checkpoints with children. (Note that omit‐
6335 ting both options does no filtering, while providing both options will
6336 either produce the same list or error out depending on whether the
6337 server recognizes the flags). Filtering options are not compatible
6338 with --tree.
6339 checkpoint-dumpxml
6341 Syntax:
6342 checkpoint-dumpxml domain checkpoint [--security-info] [--no-domain] [--size]
6344 Output the checkpoint XML for the domain's checkpoint named checkpoint.
6346 Using --security-info will also include security sensitive information.
6347 Using --size will add XML indicating the current size in bytes of guest
6349 data that has changed since the checkpoint was created (although remem‐
6350 ber that guest activity between a size check and actually creating a
6351 backup can result in the backup needing slightly more space). Note that
6352 some hypervisors may require that domain is running when --size is
6353 used.
6354 Using --no-domain will omit the <domain> element from the output for a
6356 more compact view.
6357 checkpoint-parent
6359 Syntax:
6360 checkpoint-parent domain checkpoint
6362 Output the name of the parent checkpoint, if any, for the given check‐
6364 point.
6365 checkpoint-delete
6367 Syntax:
6368 checkpoint-delete domain checkpoint
6370 [--metadata] [{--children | --children-only}]
6371 Delete the checkpoint for the domain named checkpoint. The record of
6373 which portions of the disk changed since the checkpoint are merged into
6374 the parent checkpoint (if any). If --children is passed, then delete
6375 this checkpoint and any children of this checkpoint. If --chil‐
6376 dren-only is passed, then delete any children of this checkpoint, but
6377 leave this checkpoint intact. These two flags are mutually exclusive.
6378 If --metadata is specified, then only delete the checkpoint metadata
6380 maintained by libvirt, while leaving the checkpoint contents intact for
6381 access by external tools; otherwise deleting a checkpoint also removes
6382 the ability to perform an incremental backup from that point in time.
6383
6385 The following commands manipulate network filters. Network filters al‐
6386 low filtering of the network traffic coming from and going to virtual
6387 machines. Individual network traffic filters are written in XML and
6388 may contain references to other network filters, describe traffic fil‐
6389 tering rules, or contain both. Network filters are referenced by vir‐
6390 tual machines from within their interface description. A network filter
6391 may be referenced by multiple virtual machines' interfaces.
6392 nwfilter-define
6394 Syntax:
6395 nwfilter-define xmlfile [--validate]
6397 Make a new network filter known to libvirt. If a network filter with
6399 the same name already exists, it will be replaced with the new XML.
6400 Any running virtual machine referencing this network filter will have
6401 its network traffic rules adapted. If for any reason the network traf‐
6402 fic filtering rules cannot be instantiated by any of the running vir‐
6403 tual machines, then the new XML will be rejected.
6404 Optionally, the format of the input XML file can be validated against
6406 an internal RNG schema with --validate.
6407 nwfilter-undefine
6409 Syntax:
6410 nwfilter-undefine nwfilter-name
6412 Delete a network filter. The deletion will fail if any running virtual
6414 machine is currently using this network filter.
6415 nwfilter-list
6417 Syntax:
6418 nwfilter-list
6420 List all of the available network filters.
6422 nwfilter-dumpxml
6424 Syntax:
6425 nwfilter-dumpxml nwfilter-name
6427 Output the network filter XML.
6429 nwfilter-edit
6431 Syntax:
6432 nwfilter-edit nwfilter-name
6434 Edit the XML of a network filter.
6436 This is equivalent to:
6438 virsh nwfilter-dumpxml myfilter > myfilter.xml
6440 vi myfilter.xml (or make changes with your other text editor)
6441 virsh nwfilter-define myfilter.xml
6442 except that it does some error checking. The new network filter may be
6444 rejected due to the same reason as mentioned in nwfilter-define.
6445 The editor used can be supplied by the $VISUAL or $EDITOR environment
6447 variables, and defaults to vi.
6448
6450 The following commands manipulate network filter bindings. Network fil‐
6451 ter bindings track the association between a network port and a network
6452 filter. Generally the bindings are managed automatically by the hyper‐
6453 visor drivers when adding/removing NICs on a guest.
6454 If an admin is creating/deleting TAP devices for non-guest usage, how‐
6456 ever, the network filter binding commands provide a way to make use of
6457 the network filters directly.
6458 nwfilter-binding-create
6460 Syntax:
6461 nwfilter-binding-create xmlfile [--validate]
6463 Associate a network port with a network filter. The network filter
6465 backend will immediately attempt to instantiate the filter rules on the
6466 port. This command may be used to associate a filter with a currently
6467 running guest that does not have a filter defined for a specific net‐
6468 work port. Since the bindings are generally automatically managed by
6469 the hypervisor, using this command to define a filter for a network
6470 port and then starting the guest afterwards may prevent the guest from
6471 starting if it attempts to use the network port and finds a filter al‐
6472 ready defined.
6473 Optionally, the format of the input XML file can be validated against
6475 an internal RNG schema with --validate.
6476 nwfilter-binding-delete
6478 Syntax:
6479 nwfilter-binding-delete port-name
6481 Disassociate a network port from a network filter. The network filter
6483 backend will immediately tear down the filter rules that exist on the
6484 port. This command may be used to remove the network port binding for a
6485 filter currently in use for the guest while the guest is running with‐
6486 out needing to restart the guest. Restoring the network port binding
6487 filter for the running guest would be accomplished by using nwfil‐
6488 ter-binding-create.
6489 nwfilter-binding-list
6491 Syntax:
6492 nwfilter-binding-list
6494 List all of the network ports which have filters associated with them.
6496 nwfilter-binding-dumpxml
6498 Syntax:
6499 nwfilter-binding-dumpxml port-name
6501 Output the network filter binding XML for the network device called
6503 port-name.
6504
6506 NOTE: Use of the following commands is strongly discouraged. They can
6507 cause libvirt to become confused and do the wrong thing on subsequent
6508 operations. Once you have used these commands, please do not report
6509 problems to the libvirt developers; the reports will be ignored. If
6510 you find that these commands are the only way to accomplish something,
6511 then it is better to request that the feature be added as a first-class
6512 citizen in the regular libvirt library.
6513 qemu-attach
6515 Syntax:
6516 qemu-attach pid
6518 Attach an externally launched QEMU process to the libvirt QEMU driver.
6520 The QEMU process must have been created with a monitor connection using
6521 the UNIX driver. Ideally the process will also have had the '-name' ar‐
6522 gument specified.
6523 $ qemu-kvm -cdrom ~/demo.iso \
6525 -monitor unix:/tmp/demo,server,nowait \
6526 -name foo \
6527 -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea &
6528 $ QEMUPID=$!
6529 $ virsh qemu-attach $QEMUPID
6530 Not all functions of libvirt are expected to work reliably after at‐
6532 taching to an externally launched QEMU process. There may be issues
6533 with the guest ABI changing upon migration and device hotplug or hotun‐
6534 plug may not work. The attached environment should be considered pri‐
6535 marily read-only.
6536 qemu-monitor-command
6538 Syntax:
6539 qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] } command...
6541 Send an arbitrary monitor command command to domain domain through the
6543 QEMU monitor. The results of the command will be printed on stdout.
6544 If more than one argument is provided for command, they are concate‐
6546 nated with a space in between before passing the single command to the
6547 monitor.
6548 Note that libvirt uses the QMP to talk to qemu so command must be valid
6550 JSON in QMP format to work properly. If command is not a JSON object
6551 libvirt tries to wrap it as a JSON object to provide convenient inter‐
6552 face such as the groups of commands with identical handling:
6553 # simple command
6555 $ virsh qemu-monitor-command VM commandname
6556 $ virsh qemu-monitor-command VM '{"execute":"commandname"}'
6557 # with arguments
6559 $ virsh qemu-monitor-command VM commandname '"arg1":123' '"arg2":"test"'
6560 $ virsh qemu-monitor-command VM commandname '{"arg1":123,"arg2":"test"}'
6561 $ virsh qemu-monitor-command VM '{"execute":"commandname", "arguments":{"arg1":123,"arg2":"test"}}'
6562 If --pretty is given the QMP reply is pretty-printed.
6564 If --return-value is given the 'return' key of the QMP response object
6566 is extracted rather than passing through the full reply from QEMU.
6567 If --hmp is passed, the command is considered to be a human monitor
6569 command and libvirt will automatically convert it into QMP and convert
6570 the result back.
6571 qemu-agent-command
6573 Syntax:
6574 qemu-agent-command domain [--timeout seconds | --async | --block] command...
6576 Send an arbitrary guest agent command command to domain domain through
6578 QEMU agent. --timeout, --async and --block options are exclusive.
6579 --timeout requires timeout seconds seconds and it must be positive.
6580 When --aysnc is given, the command waits for timeout whether success or
6581 failed. And when --block is given, the command waits forever with
6582 blocking timeout.
6583 qemu-monitor-event
6585 Syntax:
6586 qemu-monitor-event [domain] [--event event-name]
6588 [--loop] [--timeout seconds] [--pretty] [--regex] [--no-case]
6589 [--timestamp]
6590 Wait for arbitrary QEMU monitor events to occur, and print out the de‐
6592 tails of events as they happen. The events can optionally be filtered
6593 by domain or event-name. The 'query-events' QMP command can be used
6594 via qemu-monitor-command to learn what events are supported. If
6595 --regex is used, event-name is a basic regular expression instead of a
6596 literal string. If --no-case is used, event-name will match case-in‐
6597 sensitively.
6598 By default, this command is one-shot, and returns success once an event
6600 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
6601 If --timeout is specified, the command gives up waiting for events af‐
6602 ter seconds have elapsed. With --loop, the command prints all events
6603 until a timeout or interrupt key. If --pretty is specified, any JSON
6604 event details are pretty-printed for better legibility.
6605 When --timestamp is used, a human-readable timestamp will be printed
6607 before the event, and the timing information provided by QEMU will be
6608 omitted.
6609 lxc-enter-namespace
6611 Syntax:
6612 lxc-enter-namespace domain [--noseclabel] --
6614 /path/to/binary [arg1, [arg2, ...]]
6615 Enter the namespace of domain and execute the command /path/to/binary
6617 passing the requested args. The binary path is relative to the con‐
6618 tainer root filesystem, not the host root filesystem. The binary will
6619 inherit the environment variables / console visible to virsh. The com‐
6620 mand will be run with the same sVirt context and cgroups placement as
6621 processes within the container. This command only works when connected
6622 to the LXC hypervisor driver. This command succeeds only if
6623 /path/to/binary has 0 exit status.
6624 By default the new process will run with the security label of the new
6626 parent container. Use the --noseclabel option to instead have the
6627 process keep the same security label as virsh.
6628
6630 The following environment variables can be set to alter the behaviour
6631 of virsh
6632 • VIRSH_DEBUG=<0 to 4>
6634 Turn on verbose debugging of virsh commands. Valid levels are
6636 • VIRSH_DEBUG=0
6638 DEBUG - Messages at ALL levels get logged
6640 • VIRSH_DEBUG=1
6642 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
6644 • VIRSH_DEBUG=2
6646 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
6648 • VIRSH_DEBUG=3
6650 WARNING - Logs messages at levels WARNING and ERROR
6652 • VIRSH_DEBUG=4
6654 ERROR - Messages at only ERROR level gets logged.
6656 • VIRSH_LOG_FILE=``LOGFILE``
6658 The file to log virsh debug messages.
6660 • VIRSH_DEFAULT_CONNECT_URI
6662 The hypervisor to connect to by default. Set this to a URI, in the
6664 same format as accepted by the connect option. This environment vari‐
6665 able is deprecated in favour of the global LIBVIRT_DEFAULT_URI vari‐
6666 able which serves the same purpose.
6667 • LIBVIRT_DEFAULT_URI
6669 The hypervisor to connect to by default. Set this to a URI, in the
6671 same format as accepted by the connect option. This overrides the de‐
6672 fault URI set in any client config file and prevents libvirt from
6673 probing for drivers.
6674 • VISUAL
6676 The editor to use by the edit and related options.
6678 • EDITOR
6680 The editor to use by the edit and related options, if VISUAL is not
6682 set.
6683 • VIRSH_HISTSIZE
6685 The number of commands to remember in the command history. The de‐
6687 fault value is 500.
6688 • LIBVIRT_DEBUG=LEVEL
6690 Turn on verbose debugging of all libvirt API calls. Valid levels are
6692 • LIBVIRT_DEBUG=1
6694 Messages at level DEBUG or above
6696 • LIBVIRT_DEBUG=2
6698 Messages at level INFO or above
6700 • LIBVIRT_DEBUG=3
6702 Messages at level WARNING or above
6704 • LIBVIRT_DEBUG=4
6706 Messages at level ERROR
6708 For further information about debugging options consult
6710 https://libvirt.org/logging.html
6711
6713 Please report all bugs you discover. This should be done via either:
6714 1. the mailing list
6716 https://libvirt.org/contact.html
6718 2. the bug tracker
6720 https://libvirt.org/bugs.html
6722 Alternatively, you may report bugs to your software distributor / ven‐
6724 dor.
6725
6727 Please refer to the AUTHORS file distributed with libvirt.
6728
6730 Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in
6731 the libvirt AUTHORS file.
6732
6734 virsh is distributed under the terms of the GNU LGPL v2+. This is free
6735 software; see the source for copying conditions. There is NO warranty;
6736 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
6737
6739 virt-install(1), virt-xml-validate(1), virt-top(1), virt-df(1),
6740 https://libvirt.org/
6741 VIRSH(1)