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 [--xpath EXPRESSION] [--wrap]
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 If the --xpath argument provides an XPath expression, it will be evalu‐
408 ated against the output XML and only those matching nodes will be
409 printed. The default behaviour is to print each matching node as a
410 standalone document, however, for ease of additional processing, the
411 --wrap argument will cause the matching node to be wrapped in a common
412 root node.
413 domcapabilities
415 Syntax:
416 domcapabilities [virttype] [emulatorbin] [arch] [machine]
418 [--xpath EXPRESSION] [--wrap]
419 Print an XML document describing the domain capabilities for the hyper‐
421 visor we are connected to using information either sourced from an ex‐
422 isting domain or taken from the virsh capabilities output. This may be
423 useful if you intend to create a new domain and are curious if for in‐
424 stance it could make use of VFIO by creating a domain for the hypervi‐
425 sor with a specific emulator and architecture.
426 Each hypervisor will have different requirements regarding which op‐
428 tions are required and which are optional. A hypervisor can support
429 providing a default value for any of the options.
430 The virttype option specifies the virtualization type used. The value
432 to be used is either from the 'type' attribute of the <domain/> top
433 level element from the domain XML or the 'type' attribute found within
434 each <guest/> element from the virsh capabilities output. The emula‐
435 torbin option specifies the path to the emulator. The value to be used
436 is either the <emulator> element in the domain XML or the virsh capa‐
437 bilities output. The arch option specifies the architecture to be used
438 for the domain. The value to be used is either the "arch" attribute
439 from the domain's XML <os/> element and <type/> subelement or the
440 "name" attribute of an <arch/> element from the virsh capabililites
441 output. The machine specifies the machine type for the emulator. The
442 value to be used is either the "machine" attribute from the domain's
443 XML <os/> element and <type/> subelement or one from a list of machines
444 from the virsh capabilities output for a specific architecture and do‐
445 main type.
446 For the QEMU hypervisor, a virttype of either 'qemu' or 'kvm' must be
448 supplied along with either the emulatorbin or arch in order to generate
449 output for the default machine. Supplying a machine value will gener‐
450 ate output for the specific machine.
451 If the --xpath argument provides an XPath expression, it will be evalu‐
453 ated against the output XML and only those matching nodes will be
454 printed. The default behaviour is to print each matching node as a
455 standalone document, however, for ease of additional processing, the
456 --wrap argument will cause the matching node to be wrapped in a common
457 root node.
458 pool-capabilities
460 Syntax:
461 pool-capabilities
463 Print an XML document describing the storage pool capabilities for the
465 connected storage driver. This may be useful if you intend to create a
466 new storage pool and need to know the available pool types and sup‐
467 ported storage pool source and target volume formats as well as the re‐
468 quired source elements to create the pool.
469 inject-nmi
471 Syntax:
472 inject-nmi domain
474 Inject NMI to the guest.
476 list
478 Syntax:
479 list [--inactive | --all]
481 [--managed-save] [--title]
482 { [--table] | --name | --uuid | --id }
483 [--persistent] [--transient]
484 [--with-managed-save] [--without-managed-save]
485 [--autostart] [--no-autostart]
486 [--with-snapshot] [--without-snapshot]
487 [--with-checkpoint] [--without-checkpoint]
488 [--state-running] [--state-paused]
489 [--state-shutoff] [--state-other]
490 Prints information about existing domains. If no options are specified
492 it prints out information about running domains.
493 Example 1:
495 An example format for the list is as follows:
497 ``virsh`` list
499 Id Name State
500 ----------------------------------------------------
501 0 Domain-0 running
502 2 fedora paused
503 Name is the name of the domain. ID the domain numeric id. State is
505 the run state (see below).
506 STATES
508 The State field lists what state each domain is currently in. A domain
510 can be in one of the following possible states:
511 • running
513 The domain is currently running on a CPU
515 • idle
517 The domain is idle, and not running or runnable. This can be caused
519 because the domain is waiting on IO (a traditional wait state) or has
520 gone to sleep because there was nothing else for it to do.
521 • paused
523 The domain has been paused, usually occurring through the administra‐
525 tor running virsh suspend. When in a paused state the domain will
526 still consume allocated resources like memory, but will not be eligi‐
527 ble for scheduling by the hypervisor.
528 • in shutdown
530 The domain is in the process of shutting down, i.e. the guest operat‐
532 ing system has been notified and should be in the process of stopping
533 its operations gracefully.
534 • shut off
536 The domain is not running. Usually this indicates the domain has
538 been shut down completely, or has not been started.
539 • crashed
541 The domain has crashed, which is always a violent ending. Usually
543 this state can only occur if the domain has been configured not to
544 restart on crash.
545 • pmsuspended
547 The domain has been suspended by guest power management, e.g. entered
549 into s3 state.
550 Normally only active domains are listed. To list inactive domains spec‐
552 ify --inactive or --all to list both active and inactive domains.
553 Filtering
555 To further filter the list of domains you may specify one or more of
557 filtering flags supported by the list command. These flags are grouped
558 by function. Specifying one or more flags from a group enables the
559 filter group. Note that some combinations of flags may yield no re‐
560 sults. Supported filtering flags and groups:
561 Persistence
563 Flag --persistent is used to include persistent guests in the returned
564 list. To include transient guests specify --transient.
565 Existence of managed save image
567 To list domains having a managed save image specify flag --with-man‐
568 aged-save. For domains that don't have a managed save image specify
569 --without-managed-save.
570 Domain state
572 The following filter flags select a domain by its state: --state-run‐
573 ning for running domains, --state-paused for paused domains,
574 --state-shutoff for turned off domains and --state-other for all other
575 states as a fallback.
576 Autostarting domains
578 To list autostarting domains use the flag --autostart. To list domains
579 with this feature disabled use --no-autostart.
580 Snapshot existence
582 Domains that have snapshot images can be listed using flag --with-snap‐
583 shot, domains without a snapshot --without-snapshot.
584 Checkpoint existence
586 Domains that have checkpoints can be listed using flag --with-check‐
587 point, domains without a checkpoint --without-checkpoint.
588 When talking to older servers, this command is forced to use a series
590 of API calls with an inherent race, where a domain might not be listed
591 or might appear more than once if it changed state between calls while
592 the list was being collected. Newer servers do not have this problem.
593 If --managed-save is specified, then domains that have managed save
595 state (only possible if they are in the shut off state, so you need to
596 specify --inactive or --all to actually list them) will instead show as
597 saved in the listing. This flag is usable only with the default --table
598 output. Note that this flag does not filter the list of domains.
599 If --name is specified, domain names are printed instead of the table
601 formatted one per line. If --uuid is specified domain's UUID's are
602 printed instead of names. If --id is specified then domain's ID's are
603 printed indead of names. However, it is possible to combine --name,
604 --uuid and --id to select only desired fields for printing. Flag --ta‐
605 ble specifies that the legacy table-formatted output should be used,
606 but it is mutually exclusive with --name, --uuid and --id. This is the
607 default and will be used if neither of --name, --uuid or --id is speci‐
608 fied. If neither --name nor --uuid is specified, but --id is, then only
609 active domains are listed, even with the --all parameter as otherwise
610 the output would just contain bunch of lines with just -1.
611 If --title is specified, then the short domain description (title) is
613 printed in an extra column. This flag is usable only with the default
614 --table output.
615 Example 2:
617 $ virsh list --title
619 Id Name State Title
620 -------------------------------------------
621 0 Domain-0 running Mailserver 1
622 2 fedora paused
623 freecell
625 Syntax:
626 freecell [{ [--cellno] cellno | --all }]
628 Prints the available amount of memory on the machine or within a NUMA
630 cell. The freecell command can provide one of three different displays
631 of available memory on the machine depending on the options specified.
632 With no options, it displays the total free memory on the machine.
633 With the --all option, it displays the free memory in each cell and the
634 total free memory on the machine. Finally, with a numeric argument or
635 with --cellno plus a cell number it will display the free memory for
636 the specified cell only.
637 freepages
639 Syntax:
640 freepages [{ [--cellno] cellno [--pagesize] pagesize | --all }]
642 Prints the available amount of pages within a NUMA cell. cellno refers
644 to the NUMA cell you're interested in. pagesize is a scaled integer
645 (see NOTES above). Alternatively, if --all is used, info on each pos‐
646 sible combination of NUMA cell and page size is printed out.
647 allocpages
649 Syntax:
650 allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno] cellno] [--add] [--all]
652 Change the size of pages pool of pagesize on the host. If --add is
654 specified, then pagecount pages are added into the pool. However, if
655 --add wasn't specified, then the pagecount is taken as the new absolute
656 size of the pool (this may be used to free some pages and size the pool
657 down). The cellno modifier can be used to narrow the modification down
658 to a single host NUMA cell. On the other end of spectrum lies --all
659 which executes the modification on all NUMA cells.
660 cpu-baseline
662 Syntax:
663 cpu-baseline FILE [--features] [--migratable]
665 Compute baseline CPU which will be supported by all host CPUs given in
667 <file>. (See hypervisor-cpu-baseline command to get a CPU which can be
668 provided by a specific hypervisor.) The list of host CPUs is built by
669 extracting all <cpu> elements from the <file>. Thus, the <file> can
670 contain either a set of <cpu> elements separated by new lines or even a
671 set of complete <capabilities> elements printed by capabilities com‐
672 mand. If --features is specified, then the resulting XML description
673 will explicitly include all features that make up the CPU, without this
674 option features that are part of the CPU model will not be listed in
675 the XML description. If --migratable is specified, features that
676 block migration will not be included in the resulting CPU.
677 cpu-compare
679 Syntax:
680 cpu-compare FILE [--error] [--validate]
682 Compare CPU definition from XML <file> with host CPU. (See hypervi‐
684 sor-cpu-compare command for comparing the CPU definition with the CPU
685 which a specific hypervisor is able to provide on the host.) The XML
686 <file> may contain either host or guest CPU definition. The host CPU
687 definition is the <cpu> element and its contents as printed by capabil‐
688 ities command. The guest CPU definition is the <cpu> element and its
689 contents from domain XML definition or the CPU definition created from
690 the host CPU model found in domain capabilities XML (printed by domca‐
691 pabilities command). In addition to the <cpu> element itself, this com‐
692 mand accepts full domain XML, capabilities XML, or domain capabilities
693 XML containing the CPU definition. For more information on guest CPU
694 definition see: https://libvirt.org/formatdomain.html#elementsCPU. If
695 --error is specified, the command will return an error when the given
696 CPU is incompatible with host CPU and a message providing more details
697 about the incompatibility will be printed out. If --validate is speci‐
698 fied, validates the format of the XML document against an internal RNG
699 schema.
700 cpu-models
702 Syntax:
703 cpu-models arch
705 Print the list of CPU models known by libvirt for the specified archi‐
707 tecture. Whether a specific hypervisor is able to create a domain
708 which uses any of the printed CPU models is a separate question which
709 can be answered by looking at the domain capabilities XML returned by
710 domcapabilities command. Moreover, for some architectures libvirt does
711 not know any CPU models and the usable CPU models are only limited by
712 the hypervisor. This command will print that all CPU models are ac‐
713 cepted for these architectures and the actual list of supported CPU
714 models can be checked in the domain capabilities XML.
715 hypervisor-cpu-compare
717 Syntax:
718 hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine] [--error] [--validate]
720 Compare CPU definition from XML <file> with the CPU the hypervisor is
722 able to provide on the host. (This is different from cpu-compare which
723 compares the CPU definition with the host CPU without considering any
724 specific hypervisor and its abilities.)
725 The XML FILE may contain either a host or guest CPU definition. The
727 host CPU definition is the <cpu> element and its contents as printed by
728 the capabilities command. The guest CPU definition is the <cpu> element
729 and its contents from the domain XML definition or the CPU definition
730 created from the host CPU model found in the domain capabilities XML
731 (printed by the domcapabilities command). In addition to the <cpu> ele‐
732 ment itself, this command accepts full domain XML, capabilities XML, or
733 domain capabilities XML containing the CPU definition. For more infor‐
734 mation on guest CPU definition see:
735 https://libvirt.org/formatdomain.html#elementsCPU.
736 The virttype option specifies the virtualization type (usable in the
738 'type' attribute of the <domain> top level element from the domain
739 XML). emulator specifies the path to the emulator, arch specifies the
740 CPU architecture, and machine specifies the machine type. If --error is
741 specified, the command will return an error when the given CPU is in‐
742 compatible with the host CPU and a message providing more details about
743 the incompatibility will be printed out. If --validate is specified,
744 validates the format of the XML document against an internal RNG
745 schema.
746 hypervisor-cpu-baseline
748 Syntax:
749 hypervisor-cpu-baseline [FILE] [virttype] [emulator] [arch] [machine]
751 [--features] [--migratable] [model]
752 Compute a baseline CPU which will be compatible with all CPUs defined
754 in an XML file and with the CPU the hypervisor is able to provide on
755 the host. (This is different from cpu-baseline which does not consider
756 any hypervisor abilities when computing the baseline CPU.)
757 As an alternative for FILE in case the XML would only contain a CPU
759 model with no additional features the CPU model name itself can be
760 passed as model. Exactly one of FILE and model must be used.
761 The XML FILE may contain either host or guest CPU definitions describ‐
763 ing the host CPU model. The host CPU definition is the <cpu> element
764 and its contents as printed by capabilities command. The guest CPU def‐
765 inition may be created from the host CPU model found in domain capabil‐
766 ities XML (printed by domcapabilities command). In addition to the
767 <cpu> elements, this command accepts full capabilities XMLs, or domain
768 capabilities XMLs containing the CPU definitions. It is recommended to
769 use only the CPU definitions from domain capabilities, as on some ar‐
770 chitectures using the host CPU definition may either fail or provide
771 unexpected results.
772 When FILE contains only a single CPU definition, the command will print
774 the same CPU with restrictions imposed by the capabilities of the hy‐
775 pervisor. Specifically, running the virsh hypervisor-cpu-baseline com‐
776 mand with no additional options on the result of virsh domcapabilities
777 will transform the host CPU model from domain capabilities XML to a
778 form directly usable in domain XML. Running the command with model (or
779 FILE containing just a single CPU definition with model and no feature
780 elements) which is marked as unusable in virsh domcapabilities will
781 provide a list of features that block this CPU model from being usable.
782 The virttype option specifies the virtualization type (usable in the
784 'type' attribute of the <domain> top level element from the domain
785 XML). emulator specifies the path to the emulator, arch specifies the
786 CPU architecture, and machine specifies the machine type. If --features
787 is specified, then the resulting XML description will explicitly in‐
788 clude all features that make up the CPU, without this option features
789 that are part of the CPU model will not be listed in the XML descrip‐
790 tion. If --migratable is specified, features that block migration will
791 not be included in the resulting CPU.
792
794 The following commands manipulate domains directly, as stated previ‐
795 ously most commands take domain as the first parameter. The domain can
796 be specified as a short integer, a name or a full UUID.
797 autostart
799 Syntax:
800 autostart [--disable] domain
802 Configure a domain to be automatically started at boot.
804 The option --disable disables autostarting.
806 blkdeviotune
808 Syntax:
809 blkdeviotune domain device [[--config] [--live] | [--current]]
811 [[total-bytes-sec] | [read-bytes-sec] [write-bytes-sec]]
812 [[total-iops-sec] | [read-iops-sec] [write-iops-sec]]
813 [[total-bytes-sec-max] | [read-bytes-sec-max] [write-bytes-sec-max]]
814 [[total-iops-sec-max] | [read-iops-sec-max] [write-iops-sec-max]]
815 [[total-bytes-sec-max-length] |
816 [read-bytes-sec-max-length] [write-bytes-sec-max-length]]
817 [[total-iops-sec-max-length] |
818 [read-iops-sec-max-length] [write-iops-sec-max-length]]
819 [size-iops-sec] [group-name]
820 Set or query the block disk io parameters for a block device of domain.
822 device specifies a unique target name (<target dev='name'/>) or source
823 file (<source file='name'/>) for one of the disk devices attached to
824 domain (see also domblklist for listing these names).
825 If no limit is specified, it will query current I/O limits setting.
827 Otherwise, alter the limits with these flags: --total-bytes-sec speci‐
828 fies total throughput limit as a scaled integer, the default being
829 bytes per second if no suffix is specified. --read-bytes-sec specifies
830 read throughput limit as a scaled integer, the default being bytes per
831 second if no suffix is specified. --write-bytes-sec specifies write
832 throughput limit as a scaled integer, the default being bytes per sec‐
833 ond if no suffix is specified. --total-iops-sec specifies total I/O
834 operations limit per second. --read-iops-sec specifies read I/O opera‐
835 tions limit per second. --write-iops-sec specifies write I/O opera‐
836 tions limit per second. --total-bytes-sec-max specifies maximum total
837 throughput limit as a scaled integer, the default being bytes per sec‐
838 ond if no suffix is specified --read-bytes-sec-max specifies maximum
839 read throughput limit as a scaled integer, the default being bytes per
840 second if no suffix is specified. --write-bytes-sec-max specifies max‐
841 imum write throughput limit as a scaled integer, the default being
842 bytes per second if no suffix is specified. --total-iops-sec-max spec‐
843 ifies maximum total I/O operations limit per second.
844 --read-iops-sec-max specifies maximum read I/O operations limit per
845 second. --write-iops-sec-max specifies maximum write I/O operations
846 limit per second. --total-bytes-sec-max-length specifies duration in
847 seconds to allow maximum total throughput limit.
848 --read-bytes-sec-max-length specifies duration in seconds to allow max‐
849 imum read throughput limit. --write-bytes-sec-max-length specifies du‐
850 ration in seconds to allow maximum write throughput limit. --to‐
851 tal-iops-sec-max-length specifies duration in seconds to allow maximum
852 total I/O operations limit. --read-iops-sec-max-length specifies dura‐
853 tion in seconds to allow maximum read I/O operations limit.
854 --write-iops-sec-max-length specifies duration in seconds to allow max‐
855 imum write I/O operations limit. --size-iops-sec specifies size I/O
856 operations limit per second. --group-name specifies group name to
857 share I/O quota between multiple drives. For a QEMU domain, if no name
858 is provided, then the default is to have a single group for each de‐
859 vice.
860 Older versions of virsh only accepted these options with underscore in‐
862 stead of dash, as in --total_bytes_sec.
863 Bytes and iops values are independent, but setting only one value (such
865 as --read-bytes-sec) resets the other two in that category to unlim‐
866 ited. An explicit 0 also clears any limit. A non-zero value for a
867 given total cannot be mixed with non-zero values for read or write.
868 It is up to the hypervisor to determine how to handle the length val‐
870 ues. For the QEMU hypervisor, if an I/O limit value or maximum value
871 is set, then the default value of 1 second will be displayed. Supplying
872 a 0 will reset the value back to the default.
873 If --live is specified, affect a running guest. If --config is speci‐
875 fied, affect the next start of a persistent guest. If --current is
876 specified, it is equivalent to either --live or --config, depending on
877 the current state of the guest. When setting the disk io parameters
878 both --live and --config flags may be given, but --current is exclu‐
879 sive. For querying only one of --live, --config or --current can be
880 specified. If no flag is specified, behavior is different depending on
881 hypervisor.
882 blkiotune
884 Syntax:
885 blkiotune domain [--weight weight] [--device-weights device-weights]
887 [--device-read-iops-sec device-read-iops-sec]
888 [--device-write-iops-sec device-write-iops-sec]
889 [--device-read-bytes-sec device-read-bytes-sec]
890 [--device-write-bytes-sec device-write-bytes-sec]
891 [[--config] [--live] | [--current]]
892 Display or set the blkio parameters. QEMU/KVM supports --weight.
894 --weight is in range [100, 1000]. After kernel 2.6.39, the value could
895 be in the range [10, 1000].
896 device-weights is a single string listing one or more device/weight
898 pairs, in the format of /path/to/device,weight,/path/to/device,weight.
899 Each weight is in the range [100, 1000], [10, 1000] after kernel
900 2.6.39, or the value 0 to remove that device from per-device listings.
901 Only the devices listed in the string are modified; any existing
902 per-device weights for other devices remain unchanged.
903 device-read-iops-sec is a single string listing one or more de‐
905 vice/read_iops_sec pairs, int the format of /path/to/de‐
906 vice,read_iops_sec,/path/to/device,read_iops_sec. Each read_iops_sec
907 is a number which type is unsigned int, value 0 to remove that device
908 from per-device listing. Only the devices listed in the string are
909 modified; any existing per-device read_iops_sec for other devices re‐
910 main unchanged.
911 device-write-iops-sec is a single string listing one or more de‐
913 vice/write_iops_sec pairs, int the format of /path/to/de‐
914 vice,write_iops_sec,/path/to/device,write_iops_sec. Each
915 write_iops_sec is a number which type is unsigned int, value 0 to re‐
916 move that device from per-device listing. Only the devices listed in
917 the string are modified; any existing per-device write_iops_sec for
918 other devices remain unchanged.
919 device-read-bytes-sec is a single string listing one or more de‐
921 vice/read_bytes_sec pairs, int the format of /path/to/de‐
922 vice,read_bytes_sec,/path/to/device,read_bytes_sec. Each
923 read_bytes_sec is a number which type is unsigned long long, value 0 to
924 remove that device from per-device listing. Only the devices listed in
925 the string are modified; any existing per-device read_bytes_sec for
926 other devices remain unchanged.
927 device-write-bytes-sec is a single string listing one or more de‐
929 vice/write_bytes_sec pairs, int the format of /path/to/de‐
930 vice,write_bytes_sec,/path/to/device,write_bytes_sec. Each
931 write_bytes_sec is a number which type is unsigned long long, value 0
932 to remove that device from per-device listing. Only the devices listed
933 in the string are modified; any existing per-device write_bytes_sec for
934 other devices remain unchanged.
935 If --live is specified, affect a running guest. If --config is speci‐
937 fied, affect the next start of a persistent guest. If --current is
938 specified, it is equivalent to either --live or --config, depending on
939 the current state of the guest. Both --live and --config flags may be
940 given, but --current is exclusive. If no flag is specified, behavior is
941 different depending on hypervisor.
942 blockcommit
944 Syntax:
945 blockcommit domain path [bandwidth] [--bytes] [base]
947 [--shallow] [top] [--delete] [--keep-relative]
948 [--wait [--async] [--verbose]] [--timeout seconds]
949 [--active] [{--pivot | --keep-overlay}]
950 Reduce the length of a backing image chain, by committing changes at
952 the top of the chain (snapshot or delta files) into backing images. By
953 default, this command attempts to flatten the entire chain. If base
954 and/or top are specified as files within the backing chain, then the
955 operation is constrained to committing just that portion of the chain;
956 --shallow can be used instead of base to specify the immediate backing
957 file of the resulting top image to be committed. The files being com‐
958 mitted are rendered invalid, possibly as soon as the operation starts;
959 using the --delete flag will attempt to remove these invalidated files
960 at the successful completion of the commit operation. When the
961 --keep-relative flag is used, the backing file paths will be kept rela‐
962 tive.
963 When top is omitted or specified as the active image, it is also possi‐
965 ble to specify --active to trigger a two-phase active commit. In the
966 first phase, top is copied into base and the job can only be canceled,
967 with top still containing data not yet in base. In the second phase,
968 top and base remain identical until a call to blockjob with the --abort
969 flag (keeping top as the active image that tracks changes from that
970 point in time) or the --pivot flag (making base the new active image
971 and invalidating top).
972 By default, this command returns as soon as possible, and data for the
974 entire disk is committed in the background; the progress of the opera‐
975 tion can be checked with blockjob. However, if --wait is specified,
976 then this command will block until the operation completes (or for
977 --active, enters the second phase), or until the operation is canceled
978 because the optional timeout in seconds elapses or SIGINT is sent (usu‐
979 ally with Ctrl-C). Using --verbose along with --wait will produce pe‐
980 riodic status updates. If job cancellation is triggered, --async will
981 return control to the user as fast as possible, otherwise the command
982 may continue to block a little while longer until the job is done
983 cleaning up. Using --pivot is shorthand for combining --active --wait
984 with an automatic blockjob --pivot; and using --keep-overlay is short‐
985 hand for combining --active --wait with an automatic blockjob --abort.
986 path specifies fully-qualified path of the disk; it corresponds to a
988 unique target name (<target dev='name'/>) or source file (<source
989 file='name'/>) for one of the disk devices attached to domain (see also
990 domblklist for listing these names). bandwidth specifies copying band‐
991 width limit in MiB/s, although for QEMU, it may be non-zero only for an
992 online domain. For further information on the bandwidth argument see
993 the corresponding section for the blockjob command.
994 blockcopy
996 Syntax:
997 blockcopy domain path { dest [format] [--blockdev] | --xml file }
999 [--shallow] [--reuse-external] [bandwidth]
1000 [--wait [--async] [--verbose]] [{--pivot | --finish}]
1001 [--timeout seconds] [granularity] [buf-size] [--bytes]
1002 [--transient-job] [--synchronous-writes] [--print-xml]
1003 Copy a disk backing image chain to a destination. Either dest as the
1005 destination file name, or --xml with the name of an XML file containing
1006 a top-level <disk> element describing the destination, must be present.
1007 Additionally, if dest is given, format should be specified to declare
1008 the format of the destination (if format is omitted, then libvirt will
1009 reuse the format of the source, or with --reuse-external will be forced
1010 to probe the destination format, which could be a potential security
1011 hole). The command supports --raw as a boolean flag synonym for --for‐
1012 mat=raw. When using dest, the destination is treated as a regular file
1013 unless --blockdev is used to signal that it is a block device. By de‐
1014 fault, this command flattens the entire chain; but if --shallow is
1015 specified, the copy shares the backing chain.
1016 If --reuse-external is specified, then the destination must exist and
1018 have sufficient space to hold the copy. If --shallow is used in con‐
1019 junction with --reuse-external then the pre-created image must have
1020 guest visible contents identical to guest visible contents of the back‐
1021 ing file of the original image. This may be used to modify the backing
1022 file names on the destination.
1023 By default, the copy job runs in the background, and consists of two
1025 phases. Initially, the job must copy all data from the source, and
1026 during this phase, the job can only be canceled to revert back to the
1027 source disk, with no guarantees about the destination. After this
1028 phase completes, both the source and the destination remain mirrored
1029 until a call to blockjob with the --abort and --pivot flags pivots over
1030 to the copy, or a call without --pivot leaves the destination as a
1031 faithful copy of that point in time. However, if --wait is specified,
1032 then this command will block until the mirroring phase begins, or can‐
1033 cel the operation if the optional timeout in seconds elapses or SIGINT
1034 is sent (usually with Ctrl-C). Using --verbose along with --wait will
1035 produce periodic status updates. Using --pivot (similar to blockjob
1036 --pivot) or --finish (similar to blockjob --abort) implies --wait, and
1037 will additionally end the job cleanly rather than leaving things in the
1038 mirroring phase. If job cancellation is triggered by timeout or by
1039 --finish, --async will return control to the user as fast as possible,
1040 otherwise the command may continue to block a little while longer until
1041 the job has actually cancelled.
1042 path specifies fully-qualified path of the disk. bandwidth specifies
1044 copying bandwidth limit in MiB/s. Specifying a negative value is inter‐
1045 preted as an unsigned long long value that might be essentially unlim‐
1046 ited, but more likely would overflow; it is safer to use 0 for that
1047 purpose. For further information on the bandwidth argument see the cor‐
1048 responding section for the blockjob command. Specifying granularity
1049 allows fine-tuning of the granularity that will be copied when a dirty
1050 region is detected; larger values trigger less I/O overhead but may end
1051 up copying more data overall (the default value is usually correct);
1052 hypervisors may restrict this to be a power of two or fall within a
1053 certain range. Specifying buf-size will control how much data can be
1054 simultaneously in-flight during the copy; larger values use more memory
1055 but may allow faster completion (the default value is usually correct).
1056 --transient-job allows specifying that the user does not require the
1058 job to be recovered if the VM crashes or is turned off before the job
1059 completes. This flag removes the restriction of copy jobs to transient
1060 domains if that restriction is applied by the hypervisor.
1061 If --synchronous-writes is specified the block job will wait for guest
1063 writes to be propagated both to the original image and to the destina‐
1064 tion of the copy so that it's guaranteed that the job converges if the
1065 destination storage is slower. This may impact performance of writes
1066 while the blockjob is running.
1067 If --print-xml is specified, then the XML used to start the block copy
1069 job is printed instead of starting the job.
1070 blockjob
1072 Syntax:
1073 blockjob domain path { [--abort] [--async] [--pivot] |
1075 [--info] [--raw] [--bytes] | [bandwidth] }
1076 Manage active block operations. There are three mutually-exclusive
1078 modes: --info, bandwidth, and --abort. --async and --pivot imply abort
1079 mode; --raw implies info mode; and if no mode was given, --info mode is
1080 assumed.
1081 path specifies fully-qualified path of the disk; it corresponds to a
1083 unique target name (<target dev='name'/>) or source file (<source
1084 file='name'/>) for one of the disk devices attached to domain (see also
1085 domblklist for listing these names).
1086 In --abort mode, the active job on the specified disk will be aborted.
1088 If --async is also specified, this command will return immediately,
1089 rather than waiting for the cancellation to complete. If --pivot is
1090 specified, this requests that an active copy or active commit job be
1091 pivoted over to the new image.
1092 In --info mode, the active job information on the specified disk will
1094 be printed. By default, the output is a single human-readable summary
1095 line; this format may change in future versions. Adding --raw lists
1096 each field of the struct, in a stable format. If the --bytes flag is
1097 set, then the command errors out if the server could not supply bytes/s
1098 resolution; when omitting the flag, raw output is listed in MiB/s and
1099 human-readable output automatically selects the best resolution sup‐
1100 ported by the server.
1101 bandwidth can be used to set bandwidth limit for the active job in
1103 MiB/s. If --bytes is specified then the bandwidth value is interpreted
1104 in bytes/s. Specifying a negative value is interpreted as an unsigned
1105 long value or essentially unlimited. The hypervisor can choose whether
1106 to reject the value or convert it to the maximum value allowed. Option‐
1107 ally a scaled positive number may be used as bandwidth (see NOTES
1108 above). Using --bytes with a scaled value permits a finer granularity
1109 to be selected. A scaled value used without --bytes will be rounded
1110 down to MiB/s. Note that the --bytes may be unsupported by the hypervi‐
1111 sor.
1112 Note that the progress reported for blockjobs corresponding to a
1114 pull-mode backup don't report progress of the backup but rather usage
1115 of temporary space required for the backup.
1116 blockpull
1118 Syntax:
1119 blockpull domain path [bandwidth] [--bytes] [base]
1121 [--wait [--verbose] [--timeout seconds] [--async]]
1122 [--keep-relative]
1123 Populate a disk from its backing image chain. By default, this command
1125 flattens the entire chain; but if base is specified, containing the
1126 name of one of the backing files in the chain, then that file becomes
1127 the new backing file and only the intermediate portion of the chain is
1128 pulled. Once all requested data from the backing image chain has been
1129 pulled, the disk no longer depends on that portion of the backing
1130 chain.
1131 By default, this command returns as soon as possible, and data for the
1133 entire disk is pulled in the background; the progress of the operation
1134 can be checked with blockjob. However, if --wait is specified, then
1135 this command will block until the operation completes, or cancel the
1136 operation if the optional timeout in seconds elapses or SIGINT is sent
1137 (usually with Ctrl-C). Using --verbose along with --wait will produce
1138 periodic status updates. If job cancellation is triggered, --async
1139 will return control to the user as fast as possible, otherwise the com‐
1140 mand may continue to block a little while longer until the job is done
1141 cleaning up.
1142 Using the --keep-relative flag will keep the backing chain names rela‐
1144 tive.
1145 path specifies fully-qualified path of the disk; it corresponds to a
1147 unique target name (<target dev='name'/>) or source file (<source
1148 file='name'/>) for one of the disk devices attached to domain (see also
1149 domblklist for listing these names). bandwidth specifies copying band‐
1150 width limit in MiB/s. For further information on the bandwidth argument
1151 see the corresponding section for the blockjob command.
1152 blockresize
1154 Syntax:
1155 blockresize domain path size
1157 Resize a block device of domain while the domain is running, path spec‐
1159 ifies the absolute path of the block device; it corresponds to a unique
1160 target name (<target dev='name'/>) or source file (<source
1161 file='name'/>) for one of the disk devices attached to domain (see also
1162 domblklist for listing these names).
1163 size is a scaled integer (see NOTES above) which defaults to KiB
1165 (blocks of 1024 bytes) if there is no suffix. You must use a suffix of
1166 "B" to get bytes (note that for historical reasons, this differs from
1167 vol-resize which defaults to bytes without a suffix).
1168 console
1170 Syntax:
1171 console domain [devname] [--safe] [--force]
1173 Connect the virtual serial console for the guest. The optional devname
1175 parameter refers to the device alias of an alternate console, serial or
1176 parallel device configured for the guest. If omitted, the primary con‐
1177 sole will be opened.
1178 If the flag --safe is specified, the connection is only attempted if
1180 the driver supports safe console handling. This flag specifies that the
1181 server has to ensure exclusive access to console devices. Optionally
1182 the --force flag may be specified, requesting to disconnect any exist‐
1183 ing sessions, such as in a case of a broken connection.
1184 cpu-stats
1186 Syntax:
1187 cpu-stats domain [--total] [start] [count]
1189 Provide cpu statistics information of a domain. The domain should be
1191 running. Default it shows stats for all CPUs, and a total. Use --total
1192 for only the total stats, start for only the per-cpu stats of the CPUs
1193 from start, count for only count CPUs' stats.
1194 create
1196 Syntax:
1197 create FILE [--console] [--paused] [--autodestroy]
1199 [--pass-fds N,M,...] [--validate] [--reset-nvram]
1200 Create a domain from an XML <file>. Optionally, --validate option can
1202 be passed to validate the format of the input XML file against an in‐
1203 ternal RNG schema (identical to using virt-xml-validate(1) tool). Do‐
1204 mains created using this command are going to be either transient (tem‐
1205 porary ones that will vanish once destroyed) or existing persistent
1206 guests that will run with one-time use configuration, leaving the per‐
1207 sistent XML untouched (this can come handy during an automated testing
1208 of various configurations all based on the original XML). See the ex‐
1209 ample below for usage demonstration.
1210 The domain will be paused if the --paused option is used and supported
1212 by the driver; otherwise it will be running. If --console is requested,
1213 attach to the console after creation. If --autodestroy is requested,
1214 then the guest will be automatically destroyed when virsh closes its
1215 connection to libvirt, or otherwise exits.
1216 If --pass-fds is specified, the argument is a comma separated list of
1218 open file descriptors which should be pass on into the guest. The file
1219 descriptors will be re-numbered in the guest, starting from 3. This is
1220 only supported with container based virtualization.
1221 If --reset-nvram is specified, any existing NVRAM file will be deleted
1223 and re-initialized from its pristine template.
1224 Example:
1226 1. prepare a template from an existing domain (skip directly to 3a if
1228 writing one from scratch)
1229 # virsh dumpxml <domain> > domain.xml
1231 2. edit the template using an editor of your choice and:
1233 a. DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or
1235 b. DON'T CHANGE! either <name> or <uuid>
1237 # $EDITOR domain.xml
1239 3. create a domain from domain.xml, depending on whether following 2a
1241 or 2b respectively:
1242 a. the domain is going to be transient
1244 b. an existing persistent guest will run with a modified one-time
1246 configuration
1247 # virsh create domain.xml
1249 define
1251 Syntax:
1252 define FILE [--validate]
1254 Define a domain from an XML <file>. Optionally, the format of the input
1256 XML file can be validated against an internal RNG schema with --vali‐
1257 date (identical to using virt-xml-validate(1) tool). The domain defini‐
1258 tion is registered but not started. If domain is already running, the
1259 changes will take effect on the next boot.
1260 desc
1262 Syntax:
1263 desc domain [[--live] [--config] |
1265 [--current]] [--title] [--edit] [--new-desc
1266 New description or title message]
1267 Show or modify description and title of a domain. These values are user
1269 fields that allow storing arbitrary textual data to allow easy identi‐
1270 fication of domains. Title should be short, although it's not enforced.
1271 (See also metadata that works with XML based domain metadata.)
1272 Flags --live or --config select whether this command works on live or
1274 persistent definitions of the domain. If both --live and --config are
1275 specified, the --config option takes precedence on getting the current
1276 description and both live configuration and config are updated while
1277 setting the description. --current is exclusive and implied if none of
1278 these was specified.
1279 Flag --edit specifies that an editor with the contents of current de‐
1281 scription or title should be opened and the contents saved back after‐
1282 wards.
1283 Flag --title selects operation on the title field instead of descrip‐
1285 tion.
1286 If neither of --edit and --new-desc are specified the note or descrip‐
1288 tion is displayed instead of being modified.
1289 destroy
1291 Syntax:
1292 destroy domain [--graceful] [--remove-logs]
1294 Immediately terminate the domain domain. This doesn't give the domain
1296 OS any chance to react, and it's the equivalent of ripping the power
1297 cord out on a physical machine. In most cases you will want to use the
1298 shutdown command instead. However, this does not delete any storage
1299 volumes used by the guest, and if the domain is persistent, it can be
1300 restarted later.
1301 If domain is transient, then the metadata of any snapshots will be lost
1303 once the guest stops running, but the snapshot contents still exist,
1304 and a new domain with the same name and UUID can restore the snapshot
1305 metadata with snapshot-create. Similarly, the metadata of any check‐
1306 points will be lost, but can be restored with checkpoint-create.
1307 If --graceful is specified, don't resort to extreme measures (e.g.
1309 SIGKILL) when the guest doesn't stop after a reasonable timeout; return
1310 an error instead.
1311 If --remove-logs is specified, remove per domain log files. Not all de‐
1313 ployment configuration can be supported.
1314 In case of QEMU the flag is only supported if virlogd is used to handle
1316 QEMU process output. Otherwise the flag is ignored.
1317 domblkerror
1319 Syntax:
1320 domblkerror domain
1322 Show errors on block devices. This command usually comes handy when
1324 domstate command says that a domain was paused due to I/O error. The
1325 domblkerror command lists all block devices in error state and the er‐
1326 ror seen on each of them.
1327 domblkinfo
1329 Syntax:
1330 domblkinfo domain [block-device --all] [--human]
1332 Get block device size info for a domain. A block-device corresponds to
1334 a unique target name (<target dev='name'/>) or source file (<source
1335 file='name'/>) for one of the disk devices attached to domain (see also
1336 domblklist for listing these names). If --human is set, the output will
1337 have a human readable output. If --all is set, the output will be a
1338 table showing all block devices size info associated with domain. The
1339 --all option takes precedence of the others.
1340 domblklist
1342 Syntax:
1343 domblklist domain [--inactive] [--details]
1345 Print a table showing the brief information of all block devices asso‐
1347 ciated with domain. If --inactive is specified, query the block devices
1348 that will be used on the next boot, rather than those currently in use
1349 by a running domain. If --details is specified, disk type and device
1350 value will also be printed. Other contexts that require a block device
1351 name (such as domblkinfo or snapshot-create for disk snapshots) will
1352 accept either target or unique source names printed by this command.
1353 domblkstat
1355 Syntax:
1356 domblkstat domain [block-device] [--human]
1358 Get device block stats for a running domain. A block-device corre‐
1360 sponds to a unique target name (<target dev='name'/>) or source file
1361 (<source file='name'/>) for one of the disk devices attached to domain
1362 (see also domblklist for listing these names). On a LXC or QEMU domain,
1363 omitting the block-device yields device block stats summarily for the
1364 entire domain.
1365 Use --human for a more human readable output.
1367 Availability of these fields depends on hypervisor. Unsupported fields
1369 are missing from the output. Other fields may appear if communicating
1370 with a newer version of libvirtd.
1371 Explanation of fields (fields appear in the following order):
1373 • rd_req - count of read operations
1375 • rd_bytes - count of read bytes
1377 • wr_req - count of write operations
1379 • wr_bytes - count of written bytes
1381 • errs - error count
1383 • flush_operations - count of flush operations
1385 • rd_total_times - total time read operations took (ns)
1387 • wr_total_times - total time write operations took (ns)
1389 • flush_total_times - total time flush operations took (ns)
1391 • <-- other fields provided by hypervisor -->
1393 domblkthreshold
1395 Syntax:
1396 domblkthreshold domain dev threshold
1398 Set the threshold value for delivering the block-threshold event. dev
1400 specifies the disk device target or backing chain element of given de‐
1401 vice using the 'target[1]' syntax. threshold is a scaled value of the
1402 offset. If the block device should write beyond that offset the event
1403 will be delivered.
1404 domcontrol
1406 Syntax:
1407 domcontrol domain
1409 Returns state of an interface to VMM used to control a domain. For
1411 states other than "ok" or "error" the command also prints number of
1412 seconds elapsed since the control interface entered its current state.
1413 domdirtyrate-calc
1415 Syntax:
1416 domdirtyrate-calc <domain> [--seconds <sec>]
1418 --mode=[page-sampling | dirty-bitmap | dirty-ring]
1419 Calculate an active domain's memory dirty rate which may be expected by
1421 user in order to decide whether it's proper to be migrated out or not.
1422 The seconds parameter can be used to calculate dirty rate in a specific
1423 time which allows 60s at most now and would be default to 1s if miss‐
1424 ing. These three page-sampling, dirty-bitmap, dirty-ring modes are mu‐
1425 tually exclusive and alternative when specify calculation mode,
1426 page-sampling is the default mode if missing. The calculated dirty rate
1427 information is available by calling 'domstats --dirtyrate'.
1428 domdisplay
1430 Syntax:
1431 domdisplay domain [--include-password] [[--type] type] [--all]
1433 Output a URI which can be used to connect to the graphical display of
1435 the domain via VNC, SPICE or RDP. The particular graphical display
1436 type can be selected using the type parameter (e.g. "vnc", "spice",
1437 "rdp"). If --include-password is specified, the SPICE channel password
1438 will be included in the URI. If --all is specified, then all show all
1439 possible graphical displays, for a VM could have more than one graphi‐
1440 cal displays.
1441 domfsfreeze
1443 Syntax:
1444 domfsfreeze domain [[--mountpoint] mountpoint...]
1446 Freeze mounted filesystems within a running domain to prepare for con‐
1448 sistent snapshots.
1449 The --mountpoint option takes a parameter mountpoint, which is a mount
1451 point path of the filesystem to be frozen. This option can occur multi‐
1452 ple times. If this is not specified, every mounted filesystem is
1453 frozen.
1454 Note: snapshot-create command has a --quiesce option to freeze and thaw
1456 the filesystems automatically to keep snapshots consistent. domfs‐
1457 freeze command is only needed when a user wants to utilize the native
1458 snapshot features of storage devices not supported by libvirt.
1459 domfsinfo
1461 Syntax:
1462 domfsinfo domain
1464 Show a list of mounted filesystems within the running domain. The list
1466 contains mountpoints, names of a mounted device in the guest, filesys‐
1467 tem types, and unique target names used in the domain XML (<target
1468 dev='name'/>).
1469 Note that this command requires a guest agent configured and running in
1471 the domain's guest OS.
1472 domfsthaw
1474 Syntax:
1475 domfsthaw domain [[--mountpoint] mountpoint...]
1477 Thaw mounted filesystems within a running domain, which have been
1479 frozen by domfsfreeze command.
1480 The --mountpoint option takes a parameter mountpoint, which is a mount
1482 point path of the filesystem to be thawed. This option can occur multi‐
1483 ple times. If this is not specified, every mounted filesystem is
1484 thawed.
1485 domfstrim
1487 Syntax:
1488 domfstrim domain [--minimum bytes] [--mountpoint mountPoint]
1490 Issue a fstrim command on all mounted filesystems within a running do‐
1492 main. It discards blocks which are not in use by the filesystem. If
1493 --minimum bytes is specified, it tells guest kernel length of contigu‐
1494 ous free range. Smaller than this may be ignored (this is a hint and
1495 the guest may not respect it). By increasing this value, the fstrim op‐
1496 eration will complete more quickly for filesystems with badly frag‐
1497 mented free space, although not all blocks will be discarded. The de‐
1498 fault value is zero, meaning "discard every free block". Moreover, if a
1499 user wants to trim only one mount point, it can be specified via op‐
1500 tional --mountpoint parameter.
1501 domhostname
1503 Syntax:
1504 domhostname domain [--source lease|agent]
1506 Returns the hostname of a domain, if the hypervisor makes it available.
1508 The --source argument specifies what data source to use for the host‐
1510 names, currently 'lease' to read DHCP leases or 'agent' to query the
1511 guest OS via an agent. If unspecified, driver returns the default
1512 method available (some drivers support only one type of source).
1513 domid
1515 Syntax:
1516 domid domain-name-or-uuid
1518 Convert a domain name (or UUID) to a domain id
1520 domif-getlink
1522 Syntax:
1523 domif-getlink domain interface-device [--config]
1525 Query link state of the domain's virtual interface. If --config is
1527 specified, query the persistent configuration, for compatibility pur‐
1528 poses, --persistent is alias of --config.
1529 interface-device can be the interface's target name or the MAC address.
1531 domif-setlink
1533 Syntax:
1534 domif-setlink domain interface-device state [--config] [--print-xml]
1536 Modify link state of the domain's virtual interface. Possible values
1538 for state are "up" and "down". If --config is specified, only the per‐
1539 sistent configuration of the domain is modified, for compatibility pur‐
1540 poses, --persistent is alias of --config. interface-device can be the
1541 interface's target name or the MAC address.
1542 If --print-xml is specified, then the XML used to update the interface
1544 is printed instead.
1545 domifaddr
1547 Syntax:
1548 domifaddr domain [interface] [--full]
1550 [--source lease|agent|arp]
1551 Get a list of interfaces of a running domain along with their IP and
1553 MAC addresses, or limited output just for one interface if interface is
1554 specified. Note that interface can be driver dependent, it can be the
1555 name within guest OS or the name you would see in domain XML. Moreover,
1556 the whole command may require a guest agent to be configured for the
1557 queried domain under some hypervisors, notably QEMU.
1558 If --full is specified, the interface name and MAC address is always
1560 displayed when the interface has multiple IP addresses or aliases; oth‐
1561 erwise, only the interface name and MAC address is displayed for the
1562 first name and MAC address with "-" for the others using the same name
1563 and MAC address.
1564 The --source argument specifies what data source to use for the ad‐
1566 dresses, currently 'lease' to read DHCP leases, 'agent' to query the
1567 guest OS via an agent, or 'arp' to get IP from host's arp tables. If
1568 unspecified, 'lease' is the default.
1569 backup-begin
1571 Syntax:
1572 backup-begin domain [backupxml] [checkpointxml] [--reuse-external]
1574 Begin a new backup job. If backupxml is omitted, this defaults to a
1576 full backup using a push model to filenames generated by libvirt; sup‐
1577 plying XML allows fine-tuning such as requesting an incremental backup
1578 relative to an earlier checkpoint, controlling which disks participate
1579 or which filenames are involved, or requesting the use of a pull model
1580 backup. The backup-dumpxml command shows any resulting values assigned
1581 by libvirt. For more information on backup XML, see:
1582 https://libvirt.org/formatbackup.html
1583 If --reuse-external is used it instructs libvirt to reuse temporary and
1585 output files provided by the user in backupxml.
1586 If checkpointxml is specified, a second file with a top-level element
1588 of domaincheckpoint is used to create a simultaneous checkpoint, for
1589 doing a later incremental backup relative to the time the backup was
1590 created. See checkpoint-create for more details on checkpoints.
1591 This command returns as soon as possible, and the backup job runs in
1593 the background; the progress of a push model backup can be checked with
1594 domjobinfo or by waiting for an event with event (the progress of a
1595 pull model backup is under the control of whatever third party connects
1596 to the NBD export). The job is ended with domjobabort.
1597 backup-dumpxml
1599 Syntax:
1600 backup-dumpxml [--xpath EXPRESSION] [--wrap] domain
1602 Output XML describing the current backup job.
1604 If the --xpath argument provides an XPath expression, it will be evalu‐
1606 ated against the output XML and only those matching nodes will be
1607 printed. The default behaviour is to print each matching node as a
1608 standalone document, however, for ease of additional processing, the
1609 --wrap argument will cause the matching node to be wrapped in a common
1610 root node.
1611 domiflist
1613 Syntax:
1614 domiflist domain [--inactive]
1616 Print a table showing the brief information of all virtual interfaces
1618 associated with domain. If --inactive is specified, query the virtual
1619 interfaces that will be used on the next boot, rather than those cur‐
1620 rently in use by a running domain. Other contexts that require a MAC
1621 address of virtual interface (such as detach-interface or
1622 domif-setlink) will accept the MAC address printed by this command.
1623 domifstat
1625 Syntax:
1626 domifstat domain interface-device
1628 Get network interface stats for a running domain. The network interface
1630 stats are only available for interfaces that have a physical source in‐
1631 terface. This does not include, for example, a 'user' interface type
1632 since it is a virtual LAN with NAT to the outside world. interface-de‐
1633 vice can be the interface target by name or MAC address. Please note,
1634 for an unmanaged ethernet type returned stats might have RX/TX swapped.
1635 domiftune
1637 Syntax:
1638 domiftune domain interface-device [[--config] [--live] | [--current]]
1640 [*--inbound average,peak,burst,floor*]
1641 [*--outbound average,peak,burst*]
1642 Set or query the domain's network interface's bandwidth parameters.
1644 interface-device can be the interface's target name (<target
1645 dev='name'/>), or the MAC address.
1646 If no --inbound or --outbound is specified, this command will query and
1648 show the bandwidth settings. Otherwise, it will set the inbound or out‐
1649 bound bandwidth. average,peak,burst,floor is the same as in command at‐
1650 tach-interface. Values for average, peak and floor are expressed in
1651 kilobytes per second, while burst is expressed in kilobytes in a single
1652 burst at peak speed as described in the Network XML documentation at
1653 https://libvirt.org/formatnetwork.html#quality-of-service.
1654 To clear inbound or outbound settings, use --inbound or --outbound re‐
1656 spectfully with average value of zero.
1657 If --live is specified, affect a running guest. If --config is speci‐
1659 fied, affect the next start of a persistent guest. If --current is
1660 specified, it is equivalent to either --live or --config, depending on
1661 the current state of the guest. Both --live and --config flags may be
1662 given, but --current is exclusive. If no flag is specified, behavior is
1663 different depending on hypervisor.
1664 dominfo
1666 Syntax:
1667 dominfo domain
1669 Returns basic information about the domain.
1671 domjobabort
1673 Syntax:
1674 domjobabort domain [--postcopy]
1676 Abort the currently running domain job.
1678 When the job to be aborted is a migration which entered post-copy mode,
1680 it cannot be aborted as none of the hosts involved in migration has a
1681 complete state of the domain. Optional --postcopy can be used to inter‐
1682 rupt such migration although doing so may effectively suspend the do‐
1683 main until the migration is resumed (see also --postcopy-resume option
1684 of migrate).
1685 domjobinfo
1687 Syntax:
1688 domjobinfo domain [--completed [--keep-completed]] [--anystats] [--rawstats]
1690 Returns information about jobs running on a domain. --completed tells
1692 virsh to return information about a recently finished job. Statistics
1693 of a completed job are automatically destroyed once read (unless
1694 --keep-completed is used) or when libvirtd is restarted.
1695 Normally only statistics for running and successful completed jobs are
1697 printed. --anystats can be used to also display statistics for failed
1698 jobs.
1699 In case --rawstats is used, all fields are printed as received from the
1701 server without any attempts to interpret the data. The "Job type:"
1702 field is special, since it's reported by the API and not part of stats.
1703 Note that time information returned for completed migrations may be
1705 completely irrelevant unless both source and destination hosts have
1706 synchronized time (i.e., NTP daemon is running on both of them).
1707 domlaunchsecinfo
1709 Syntax:
1710 domlaunchsecinfo domain
1712 Returns information about the launch security parameters associated
1714 with a running domain.
1715 The set of parameters reported will vary depending on which type of
1717 launch security protection is active. If none is active, no parameters
1718 will be reported.
1719 domsetlaunchsecstate
1721 Syntax:
1722 domsetlaunchsecstate domain --secrethdr hdr-filename
1724 --secret secret-filename [--set-address address]
1725 Set a launch security secret in the guest's memory. The guest must have
1727 a launchSecurity type enabled in its configuration and be in a paused
1728 state. On success, the guest can be transitioned to a running state.
1729 On failure, the guest should be destroyed.
1730 --secrethdr specifies a filename containing the base64-encoded secret
1732 header. The header includes artifacts needed by the hypervisor
1733 firmware to recover the plain text of the launch secret. --secret spec‐
1734 ifies the filename containing the base64-encoded encrypted launch se‐
1735 cret.
1736 The --set-address option can be used to specify a physical address
1738 within the guest's memory to set the secret. If not specified, the ad‐
1739 dress will be determined by the hypervisor.
1740 dommemstat
1742 Syntax:
1743 dommemstat domain [--period seconds] [[--config] [--live] | [--current]]
1745 Get memory stats for a running domain.
1747 Availability of these fields depends on hypervisor. Unsupported fields
1749 are missing from the output. Other fields may appear if communicating
1750 with a newer version of libvirtd.
1751 Explanation of fields:
1753 • swap_in - The amount of data read from swap space (in KiB)
1755 • swap_out - The amount of memory written out to swap space
1757 (in KiB)
1758 • major_fault - The number of page faults where disk IO was re‐
1760 quired
1761 • minor_fault - The number of other page faults
1763 • unused - The amount of memory left unused by the system
1765 (in KiB)
1766 • available - The amount of usable memory as seen by the domain
1768 (in KiB)
1769 • actual - Current balloon value (in KiB)
1771 • rss - Resident Set Size of the running domain's process
1773 (in KiB)
1774 • usable - The amount of memory which can be reclaimed by
1776 balloon without causing host swapping (in KiB)
1777 • last-update - Timestamp of the last update of statistics (in
1779 seconds)
1780 • disk_caches - The amount of memory that can be reclaimed with‐
1782 out additional I/O, typically disk caches (in KiB)
1783 • hugetlb_pgalloc - The number of successful huge page allocations
1785 initiated from within the domain
1786 • hugetlb_pgfail - The number of failed huge page allocations initi‐
1788 ated from within the domain
1789 For QEMU/KVM with a memory balloon, setting the optional --period to a
1791 value larger than 0 in seconds will allow the balloon driver to return
1792 additional statistics which will be displayed by subsequent dommemstat
1793 commands. Setting the --period to 0 will stop the balloon driver col‐
1794 lection, but does not clear the statistics in the balloon driver. Re‐
1795 quires at least QEMU/KVM 1.5 to be running on the host.
1796 The --live, --config, and --current flags are only valid when using the
1798 --period option in order to set the collection period for the balloon
1799 driver. If --live is specified, only the running guest collection pe‐
1800 riod is affected. If --config is specified, affect the next start of a
1801 persistent guest. If --current is specified, it is equivalent to either
1802 --live or --config, depending on the current state of the guest.
1803 Both --live and --config flags may be given, but --current is exclu‐
1805 sive. If no flag is specified, behavior is different depending on the
1806 guest state.
1807 domname
1809 Syntax:
1810 domname domain-id-or-uuid
1812 Convert a domain Id (or UUID) to domain name
1814 dompmsuspend
1816 Syntax:
1817 dompmsuspend domain target [--duration]
1819 Suspend a running domain into one of these states (possible target val‐
1821 ues):
1822 • mem - equivalent of S3 ACPI state
1824 • disk - equivalent of S4 ACPI state
1826 • hybrid - RAM is saved to disk but not powered off
1828 The --duration argument specifies number of seconds before the domain
1830 is woken up after it was suspended (see also dompmwakeup). Default is 0
1831 for unlimited suspend time. (This feature isn't currently supported by
1832 any hypervisor driver and 0 should be used.).
1833 Note that this command requires a guest agent configured and running in
1835 the domain's guest OS.
1836 Beware that at least for QEMU, the domain's process will be terminated
1838 when target disk is used and a new process will be launched when lib‐
1839 virt is asked to wake up the domain. As a result of this, any runtime
1840 changes, such as device hotplug or memory settings, are lost unless
1841 such changes were made with --config flag.
1842 dompmwakeup
1844 Syntax:
1845 dompmwakeup domain
1847 Wakeup a domain from pmsuspended state (either suspended by dompmsus‐
1849 pend or from the guest itself). Injects a wakeup into the guest that is
1850 in pmsuspended state, rather than waiting for the previously requested
1851 duration (if any) to elapse. This operation does not necessarily fail
1852 if the domain is running.
1853 domrename
1855 Syntax:
1856 domrename domain new-name
1858 Rename a domain. This command changes current domain name to the new
1860 name specified in the second argument.
1861 Note: Domain must be inactive.
1863 domstate
1865 Syntax:
1866 domstate domain [--reason]
1868 Returns state about a domain. --reason tells virsh to also print rea‐
1870 son for the state.
1871 domstats
1873 Syntax:
1874 domstats [--raw] [--enforce] [--backing] [--nowait] [--state]
1876 [--cpu-total] [--balloon] [--vcpu] [--interface]
1877 [--block] [--perf] [--iothread] [--memory] [--dirtyrate] [--vm]
1878 [[--list-active] [--list-inactive]
1879 [--list-persistent] [--list-transient] [--list-running]y
1880 [--list-paused] [--list-shutoff] [--list-other]] | [domain ...]
1881 Get statistics for multiple or all domains. Without any argument this
1883 command prints all available statistics for all domains.
1884 The list of domains to gather stats for can be either limited by list‐
1886 ing the domains as a space separated list, or by specifying one of the
1887 filtering flags --list-NNN. (The approaches can't be combined.)
1888 By default some of the returned fields may be converted to more human
1890 friendly values by a set of pretty-printers. To suppress this behavior
1891 use the --raw flag.
1892 The individual statistics groups are selectable via specific flags. By
1894 default all supported statistics groups are returned. Supported statis‐
1895 tics groups flags are: --state, --cpu-total, --balloon, --vcpu, --in‐
1896 terface, --block, --perf, --iothread, --memory, --dirtyrate, --vm.
1897 Note that - depending on the hypervisor type and version or the domain
1899 state - not all of the following statistics may be returned.
1900 When selecting the --state group the following fields are returned:
1902 • state.state - state of the VM, returned as number from virDomainState
1904 enum
1905 • state.reason - reason for entering given state, returned as int from
1907 virDomain*Reason enum corresponding to given state
1908 --cpu-total returns:
1910 • cpu.time - total cpu time spent for this domain in nanoseconds
1912 • cpu.user - user cpu time spent in nanoseconds
1914 • cpu.system - system cpu time spent in nanoseconds
1916 • cpu.haltpoll.success.time - cpu halt polling success time spent in
1918 nanoseconds
1919 • cpu.haltpoll.fail.time - cpu halt polling fail time spent in nanosec‐
1921 onds
1922 • cpu.cache.monitor.count - the number of cache monitors for this do‐
1924 main
1925 • cpu.cache.monitor.<num>.name - the name of cache monitor <num>
1927 • cpu.cache.monitor.<num>.vcpus - vcpu list of cache monitor <num>
1929 • cpu.cache.monitor.<num>.bank.count - the number of cache banks in
1931 cache monitor <num>
1932 • cpu.cache.monitor.<num>.bank.<index>.id - host allocated cache id for
1934 bank <index> in cache monitor <num>
1935 • cpu.cache.monitor.<num>.bank.<index>.bytes - the number of bytes of
1937 last level cache that the domain is using on cache bank <index>
1938 --balloon returns:
1940 • balloon.current - the memory in KiB currently used
1942 • balloon.maximum - the maximum memory in KiB allowed
1944 • balloon.swap_in - the amount of data read from swap space (in KiB)
1946 • balloon.swap_out - the amount of memory written out to swap space (in
1948 KiB)
1949 • balloon.major_fault - the number of page faults when disk IO was re‐
1951 quired
1952 • balloon.minor_fault - the number of other page faults
1954 • balloon.unused - the amount of memory left unused by the system (in
1956 KiB)
1957 • balloon.available - the amount of usable memory as seen by the domain
1959 (in KiB)
1960 • balloon.rss - Resident Set Size of running domain's process (in KiB)
1962 • balloon.usable - the amount of memory which can be reclaimed by bal‐
1964 loon without causing host swapping (in KiB)
1965 • balloon.last-update - timestamp of the last update of statistics (in
1967 seconds)
1968 • balloon.disk_caches - the amount of memory that can be reclaimed
1970 without additional I/O, typically disk (in KiB)
1971 • balloon.hugetlb_pgalloc - the number of successful huge page alloca‐
1973 tions from inside the domain via virtio balloon
1974 • balloon.hugetlb_pgfail - the number of failed huge page allocations
1976 from inside the domain via virtio balloon
1977 --vcpu returns:
1979 • vcpu.current - current number of online virtual CPUs
1981 • vcpu.maximum - maximum number of online virtual CPUs
1983 • vcpu.<num>.state - state of the virtual CPU <num>, as number from
1985 virVcpuState enum
1986 • vcpu.<num>.time - virtual cpu time spent by virtual CPU <num> (in mi‐
1988 croseconds)
1989 • vcpu.<num>.wait - virtual cpu time spent by virtual CPU <num> waiting
1991 on I/O (in microseconds)
1992 • vcpu.<num>.halted - virtual CPU <num> is halted: yes or no (may indi‐
1994 cate the processor is idle or even disabled, depending on the archi‐
1995 tecture)
1996 • vcpu.<num>.delay - time the vCPU <num> thread was enqueued by the
1998 host scheduler, but was waiting in the queue instead of running. Ex‐
1999 posed to the VM as a steal time.
2000 This group of statistics also reports additional hypervisor-originating
2002 per-vCPU stats. The hypervisor-specific statistics in this group have
2003 the following naming scheme:
2004 vcpu.<num>.$NAME.$TYPE
2005 $NAME name of the statistics field provided by the hypervisor
2007 $TYPE Type of the value. The following types are returned:
2009 cur current instant value
2011 sum aggregate value
2013 max peak value
2015 The returned value may be either an unsigned long long or a boolean.
2017 Meaning is hypervisor specific. Please see the disclaimer for the
2018 --vm group which also consists of hypervisor-specific stats.
2019 --interface returns:
2021 • net.count - number of network interfaces on this domain
2023 • net.<num>.name - name of the interface <num>
2025 • net.<num>.rx.bytes - number of bytes received
2027 • net.<num>.rx.pkts - number of packets received
2029 • net.<num>.rx.errs - number of receive errors
2031 • net.<num>.rx.drop - number of receive packets dropped
2033 • net.<num>.tx.bytes - number of bytes transmitted
2035 • net.<num>.tx.pkts - number of packets transmitted
2037 • net.<num>.tx.errs - number of transmission errors
2039 • net.<num>.tx.drop - number of transmit packets dropped
2041 --perf returns the statistics of all enabled perf events:
2043 • perf.cmt - the cache usage in Byte currently used
2045 • perf.mbmt - total system bandwidth from one level of cache
2047 • perf.mbml - bandwidth of memory traffic for a memory controller
2049 • perf.cpu_cycles - the count of cpu cycles (total/elapsed)
2051 • perf.instructions - the count of instructions
2053 • perf.cache_references - the count of cache hits
2055 • perf.cache_misses - the count of caches misses
2057 • perf.branch_instructions - the count of branch instructions
2059 • perf.branch_misses - the count of branch misses
2061 • perf.bus_cycles - the count of bus cycles
2063 • perf.stalled_cycles_frontend - the count of stalled frontend cpu cy‐
2065 cles
2066 • perf.stalled_cycles_backend - the count of stalled backend cpu cycles
2068 • perf.ref_cpu_cycles - the count of ref cpu cycles
2070 • perf.cpu_clock - the count of cpu clock time
2072 • perf.task_clock - the count of task clock time
2074 • perf.page_faults - the count of page faults
2076 • perf.context_switches - the count of context switches
2078 • perf.cpu_migrations - the count of cpu migrations
2080 • perf.page_faults_min - the count of minor page faults
2082 • perf.page_faults_maj - the count of major page faults
2084 • perf.alignment_faults - the count of alignment faults
2086 • perf.emulation_faults - the count of emulation faults
2088 See the perf command for more details about each event.
2090 --block returns information about disks associated with each domain.
2092 Using the --backing flag extends this information to cover all re‐
2093 sources in the backing chain, rather than the default of limiting in‐
2094 formation to the active layer for each guest disk. Information listed
2095 includes:
2096 • block.count - number of block devices being listed
2098 • block.<num>.name - name of the target of the block device <num> (the
2100 same name for multiple entries if --backing is present)
2101 • block.<num>.backingIndex - when --backing is present, matches up with
2103 the <backingStore> index listed in domain XML for backing files
2104 • block.<num>.path - file source of block device <num>, if it is a lo‐
2106 cal file or block device
2107 • block.<num>.rd.reqs - number of read requests
2109 • block.<num>.rd.bytes - number of read bytes
2111 • block.<num>.rd.times - total time (ns) spent on reads
2113 • block.<num>.wr.reqs - number of write requests
2115 • block.<num>.wr.bytes - number of written bytes
2117 • block.<num>.wr.times - total time (ns) spent on writes
2119 • block.<num>.fl.reqs - total flush requests
2121 • block.<num>.fl.times - total time (ns) spent on cache flushing
2123 • block.<num>.errors - Xen only: the 'oo_req' value
2125 • block.<num>.allocation - offset of highest written sector in bytes
2127 • block.<num>.capacity - logical size of source file in bytes
2129 • block.<num>.physical - physical size of source file in bytes
2131 • block.<num>.threshold - threshold (in bytes) for delivering the
2133 VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event. See domblkthreshold.
2134 --iothread returns information about IOThreads on the running guest if
2136 supported by the hypervisor.
2137 The "poll-max-ns" for each thread is the maximum nanoseconds to allow
2139 each polling interval to occur. A polling interval is a period of time
2140 allowed for a thread to process data before being the guest gives up
2141 its CPU quantum back to the host. A value set too small will not allow
2142 the IOThread to run long enough on a CPU to process data. A value set
2143 too high will consume too much CPU time per IOThread failing to allow
2144 other threads running on the CPU to get time. The polling interval is
2145 not available for statistical purposes.
2146 •
2148 iothread.count - maximum number of IOThreads in the subsequent list
2150 as unsigned int. Each IOThread in the list will will use it's
2151 iothread_id value as the <id>. There may be fewer <id> entries
2152 than the iothread.count value if the polling values are not
2153 supported.
2154 • iothread.<id>.poll-max-ns - maximum polling time in nanoseconds used
2156 by the <id> IOThread. A value of 0 (zero) indicates polling is dis‐
2157 abled.
2158 • iothread.<id>.poll-grow - polling time grow value. A value of 0
2160 (zero) growth is managed by the hypervisor.
2161 • iothread.<id>.poll-shrink - polling time shrink value. A value of
2163 (zero) indicates shrink is managed by hypervisor.
2164 --memory returns:
2166 • memory.bandwidth.monitor.count - the number of memory bandwidth moni‐
2168 tors for this domain
2169 • memory.bandwidth.monitor.<num>.name - the name of monitor <num>
2171 • memory.bandwidth.monitor.<num>.vcpus - the vcpu list of monitor <num>
2173 •
2175 memory.bandwidth.monitor.<num>.node.count - the number of memory
2177 controller in monitor <num>
2178 • memory.bandwidth.monitor.<num>.node.<index>.id - host allocated mem‐
2180 ory controller id for controller <index> of monitor <num>
2181 • memory.bandwidth.monitor.<num>.node.<index>.bytes.local - the accumu‐
2183 lative bytes consumed by @vcpus that passing through the memory con‐
2184 troller in the same processor that the scheduled host CPU belongs to.
2185 • memory.bandwidth.monitor.<num>.node.<index>.bytes.total - the total
2187 bytes consumed by @vcpus that passing through all memory controllers,
2188 either local or remote controller.
2189 --dirtyrate returns:
2191 • dirtyrate.calc_status - the status of last memory dirty rate calcula‐
2193 tion, returned as number from virDomainDirtyRateStatus enum.
2194 • dirtyrate.calc_start_time - the start time of last memory dirty rate
2196 calculation.
2197 • dirtyrate.calc_period - the period of last memory dirty rate calcula‐
2199 tion.
2200 • dirtyrate.megabytes_per_second - the calculated memory dirty rate in
2202 MiB/s.
2203 • dirtyrate.calc_mode - the calculation mode used last measurement
2205 (page-sampling/dirty-bitmap/dirty-ring)
2206 • dirtyrate.vcpu.<num>.megabytes_per_second - the calculated memory
2208 dirty rate for a virtual cpu in MiB/s
2209 --vm returns:
2211 The --vm option enables reporting of hypervisor-specific statistics.
2213 Naming and meaning of the fields is entirely hypervisor dependent.
2214 The statistics in this group have the following naming scheme:
2216 vm.$NAME.$TYPE
2217 $NAME name of the statistics field provided by the hypervisor
2219 $TYPE Type of the value. The following types are returned:
2221 cur current instant value
2223 sum aggregate value
2225 max peak value
2227 The returned value may be either an unsigned long long or a boolean.
2229 WARNING: The stats reported in this group are runtime-collected and
2231 hypervisor originated, thus fall outside of the usual stable API
2232 policies of libvirt.
2233 Libvirt can't guarantee that the statistics reported from the out‐
2235 side source will be present in further versions of the hypervisor,
2236 or that naming or meaning will stay consistent. Changes to existing
2237 fields, however, are expected to be rare.
2238 Selecting a specific statistics groups doesn't guarantee that the dae‐
2240 mon supports the selected group of stats. Flag --enforce forces the
2241 command to fail if the daemon doesn't support the selected group.
2242 When collecting stats libvirtd may wait for some time if there's al‐
2244 ready another job running on given domain for it to finish. This may
2245 cause unnecessary delay in delivering stats. Using --nowait suppresses
2246 this behaviour. On the other hand some statistics might be missing for
2247 such domain.
2248 domtime
2250 Syntax:
2251 domtime domain { [--now] [--pretty] [--sync] [--time time] }
2253 Gets or sets the domain's system time. When run without any arguments
2255 (but domain), the current domain's system time is printed out. The
2256 --pretty modifier can be used to print the time in more human readable
2257 form.
2258 When --time time is specified, the domain's time is not gotten but set
2260 instead. The --now modifier acts like if it was an alias for --time
2261 $now, which means it sets the time that is currently on the host virsh
2262 is running at. In both cases (setting and getting), time is in seconds
2263 relative to Epoch of 1970-01-01 in UTC. The --sync modifies the set
2264 behavior a bit: The time passed is ignored, but the time to set is read
2265 from domain's RTC instead. Please note, that some hypervisors may re‐
2266 quire a guest agent to be configured in order to get or set the guest
2267 time.
2268 domuuid
2270 Syntax:
2271 domuuid domain-name-or-id
2273 Convert a domain name or id to domain UUID
2275 domxml-from-native
2277 Syntax:
2278 domxml-from-native format config
2280 Convert the file config in the native guest configuration format named
2282 by format to a domain XML format. For QEMU/KVM hypervisor, the format
2283 argument must be qemu-argv. For Xen hypervisor, the format argument may
2284 be xen-xm, xen-xl, or xen-sxpr. For LXC hypervisor, the format argument
2285 must be lxc-tools. For VMware/ESX hypervisor, the format argument must
2286 be vmware-vmx. For the Bhyve hypervisor, the format argument must be
2287 bhyve-argv.
2288 domxml-to-native
2290 Syntax:
2291 domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-uuid }
2293 Convert the file xml into domain XML format or convert an existing
2295 --domain to the native guest configuration format named by format. The
2296 xml and --domain arguments are mutually exclusive. For the types of
2297 format argument, refer to domxml-from-native.
2298 dump
2300 Syntax:
2301 dump domain corefilepath [--bypass-cache]
2303 { [--live] | [--crash] | [--reset] }
2304 [--verbose] [--memory-only] [--format string]
2305 Dumps the core of a domain to a file for analysis. If --live is speci‐
2307 fied, the domain continues to run until the core dump is complete,
2308 rather than pausing up front. If --crash is specified, the domain is
2309 halted with a crashed status, rather than merely left in a paused
2310 state. If --reset is specified, the domain is reset after successful
2311 dump. Note, these three switches are mutually exclusive. If --by‐
2312 pass-cache is specified, the save will avoid the file system cache, al‐
2313 though this may slow down the operation. If --memory-only is speci‐
2314 fied, the file is elf file, and will only include domain's memory and
2315 cpu common register value. It is very useful if the domain uses host
2316 devices directly. --format string is used to specify the format of
2317 'memory-only' dump, and string can be one of: elf,
2318 kdump-zlib(kdump-compressed format with zlib-compressed),
2319 kdump-lzo(kdump-compressed format with lzo-compressed),
2320 kdump-snappy(kdump-compressed format with snappy-compressed),
2321 win-dmp(Windows full crashdump format).
2322 The progress may be monitored using domjobinfo virsh command and can‐
2324 celed with domjobabort command (sent by another virsh instance). An‐
2325 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2326 process running dump command. --verbose displays the progress of dump.
2327 NOTE: Some hypervisors may require the user to manually ensure proper
2329 permissions on file and path specified by argument corefilepath.
2330 NOTE: Crash dump in a old kvmdump format is being obsolete and cannot
2332 be loaded and processed by crash utility since its version 6.1.0. A
2333 --memory-only option is required in order to produce valid ELF file
2334 which can be later processed by the crash utility.
2335 dumpxml
2337 Syntax:
2338 dumpxml [--inactive] [--security-info] [--update-cpu] [--migratable]
2340 [--xpath EXPRESSION] [--wrap] domain
2341 Output the domain information as an XML dump to stdout, this format can
2343 be used by the create command. Additional options affecting the XML
2344 dump may be used. --inactive tells virsh to dump domain configuration
2345 that will be used on next start of the domain as opposed to the current
2346 domain configuration. Using --security-info will also include security
2347 sensitive information in the XML dump. --update-cpu updates domain CPU
2348 requirements according to host CPU. With --migratable one can request
2349 an XML that is suitable for migrations, i.e., compatible with older
2350 libvirt releases and possibly amended with internal run-time options.
2351 This option may automatically enable other options (--update-cpu, --se‐
2352 curity-info, ...) as necessary.
2353 If the --xpath argument provides an XPath expression, it will be evalu‐
2355 ated against the output XML and only those matching nodes will be
2356 printed. The default behaviour is to print each matching node as a
2357 standalone document, however, for ease of additional processing, the
2358 --wrap argument will cause the matching node to be wrapped in a common
2359 root node.
2360 edit
2362 Syntax:
2363 edit domain
2365 Edit the XML configuration file for a domain, which will affect the
2367 next boot of the guest.
2368 This is equivalent to:
2370 virsh dumpxml --inactive --security-info domain > domain.xml
2372 vi domain.xml (or make changes with your other text editor)
2373 virsh define domain.xml
2374 except that it does some error checking.
2376 The editor used can be supplied by the $VISUAL or $EDITOR environment
2378 variables, and defaults to vi.
2379 emulatorpin
2381 Syntax:
2382 emulatorpin domain [cpulist] [[--live] [--config] | [--current]]
2384 Query or change the pinning of domain's emulator threads to host physi‐
2386 cal CPUs.
2387 See vcpupin for cpulist.
2389 If --live is specified, affect a running guest. If --config is speci‐
2391 fied, affect the next start of a persistent guest. If --current is
2392 specified, it is equivalent to either --live or --config, depending on
2393 the current state of the guest. Both --live and --config flags may be
2394 given if cpulist is present, but --current is exclusive. If no flag is
2395 specified, behavior is different depending on hypervisor.
2396 event
2398 Syntax:
2399 event {[domain] { event | --all } [--loop] [--timeout seconds] [--timestamp] | --list}
2401 Wait for a class of domain events to occur, and print appropriate de‐
2403 tails of events as they happen. The events can optionally be filtered
2404 by domain. Using --list as the only argument will provide a list of
2405 possible event values known by this client, although the connection
2406 might not allow registering for all these events. It is also possible
2407 to use --all instead of event to register for all possible event types
2408 at once.
2409 By default, this command is one-shot, and returns success once an event
2411 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
2412 If --timeout is specified, the command gives up waiting for events af‐
2413 ter seconds have elapsed. With --loop, the command prints all events
2414 until a timeout or interrupt key.
2415 When --timestamp is used, a human-readable timestamp will be printed
2417 before the event.
2418 get-user-sshkeys
2420 Syntax:
2421 get-user-sshkeys domain user
2423 Print SSH authorized keys for given user in the guest domain. Please
2425 note, that an entry in the file has internal structure as defined by
2426 sshd(8) and virsh/libvirt does handle keys as opaque strings, i.e. does
2427 not interpret them.
2428 guest-agent-timeout
2430 Syntax:
2431 guest-agent-timeout domain [--timeout value]
2433 Set how long to wait for a response from guest agent commands. By de‐
2435 fault, agent commands block forever waiting for a response. value must
2436 be a positive value (wait for given amount of seconds) or one of the
2437 following values:
2438 • -2 - block forever waiting for a result (used when --timeout is omit‐
2440 ted),
2441 • -1 - reset timeout to the default value (currently defined as 5 sec‐
2443 onds in libvirt daemon),
2444 • 0 - do not wait at all,
2446 guestinfo
2448 Syntax:
2449 guestinfo domain [--user] [--os] [--timezone] [--hostname] [--filesystem]
2451 [--disk] [--interface]
2452 Print information about the guest from the point of view of the guest
2454 agent. Note that this command requires a guest agent to be configured
2455 and running in the domain's guest OS.
2456 When run without any arguments, this command prints all information
2458 types that are supported by the guest agent at that point, omitting un‐
2459 available ones. Success is always reported in this case.
2460 You can limit the types of information that are returned by specifying
2462 one or more flags. Available information types flags are --user, --os,
2463 --timezone, --hostname, --filesystem, --disk and --interface. If an
2464 explicitly requested information type is not supported by the guest
2465 agent at that point, the processes will provide an exit code of 1.
2466 Note that depending on the hypervisor type and the version of the guest
2468 agent running within the domain, not all of the following information
2469 may be returned.
2470 When selecting the --user information type, the following fields may be
2472 returned:
2473 • user.count - the number of active users on this domain
2475 • user.<num>.name - username of user <num>
2477 • user.<num>.domain - domain of the user <num> (may only be present on
2479 certain guets types)
2480 • user.<num>.login-time - the login time of user <num> in milliseconds
2482 since the epoch
2483 --os returns:
2485 • os.id - a string identifying the operating system
2487 • os.name - the name of the operating system
2489 • os.pretty-name - a pretty name for the operating system
2491 • os.version - the version of the operating system
2493 • os.version-id - the version id of the operating system
2495 • os.kernel-release - the release of the operating system kernel
2497 • os.kernel-version - the version of the operating system kernel
2499 • os.machine - the machine hardware name
2501 • os.variant - a specific variant or edition of the operating system
2503 • os.variant-id - the id for a specific variant or edition of the oper‐
2505 ating system
2506 --timezone returns:
2508 • timezone.name - the name of the timezone
2510 • timezone.offset - the offset to UTC in seconds
2512 --hostname returns:
2514 • hostname - the hostname of the domain
2516 --filesystem returns:
2518 • fs.count - the number of filesystems defined on this domain
2520 • fs.<num>.mountpoint - the path to the mount point for filesystem
2522 <num>
2523 • fs.<num>.name - device name in the guest (e.g. sda1) for filesystem
2525 <num>
2526 • fs.<num>.fstype - the type of filesystem <num>
2528 • fs.<num>.total-bytes - the total size of filesystem <num>
2530 • fs.<num>.used-bytes - the number of bytes used in filesystem <num>
2532 • fs.<num>.disk.count - the number of disks targeted by filesystem
2534 <num>
2535 • fs.<num>.disk.<num>.alias - the device alias of disk <num> (e.g. sda)
2537 • fs.<num>.disk.<num>.serial - the serial number of disk <num>
2539 • fs.<num>.disk.<num>.device - the device node of disk <num>
2541 --disk returns:
2543 • disk.count - the number of disks defined on this domain
2545 • disk.<num>.name - device node (Linux) or device UNC (Windows)
2547 • disk.<num>.partition - whether this is a partition or disk
2549 • disk.<num>.dependency.count - the number of device dependencies
2551 • disk.<num>.dependency.<num>.name - a dependency name
2553 • disk.<num>.serial - optional disk serial number
2555 • disk.<num>.alias - the device alias of the disk (e.g. sda)
2557 • disk.<num>.guest_alias - optional alias assigned to the disk
2559 --interface returns: * if.count - the number of interfaces defined on
2561 this domain * if.<num>.name - name in the guest (e.g. eth0) for inter‐
2562 face <num> * if.<num>.hwaddr - hardware address in the guest for inter‐
2563 face <num> * if.<num>.addr.count - the number of IP addresses of inter‐
2564 face <num> * if.<num>.addr.<num1>.type - the IP address type of addr
2565 <num1> (e.g. ipv4) * if.<num>.addr.<num1>.addr - the IP address of addr
2566 <num1> * if.<num>.addr.<num1>.prefix - the prefix of IP address of addr
2567 <num1>
2568 guestvcpus
2570 Syntax:
2571 guestvcpus domain [[--enable] | [--disable]] [cpulist]
2573 Query or change state of vCPUs from guest's point of view using the
2575 guest agent. When invoked without cpulist the guest is queried for
2576 available guest vCPUs, their state and possibility to be offlined.
2577 If cpulist is provided then one of --enable or --disable must be pro‐
2579 vided too. The desired operation is then executed on the domain.
2580 See vcpupin for information on cpulist.
2582 iothreadadd
2584 Syntax:
2585 iothreadadd domain iothread_id [[--config] [--live] | [--current]]
2587 Add a new IOThread to the domain using the specified iothread_id. If
2589 the iothread_id already exists, the command will fail. The iothread_id
2590 must be greater than zero.
2591 If --live is specified, affect a running guest. If the guest is not
2593 running an error is returned. If --config is specified, affect the
2594 next start of a persistent guest. If --current is specified, it is
2595 equivalent to either --live or --config, depending on the current state
2596 of the guest.
2597 iothreaddel
2599 Syntax:
2600 iothreaddel domain iothread_id [[--config] [--live] | [--current]]
2602 Delete an IOThread from the domain using the specified iothread_id. If
2604 an IOThread is currently assigned to a disk resource such as via the
2605 attach-disk command, then the attempt to remove the IOThread will fail.
2606 If the iothread_id does not exist an error will occur.
2607 If --live is specified, affect a running guest. If the guest is not
2609 running an error is returned. If --config is specified, affect the
2610 next start of a persistent guest. If --current is specified, it is
2611 equivalent to either --live or --config, depending on the current state
2612 of the guest.
2613 iothreadinfo
2615 Syntax:
2616 iothreadinfo domain [[--live] [--config] | [--current]]
2618 Display basic domain IOThreads information including the IOThread ID
2620 and the CPU Affinity for each IOThread.
2621 If --live is specified, get the IOThreads data from the running guest.
2623 If the guest is not running, an error is returned. If --config is
2624 specified, get the IOThreads data from the next start of a persistent
2625 guest. If --current is specified or --live and --config are not speci‐
2626 fied, then get the IOThread data based on the current guest state,
2627 which can either be live or offline.
2628 iothreadpin
2630 Syntax:
2631 iothreadpin domain iothread cpulist [[--live] [--config] | [--current]]
2633 Change the pinning of a domain IOThread to host physical CPUs. In order
2635 to retrieve a list of all IOThreads, use iothreadinfo. To pin an io‐
2636 thread specify the cpulist desired for the IOThread ID as listed in the
2637 iothreadinfo output.
2638 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
2640 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
2641 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
2642 clusive. If you want to reset iothreadpin setting, that is, to pin an
2643 iothread to all physical cpus, simply specify 'r' as a cpulist.
2644 If --live is specified, affect a running guest. If the guest is not
2646 running, an error is returned. If --config is specified, affect the
2647 next start of a persistent guest. If --current is specified, it is
2648 equivalent to either --live or --config, depending on the current state
2649 of the guest. Both --live and --config flags may be given if cpulist
2650 is present, but --current is exclusive. If no flag is specified, be‐
2651 havior is different depending on hypervisor.
2652 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
2654 cal to "9-14,0-7,15" but not identical to "^8,0-15".
2655 iothreadset
2657 Syntax:
2658 iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor]
2660 [--poll-shrink divisor] [--thread-pool-min value]
2661 [--thread-pool-max value]]
2662 [[--config] [--live] | [--current]]
2663 Modifies an existing iothread of the domain using the specified io‐
2665 thread_id. The --poll-max-ns provides the maximum polling interval to
2666 be allowed for an IOThread in ns. If a 0 (zero) is provided, then
2667 polling for the IOThread is disabled. The --poll-grow is the factor by
2668 which the current polling time will be adjusted in order to reach the
2669 maximum polling time. If a 0 (zero) is provided, then the default fac‐
2670 tor will be used. The --poll-shrink is the quotient by which the cur‐
2671 rent polling time will be reduced in order to get below the maximum
2672 polling interval. If a 0 (zero) is provided, then the default quotient
2673 will be used. The polling values are purely dynamic for a running
2674 guest. Saving, destroying, stopping, etc. the guest will result in the
2675 polling values returning to hypervisor defaults at the next start, re‐
2676 store, etc.
2677 The --thread-pool-min and --thread-pool-max options then set lower and
2679 upper bound, respectively of number of threads in worker pool of given
2680 iothread. For changes to an inactive configuration -1 can be specified
2681 to remove corresponding boundary from the domain configuration. For
2682 changes to a running guest it's recommended to set the upper boundary
2683 first (--thread-pool-max) and only after that set the lower boundary
2684 (--thread-pool-min). It is allowed for the lower boundary to be the
2685 same as the upper boundary, however it's not allowed for the upper
2686 boundary to be value of zero.
2687 If --live is specified, affect a running guest. If the guest is not
2689 running an error is returned. If --current is specified or --live is
2690 not specified, then handle as if --live was specified. (Where "cur‐
2691 rent" here means whatever the present guest state is: live or offline.)
2692 managedsave
2694 Syntax:
2695 managedsave domain [--bypass-cache] [{--running | --paused}] [--verbose]
2697 Save and destroy (stop) a running domain, so it can be restarted from
2699 the same state at a later time. When the virsh start command is next
2700 run for the domain, it will automatically be started from this saved
2701 state. If --bypass-cache is specified, the save will avoid the file
2702 system cache, although this may slow down the operation.
2703 The progress may be monitored using domjobinfo virsh command and can‐
2705 celed with domjobabort command (sent by another virsh instance). An‐
2706 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2707 process running managedsave command. --verbose displays the progress of
2708 save.
2709 Normally, starting a managed save will decide between running or paused
2711 based on the state the domain was in when the save was done; passing
2712 either the --running or --paused flag will allow overriding which state
2713 the start should use.
2714 The dominfo command can be used to query whether a domain currently has
2716 any managed save image.
2717 managedsave-define
2719 Syntax:
2720 managedsave-define domain xml [{--running | --paused}]
2722 Update the domain XML that will be used when domain is later started.
2724 The xml argument must be a file name containing the alternative XML,
2725 with changes only in the host-specific portions of the domain XML. For
2726 example, it can be used to change disk file paths.
2727 The managed save image records whether the domain should be started to
2729 a running or paused state. Normally, this command does not alter the
2730 recorded state; passing either the --running or --paused flag will al‐
2731 low overriding which state the start should use.
2732 managedsave-dumpxml
2734 Syntax:
2735 managedsave-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap] domain
2737 Extract the domain XML that was in effect at the time the saved state
2739 file file was created with the managedsave command. Using --secu‐
2740 rity-info will also include security sensitive information.
2741 If the --xpath argument provides an XPath expression, it will be evalu‐
2743 ated against the output XML and only those matching nodes will be
2744 printed. The default behaviour is to print each matching node as a
2745 standalone document, however, for ease of additional processing, the
2746 --wrap argument will cause the matching node to be wrapped in a common
2747 root node.
2748 managedsave-edit
2750 Syntax:
2751 managedsave-edit domain [{--running | --paused}]
2753 Edit the XML configuration associated with a saved state file of a do‐
2755 main was created by the managedsave command.
2756 The managed save image records whether the domain should be started to
2758 a running or paused state. Normally, this command does not alter the
2759 recorded state; passing either the --running or --paused flag will al‐
2760 low overriding which state the restore should use.
2761 This is equivalent to:
2763 virsh managedsave-dumpxml domain-name > state-file.xml
2765 vi state-file.xml (or make changes with your other text editor)
2766 virsh managedsave-define domain-name state-file-xml
2767 except that it does some error checking.
2769 The editor used can be supplied by the $VISUAL or $EDITOR environment
2771 variables, and defaults to vi.
2772 managedsave-remove
2774 Syntax:
2775 managedsave-remove domain
2777 Remove the managedsave state file for a domain, if it exists. This en‐
2779 sures the domain will do a full boot the next time it is started.
2780 maxvcpus
2782 Syntax:
2783 maxvcpus [type]
2785 Provide the maximum number of virtual CPUs supported for a guest VM on
2787 this connection. If provided, the type parameter must be a valid type
2788 attribute for the <domain> element of XML.
2789 memtune
2791 Syntax:
2792 memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-limit size]
2794 [--min-guarantee size] [[--config] [--live] | [--current]]
2795 Allows you to display or set the domain memory parameters. Without
2797 flags, the current settings are displayed; with a flag, the appropriate
2798 limit is adjusted if supported by the hypervisor. LXC and QEMU/KVM
2799 support --hard-limit, --soft-limit, and --swap-hard-limit. --min-guar‐
2800 antee is supported only by ESX hypervisor. Each of these limits are
2801 scaled integers (see NOTES above), with a default of kibibytes (blocks
2802 of 1024 bytes) if no suffix is present. Libvirt rounds up to the near‐
2803 est kibibyte. Some hypervisors require a larger granularity than KiB,
2804 and requests that are not an even multiple will be rounded up. For ex‐
2805 ample, vSphere/ESX rounds the parameter up to mebibytes (1024
2806 kibibytes).
2807 If --live is specified, affect a running guest. If --config is speci‐
2809 fied, affect the next start of a persistent guest. If --current is
2810 specified, it is equivalent to either --live or --config, depending on
2811 the current state of the guest. Both --live and --config flags may be
2812 given, but --current is exclusive. If no flag is specified, behavior is
2813 different depending on hypervisor.
2814 For QEMU/KVM, the parameters are applied to the QEMU process as a
2816 whole. Thus, when counting them, one needs to add up guest RAM, guest
2817 video RAM, and some memory overhead of QEMU itself. The last piece is
2818 hard to determine so one needs guess and try.
2819 For LXC, the displayed hard_limit value is the current memory setting
2821 from the XML or the results from a virsh setmem command.
2822 • --hard-limit
2824 The maximum memory the guest can use.
2826 • --soft-limit
2828 The memory limit to enforce during memory contention.
2830 • --swap-hard-limit
2832 The maximum memory plus swap the guest can use. This has to be more
2834 than hard-limit value provided.
2835 • --min-guarantee
2837 The guaranteed minimum memory allocation for the guest.
2839 Specifying -1 as a value for these limits is interpreted as unlimited.
2841 metadata
2843 Syntax:
2844 metadata domain [[--live] [--config] | [--current]]
2846 [--edit] [uri] [key] [set] [--remove]
2847 Show or modify custom XML metadata of a domain. The metadata is a user
2849 defined XML that allows storing arbitrary XML data in the domain defi‐
2850 nition. Multiple separate custom metadata pieces can be stored in the
2851 domain XML. The pieces are identified by a private XML namespace pro‐
2852 vided via the uri argument. (See also desc that works with textual
2853 metadata of a domain.)
2854 Flags --live or --config select whether this command works on live or
2856 persistent definitions of the domain. If both --live and --config are
2857 specified, the --config option takes precedence on getting the current
2858 description and both live configuration and config are updated while
2859 setting the description. --current is exclusive and implied if none of
2860 these was specified.
2861 Flag --remove specifies that the metadata element specified by the uri
2863 argument should be removed rather than updated.
2864 Flag --edit specifies that an editor with the metadata identified by
2866 the uri argument should be opened and the contents saved back after‐
2867 wards. Otherwise the new contents can be provided via the set argu‐
2868 ment.
2869 When setting metadata via --edit or set the key argument must be speci‐
2871 fied and is used to prefix the custom elements to bind them to the pri‐
2872 vate namespace.
2873 If neither of --edit and set are specified the XML metadata correspond‐
2875 ing to the uri namespace is displayed instead of being modified.
2876 migrate
2878 Syntax:
2879 migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]]
2881 [--persistent] [--undefinesource] [--suspend] [--copy-storage-all]
2882 [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose]
2883 [--rdma-pin-all] [--abort-on-error] [--postcopy]
2884 [--postcopy-after-precopy] [--postcopy-resume] [--zerocopy]
2885 domain desturi [migrateuri] [graphicsuri] [listen-address] [dname]
2886 [--timeout seconds [--timeout-suspend | --timeout-postcopy]]
2887 [--xml file] [--migrate-disks disk-list] [--disks-port port]
2888 [--compressed] [--comp-methods method-list]
2889 [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads]
2890 [--comp-xbzrle-cache] [--comp-zlib-level] [--comp-zstd-level]
2891 [--auto-converge] [auto-converge-initial]
2892 [auto-converge-increment] [--persistent-xml file] [--tls]
2893 [--postcopy-bandwidth bandwidth]
2894 [--parallel [--parallel-connections connections]]
2895 [--bandwidth bandwidth] [--tls-destination hostname]
2896 [--disks-uri URI] [--copy-storage-synchronous-writes]
2897 Migrate domain to another host. Add --live for live migration; <--p2p>
2899 for peer-2-peer migration; --direct for direct migration; or --tun‐
2900 nelled for tunnelled migration. --offline migrates domain definition
2901 without starting the domain on destination and without stopping it on
2902 source host. Offline migration may be used with inactive domains and
2903 it must be used with --persistent option.
2904 --persistent leaves the domain persistent on destination host, --unde‐
2906 finesource undefines the domain on the source host, and --suspend
2907 leaves the domain paused on the destination host.
2908 --copy-storage-all indicates migration with non-shared storage with
2910 full disk copy, --copy-storage-inc indicates migration with non-shared
2911 storage with incremental copy (same base image shared between source
2912 and destination). In both cases the disk images have to exist on des‐
2913 tination host, the --copy-storage-... options only tell libvirt to
2914 transfer data from the images on source host to the images found at the
2915 same place on the destination host. By default only non-shared
2916 non-readonly images are transferred. Use --migrate-disks to explicitly
2917 specify a list of disk targets to transfer via the comma separated
2918 disk-list argument. With --copy-storage-synchronous-writes flag used
2919 the disk data migration will synchronously handle guest disk writes to
2920 both the original source and the destination to ensure that the disk
2921 migration converges at the price of possibly decreased burst perfor‐
2922 mance.
2923 --change-protection enforces that no incompatible configuration changes
2925 will be made to the domain while the migration is underway; this flag
2926 is implicitly enabled when supported by the hypervisor, but can be ex‐
2927 plicitly used to reject the migration if the hypervisor lacks change
2928 protection support.
2929 --verbose displays the progress of migration.
2931 --abort-on-error cancels the migration if a soft error (for example I/O
2933 error) happens during the migration.
2934 --postcopy enables post-copy logic in migration, but does not actually
2936 start post-copy, i.e., migration is started in pre-copy mode. Once mi‐
2937 gration is running, the user may switch to post-copy using the mi‐
2938 grate-postcopy command sent from another virsh instance or use --post‐
2939 copy-after-precopy along with --postcopy to let libvirt automatically
2940 switch to post-copy after the first pass of pre-copy is finished. The
2941 maximum bandwidth consumed during the post-copy phase may be limited
2942 using --postcopy-bandwidth. The maximum bandwidth consumed during the
2943 pre-copy phase may be limited using --bandwidth. In case connection be‐
2944 tween the hosts breaks while migration is in post-copy mode, the domain
2945 cannot be resumed on either source or destination host and the migrate
2946 command will report an error leaving the domain active on both hosts.
2947 To recover from such situation repeat the original migrate command with
2948 an additional --postcopy-resume flag.
2949 --auto-converge forces convergence during live migration. The initial
2951 guest CPU throttling rate can be set with auto-converge-initial. If the
2952 initial throttling rate is not enough to ensure convergence, the rate
2953 is periodically increased by auto-converge-increment.
2954 --rdma-pin-all can be used with RDMA migration (i.e., when migrateuri
2956 starts with rdma://) to tell the hypervisor to pin all domain's memory
2957 at once before migration starts rather than letting it pin memory pages
2958 as needed. For QEMU/KVM this requires hard_limit memory tuning element
2959 (in the domain XML) to be used and set to the maximum memory configured
2960 for the domain plus any memory consumed by the QEMU process itself. Be‐
2961 ware of setting the memory limit too high (and thus allowing the domain
2962 to lock most of the host's memory). Doing so may be dangerous to both
2963 the domain and the host itself since the host's kernel may run out of
2964 memory.
2965 --zerocopy requests zero-copy mechanism to be used for migrating memory
2967 pages. For QEMU/KVM this means QEMU will be temporarily allowed to
2968 lock all guest pages in host's memory, although only those that are
2969 queued for transfer will be locked at the same time.
2970 Note: Individual hypervisors usually do not support all possible types
2972 of migration. For example, QEMU does not support direct migration.
2973 In some cases libvirt may refuse to migrate the domain because doing so
2975 may lead to potential problems such as data corruption, and thus the
2976 migration is considered unsafe. For QEMU domain, this may happen if the
2977 domain uses disks without explicitly setting cache mode to "none". Mi‐
2978 grating such domains is unsafe unless the disk images are stored on co‐
2979 herent clustered filesystem, such as GFS2 or GPFS. If you are sure the
2980 migration is safe or you just do not care, use --unsafe to force the
2981 migration.
2982 dname is used for renaming the domain to new name during migration,
2984 which also usually can be omitted. Likewise, --xml file is usually
2985 omitted, but can be used to supply an alternative XML file for use on
2986 the destination to supply a larger set of changes to any host-specific
2987 portions of the domain XML, such as accounting for naming differences
2988 between source and destination in accessing underlying storage. If
2989 --persistent is enabled, --persistent-xml file can be used to supply an
2990 alternative XML file which will be used as the persistent guest defini‐
2991 tion on the destination host.
2992 --timeout seconds tells virsh to run a specified action when live mi‐
2994 gration exceeds that many seconds. It can only be used with --live.
2995 If --timeout-suspend is specified, the domain will be suspended after
2996 the timeout and the migration will complete offline; this is the de‐
2997 fault if no --timeout-\`` option is specified on the command line.
2998 When *--timeout-postcopy is used, virsh will switch migration from
2999 pre-copy to post-copy upon timeout; migration has to be started with
3000 --postcopy option for this to work.
3001 --compressed activates compression, the compression method is chosen
3003 with --comp-methods. Supported methods are "mt", "xbzrle", "zlib", and
3004 "zstd". The supported set of methods and their combinations depend on a
3005 hypervisor and migration options. QEMU only supports "zlib" and "zstd"
3006 methods when --parallel is used and they cannot be used at once. When
3007 no methods are specified, a hypervisor default methods will be used.
3008 QEMU defaults to "xbzrle" as long as --parallel is not used. For
3009 --parallel migrations QEMU does not provide any default compression
3010 method and thus it has to be specified explicitly using --comp-method.
3011 Compression methods can be tuned further. --comp-mt-level sets compres‐
3012 sion level for "mt" method. Values are in range from 0 to 9, where 1 is
3013 maximum speed and 9 is maximum compression. --comp-mt-threads and
3014 --comp-mt-dthreads set the number of compress threads on source and the
3015 number of decompress threads on target respectively.
3016 --comp-xbzrle-cache sets size of page cache in bytes. --comp-zlib-level
3017 sets the compression level when using "zlib" method. Values are in
3018 range from 0 to 9 and defaults to 1, where 0 is no compression, 1 is
3019 maximum speed and 9 is maximum compression. --comp-zstd-level sets the
3020 compression level when using "zstd" method. Values are in range from 0
3021 to 20 and defaults to 1, where 0 is no compression, 1 is maximum speed
3022 and 20 is maximum compression.
3023 Providing --tls causes the migration to use the host configured TLS
3025 setup (see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in or‐
3026 der to perform the migration of the domain. Usage requires proper TLS
3027 setup for both source and target. Normally the TLS certificate from the
3028 destination host must match the host's name for TLS verification to
3029 succeed. When the certificate does not match the destination hostname
3030 and the expected certificate's hostname is known, --tls-destination can
3031 be used to pass the expected hostname when starting the migration.
3032 --parallel option will cause migration data to be sent over multiple
3034 parallel connections. The number of such connections can be set using
3035 --parallel-connections. Parallel connections may help with saturating
3036 the network link between the source and the target and thus speeding up
3037 the migration.
3038 Running migration can be canceled by interrupting virsh (usually using
3040 Ctrl-C) or by domjobabort command sent from another virsh instance.
3041 The desturi and migrateuri parameters can be used to control which des‐
3043 tination the migration uses. desturi is important for managed migra‐
3044 tion, but unused for direct migration; migrateuri is required for di‐
3045 rect migration, but can usually be automatically determined for managed
3046 migration.
3047 Note: The desturi parameter for normal migration and peer2peer migra‐
3049 tion has different semantics:
3050 • normal migration: the desturi is an address of the target host as
3052 seen from the client machine.
3053 • peer2peer migration: the desturi is an address of the target host as
3055 seen from the source machine.
3056 In a special circumstance where you require a complete control of the
3058 connection and/or libvirt does not have network access to the remote
3059 side you can use a UNIX transport in the URI and specify a socket path
3060 in the query, for example with the qemu driver you could use this:
3061 qemu+unix:///system?socket=/path/to/socket
3063 When migrateuri is not specified, libvirt will automatically determine
3065 the hypervisor specific URI. Some hypervisors, including QEMU, have an
3066 optional "migration_host" configuration parameter (useful when the host
3067 has multiple network interfaces). If this is unspecified, libvirt de‐
3068 termines a name by looking up the target host's configured hostname.
3069 There are a few scenarios where specifying migrateuri may help:
3071 • The configured hostname is incorrect, or DNS is broken. If a host
3073 has a hostname which will not resolve to match one of its public IP
3074 addresses, then libvirt will generate an incorrect URI. In this case
3075 migrateuri should be explicitly specified, using an IP address, or a
3076 correct hostname.
3077 • The host has multiple network interfaces. If a host has multiple
3079 network interfaces, it might be desirable for the migration data
3080 stream to be sent over a specific interface for either security or
3081 performance reasons. In this case migrateuri should be explicitly
3082 specified, using an IP address associated with the network to be
3083 used.
3084 • The firewall restricts what ports are available. When libvirt gener‐
3086 ates a migration URI, it will pick a port number using hypervisor
3087 specific rules. Some hypervisors only require a single port to be
3088 open in the firewalls, while others require a whole range of port
3089 numbers. In the latter case migrateuri might be specified to choose
3090 a specific port number outside the default range in order to comply
3091 with local firewall policies.
3092 • The desturi uses UNIX transport method. In this advanced case lib‐
3094 virt should not guess a migrateuri and it should be specified using
3095 UNIX socket path URI:
3096 unix:///path/to/socket
3098 See https://libvirt.org/migration.html#uris for more details on migra‐
3100 tion URIs.
3101 Optional graphicsuri overrides connection parameters used for automati‐
3103 cally reconnecting a graphical clients at the end of migration. If
3104 omitted, libvirt will compute the parameters based on target host IP
3105 address. In case the client does not have a direct access to the net‐
3106 work virtualization hosts are connected to and needs to connect through
3107 a proxy, graphicsuri may be used to specify the address the client
3108 should connect to. The URI is formed as follows:
3109 protocol://hostname[:port]/[?parameters]
3111 where protocol is either "spice" or "vnc" and parameters is a list of
3113 protocol specific parameters separated by '&'. Currently recognized pa‐
3114 rameters are "tlsPort" and "tlsSubject". For example,
3115 spice://target.host.com:1234/?tlsPort=4567
3117 Optional listen-address sets the listen address that hypervisor on the
3119 destination side should bind to for incoming migration. Both IPv4 and
3120 IPv6 addresses are accepted as well as hostnames (the resolving is done
3121 on destination). Some hypervisors do not support specifying the listen
3122 address and will return an error if this parameter is used. This param‐
3123 eter cannot be used if desturi uses UNIX transport method.
3124 Optional disks-port sets the port that hypervisor on destination side
3126 should bind to for incoming disks traffic. Currently it is supported
3127 only by QEMU.
3128 Optional disks-uri can also be specified (mutually exclusive with
3130 disks-port) to specify what the remote hypervisor should bind/connect
3131 to when migrating disks. This can be tcp://address:port to specify a
3132 listen address (which overrides --migrate-uri and --listen-address for
3133 the disk migration) and a port or unix:///path/to/socket in case you
3134 need the disk migration to happen over a UNIX socket with that speci‐
3135 fied path. In this case you need to make sure the same socket path is
3136 accessible to both source and destination hypervisors and connecting to
3137 the socket on the source (after hypervisor creates it on the destina‐
3138 tion) will actually connect to the destination. If you are using
3139 SELinux (at least on the source host) you need to make sure the socket
3140 on the source is accessible to libvirtd/QEMU for connection. Libvirt
3141 cannot change the context of the existing socket because it is differ‐
3142 ent from the file representation of the socket and the context is cho‐
3143 sen by its creator (usually by using setsockcreatecon{,_raw}() func‐
3144 tions).
3145 migrate-compcache
3147 Syntax:
3148 migrate-compcache domain [--size bytes]
3150 Sets and/or gets size of the cache (in bytes) used for compressing re‐
3152 peatedly transferred memory pages during live migration. When called
3153 without size, the command just prints current size of the compression
3154 cache. When size is specified, the hypervisor is asked to change com‐
3155 pression cache to size bytes and then the current size is printed (the
3156 result may differ from the requested size due to rounding done by the
3157 hypervisor). The size option is supposed to be used while the domain is
3158 being live-migrated as a reaction to migration progress and increasing
3159 number of compression cache misses obtained from domjobinfo.
3160 migrate-getmaxdowntime
3162 Syntax:
3163 migrate-getmaxdowntime domain
3165 Get the maximum tolerable downtime for a domain which is being live-mi‐
3167 grated to another host. This is the number of milliseconds the guest
3168 is allowed to be down at the end of live migration.
3169 migrate-getspeed
3171 Syntax:
3172 migrate-getspeed domain [--postcopy]
3174 Get the maximum migration bandwidth (in MiB/s) for a domain. If the
3176 --postcopy option is specified, the command will get the maximum band‐
3177 width allowed during a post-copy migration phase.
3178 migrate-postcopy
3180 Syntax:
3181 migrate-postcopy domain
3183 Switch the current migration from pre-copy to post-copy. This is only
3185 supported for a migration started with --postcopy option.
3186 migrate-setmaxdowntime
3188 Syntax:
3189 migrate-setmaxdowntime domain downtime
3191 Set maximum tolerable downtime for a domain which is being live-mi‐
3193 grated to another host. The downtime is a number of milliseconds the
3194 guest is allowed to be down at the end of live migration.
3195 migrate-setspeed
3197 Syntax:
3198 migrate-setspeed domain bandwidth [--postcopy]
3200 Set the maximum migration bandwidth (in MiB/s) for a domain which is
3202 being migrated to another host. bandwidth is interpreted as an unsigned
3203 long long value. Specifying a negative value results in an essentially
3204 unlimited value being provided to the hypervisor. The hypervisor can
3205 choose whether to reject the value or convert it to the maximum value
3206 allowed. If the --postcopy option is specified, the command will set
3207 the maximum bandwidth allowed during a post-copy migration phase.
3208 numatune
3210 Syntax:
3211 numatune domain [--mode mode] [--nodeset nodeset]
3213 [[--config] [--live] | [--current]]
3214 Set or get a domain's numa parameters, corresponding to the <numatune>
3216 element of domain XML. Without flags, the current settings are dis‐
3217 played.
3218 mode can be one of `strict', `interleave', `preferred' and 'restric‐
3220 tive' or any valid number from the virDomainNumatuneMemMode enum in
3221 case the daemon supports it. For a running domain, the mode can't be
3222 changed, and the nodeset can be changed only if the domain was started
3223 with `restrictive' mode.
3224 nodeset is a list of numa nodes used by the host for running the do‐
3226 main. Its syntax is a comma separated list, with '-' for ranges and
3227 '^' for excluding a node.
3228 If --live is specified, set scheduler information of a running guest.
3230 If --config is specified, affect the next start of a persistent guest.
3231 If --current is specified, it is equivalent to either --live or --con‐
3232 fig, depending on the current state of the guest.
3233 For running guests in Linux hosts, the changes made in the domain's
3235 numa parameters does not imply that the guest memory will be moved to a
3236 different nodeset immediately. The memory migration depends on the
3237 guest activity, and the memory of an idle guest will remain in its pre‐
3238 vious nodeset for longer. The presence of VFIO devices will also lock
3239 parts of the guest memory in the same nodeset used to start the guest,
3240 regardless of nodeset changes.
3241 perf
3243 Syntax:
3244 perf domain [--enable eventSpec] [--disable eventSpec]
3246 [[--config] [--live] | [--current]]
3247 Get the current perf events setting or enable/disable specific perf
3249 events for a guest domain.
3250 Perf is a performance analyzing tool in Linux, and it can instrument
3252 CPU performance counters, tracepoints, kprobes, and uprobes (dynamic
3253 tracing). Perf supports a list of measurable events, and can measure
3254 events coming from different sources. For instance, some event are pure
3255 kernel counters, in this case they are called software events, includ‐
3256 ing context-switches, minor-faults, etc.. Now dozens of events from
3257 different sources can be supported by perf.
3258 Currently only QEMU/KVM supports this command. The --enable and --dis‐
3260 able option combined with eventSpec can be used to enable or disable
3261 specific performance event. eventSpec is a string list of one or more
3262 events separated by commas. Valid event names are as follows:
3263 Valid perf event names
3265 • cmt - A PQos (Platform Qos) feature to monitor the usage of cache by
3267 applications running on the platform.
3268 • mbmt - Provides a way to monitor the total system memory bandwidth
3270 between one level of cache and another.
3271 • mbml - Provides a way to limit the amount of data (bytes/s) send
3273 through the memory controller on the socket.
3274 • cache_misses - Provides the count of cache misses by applications
3276 running on the platform.
3277 • cache_references - Provides the count of cache hits by applications
3279 running on th e platform.
3280 • instructions - Provides the count of instructions executed by appli‐
3282 cations running on the platform.
3283 • cpu_cycles - Provides the count of cpu cycles (total/elapsed). May be
3285 used with instructions in order to get a cycles per instruction.
3286 • branch_instructions - Provides the count of branch instructions exe‐
3288 cuted by applications running on the platform.
3289 • branch_misses - Provides the count of branch misses executed by ap‐
3291 plications running on the platform.
3292 • bus_cycles - Provides the count of bus cycles executed by applica‐
3294 tions running on the platform.
3295 • stalled_cycles_frontend - Provides the count of stalled cpu cycles in
3297 the frontend of the instruction processor pipeline by applications
3298 running on the platform.
3299 • stalled_cycles_backend - Provides the count of stalled cpu cycles in
3301 the backend of the instruction processor pipeline by applications
3302 running on the platform.
3303 • ref_cpu_cycles - Provides the count of total cpu cycles not affected
3305 by CPU frequency scaling by applications running on the platform.
3306 • cpu_clock - Provides the cpu clock time consumed by applications run‐
3308 ning on the platform.
3309 • task_clock - Provides the task clock time consumed by applications
3311 running on the platform.
3312 • page_faults - Provides the count of page faults by applications run‐
3314 ning on the platform.
3315 • context_switches - Provides the count of context switches by applica‐
3317 tions running on the platform.
3318 • cpu_migrations - Provides the count cpu migrations by applications
3320 running on the platform.
3321 • page_faults_min - Provides the count minor page faults by applica‐
3323 tions running on the platform.
3324 • page_faults_maj - Provides the count major page faults by applica‐
3326 tions running on the platform.
3327 • alignment_faults - Provides the count alignment faults by applica‐
3329 tions running on the platform.
3330 • emulation_faults - Provides the count emulation faults by applica‐
3332 tions running on the platform.
3333 Note: The statistics can be retrieved using the domstats command using
3335 the --perf flag.
3336 If --live is specified, affect a running guest. If --config is speci‐
3338 fied, affect the next start of a persistent guest. If --current is
3339 specified, it is equivalent to either --live or --config, depending on
3340 the current state of the guest. Both --live and --config flags may be
3341 given, but --current is exclusive. If no flag is specified, behavior is
3342 different depending on hypervisor.
3343 reboot
3345 Syntax:
3346 reboot domain [--mode MODE-LIST]
3348 Reboot a domain. This acts just as if the domain had the reboot com‐
3350 mand run from the console. The command returns as soon as it has exe‐
3351 cuted the reboot action, which may be significantly before the domain
3352 actually reboots.
3353 The exact behavior of a domain when it reboots is set by the on_reboot
3355 parameter in the domain's XML definition.
3356 By default the hypervisor will try to pick a suitable shutdown method.
3358 To specify an alternative method, the --mode parameter can specify a
3359 comma separated list which includes acpi, agent, initctl, signal and
3360 paravirt. The order in which drivers will try each mode is undefined,
3361 and not related to the order specified to virsh. For strict control
3362 over ordering, use a single mode at a time and repeat the command.
3363 reset
3365 Syntax:
3366 reset domain
3368 Reset a domain immediately without any guest shutdown. reset emulates
3370 the power reset button on a machine, where all guest hardware sees the
3371 RST line set and reinitializes internal state.
3372 Note: Reset without any guest OS shutdown risks data loss.
3374 restore
3376 Syntax:
3377 restore state-file [--bypass-cache] [--xml file]
3379 [{--running | --paused}] [--reset-nvram]
3380 Restores a domain from a virsh save state file. See save for more info.
3382 If --bypass-cache is specified, the restore will avoid the file system
3384 cache, although this may slow down the operation.
3385 --xml file is usually omitted, but can be used to supply an alternative
3387 XML file for use on the restored guest with changes only in the
3388 host-specific portions of the domain XML. For example, it can be used
3389 to account for file naming differences in underlying storage due to
3390 disk snapshots taken after the guest was saved.
3391 Normally, restoring a saved image will use the state recorded in the
3393 save image to decide between running or paused; passing either the
3394 --running or --paused flag will allow overriding which state the domain
3395 should be started in.
3396 If --reset-nvram is specified, any existing NVRAM file will be deleted
3398 and re-initialized from its pristine template.
3399 Note: To avoid corrupting file system contents within the domain, you
3401 should not reuse the saved state file for a second restore unless you
3402 have also reverted all storage volumes back to the same contents as
3403 when the state file was created.
3404 resume
3406 Syntax:
3407 resume domain
3409 Moves a domain out of the suspended state. This will allow a previ‐
3411 ously suspended domain to now be eligible for scheduling by the under‐
3412 lying hypervisor.
3413 save
3415 Syntax:
3416 save domain state-file [--bypass-cache] [--xml file]
3418 [{--running | --paused}] [--verbose]
3419 Saves a running domain (RAM, but not disk state) to a state file so
3421 that it can be restored later. Once saved, the domain will no longer
3422 be running on the system, thus the memory allocated for the domain will
3423 be free for other domains to use. virsh restore restores from this
3424 state file. If --bypass-cache is specified, the save will avoid the
3425 file system cache, although this may slow down the operation.
3426 The progress may be monitored using domjobinfo virsh command and can‐
3428 celed with domjobabort command (sent by another virsh instance). An‐
3429 other option is to send SIGINT (usually with Ctrl-C) to the virsh
3430 process running save command. --verbose displays the progress of save.
3431 This is roughly equivalent to doing a hibernate on a running computer,
3433 with all the same limitations. Open network connections may be severed
3434 upon restore, as TCP timeouts may have expired.
3435 --xml file is usually omitted, but can be used to supply an alternative
3437 XML file for use on the restored guest with changes only in the
3438 host-specific portions of the domain XML. For example, it can be used
3439 to account for file naming differences that are planned to be made via
3440 disk snapshots of underlying storage after the guest is saved.
3441 Normally, restoring a saved image will decide between running or paused
3443 based on the state the domain was in when the save was done; passing
3444 either the --running or --paused flag will allow overriding which state
3445 the restore should use.
3446 Domain saved state files assume that disk images will be unchanged be‐
3448 tween the creation and restore point. For a more complete system re‐
3449 store point, where the disk state is saved alongside the memory state,
3450 see the snapshot family of commands.
3451 save-image-define
3453 Syntax:
3454 save-image-define file xml [{--running | --paused}]
3456 Update the domain XML that will be used when file is later used in the
3458 restore command. The xml argument must be a file name containing the
3459 alternative XML, with changes only in the host-specific portions of the
3460 domain XML. For example, it can be used to account for file naming
3461 differences resulting from creating disk snapshots of underlying stor‐
3462 age after the guest was saved.
3463 The save image records whether the domain should be restored to a run‐
3465 ning or paused state. Normally, this command does not alter the
3466 recorded state; passing either the --running or --paused flag will al‐
3467 low overriding which state the restore should use.
3468 save-image-dumpxml
3470 Syntax:
3471 save-image-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap] file
3473 Extract the domain XML that was in effect at the time the saved state
3475 file file was created with the save command. Using --security-info
3476 will also include security sensitive information.
3477 If the --xpath argument provides an XPath expression, it will be evalu‐
3479 ated against the output XML and only those matching nodes will be
3480 printed. The default behaviour is to print each matching node as a
3481 standalone document, however, for ease of additional processing, the
3482 --wrap argument will cause the matching node to be wrapped in a common
3483 root node.
3484 save-image-edit
3486 Syntax:
3487 save-image-edit file [{--running | --paused}]
3489 Edit the XML configuration associated with a saved state file file cre‐
3491 ated by the save command.
3492 The save image records whether the domain should be restored to a run‐
3494 ning or paused state. Normally, this command does not alter the
3495 recorded state; passing either the --running or --paused flag will al‐
3496 low overriding which state the restore should use.
3497 This is equivalent to:
3499 virsh save-image-dumpxml state-file > state-file.xml
3501 vi state-file.xml (or make changes with your other text editor)
3502 virsh save-image-define state-file state-file-xml
3503 except that it does some error checking.
3505 The editor used can be supplied by the $VISUAL or $EDITOR environment
3507 variables, and defaults to vi.
3508 schedinfo
3510 Syntax:
3511 schedinfo domain [[--config] [--live] | [--current]] [[--set] parameter=value]...
3513 schedinfo [--weight number] [--cap number] domain
3514 Allows you to show (and set) the domain scheduler parameters. The pa‐
3516 rameters available for each hypervisor are:
3517 LXC (posix scheduler) : cpu_shares, vcpu_period, vcpu_quota
3519 QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota, emula‐
3521 tor_period, emulator_quota, global_period, global_quota, iothread_pe‐
3522 riod, iothread_quota
3523 Xen (credit scheduler): weight, cap
3525 ESX (allocation scheduler): reservation, limit, shares
3527 If --live is specified, set scheduler information of a running guest.
3529 If --config is specified, affect the next start of a persistent guest.
3530 If --current is specified, it is equivalent to either --live or --con‐
3531 fig, depending on the current state of the guest.
3532 Note: The cpu_shares parameter has a valid value range of 2-262144 with
3534 cgroups v1, 1-10000 with cgroups v2.
3535 Note: The weight and cap parameters are defined only for the XEN_CREDIT
3537 scheduler.
3538 Note: The vcpu_period, emulator_period, and iothread_period parameters
3540 have a valid value range of 1000-1000000 or 0, and the vcpu_quota, emu‐
3541 lator_quota, and iothread_quota parameters have a valid value range of
3542 1000-17592186044415 or less than 0. The value 0 for either parameter is
3543 the same as not specifying that parameter.
3544 screenshot
3546 Syntax:
3547 screenshot domain [imagefilepath] [--screen screenID]
3549 Takes a screenshot of a current domain console and stores it into a
3551 file. Optionally, if the hypervisor supports more displays for a do‐
3552 main, screenID allows specifying which screen will be captured. It is
3553 the sequential number of screen. In case of multiple graphics cards,
3554 heads are enumerated before devices, e.g. having two graphics cards,
3555 both with four heads, screen ID 5 addresses the second head on the sec‐
3556 ond card.
3557 send-key
3559 Syntax:
3560 send-key domain [--codeset codeset] [--holdtime holdtime] keycode...
3562 Parse the keycode sequence as keystrokes to send to domain. Each key‐
3564 code can either be a numeric value or a symbolic name from the corre‐
3565 sponding codeset. If --holdtime is given, each keystroke will be held
3566 for that many milliseconds. The default codeset is linux, but use of
3567 the --codeset option allows other codesets to be chosen.
3568 If multiple keycodes are specified, they are all sent simultaneously to
3570 the guest, and they may be received in random order. If you need dis‐
3571 tinct keypresses, you must use multiple send-key invocations.
3572 • linux
3574 The numeric values are those defined by the Linux generic input event
3576 subsystem. The symbolic names match the corresponding Linux key con‐
3577 stant macro names.
3578 See virkeycode-linux(7) and virkeyname-linux(7)
3580 • xt
3582 The numeric values are those defined by the original XT keyboard con‐
3584 troller. No symbolic names are provided
3585 See virkeycode-xt(7)
3587 • atset1
3589 The numeric values are those defined by the AT keyboard controller,
3591 set 1 (aka XT compatible set). Extended keycoes from atset1 may dif‐
3592 fer from extended keycodes in the xt codeset. No symbolic names are
3593 provided
3594 See virkeycode-atset1(7)
3596 • atset2
3598 The numeric values are those defined by the AT keyboard controller,
3600 set 2. No symbolic names are provided
3601 See virkeycode-atset2(7)
3603 • atset3
3605 The numeric values are those defined by the AT keyboard controller,
3607 set 3 (aka PS/2 compatible set). No symbolic names are provided
3608 See virkeycode-atset3(7)
3610 • os_x
3612 The numeric values are those defined by the macOS keyboard input sub‐
3614 system. The symbolic names match the corresponding macOS key constant
3615 macro names
3616 See virkeycode-osx(7) and virkeyname-osx(7)
3618 • xt_kbd
3620 The numeric values are those defined by the Linux KBD device. These
3622 are a variant on the original XT codeset, but often with different
3623 encoding for extended keycodes. No symbolic names are provided.
3624 See virkeycode-xtkbd(7)
3626 • win32
3628 The numeric values are those defined by the Win32 keyboard input sub‐
3630 system. The symbolic names match the corresponding Win32 key constant
3631 macro names
3632 See virkeycode-win32(7) and virkeyname-win32(7)
3634 • usb
3636 The numeric values are those defined by the USB HID specification for
3638 keyboard input. No symbolic names are provided
3639 See virkeycode-usb(7)
3641 • qnum
3643 The numeric values are those defined by the QNUM extension for send‐
3645 ing raw keycodes. These are a variant on the XT codeset, but extended
3646 keycodes have the low bit of the second byte set, instead of the high
3647 bit of the first byte. No symbolic names are provided.
3648 See virkeycode-qnum(7)
3650 Examples:
3652 # send three strokes 'k', 'e', 'y', using xt codeset. these
3654 # are all pressed simultaneously and may be received by the guest
3655 # in random order
3656 virsh send-key dom --codeset xt 37 18 21
3657 # send one stroke 'right-ctrl+C'
3659 virsh send-key dom KEY_RIGHTCTRL KEY_C
3660 # send a tab, held for 1 second
3662 virsh send-key --holdtime 1000 0xf
3663 send-process-signal
3665 Syntax:
3666 send-process-signal domain-id pid signame
3668 Send a signal signame to the process identified by pid running in the
3670 virtual domain domain-id. The pid is a process ID in the virtual domain
3671 namespace.
3672 The signame argument may be either an integer signal constant number,
3674 or one of the symbolic names:
3675 "nop", "hup", "int", "quit", "ill",
3677 "trap", "abrt", "bus", "fpe", "kill",
3678 "usr1", "segv", "usr2", "pipe", "alrm",
3679 "term", "stkflt", "chld", "cont", "stop",
3680 "tstp", "ttin", "ttou", "urg", "xcpu",
3681 "xfsz", "vtalrm", "prof", "winch", "poll",
3682 "pwr", "sys", "rt0", "rt1", "rt2", "rt3",
3683 "rt4", "rt5", "rt6", "rt7", "rt8", "rt9",
3684 "rt10", "rt11", "rt12", "rt13", "rt14", "rt15",
3685 "rt16", "rt17", "rt18", "rt19", "rt20", "rt21",
3686 "rt22", "rt23", "rt24", "rt25", "rt26", "rt27",
3687 "rt28", "rt29", "rt30", "rt31", "rt32"
3688 The symbol name may optionally be prefixed with sig or sig_ and may be
3690 in uppercase or lowercase.
3691 Examples:
3693 virsh send-process-signal myguest 1 15
3695 virsh send-process-signal myguest 1 term
3696 virsh send-process-signal myguest 1 sigterm
3697 virsh send-process-signal myguest 1 SIG_HUP
3698 set-lifecycle-action
3700 Syntax:
3701 set-lifecycle-action domain type action
3703 [[--config] [--live] | [--current]]
3704 Set the lifecycle action for specified lifecycle type. The valid types
3706 are "poweroff", "reboot" and "crash", and for each of them valid action
3707 is one of "destroy", "restart", "rename-restart", "preserve". For type
3708 "crash", additional actions "coredump-destroy" and "coredump-restart"
3709 are supported.
3710 set-user-password
3712 Syntax:
3713 set-user-password domain user password [--encrypted]
3715 Set the password for the user account in the guest domain.
3717 If --encrypted is specified, the password is assumed to be already en‐
3719 crypted by the method required by the guest OS.
3720 For QEMU/KVM, this requires the guest agent to be configured and run‐
3722 ning.
3723 set-user-sshkeys
3725 Syntax:
3726 set-user-sshkeys domain user [--file FILE] [{--reset | --remove}]
3728 Append keys read from FILE into user's SSH authorized keys file in the
3730 guest domain. In the FILE keys must be on separate lines and each line
3731 must follow authorized keys format as defined by sshd(8).
3732 If --reset is specified, then the guest authorized keys file content is
3734 removed before appending new keys. As a special case, if --reset is
3735 provided and no FILE was provided then no new keys are added and the
3736 authorized keys file is cleared out.
3737 If --remove is specified, then instead of adding any new keys then keys
3739 read from FILE are removed from the authorized keys file. It is not
3740 considered an error if the key does not exist in the file.
3741 setmaxmem
3743 Syntax:
3744 setmaxmem domain size [[--config] [--live] | [--current]]
3746 Change the maximum memory allocation limit for a guest domain. If
3748 --live is specified, affect a running guest. If --config is specified,
3749 affect the next start of a persistent guest. If --current is speci‐
3750 fied, it is equivalent to either --live or --config, depending on the
3751 current state of the guest. Both --live and --config flags may be
3752 given, but --current is exclusive. If no flag is specified, behavior is
3753 different depending on hypervisor.
3754 Some hypervisors such as QEMU/KVM don't support live changes (espe‐
3756 cially increasing) of the maximum memory limit. Even persistent con‐
3757 figuration changes might not be performed with some hypervisors/config‐
3758 uration (e.g. on NUMA enabled domains on QEMU). For complex configura‐
3759 tion changes use command edit instead).
3760 size is a scaled integer (see NOTES above); it defaults to kibibytes
3762 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3763 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3764 rounds up to the nearest kibibyte. Some hypervisors require a larger
3765 granularity than KiB, and requests that are not an even multiple will
3766 be rounded up. For example, vSphere/ESX rounds the parameter up to
3767 mebibytes (1024 kibibytes).
3768 setmem
3770 Syntax:
3771 setmem domain size [[--config] [--live] | [--current]]
3773 Change the memory allocation for a guest domain. If --live is speci‐
3775 fied, perform a memory balloon of a running guest. If --config is
3776 specified, affect the next start of a persistent guest. If --current
3777 is specified, it is equivalent to either --live or --config, depending
3778 on the current state of the guest. Both --live and --config flags may
3779 be given, but --current is exclusive. If no flag is specified, behavior
3780 is different depending on hypervisor.
3781 size is a scaled integer (see NOTES above); it defaults to kibibytes
3783 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3784 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3785 rounds up to the nearest kibibyte. Some hypervisors require a larger
3786 granularity than KiB, and requests that are not an even multiple will
3787 be rounded up. For example, vSphere/ESX rounds the parameter up to
3788 mebibytes (1024 kibibytes).
3789 For Xen, you can only adjust the memory of a running domain if the do‐
3791 main is paravirtualized or running the PV balloon driver.
3792 For LXC, the value being set is the cgroups value for limit_in_bytes or
3794 the maximum amount of user memory (including file cache). When viewing
3795 memory inside the container, this is the /proc/meminfo "MemTotal"
3796 value. When viewing the value from the host, use the virsh memtune com‐
3797 mand. In order to view the current memory in use and the maximum value
3798 allowed to set memory, use the virsh dominfo command.
3799 setvcpus
3801 Syntax:
3802 setvcpus domain count [--maximum] [[--config] [--live] | [--current]] [--guest] [--hotpluggable]
3804 Change the number of virtual CPUs active in a guest domain. By de‐
3806 fault, this command works on active guest domains. To change the set‐
3807 tings for an inactive guest domain, use the --config flag.
3808 The count value may be limited by host, hypervisor, or a limit coming
3810 from the original description of the guest domain. For Xen, you can
3811 only adjust the virtual CPUs of a running domain if the domain is par‐
3812 avirtualized.
3813 If the --config flag is specified, the change is made to the stored XML
3815 configuration for the guest domain, and will only take effect when the
3816 guest domain is next started.
3817 If --live is specified, the guest domain must be active, and the change
3819 takes place immediately. Both the --config and --live flags may be
3820 specified together if supported by the hypervisor. If this command is
3821 run before the guest has finished booting, the guest may fail to
3822 process the change.
3823 If --current is specified, it is equivalent to either --live or --con‐
3825 fig, depending on the current state of the guest.
3826 When no flags are given, the --live flag is assumed and the guest do‐
3828 main must be active. In this situation it is up to the hypervisor
3829 whether the --config flag is also assumed, and therefore whether the
3830 XML configuration is adjusted to make the change persistent.
3831 If --guest is specified, then the count of cpus is modified in the
3833 guest instead of the hypervisor. This flag is usable only for live do‐
3834 mains and may require guest agent to be configured in the guest.
3835 To allow adding vcpus to persistent definitions that can be later ho‐
3837 tunplugged after the domain is booted it is necessary to specify the
3838 --hotpluggable flag. Vcpus added to live domains supporting vcpu unplug
3839 are automatically marked as hotpluggable.
3840 The --maximum flag controls the maximum number of virtual cpus that can
3842 be hot-plugged the next time the domain is booted. As such, it must
3843 only be used with the --config flag, and not with the --live or the
3844 --current flag. Note that it may not be possible to change the maximum
3845 vcpu count if the processor topology is specified for the guest.
3846 setvcpu
3848 Syntax:
3849 setvcpu domain vcpulist [--enable] | [--disable]
3851 [[--live] [--config] | [--current]]
3852 Change state of individual vCPUs using hot(un)plug mechanism.
3854 See vcpupin for information on format of vcpulist. Hypervisor drivers
3856 may require that vcpulist contains exactly vCPUs belonging to one hot‐
3857 pluggable entity. This is usually just a single vCPU but certain archi‐
3858 tectures such as ppc64 require a full core to be specified at once.
3859 Note that hypervisors may refuse to disable certain vcpus such as vcpu
3861 0 or others.
3862 If --live is specified, affect a running domain. If --config is speci‐
3864 fied, affect the next startup of a persistent guest. If --current is
3865 specified, it is equivalent to either --live or --config, depending on
3866 the current state of the guest. This is the default. Both --live and
3867 --config flags may be given, but --current is exclusive.
3868 shutdown
3870 Syntax:
3871 shutdown domain [--mode MODE-LIST]
3873 Gracefully shuts down a domain. This coordinates with the domain OS to
3875 perform graceful shutdown, so there is no guarantee that it will suc‐
3876 ceed, and may take a variable length of time depending on what services
3877 must be shutdown in the domain.
3878 The exact behavior of a domain when it shuts down is set by the
3880 on_poweroff parameter in the domain's XML definition.
3881 If domain is transient, then the metadata of any snapshots and check‐
3883 points will be lost once the guest stops running, but the underlying
3884 contents still exist, and a new domain with the same name and UUID can
3885 restore the snapshot metadata with snapshot-create, and the checkpoint
3886 metadata with checkpoint-create.
3887 By default the hypervisor will try to pick a suitable shutdown method.
3889 To specify an alternative method, the --mode parameter can specify a
3890 comma separated list which includes acpi, agent, initctl, signal and
3891 paravirt. The order in which drivers will try each mode is undefined,
3892 and not related to the order specified to virsh. For strict control
3893 over ordering, use a single mode at a time and repeat the command.
3894 start
3896 Syntax:
3897 start domain-name-or-uuid [--console] [--paused]
3899 [--autodestroy] [--bypass-cache] [--force-boot]
3900 [--pass-fds N,M,...] [--reset-nvram]
3901 Start a (previously defined) inactive domain, either from the last man‐
3903 agedsave state, or via a fresh boot if no managedsave state is present.
3904 The domain will be paused if the --paused option is used and supported
3905 by the driver; otherwise it will be running. If --console is re‐
3906 quested, attach to the console after creation. If --autodestroy is re‐
3907 quested, then the guest will be automatically destroyed when virsh
3908 closes its connection to libvirt, or otherwise exits. If --by‐
3909 pass-cache is specified, and managedsave state exists, the restore will
3910 avoid the file system cache, although this may slow down the operation.
3911 If --force-boot is specified, then any managedsave state is discarded
3912 and a fresh boot occurs.
3913 If --pass-fds is specified, the argument is a comma separated list of
3915 open file descriptors which should be pass on into the guest. The file
3916 descriptors will be re-numbered in the guest, starting from 3. This is
3917 only supported with container based virtualization.
3918 If --reset-nvram is specified, any existing NVRAM file will be deleted
3920 and re-initialized from its pristine template.
3921 suspend
3923 Syntax:
3924 suspend domain
3926 Suspend a running domain. It is kept in memory but won't be scheduled
3928 anymore.
3929 ttyconsole
3931 Syntax:
3932 ttyconsole domain
3934 Output the device used for the TTY console of the domain. If the infor‐
3936 mation is not available the processes will provide an exit code of 1.
3937 undefine
3939 Syntax:
3940 undefine domain [--managed-save] [--snapshots-metadata]
3942 [--checkpoints-metadata] [--nvram] [--keep-nvram]
3943 [ {--storage volumes | --remove-all-storage
3944 [--delete-storage-volume-snapshots]} --wipe-storage]
3945 [--tpm] [--keep-tpm]
3946 Undefine a domain. If the domain is running, this converts it to a
3948 transient domain, without stopping it. If the domain is inactive, the
3949 domain configuration is removed.
3950 The --managed-save flag guarantees that any managed save image (see the
3952 managedsave command) is also cleaned up. Without the flag, attempts to
3953 undefine a domain with a managed save image will fail.
3954 The --snapshots-metadata flag guarantees that any snapshots (see the
3956 snapshot-list command) are also cleaned up when undefining an inactive
3957 domain. Without the flag, attempts to undefine an inactive domain with
3958 snapshot metadata will fail. If the domain is active, this flag is ig‐
3959 nored.
3960 The --checkpoints-metadata flag guarantees that any checkpoints (see
3962 the checkpoint-list command) are also cleaned up when undefining an in‐
3963 active domain. Without the flag, attempts to undefine an inactive do‐
3964 main with checkpoint metadata will fail. If the domain is active, this
3965 flag is ignored.
3966 --nvram and --keep-nvram specify accordingly to delete or keep nvram
3968 (/domain/os/nvram/) file. If the domain has an nvram file and the flags
3969 are omitted, the undefine will fail.
3970 The --storage flag takes a parameter volumes, which is a comma sepa‐
3972 rated list of volume target names or source paths of storage volumes to
3973 be removed along with the undefined domain. Volumes can be undefined
3974 and thus removed only on inactive domains. Volume deletion is only at‐
3975 tempted after the domain is undefined; if not all of the requested vol‐
3976 umes could be deleted, the error message indicates what still remains
3977 behind. If a volume path is not found in the domain definition, it's
3978 treated as if the volume was successfully deleted. Only volumes managed
3979 by libvirt in storage pools can be removed this way. (See domblklist
3980 for list of target names associated to a domain). Example: --storage
3981 vda,/path/to/storage.img
3982 The --remove-all-storage flag specifies that all of the domain's stor‐
3984 age volumes should be deleted.
3985 The --delete-storage-volume-snapshots (previously --delete-snapshots)
3987 flag specifies that any snapshots associated with the storage volume
3988 should be deleted as well. Requires the --remove-all-storage flag to be
3989 provided. Not all storage drivers support this option, presently only
3990 rbd. Using this when also removing volumes handled by a storage driver
3991 which does not support the flag will result in failure.
3992 The flag --wipe-storage specifies that the storage volumes should be
3994 wiped before removal.
3995 --tpm and --keep-tpm specify accordingly to delete or keep a TPM's per‐
3997 sistent state directory structure and files. If the flags are omitted
3998 then the persistent_state attribute in the TPM emulator definition in
3999 the domain XML determines whether the TPM state is kept.
4000 NOTE: For an inactive domain, the domain name or UUID must be used as
4002 the domain.
4003 vcpucount
4005 Syntax:
4006 vcpucount domain [{--maximum | --active}
4008 {--config | --live | --current}] [--guest]
4009 Print information about the virtual cpu counts of the given domain. If
4011 no flags are specified, all possible counts are listed in a table; oth‐
4012 erwise, the output is limited to just the numeric value requested. For
4013 historical reasons, the table lists the label "current" on the rows
4014 that can be queried in isolation via the --active flag, rather than re‐
4015 lating to the --current flag.
4016 --maximum requests information on the maximum cap of vcpus that a do‐
4018 main can add via setvcpus, while --active shows the current usage;
4019 these two flags cannot both be specified. --config requires a persis‐
4020 tent guest and requests information regarding the next time the domain
4021 will be booted, --live requires a running domain and lists current val‐
4022 ues, and --current queries according to the current state of the domain
4023 (corresponding to --live if running, or --config if inactive); these
4024 three flags are mutually exclusive.
4025 If --guest is specified, then the count of cpus is reported from the
4027 perspective of the guest. This flag is usable only for live domains and
4028 may require guest agent to be configured in the guest.
4029 vcpuinfo
4031 Syntax:
4032 vcpuinfo domain [--pretty]
4034 Returns basic information about the domain virtual CPUs, like the num‐
4036 ber of vCPUs, the running time, the affinity to physical processors.
4037 With --pretty, cpu affinities are shown as ranges.
4039 Example:
4041 $ virsh vcpuinfo fedora
4043 VCPU: 0
4044 CPU: 0
4045 State: running
4046 CPU time: 7,0s
4047 CPU Affinity: yyyy
4048 VCPU: 1
4050 CPU: 1
4051 State: running
4052 CPU time: 0,7s
4053 CPU Affinity: yyyy
4054 STATES
4056 The State field displays the current operating state of a virtual CPU
4058 • offline
4060 The virtual CPU is offline and not usable by the domain. This state
4062 is not supported by all hypervisors.
4063 • running
4065 The virtual CPU is available to the domain and is operating.
4067 • blocked
4069 The virtual CPU is available to the domain but is waiting for a re‐
4071 source. This state is not supported by all hypervisors, in which
4072 case running may be reported instead.
4073 • no state
4075 The virtual CPU state could not be determined. This could happen if
4077 the hypervisor is newer than virsh.
4078 • N/A
4080 There's no information about the virtual CPU state available. This
4082 can be the case if the domain is not running or the hypervisor does
4083 not report the virtual CPU state.
4084 vcpupin
4086 Syntax:
4087 vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]]
4089 Query or change the pinning of domain VCPUs to host physical CPUs. To
4091 pin a single vcpu, specify cpulist; otherwise, you can query one vcpu
4092 or omit vcpu to list all at once.
4093 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
4095 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
4096 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
4097 clusive. For pinning the vcpu to all physical cpus specify 'r' as a
4098 cpulist. If --live is specified, affect a running guest. If --config
4099 is specified, affect the next start of a persistent guest. If --cur‐
4100 rent is specified, it is equivalent to either --live or --config, de‐
4101 pending on the current state of the guest. Both --live and --config
4102 flags may be given if cpulist is present, but --current is exclusive.
4103 If no flag is specified, behavior is different depending on hypervisor.
4104 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
4106 cal to "9-14,0-7,15" but not identical to "^8,0-15".
4107 vncdisplay
4109 Syntax:
4110 vncdisplay domain
4112 Output the IP address and port number for the VNC display. If the in‐
4114 formation is not available the processes will provide an exit code of
4115 1.
4116
4118 The following commands manipulate devices associated to domains. The
4119 domain can be specified as a short integer, a name or a full UUID. To
4120 better understand the values allowed as options for the command reading
4121 the documentation at https://libvirt.org/formatdomain.html on the for‐
4122 mat of the device sections to get the most accurate set of accepted
4123 values.
4124 attach-device
4126 Syntax:
4127 attach-device domain FILE [[[--live] [--config] | [--current]] | [--persistent]]
4129 Attach a device to the domain, using a device definition in an XML file
4131 using a device definition element such as <disk> or <interface> as the
4132 top-level element. See the documentation at
4133 https://libvirt.org/formatdomain.html#elementsDevices to learn about
4134 libvirt XML format for a device. If --config is specified the command
4135 alters the persistent guest configuration with the device attach taking
4136 effect the next time libvirt starts the domain. For cdrom and floppy
4137 devices, this command only replaces the media within an existing de‐
4138 vice; consider using update-device for this usage. For passthrough
4139 host devices, see also nodedev-detach, needed if the PCI device does
4140 not use managed mode.
4141 If --live is specified, affect a running domain. If --config is speci‐
4143 fied, affect the next startup of a persistent guest. If --current is
4144 specified, it is equivalent to either --live or --config, depending on
4145 the current state of the guest. Both --live and --config flags may be
4146 given, but --current is exclusive. When no flag is specified legacy API
4147 is used whose behavior depends on the hypervisor driver.
4148 For compatibility purposes, --persistent behaves like --config for an
4150 offline domain, and like --live --config for a running domain.
4151 Note: using of partial device definition XML files may lead to unex‐
4153 pected results as some fields may be autogenerated and thus match de‐
4154 vices other than expected.
4155 attach-disk
4157 Syntax:
4158 attach-disk domain source target [[[--live] [--config] |
4160 [--current]] | [--persistent]] [--targetbus bus]
4161 [--driver driver] [--subdriver subdriver] [--iothread iothread]
4162 [--cache cache] [--io io] [--type type] [--alias alias]
4163 [--mode mode] [--sourcetype sourcetype]
4164 [--source-protocol protocol] [--source-host-name hostname:port]
4165 [--source-host-transport transport] [--source-host-socket socket]
4166 [--serial serial] [--wwn wwn] [--rawio] [--address address]
4167 [--multifunction] [--print-xml]
4168 Attach a new disk device to the domain. source is path for the files
4170 and devices unless --source-protocol is specified, in which case source
4171 is the name of a network disk. target controls the bus or device under
4172 which the disk is exposed to the guest OS. It indicates the "logical"
4173 device name; the optional targetbus attribute specifies the type of
4174 disk device to emulate; possible values are driver specific, with typi‐
4175 cal values being ide, scsi, virtio, xen, usb, sata, or sd, if omitted,
4176 the bus type is inferred from the style of the device name (e.g. a de‐
4177 vice named 'sda' will typically be exported using a SCSI bus). driver
4178 can be file, tap or phy for the Xen hypervisor depending on the kind of
4179 access; or qemu for the QEMU emulator. Further details to the driver
4180 can be passed using subdriver. For Xen subdriver can be aio, while for
4181 QEMU subdriver should match the format of the disk source, such as raw
4182 or qcow2. Hypervisor default will be used if subdriver is not speci‐
4183 fied. However, the default may not be correct, esp. for QEMU as for
4184 security reasons it is configured not to detect disk formats. type can
4185 indicate lun, cdrom or floppy as alternative to the disk default, al‐
4186 though this use only replaces the media within the existing virtual
4187 cdrom or floppy device; consider using update-device for this usage in‐
4188 stead. alias can set user supplied alias. mode can specify the two
4189 specific mode readonly or shareable. sourcetype can indicate the type
4190 of source (block|file|network) cache can be one of "default", "none",
4191 "writethrough", "writeback", "directsync" or "unsafe". io controls
4192 specific policies on I/O; QEMU guests support "threads", "native" and
4193 "io_uring". iothread is the number within the range of domain IO‐
4194 Threads to which this disk may be attached (QEMU only). serial is the
4195 serial of disk device. wwn is the wwn of disk device. rawio indicates
4196 the disk needs rawio capability. address is the address of disk device
4197 in the form of pci:domain.bus.slot.function, scsi:controller.bus.unit,
4198 ide:controller.bus.unit, usb:bus.port, sata:controller.bus.unit or
4199 ccw:cssid.ssid.devno. Virtio-ccw devices must have their cssid set to
4200 0xfe. multifunction indicates specified pci address is a multifunction
4201 pci device address.
4202 There is also support for using a network disk. As specified, the user
4204 can provide a --source-protocol in which case the source parameter will
4205 be interpreted as the source name. --source-protocol must be provided
4206 if the user intends to provide a network disk or host information.
4207 Host information can be provided using the tags --source-host-name,
4208 --source-host-transport, and --source-host-socket, which respectively
4209 denote the name of the host, the host's transport method, and the
4210 socket that the host uses. --source-host-socket and --source-host-name
4211 cannot both be provided, and the user must provide a
4212 --source-host-transport if they want to provide a --source-host-socket.
4213 The --source-host-name parameter supports host:port syntax if the user
4214 wants to provide a port as well.
4215 If --print-xml is specified, then the XML of the disk that would be at‐
4217 tached is printed instead.
4218 If --live is specified, affect a running domain. If --config is speci‐
4220 fied, affect the next startup of a persistent guest. If --current is
4221 specified, it is equivalent to either --live or --config, depending on
4222 the current state of the guest. Both --live and --config flags may be
4223 given, but --current is exclusive. When no flag is specified legacy API
4224 is used whose behavior depends on the hypervisor driver.
4225 For compatibility purposes, --persistent behaves like --config for an
4227 offline domain, and like --live --config for a running domain. Like‐
4228 wise, --shareable is an alias for --mode shareable.
4229 attach-interface
4231 Syntax:
4232 attach-interface domain type source [[[--live]
4234 [--config] | [--current]] | [--persistent]]
4235 [--target target] [--mac mac] [--script script] [--model model]
4236 [--inbound average,peak,burst,floor] [--outbound average,peak,burst]
4237 [--alias alias] [--managed] [--print-xml]
4238 [--source-mode mode]
4239 Attach a new network interface to the domain.
4241 type can be one of the:
4243 network to indicate connection via a libvirt virtual network,
4245 bridge to indicate connection via a bridge device on the host,
4247 direct to indicate connection directly to one of the host's network in‐
4249 terfaces or bridges,
4250 hostdev to indicate connection using a passthrough of PCI device on the
4252 host,
4253 vhostuser to indicate connection using a virtio transport protocol.
4255 source indicates the source of the connection. The source depends on
4257 the type of the interface:
4258 network name of the virtual network,
4260 bridge the name of the bridge device,
4262 direct the name of the host's interface or bridge,
4264 hostdev the PCI address of the host's interface formatted as do‐
4266 main:bus:slot.function.
4267 vhostuser the path to UNIX socket (control plane)
4269 --target is used to specify the tap/macvtap device to be used to con‐
4271 nect the domain to the source. Names starting with 'vnet' are consid‐
4272 ered as auto-generated and are blanked out/regenerated each time the
4273 interface is attached.
4274 --mac specifies the MAC address of the network interface; if a MAC ad‐
4276 dress is not given, a new address will be automatically generated (and
4277 stored in the persistent configuration if "--config" is given on the
4278 command line).
4279 --script is used to specify a path to a custom script to be called
4281 while attaching to a bridge - this will be called instead of the de‐
4282 fault script not in addition to it. This is valid only for interfaces
4283 of bridge type and only for Xen domains.
4284 --model specifies the network device model to be presented to the do‐
4286 main.
4287 alias can set user supplied alias.
4289 --inbound and --outbound control the bandwidth of the interface. At
4291 least one from the average, floor pair must be specified. The other
4292 two peak and burst are optional, so "average,peak", "average,,burst",
4293 "average,,,floor", "average" and ",,,floor" are also legal. Values for
4294 average, floor and peak are expressed in kilobytes per second, while
4295 burst is expressed in kilobytes in a single burst at peak speed as de‐
4296 scribed in the Network XML documentation at
4297 https://libvirt.org/formatnetwork.html#quality-of-service.
4298 --managed is usable only for hostdev type and tells libvirt that the
4300 interface should be managed, which means detached and reattached
4301 from/to the host by libvirt.
4302 --source-mode is mandatory for vhostuser interface and accepts values
4304 server and client that control whether hypervisor waits for the other
4305 process to connect, or initiates connection, respectively.
4306 If --print-xml is specified, then the XML of the interface that would
4308 be attached is printed instead.
4309 If --live is specified, affect a running domain. If --config is speci‐
4311 fied, affect the next startup of a persistent guest. If --current is
4312 specified, affect the current domain state, which can either be live or
4313 offline. Both --live and --config flags may be given, but --current is
4314 exclusive. When no flag is specified legacy API is used whose behavior
4315 depends on the hypervisor driver.
4316 For compatibility purposes, --persistent behaves like --config for an
4318 offline domain, and like --live --config for a running domain.
4319 Note: the optional target value is the name of a device to be created
4321 as the back-end on the node. If not provided a device named "vnetN" or
4322 "vifN" will be created automatically.
4323 detach-device
4325 Syntax:
4326 detach-device domain FILE [[[--live] [--config] |
4328 [--current]] | [--persistent]]
4329 Detach a device from the domain, takes the same kind of XML descrip‐
4331 tions as command attach-device. For passthrough host devices, see also
4332 nodedev-reattach, needed if the device does not use managed mode.
4333 Note: The supplied XML description of the device should be as specific
4335 as its definition in the domain XML. The set of attributes used to
4336 match the device are internal to the drivers. Using a partial defini‐
4337 tion, or attempting to detach a device that is not present in the do‐
4338 main XML, but shares some specific attributes with one that is present,
4339 may lead to unexpected results.
4340 Quirk: Device unplug is asynchronous in most cases and requires guest
4342 cooperation. This means that it's up to the discretion of the guest to
4343 disallow or delay the unplug arbitrarily. As the libvirt API used in
4344 this command was designed as synchronous it returns success after some
4345 timeout even if the device was not unplugged yet to allow further in‐
4346 teractions with the domain e.g. if the guest is unresponsive. Callers
4347 which need to make sure that the device was unplugged can use libvirt
4348 events (see virsh event) to be notified when the device is removed.
4349 Note that the event may arrive before the command returns.
4350 If --live is specified, affect a running domain. If --config is speci‐
4352 fied, affect the next startup of a persistent guest. If --current is
4353 specified, it is equivalent to either --live or --config, depending on
4354 the current state of the guest. Both --live and --config flags may be
4355 given, but --current is exclusive. When no flag is specified legacy API
4356 is used whose behavior depends on the hypervisor driver.
4357 For compatibility purposes, --persistent behaves like --config for an
4359 offline domain, and like --live --config for a running domain.
4360 Note that older versions of virsh used --config as an alias for --per‐
4362 sistent.
4363 detach-device-alias
4365 Syntax:
4366 detach-device-alias domain alias [[[--live] [--config] | [--current]]]]
4368 Detach a device with given alias from the domain. This command returns
4370 successfully after the unplug request was sent to the hypervisor. The
4371 actual removal of the device is notified asynchronously via libvirt
4372 events (see virsh event).
4373 If --live is specified, affect a running domain. If --config is speci‐
4375 fied, affect the next startup of a persistent guest. If --current is
4376 specified, it is equivalent to either --live or --config, depending on
4377 the current state of the guest. Both --live and --config flags may be
4378 given, but --current is exclusive.
4379 detach-disk
4381 Syntax:
4382 detach-disk domain target [[[--live] [--config] |
4384 [--current]] | [--persistent]] [--print-xml]
4385 Detach a disk device from a domain. The target is the device as seen
4387 from the domain.
4388 If --live is specified, affect a running domain. If --config is speci‐
4390 fied, affect the next startup of a persistent guest. If --current is
4391 specified, it is equivalent to either --live or --config, depending on
4392 the current state of the guest. Both --live and --config flags may be
4393 given, but --current is exclusive. When no flag is specified legacy API
4394 is used whose behavior depends on the hypervisor driver.
4395 For compatibility purposes, --persistent behaves like --config for an
4397 offline domain, and like --live --config for a running domain.
4398 Note that older versions of virsh used --config as an alias for --per‐
4400 sistent.
4401 If --print-xml is specified, then the XML which would be used to detach
4403 the disk is printed instead.
4404 Please see documentation for detach-device for known quirks.
4406 detach-interface
4408 Syntax:
4409 detach-interface domain type [--mac mac]
4411 [[[--live] [--config] | [--current]] | [--persistent]] [--print-xml]
4412 Detach a network interface from a domain. type can be either network
4414 to indicate a physical network device or bridge to indicate a bridge to
4415 a device. It is recommended to use the mac option to distinguish be‐
4416 tween the interfaces if more than one are present on the domain.
4417 If --live is specified, affect a running domain. If --config is speci‐
4419 fied, affect the next startup of a persistent guest. If --current is
4420 specified, it is equivalent to either --live or --config, depending on
4421 the current state of the guest. Both --live and --config flags may be
4422 given, but --current is exclusive. When no flag is specified legacy API
4423 is used whose behavior depends on the hypervisor driver.
4424 For compatibility purposes, --persistent behaves like --config for an
4426 offline domain, and like --live --config for a running domain.
4427 Note that older versions of virsh used --config as an alias for --per‐
4429 sistent.
4430 If --print-xml is specified, then the XML used to detach the interface
4432 is printed instead.
4433 Please see documentation for detach-device for known quirks.
4435 update-device
4437 Syntax:
4438 update-device domain file [--force] [[[--live]
4440 [--config] | [--current]] | [--persistent]]
4441 Update the characteristics of a device associated with domain, based on
4443 the device definition in an XML file. The --force option can be used
4444 to force device update, e.g., to eject a CD-ROM even if it is
4445 locked/mounted in the domain. See the documentation at
4446 https://libvirt.org/formatdomain.html#elementsDevices to learn about
4447 libvirt XML format for a device.
4448 If --live is specified, affect a running domain. If --config is speci‐
4450 fied, affect the next startup of a persistent guest. If --current is
4451 specified, it is equivalent to either --live or --config, depending on
4452 the current state of the guest. Both --live and --config flags may be
4453 given, but --current is exclusive. Not specifying any flag is the same
4454 as specifying --current.
4455 For compatibility purposes, --persistent behaves like --config for an
4457 offline domain, and like --live --config for a running domain.
4458 Note that older versions of virsh used --config as an alias for --per‐
4460 sistent.
4461 Note: using of partial device definition XML files may lead to unex‐
4463 pected results as some fields may be autogenerated and thus match de‐
4464 vices other than expected.
4465 update-memory-device
4467 Syntax:
4468 update-memory-device domain [--print-xml] [[--alias alias] | [--node node]]
4470 [[--live] [--config] | [--current]]
4471 [--requested-size size]
4472 This command finds <memory/> device inside given domain, changes re‐
4474 quested values and passes updated device XML to daemon. If --print-xml
4475 is specified then the device is not changed, but the updated device XML
4476 is printed to stdout. If there are more than one <memory/> devices in
4477 domain use --alias or --node to select the desired one.
4478 If --live is specified, affect a running domain. If --config is speci‐
4480 fied, affect the next startup of a persistent guest. If --current is
4481 specified, it is equivalent to either --live or --config, depending on
4482 the current state of the guest. Both --live and --config flags may be
4483 given, but --current is exclusive. Not specifying any flag is the same
4484 as specifying --current.
4485 If --requested-size is specified then <requested/> under memory target
4487 is changed to requested size (as scaled integer, see NOTES above). It
4488 defaults to kibibytes if no suffix is provided. The option is valid
4489 only for virtio-mem memory device model.
4490 change-media
4492 Syntax:
4493 change-media domain path [--eject] [--insert]
4495 [--update] [source] [--force] [[--live] [--config] |
4496 [--current]] [--print-xml] [--block]
4497 Change media of CDROM or floppy drive. path can be the fully-qualified
4499 path or the unique target name (<target dev='hdc'>) of the disk device.
4500 source specifies the path of the media to be inserted or updated. The
4501 --block flag allows setting the backing type in case a block device is
4502 used as media for the CDROM or floppy drive instead of a file.
4503 --eject indicates the media will be ejected. --insert indicates the
4505 media will be inserted. source must be specified. If the device has
4506 source (e.g. <source file='media'>), and source is not specified, --up‐
4507 date is equal to --eject. If the device has no source, and source is
4508 specified, --update is equal to --insert. If the device has source, and
4509 source is specified, --update behaves like combination of --eject and
4510 --insert. If none of --eject, --insert, and --update is specified,
4511 --update is used by default. The --force option can be used to force
4512 media changing. If --live is specified, alter live configuration of
4513 running guest. If --config is specified, alter persistent configura‐
4514 tion, effect observed on next startup of the guest. --current can be
4515 either or both of live and config, depends on the hypervisor's imple‐
4516 mentation. Both --live and --config flags may be given, but --current
4517 is exclusive. If no flag is specified, behavior is different depending
4518 on hypervisor. If --print-xml is specified, the XML that would be used
4519 to change media is printed instead of changing the media.
4520 dom-fd-associate
4522 Syntax:
4523 dom-fd-associate domain --name FDGROUPNAME --pass-fds M,N,....
4525 [--seclabel-writable] [--seclabel-restore]
4526 Associate one or more fds described via --pass-fds argument to domain
4528 as --name. The lifetime of the passed fd group is the same as the con‐
4529 nection, thus exitting virsh un-registers them afterwards.
4530 By default security labels are applied if needed but they are not re‐
4532 stored after use to avoid keeping them open unnecessarily. Best-effort
4533 security label restore may be requested by using the --seclabel-restore
4534 flag.
4535
4537 The following commands manipulate host devices that are intended to be
4538 passed through to guest domains via <hostdev> elements in a domain's
4539 <devices> section. A node device key is generally specified by the bus
4540 name followed by its address, using underscores between all components,
4541 such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
4542 The nodedev-list gives the full list of host devices that are known to
4543 libvirt, although this includes devices that cannot be assigned to a
4544 guest (for example, attempting to detach the PCI device that controls
4545 the host's hard disk controller where the guest's disk images live
4546 could cause the host system to lock up or reboot).
4547 For more information on node device definition see:
4549 https://libvirt.org/formatnode.html.
4550 Passthrough devices cannot be simultaneously used by the host and its
4552 guest domains, nor by multiple active guests at once. If the <hostdev>
4553 description of a PCI device includes the attribute managed='yes', and
4554 the hypervisor driver supports it, then the device is in managed mode,
4555 and attempts to use that passthrough device in an active guest will au‐
4556 tomatically behave as if nodedev-detach (guest start, device hot-plug)
4557 and nodedev-reattach (guest stop, device hot-unplug) were called at the
4558 right points. If a PCI device is not marked as managed, then it must
4559 manually be detached before guests can use it, and manually reattached
4560 to be returned to the host. Also, if a device is manually detached,
4561 then the host does not regain control of the device without a matching
4562 reattach, even if the guests use the device in managed mode.
4563 nodedev-create
4565 Syntax:
4566 nodedev-create FILE [--validate]
4568 Create a device on the host node that can then be assigned to virtual
4570 machines. Normally, libvirt is able to automatically determine which
4571 host nodes are available for use, but this allows registration of host
4572 hardware that libvirt did not automatically detect. file contains xml
4573 for a top-level <device> description of a node device.
4574 If --validate is specified, validates the format of the XML document
4576 against an internal RNG schema.
4577 nodedev-destroy
4579 Syntax:
4580 nodedev-destroy device
4582 Destroy (stop) a device on the host. device can be either device name
4584 or wwn pair in "wwnn,wwpn" format (only works for vHBA currently).
4585 Note that this makes libvirt quit managing a host device, and may even
4586 make that device unusable by the rest of the physical host until a re‐
4587 boot.
4588 nodedev-define
4590 Syntax:
4591 nodedev-define FILE [--validate]
4593 Define an inactive persistent device or modify an existing persistent
4595 one from the XML FILE.
4596 If --validate is specified, validates the format of the XML document
4598 against an internal RNG schema.
4599 nodedev-undefine
4601 Syntax:
4602 nodedev-undefine device
4604 Undefine the configuration for a persistent device. If the device is
4606 active, make it transient.
4607 nodedev-start
4609 Syntax:
4610 nodedev-start device
4612 Start a (previously defined) inactive device.
4614 nodedev-detach
4616 Syntax:
4617 nodedev-detach nodedev [--driver backend_driver]
4619 Detach nodedev from the host driver and bind it to a special driver
4621 that provides the API needed by the hypervisor for assigning the device
4622 to a virtual machine (using <hostdev> in the domain XML definition).
4623 This is reversed with nodedev-reattach, and is done automatically by
4624 the hypervisor driver for managed devices (those devices with "man‐
4625 aged='yes'" in their XML definition).
4626 Different hypervisors expect the device being assigned to be bound to
4628 different drivers. For example, QEMU's "vfio" backend requires the de‐
4629 vice to be bound to the driver "vfio-pci" or to a "VFIO variant" driver
4630 (this is a driver that supports the full API provided by vfio-pci, plus
4631 some other APIs to support things like live migration). The --driver
4632 parameter can be used to specify a particular driver (e.g. a de‐
4633 vice-specific VFIO variant driver) the device should be bound to. When
4634 --driver is omitted, the default driver for the hypervisor is used
4635 ("vfio-pci" for QEMU, "pciback" for Xen).
4636 nodedev-dumpxml
4638 Syntax:
4639 nodedev-dumpxml [--xpath EXPRESSION] [--wrap] device
4641 Dump a <device> XML representation for the given node device, including
4643 such information as the device name, which bus owns the device, the
4644 vendor and product id, and any capabilities of the device usable by
4645 libvirt (such as whether device reset is supported). device can be ei‐
4646 ther device name or wwn pair in "wwnn,wwpn" format (only works for
4647 HBA).
4648 If the --xpath argument provides an XPath expression, it will be evalu‐
4650 ated against the output XML and only those matching nodes will be
4651 printed. The default behaviour is to print each matching node as a
4652 standalone document, however, for ease of additional processing, the
4653 --wrap argument will cause the matching node to be wrapped in a common
4654 root node.
4655 nodedev-info
4657 Syntax:
4658 nodedev-info device
4660 Returns basic information about the device object.
4662 nodedev-list
4664 Syntax:
4665 nodedev-list [--cap capability] [--tree] [--inactive | --all]
4667 List all of the devices available on the node that are known by lib‐
4669 virt. cap is used to filter the list by capability types, the types
4670 must be separated by comma, e.g. --cap pci,scsi. Valid capability types
4671 include 'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host',
4672 'scsi_target', 'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic',
4673 'drm', 'mdev', 'mdev_types', 'ccw', 'css', 'ap_card', 'ap_queue',
4674 'ap_matrix'. By default, only active devices are listed. --inactive is
4675 used to list only inactive devices, and -all is used to list both ac‐
4676 tive and inactive devices. If --tree is used, the output is formatted
4677 in a tree representing parents of each node. --tree is mutually exclu‐
4678 sive with all other options.
4679 nodedev-reattach
4681 Syntax:
4682 nodedev-reattach nodedev
4684 Declare that nodedev is no longer in use by any guests, and that the
4686 host can resume normal use of the device. This is done automatically
4687 for PCI devices in managed mode and USB devices, but must be done ex‐
4688 plicitly to match any explicit nodedev-detach.
4689 nodedev-reset
4691 Syntax:
4692 nodedev-reset nodedev
4694 Trigger a device reset for nodedev, useful prior to transferring a node
4696 device between guest passthrough or the host. Libvirt will often do
4697 this action implicitly when required, but this command allows an ex‐
4698 plicit reset when needed.
4699 nodedev-event
4701 Syntax:
4702 nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list}
4704 Wait for a class of node device events to occur, and print appropriate
4706 details of events as they happen. The events can optionally be fil‐
4707 tered by nodedev. Using --list as the only argument will provide a
4708 list of possible event values known by this client, although the con‐
4709 nection might not allow registering for all these events.
4710 By default, this command is one-shot, and returns success once an event
4712 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4713 If --timeout is specified, the command gives up waiting for events af‐
4714 ter seconds have elapsed. With --loop, the command prints all events
4715 until a timeout or interrupt key.
4716 When --timestamp is used, a human-readable timestamp will be printed
4718 before the event.
4719 nodedev-autostart
4721 Syntax:
4722 nodedev-autostart [--disable] device
4724 Configure a device to be automatically started when the host machine
4726 boots or the parent device becomes available. With --disable, the de‐
4727 vice will be set to manual mode and will no longer be automatically
4728 started by the host. This command is only supported for persis‐
4729 tently-defined mediated devices.
4730
4732 The following commands manipulate networks. Libvirt has the capability
4733 to define virtual networks which can then be used by domains and linked
4734 to actual network devices. For more detailed information about this
4735 feature see the documentation at https://libvirt.org/formatnetwork.html
4736 . Many of the commands for virtual networks are similar to the ones
4737 used for domains, but the way to name a virtual network is either by
4738 its name or UUID.
4739 net-autostart
4741 Syntax:
4742 net-autostart network [--disable]
4744 Configure a virtual network to be automatically started at boot. The
4746 --disable option disable autostarting.
4747 net-create
4749 Syntax:
4750 net-create file [--validate]
4752 Create a transient (temporary) virtual network from an XML file and in‐
4754 stantiate (start) the network. See the documentation at
4755 https://libvirt.org/formatnetwork.html to get a description of the XML
4756 network format used by libvirt.
4757 Optionally, the format of the input XML file can be validated against
4759 an internal RNG schema with --validate.
4760 net-define
4762 Syntax:
4763 net-define file [--validate]
4765 Define an inactive persistent virtual network or modify an existing
4767 persistent one from the XML file. Optionally, the format of the input
4768 XML file can be validated against an internal RNG schema with --vali‐
4769 date.
4770 net-desc
4772 Syntax:
4773 net-desc network [[--live] [--config] |
4775 [--current]] [--title] [--edit] [--new-desc
4776 New description or title message]
4777 Show or modify description and title of a network. These values are
4779 user fields that allow storing arbitrary textual data to allow easy
4780 identification of networks. Title should be short, although it's not
4781 enforced. (See also net-metadata that works with XML based network
4782 metadata.)
4783 Flags --live or --config select whether this command works on live or
4785 persistent definitions of the network. If both --live and --config are
4786 specified, the --config option takes precedence on getting the current
4787 description and both live configuration and config are updated while
4788 setting the description. --current is exclusive and implied if none of
4789 these was specified.
4790 Flag --edit specifies that an editor with the contents of current de‐
4792 scription or title should be opened and the contents saved back after‐
4793 wards.
4794 Flag --title selects operation on the title field instead of descrip‐
4796 tion.
4797 If neither of --edit and --new-desc are specified the note or descrip‐
4799 tion is displayed instead of being modified.
4800 net-destroy
4802 Syntax:
4803 net-destroy network
4805 Destroy (stop) a given transient or persistent virtual network speci‐
4807 fied by its name or UUID. This takes effect immediately.
4808 net-dumpxml
4810 Syntax:
4811 net-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] network
4813 Output the virtual network information as an XML dump to stdout. If
4815 --inactive is specified, then physical functions are not expanded into
4816 their associated virtual functions.
4817 If the --xpath argument provides an XPath expression, it will be evalu‐
4819 ated against the output XML and only those matching nodes will be
4820 printed. The default behaviour is to print each matching node as a
4821 standalone document, however, for ease of additional processing, the
4822 --wrap argument will cause the matching node to be wrapped in a common
4823 root node.
4824 net-edit
4826 Syntax:
4827 net-edit network
4829 Edit the XML configuration file for a network.
4831 This is equivalent to:
4833 virsh net-dumpxml --inactive network > network.xml
4835 vi network.xml (or make changes with your other text editor)
4836 virsh net-define network.xml
4837 except that it does some error checking.
4839 The editor used can be supplied by the $VISUAL or $EDITOR environment
4841 variables, and defaults to vi.
4842 net-event
4844 Syntax:
4845 net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list}
4847 Wait for a class of network events to occur, and print appropriate de‐
4849 tails of events as they happen. The events can optionally be filtered
4850 by network. Using --list as the only argument will provide a list of
4851 possible event values known by this client, although the connection
4852 might not allow registering for all these events.
4853 By default, this command is one-shot, and returns success once an event
4855 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4856 If --timeout is specified, the command gives up waiting for events af‐
4857 ter seconds have elapsed. With --loop, the command prints all events
4858 until a timeout or interrupt key.
4859 When --timestamp is used, a human-readable timestamp will be printed
4861 before the event.
4862 net-info
4864 Syntax:
4865 net-info network
4867 Returns basic information about the network object.
4869 net-list
4871 Syntax:
4872 net-list [--inactive | --all]
4874 { [--table] | --name | --uuid }
4875 [--persistent] [<--transient>]
4876 [--autostart] [<--no-autostart>]
4877 [--title]
4878 Returns the list of active networks, if --all is specified this will
4880 also include defined but inactive networks, if --inactive is specified
4881 only the inactive ones will be listed. You may also want to filter the
4882 returned networks by --persistent to list the persistent ones, --tran‐
4883 sient to list the transient ones, --autostart to list the ones with au‐
4884 tostart enabled, and --no-autostart to list the ones with autostart
4885 disabled.
4886 If --name is specified, network names are printed instead of the table
4888 formatted one per line. If --uuid is specified network's UUID's are
4889 printed instead of names. Flag --table specifies that the legacy ta‐
4890 ble-formatted output should be used. This is the default. All of these
4891 are mutually exclusive.
4892 If --title is specified, then the short network description (title) is
4894 printed in an extra column. This flag is usable only with the default
4895 --table output.
4896 NOTE: When talking to older servers, this command is forced to use a
4898 series of API calls with an inherent race, where a pool might not be
4899 listed or might appear more than once if it changed state between calls
4900 while the list was being collected. Newer servers do not have this
4901 problem.
4902 net-metadata
4904 Syntax:
4905 net-metadata network [[--live] [--config] | [--current]]
4907 [--edit] [uri] [key] [set] [--remove]
4908 Show or modify custom XML metadata of a network. The metadata is a user
4910 defined XML that allows storing arbitrary XML data in the network defi‐
4911 nition. Multiple separate custom metadata pieces can be stored in the
4912 network XML. The pieces are identified by a private XML namespace pro‐
4913 vided via the uri argument. (See also net-desc that works with textual
4914 metadata of a network, such as title and description.)
4915 Flags --live or --config select whether this command works on live or
4917 persistent definitions of the network. If both --live and --config are
4918 specified, the --config option takes precedence on getting the current
4919 description and both live configuration and config are updated while
4920 setting the description. --current is exclusive and implied if none of
4921 these was specified.
4922 Flag --remove specifies that the metadata element specified by the uri
4924 argument should be removed rather than updated.
4925 Flag --edit specifies that an editor with the metadata identified by
4927 the uri argument should be opened and the contents saved back after‐
4928 wards. Otherwise the new contents can be provided via the set argu‐
4929 ment.
4930 When setting metadata via --edit or set the key argument must be speci‐
4932 fied and is used to prefix the custom elements to bind them to the pri‐
4933 vate namespace.
4934 If neither of --edit and set are specified the XML metadata correspond‐
4936 ing to the uri namespace is displayed instead of being modified.
4937 net-name
4939 Syntax:
4940 net-name network-UUID
4942 Convert a network UUID to network name.
4944 net-start
4946 Syntax:
4947 net-start network
4949 Start a (previously defined) inactive network.
4951 net-undefine
4953 Syntax:
4954 net-undefine network
4956 Undefine the configuration for a persistent network. If the network is
4958 active, make it transient.
4959 net-uuid
4961 Syntax:
4962 net-uuid network-name
4964 Convert a network name to network UUID.
4966 net-update
4968 Syntax:
4969 net-update network command section xml
4971 [--parent-index index] [[--live] [--config] | [--current]]
4972 Update the given section of an existing network definition, with the
4974 changes optionally taking effect immediately, without needing to de‐
4975 stroy and re-start the network.
4976 command is one of "add-first", "add-last", "add" (a synonym for
4978 add-last), "delete", or "modify".
4979 section is one of "bridge", "domain", "ip", "ip-dhcp-host",
4981 "ip-dhcp-range", "forward", "forward-interface", "forward-pf", "port‐
4982 group", "dns-host", "dns-txt", or "dns-srv", each section being named
4983 by a concatenation of the xml element hierarchy leading to the element
4984 being changed. For example, "ip-dhcp-host" will change a <host> element
4985 that is contained inside a <dhcp> element inside an <ip> element of the
4986 network.
4987 xml is either the text of a complete xml element of the type being
4989 changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the
4990 name of a file that contains a complete xml element. Disambiguation is
4991 done by looking at the first character of the provided text - if the
4992 first character is "<", it is xml text, if the first character is not
4993 "<", it is the name of a file that contains the xml text to be used.
4994 The --parent-index option is used to specify which of several parent
4996 elements the requested element is in (0-based). For example, a dhcp
4997 <host> element could be in any one of multiple <ip> elements in the
4998 network; if a parent-index isn't provided, the "most appropriate" <ip>
4999 element will be selected (usually the only one that already has a
5000 <dhcp> element), but if --parent-index is given, that particular in‐
5001 stance of <ip> will get the modification.
5002 If --live is specified, affect a running network. If --config is spec‐
5004 ified, affect the next startup of a persistent network. If --current
5005 is specified, it is equivalent to either --live or --config, depending
5006 on the current state of the guest. Both --live and --config flags may
5007 be given, but --current is exclusive. Not specifying any flag is the
5008 same as specifying --current.
5009 net-dhcp-leases
5011 Syntax:
5012 net-dhcp-leases network [mac]
5014 Get a list of dhcp leases for all network interfaces connected to the
5016 given virtual network or limited output just for one interface if mac
5017 is specified.
5018
5020 The following commands manipulate network ports. Libvirt virtual net‐
5021 works have ports created when a virtual machine has a virtual network
5022 interface added. In general there should be no need to use any of the
5023 commands here, since the hypervisor drivers run these commands are the
5024 right point in a virtual machine's lifecycle. They can be useful for
5025 debugging problems and / or recovering from bugs / stale state.
5026 net-port-list
5028 Syntax:
5029 net-port-list { [--table] | --uuid } network
5031 List all network ports recorded against the network.
5033 If --uuid is specified network ports' UUID's are printed instead of a
5035 table. Flag --table specifies that the legacy table-formatted output
5036 should be used. This is the default. All of these are mutually exclu‐
5037 sive.
5038 net-port-create
5040 Syntax:
5041 net-port-create network file [--validate]
5043 Allocate a new network port reserving resources based on the port de‐
5045 scription. Optionally, the format of the input XML file can be vali‐
5046 dated against an internal RNG schema with --validate.
5047 net-port-dumpxml
5049 Syntax:
5050 net-port-dumpxml [--xpath EXPRESSION] [--wrap] network port
5052 Output the network port information as an XML dump to stdout.
5054 If the --xpath argument provides an XPath expression, it will be evalu‐
5056 ated against the output XML and only those matching nodes will be
5057 printed. The default behaviour is to print each matching node as a
5058 standalone document, however, for ease of additional processing, the
5059 --wrap argument will cause the matching node to be wrapped in a common
5060 root node.
5061 net-port-delete
5063 Syntax:
5064 net-port-delete network port
5066 Delete record of the network port and release its resources
5068
5070 The following commands manipulate host interfaces. Often, these host
5071 interfaces can then be used by name within domain <interface> elements
5072 (such as a system-created bridge interface), but there is no require‐
5073 ment that host interfaces be tied to any particular guest configuration
5074 XML at all.
5075 Many of the commands for host interfaces are similar to the ones used
5077 for domains, and the way to name an interface is either by its name or
5078 its MAC address. However, using a MAC address for an iface argument
5079 only works when that address is unique (if an interface and a bridge
5080 share the same MAC address, which is often the case, then using that
5081 MAC address results in an error due to ambiguity, and you must resort
5082 to a name instead).
5083 iface-bridge
5085 Syntax:
5086 iface-bridge interface bridge [--no-stp] [delay] [--no-start]
5088 Create a bridge device named bridge, and attach the existing network
5090 device interface to the new bridge. The new bridge defaults to start‐
5091 ing immediately, with STP enabled and a delay of 0; these settings can
5092 be altered with --no-stp, --no-start, and an integer number of seconds
5093 for delay. All IP address configuration of interface will be moved to
5094 the new bridge device.
5095 See also iface-unbridge for undoing this operation.
5097 iface-define
5099 Syntax:
5100 iface-define file [--validate]
5102 Define an inactive persistent physical host interface or modify an ex‐
5104 isting persistent one from the XML file. Optionally, the format of the
5105 input XML file can be validated against an internal RNG schema with
5106 --validate.
5107 iface-destroy
5109 Syntax:
5110 iface-destroy interface
5112 Destroy (stop) a given host interface, such as by running "if-down" to
5114 disable that interface from active use. This takes effect immediately.
5115 iface-dumpxml
5117 Syntax:
5118 iface-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] interface
5120 Output the host interface information as an XML dump to stdout. If
5122 --inactive is specified, then the output reflects the persistent state
5123 of the interface that will be used the next time it is started.
5124 If the --xpath argument provides an XPath expression, it will be evalu‐
5126 ated against the output XML and only those matching nodes will be
5127 printed. The default behaviour is to print each matching node as a
5128 standalone document, however, for ease of additional processing, the
5129 --wrap argument will cause the matching node to be wrapped in a common
5130 root node.
5131 iface-edit
5133 Syntax:
5134 iface-edit interface
5136 Edit the XML configuration file for a host interface.
5138 This is equivalent to:
5140 virsh iface-dumpxml iface > iface.xml
5142 vi iface.xml (or make changes with your other text editor)
5143 virsh iface-define iface.xml
5144 except that it does some error checking.
5146 The editor used can be supplied by the $VISUAL or $EDITOR environment
5148 variables, and defaults to vi.
5149 iface-list
5151 Syntax:
5152 iface-list [--inactive | --all]
5154 Returns the list of active host interfaces. If --all is specified this
5156 will also include defined but inactive interfaces. If --inactive is
5157 specified only the inactive ones will be listed.
5158 iface-name
5160 Syntax:
5161 iface-name interface
5163 Convert a host interface MAC to interface name, if the MAC address is
5165 unique among the host's interfaces.
5166 interface specifies the interface MAC address.
5168 iface-mac
5170 Syntax:
5171 iface-mac interface
5173 Convert a host interface name to MAC address.
5175 interface specifies the interface name.
5177 iface-start
5179 Syntax:
5180 iface-start interface
5182 Start a (previously defined) host interface, such as by running
5184 "if-up".
5185 iface-unbridge
5187 Syntax:
5188 iface-unbridge bridge [--no-start]
5190 Tear down a bridge device named bridge, releasing its underlying inter‐
5192 face back to normal usage, and moving all IP address configuration from
5193 the bridge device to the underlying device. The underlying interface
5194 is restarted unless --no-start is present; this flag is present for
5195 symmetry, but generally not recommended.
5196 See also iface-bridge for creating a bridge.
5198 iface-undefine
5200 Syntax:
5201 iface-undefine interface
5203 Undefine the configuration for an inactive host interface.
5205 iface-begin
5207 Syntax:
5208 iface-begin
5210 Create a snapshot of current host interface settings, which can later
5212 be committed (iface-commit) or restored (iface-rollback). If a snap‐
5213 shot already exists, then this command will fail until the previous
5214 snapshot has been committed or restored. Undefined behavior results if
5215 any external changes are made to host interfaces outside of the libvirt
5216 API between the beginning of a snapshot and its eventual commit or
5217 rollback.
5218 iface-commit
5220 Syntax:
5221 iface-commit
5223 Declare all changes since the last iface-begin as working, and delete
5225 the rollback point. If no interface snapshot has already been started,
5226 then this command will fail.
5227 iface-rollback
5229 Syntax:
5230 iface-rollback
5232 Revert all host interface settings back to the state recorded in the
5234 last iface-begin. If no interface snapshot has already been started,
5235 then this command will fail. Rebooting the host also serves as an im‐
5236 plicit rollback point.
5237
5239 The following commands manipulate storage pools. Libvirt has the capa‐
5240 bility to manage various storage solutions, including files, raw parti‐
5241 tions, and domain-specific formats, used to provide the storage volumes
5242 visible as devices within virtual machines. For more detailed informa‐
5243 tion about this feature, see the documentation at
5244 https://libvirt.org/formatstorage.html . Many of the commands for pools
5245 are similar to the ones used for domains.
5246 find-storage-pool-sources
5248 Syntax:
5249 find-storage-pool-sources type [srcSpec]
5251 Returns XML describing all possible available storage pool sources that
5253 could be used to create or define a storage pool of a given type. If
5254 srcSpec is provided, it is a file that contains XML to further restrict
5255 the query for pools.
5256 Not all storage pools support discovery in this manner. Furthermore,
5258 for those that do support discovery, only specific XML elements are re‐
5259 quired in order to return valid data, while other elements and even at‐
5260 tributes of some elements are ignored since they are not necessary to
5261 find the pool based on the search criteria. The following lists the
5262 supported type options and the expected minimal XML elements used to
5263 perform the search.
5264 For a "netfs" or "gluster" pool, the minimal expected XML required is
5266 the <host> element with a "name" attribute describing the IP address or
5267 hostname to be used to find the pool. The "port" attribute will be ig‐
5268 nored as will any other provided XML elements in srcSpec.
5269 For a "logical" pool, the contents of the srcSpec file are ignored, al‐
5271 though if provided the file must at least exist.
5272 For an "iscsi" or "iscsi-direct" pool, the minimal expect XML required
5274 is the <host> element with a "name" attribute describing the IP address
5275 or hostname to be used to find the pool (the iSCSI server address). Op‐
5276 tionally, the "port" attribute may be provided, although it will de‐
5277 fault to 3260. Optionally, an <initiator> XML element with a "name" at‐
5278 tribute may be provided to further restrict the iSCSI target search to
5279 a specific initiator for multi-iqn iSCSI storage pools.
5280 find-pool-sources-as
5282 Syntax:
5283 find-storage-pool-sources-as type [host] [port] [initiator]
5285 Rather than providing srcSpec XML file for find-storage-pool-sources
5287 use this command option in order to have virsh generate the query XML
5288 file using the optional arguments. The command will return the same
5289 output XML as find-storage-pool-sources.
5290 Use host to describe a specific host to use for networked storage, such
5292 as netfs, gluster, and iscsi type pools.
5293 Use port to further restrict which networked port to utilize for the
5295 connection if required by the specific storage backend, such as iscsi.
5296 Use initiator to further restrict the iscsi type pool searches to spe‐
5298 cific target initiators.
5299 pool-autostart
5301 Syntax:
5302 pool-autostart pool-or-uuid [--disable]
5304 Configure whether pool should automatically start at boot.
5306 pool-build
5308 Syntax:
5309 pool-build pool-or-uuid [--overwrite] [--no-overwrite]
5311 Build a given pool.
5313 Options --overwrite and --no-overwrite can only be used for pool-build
5315 a filesystem, disk, or logical pool.
5316 For a file system pool if neither flag is specified, then pool-build
5318 just makes the target path directory and no attempt to run mkfs on the
5319 target volume device. If --no-overwrite is specified, it probes to de‐
5320 termine if a filesystem already exists on the target device, returning
5321 an error if one exists or using mkfs to format the target device if
5322 not. If --overwrite is specified, mkfs is always executed and any ex‐
5323 isting data on the target device is overwritten unconditionally.
5324 For a disk pool, if neither of them is specified or --no-overwrite is
5326 specified, pool-build will check the target volume device for existing
5327 filesystems or partitions before attempting to write a new label on the
5328 target volume device. If the target volume device already has a label,
5329 the command will fail. If --overwrite is specified, then no check will
5330 be made on the target volume device prior to writing a new label. Writ‐
5331 ing of the label uses the pool source format type or "dos" if not spec‐
5332 ified.
5333 For a logical pool, if neither of them is specified or --no-overwrite
5335 is specified, pool-build will check the target volume devices for ex‐
5336 isting filesystems or partitions before attempting to initialize and
5337 format each device for usage by the logical pool. If any target volume
5338 device already has a label, the command will fail. If --overwrite is
5339 specified, then no check will be made on the target volume devices
5340 prior to initializing and formatting each device. Once all the target
5341 volume devices are properly formatted via pvcreate, the volume group
5342 will be created using all the devices.
5343 pool-create
5345 Syntax:
5346 pool-create file [--build] [[--overwrite] | [--no-overwrite]]
5348 Create and start a pool object from the XML file.
5350 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
5352 creation in order to remove the need for a follow-up command to build
5353 the pool. The --overwrite and --no-overwrite flags follow the same
5354 rules as pool-build. If just --build is provided, then pool-build is
5355 called with no flags.
5356 pool-create-as
5358 Syntax:
5359 pool-create-as name type
5361 [--source-host hostname] [--source-path path] [--source-dev path]
5362 [--source-name name] [--target path] [--source-format format]
5363 [--source-initiator initiator-iqn]
5364 [--auth-type authtype --auth-username username
5365 [--secret-usage usage | --secret-uuid uuid]]
5366 [--source-protocol-ver ver]
5367 [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn]
5368 [--adapter-parent parent |
5369 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
5370 --adapter-parent-fabric-wwn parent_fabric_wwn]]
5371 [--build] [[--overwrite] | [--no-overwrite]] [--print-xml]
5372 Create and start a pool object name from the raw parameters. If
5374 --print-xml is specified, then print the XML of the pool object without
5375 creating the pool. Otherwise, the pool has the specified type. When
5376 using pool-create-as for a pool of type "disk", the existing partitions
5377 found on the --source-dev path will be used to populate the disk pool.
5378 Therefore, it is suggested to use pool-define-as and pool-build with
5379 the --overwrite in order to properly initialize the disk pool.
5380 [--source-host hostname] provides the source hostname for pools backed
5382 by storage from a remote server (pool types netfs, iscsi, rbd, sheep‐
5383 dog, gluster).
5384 [--source-path path] provides the source directory path for pools
5386 backed by directories (pool type dir).
5387 [--source-dev path] provides the source path for pools backed by physi‐
5389 cal devices (pool types fs, logical, disk, iscsi, zfs).
5390 [--source-name name] provides the source name for pools backed by stor‐
5392 age from a named element (pool types logical, rbd, sheepdog, gluster).
5393 [--target path] is the path for the mapping of the storage pool into
5395 the host file system.
5396 [--source-format format] provides information about the format of the
5398 pool (pool types fs, netfs, disk, logical).
5399 [--source-initiator initiator-iqn] provides the initiator iqn for iscsi
5401 connection of the pool (pool type iscsi-direct).
5402 [--auth-type authtype --auth-username username [--secret-usage usage |
5404 --secret-uuid uuid]] provides the elements required to generate authen‐
5405 tication credentials for the storage pool. The authtype is either chap
5406 for iscsi type pools or ceph for rbd type pools. Either the secret us‐
5407 age or uuid value may be provided, but not both.
5408 [--source-protocol-ver ver] provides the NFS protocol version number
5410 used to contact the server's NFS service via nfs mount option
5411 'nfsvers=n'. It is expect the ver value is an unsigned integer.
5412 [--adapter-name name] defines the scsi_hostN adapter name to be used
5414 for the scsi_host adapter type pool.
5415 [--adapter-wwnn wwnn --adapter-wwpn wwpn [--adapter-parent parent |
5417 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
5418 --adapter-parent-fabric-wwn parent_fabric_wwn]] defines the wwnn and
5419 wwpn to be used for the fc_host adapter type pool. Optionally provide
5420 the parent scsi_hostN node device to be used for the vHBA either by
5421 parent name, parent_wwnn and parent_wwpn, or parent_fabric_wwn. The
5422 parent name could change between reboots if the hardware environment
5423 changes, so providing the parent_wwnn and parent_wwpn ensure usage of
5424 the same physical HBA even if the scsi_hostN node device changes. Usage
5425 of the parent_fabric_wwn allows a bit more flexibility to choose an HBA
5426 on the same storage fabric in order to define the pool.
5427 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
5429 creation in order to remove the need for a follow-up command to build
5430 the pool. The --overwrite and --no-overwrite flags follow the same
5431 rules as pool-build. If just --build is provided, then pool-build is
5432 called with no flags.
5433 For a "logical" pool only [--name] needs to be provided. The
5435 [--source-name] if provided must match the Volume Group name. If not
5436 provided, one will be generated using the [--name]. If provided the
5437 [--target] is ignored and a target source is generated using the
5438 [--source-name] (or as generated from the [--name]).
5439 pool-define
5441 Syntax:
5442 pool-define file [--validate]
5444 Define an inactive persistent storage pool or modify an existing per‐
5446 sistent one from the XML file. Optionally, the format of the input XML
5447 file can be validated against an internal RNG schema with --validate.
5448 pool-define-as
5450 Syntax:
5451 pool-define-as name type
5453 [--source-host hostname] [--source-path path] [--source-dev path]
5454 [*--source-name name*] [*--target path*] [*--source-format format*]
5455 [--source-initiator initiator-iqn]
5456 [*--auth-type authtype* *--auth-username username*
5457 [*--secret-usage usage* | *--secret-uuid uuid*]]
5458 [*--source-protocol-ver ver*]
5459 [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*]
5460 [*--adapter-parent parent*]] [*--print-xml*]
5461 Create, but do not start, a pool object name from the raw parameters.
5463 If --print-xml is specified, then print the XML of the pool object
5464 without defining the pool. Otherwise, the pool has the specified type.
5465 Use the same arguments as pool-create-as, except for the --build,
5467 --overwrite, and --no-overwrite options.
5468 pool-destroy
5470 Syntax:
5471 pool-destroy pool-or-uuid
5473 Destroy (stop) a given pool object. Libvirt will no longer manage the
5475 storage described by the pool object, but the raw data contained in the
5476 pool is not changed, and can be later recovered with pool-create.
5477 pool-delete
5479 Syntax:
5480 pool-delete pool-or-uuid
5482 Destroy the resources used by a given pool object. This operation is
5484 non-recoverable. The pool object will still exist after this command,
5485 ready for the creation of new storage volumes.
5486 pool-dumpxml
5488 Syntax:
5489 pool-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] pool-or-uuid
5491 Returns the XML information about the pool object. --inactive tells
5493 virsh to dump pool configuration that will be used on next start of the
5494 pool as opposed to the current pool configuration.
5495 If the --xpath argument provides an XPath expression, it will be evalu‐
5497 ated against the output XML and only those matching nodes will be
5498 printed. The default behaviour is to print each matching node as a
5499 standalone document, however, for ease of additional processing, the
5500 --wrap argument will cause the matching node to be wrapped in a common
5501 root node.
5502 pool-edit
5504 Syntax:
5505 pool-edit pool-or-uuid
5507 Edit the XML configuration file for a storage pool.
5509 This is equivalent to:
5511 virsh pool-dumpxml pool > pool.xml
5513 vi pool.xml (or make changes with your other text editor)
5514 virsh pool-define pool.xml
5515 except that it does some error checking.
5517 The editor used can be supplied by the $VISUAL or $EDITOR environment
5519 variables, and defaults to vi.
5520 pool-info
5522 Syntax:
5523 pool-info [--bytes] pool-or-uuid
5525 Returns basic information about the pool object. If --bytes is speci‐
5527 fied the sizes of basic info are not converted to human friendly units.
5528 pool-list
5530 Syntax:
5531 pool-list [--inactive] [--all]
5533 [--persistent] [--transient]
5534 [--autostart] [--no-autostart]
5535 [[--details] [--uuid]
5536 [--name] [<type>]
5537 List pool objects known to libvirt. By default, only active pools are
5539 listed; --inactive lists just the inactive pools, and --all lists all
5540 pools.
5541 In addition, there are several sets of filtering flags. --persistent is
5543 to list the persistent pools, --transient is to list the transient
5544 pools. --autostart lists the autostarting pools, --no-autostart lists
5545 the pools with autostarting disabled. If --uuid is specified only
5546 pool's UUIDs are printed. If --name is specified only pool's names are
5547 printed. If both --name and --uuid are specified, pool's UUID and names
5548 are printed side by side without any header. Option --details is mutu‐
5549 ally exclusive with options --uuid and --name.
5550 You may also want to list pools with specified types using type, the
5552 pool types must be separated by comma, e.g. --type dir,disk. The valid
5553 pool types include 'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi',
5554 'scsi', 'mpath', 'rbd', 'sheepdog', 'gluster', 'zfs', 'vstorage' and
5555 'iscsi-direct'.
5556 The --details option instructs virsh to additionally display pool per‐
5558 sistence and capacity related information where available.
5559 NOTE: When talking to older servers, this command is forced to use a
5561 series of API calls with an inherent race, where a pool might not be
5562 listed or might appear more than once if it changed state between calls
5563 while the list was being collected. Newer servers do not have this
5564 problem.
5565 pool-name
5567 Syntax:
5568 pool-name uuid
5570 Convert the uuid to a pool name.
5572 pool-refresh
5574 Syntax:
5575 pool-refresh pool-or-uuid
5577 Refresh the list of volumes contained in pool.
5579 pool-start
5581 Syntax:
5582 pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]
5584 Start the storage pool, which is previously defined but inactive.
5586 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build prior
5588 to pool-start to ensure the pool environment is in an expected state
5589 rather than needing to run the build command prior to startup. The
5590 --overwrite and --no-overwrite flags follow the same rules as
5591 pool-build. If just --build is provided, then pool-build is called with
5592 no flags.
5593 Note: A storage pool that relies on remote resources such as an "iscsi"
5595 or a (v)HBA backed "scsi" pool may need to be refreshed multiple times
5596 in order to have all the volumes detected (see pool-refresh). This is
5597 because the corresponding volume devices may not be present in the
5598 host's filesystem during the initial pool startup or the current re‐
5599 fresh attempt. The number of refresh retries is dependent upon the net‐
5600 work connection and the time the host takes to export the corresponding
5601 devices.
5602 pool-undefine
5604 Syntax:
5605 pool-undefine pool-or-uuid
5607 Undefine the configuration for an inactive pool.
5609 pool-uuid
5611 Syntax:
5612 pool-uuid pool
5614 Returns the UUID of the named pool.
5616 pool-event
5618 Syntax:
5619 pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list}
5621 Wait for a class of storage pool events to occur, and print appropriate
5623 details of events as they happen. The events can optionally be fil‐
5624 tered by pool. Using --list as the only argument will provide a list
5625 of possible event values known by this client, although the connection
5626 might not allow registering for all these events.
5627 By default, this command is one-shot, and returns success once an event
5629 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
5630 If --timeout is specified, the command gives up waiting for events af‐
5631 ter seconds have elapsed. With --loop, the command prints all events
5632 until a timeout or interrupt key.
5633 When --timestamp is used, a human-readable timestamp will be printed
5635 before the event.
5636
5638 vol-create
5639 Syntax:
5640 vol-create pool-or-uuid FILE [--prealloc-metadata] [--validate]
5642 Create a volume from an XML <file>.
5644 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5646 ume in.
5647 FILE is the XML <file> with the volume definition. An easy way to cre‐
5649 ate the XML <file> is to use the vol-dumpxml command to obtain the def‐
5650 inition of a pre-existing volume.
5651 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5653 don't support full allocation). This option creates a sparse image file
5654 with metadata, resulting in higher performance compared to images with
5655 no preallocation and only slightly higher initial disk space usage.
5656 If --validate is specified, validates the format of the XML document
5658 against an internal RNG schema.
5659 Example:
5661 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
5663 vi newvolume.xml (or make changes with your other text editor)
5664 virsh vol-create differentstoragepool newvolume.xml
5665 vol-create-from
5667 Syntax:
5668 vol-create-from pool-or-uuid FILE vol-name-or-key-or-path
5670 [--inputpool pool-or-uuid] [--prealloc-metadata] [--reflink] [--validate]
5671 Create a volume, using another volume as input.
5673 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5675 ume in.
5676 FILE is the XML <file> with the volume definition.
5678 vol-name-or-key-or-path is the name or key or path of the source vol‐
5680 ume.
5681 --inputpool pool-or-uuid is the name or uuid of the storage pool the
5683 source volume is in.
5684 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5686 don't support full allocation). This option creates a sparse image file
5687 with metadata, resulting in higher performance compared to images with
5688 no preallocation and only slightly higher initial disk space usage.
5689 When --reflink is specified, perform a COW lightweight copy, where the
5691 data blocks are copied only when modified. If this is not possible,
5692 the copy fails.
5693 If --validate is specified, validates the format of the XML document
5695 against an internal RNG schema.
5696 vol-create-as
5698 Syntax:
5699 vol-create-as pool-or-uuid name capacity [--allocation size] [--format string]
5701 [--backing-vol vol-name-or-key-or-path]
5702 [--backing-vol-format string] [--prealloc-metadata] [--print-xml]
5703 Create a volume from a set of arguments unless --print-xml is speci‐
5705 fied, in which case just the XML of the volume object is printed out
5706 without any actual object creation.
5707 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5709 ume in.
5710 name is the name of the new volume. For a disk pool, this must match
5712 the partition name as determined from the pool's source device path and
5713 the next available partition. For example, a source device path of
5714 /dev/sdb and there are no partitions on the disk, then the name must be
5715 sdb1 with the next name being sdb2 and so on.
5716 capacity is the size of the volume to be created, as a scaled integer
5718 (see NOTES above), defaulting to bytes if there is no suffix.
5719 --allocation size is the initial size to be allocated in the volume,
5721 also as a scaled integer defaulting to bytes.
5722 --format string is used in file based storage pools to specify the vol‐
5724 ume file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use ex‐
5725 tended for disk storage pools in order to create an extended partition
5726 (other values are validity checked but not preserved when libvirtd is
5727 restarted or the pool is refreshed).
5728 --backing-vol vol-name-or-key-or-path is the source backing volume to
5730 be used if taking a snapshot of an existing volume.
5731 --backing-vol-format string is the format of the snapshot backing vol‐
5733 ume; raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, how‐
5734 ever, meant for file based storage pools.
5735 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5737 don't support full allocation). This option creates a sparse image file
5738 with metadata, resulting in higher performance compared to images with
5739 no preallocation and only slightly higher initial disk space usage.
5740 vol-clone
5742 Syntax:
5743 vol-clone vol-name-or-key-or-path name
5745 [--pool pool-or-uuid] [--prealloc-metadata] [--reflink] [--print-xml]
5746 Clone an existing volume within the parent pool. Less powerful, but
5748 easier to type, version of vol-create-from.
5749 vol-name-or-key-or-path is the name or key or path of the source vol‐
5751 ume.
5752 name is the name of the new volume.
5754 --pool pool-or-uuid is the name or UUID of the storage pool that con‐
5756 tains the source volume and will contain the new volume. If the source
5757 volume name is provided instead of the key or path, then providing the
5758 pool is necessary to find the volume to be cloned; otherwise, the first
5759 volume found by the key or path will be used.
5760 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5762 don't support full allocation). This option creates a sparse image file
5763 with metadata, resulting in higher performance compared to images with
5764 no preallocation and only slightly higher initial disk space usage.
5765 When --reflink is specified, perform a COW lightweight copy, where the
5767 data blocks are copied only when modified. If this is not possible,
5768 the copy fails.
5769 If --print-xml is specified, then the XML used to clone the volume is
5771 printed instead.
5772 vol-delete
5774 Syntax:
5775 vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots]
5777 Delete a given volume.
5779 vol-name-or-key-or-path is the volume name or key or path of the volume
5781 to delete.
5782 [--pool pool-or-uuid] is the name or UUID of the storage pool the vol‐
5784 ume is in. If the volume name is provided instead of the key or path,
5785 then providing the pool is necessary to find the volume to be deleted;
5786 otherwise, the first volume found by the key or path will be used.
5787 The --delete-snapshots flag specifies that any snapshots associated
5789 with the storage volume should be deleted as well. Not all storage
5790 drivers support this option, presently only rbd.
5791 vol-upload
5793 Syntax:
5794 vol-upload vol-name-or-key-or-path local-file
5796 [--pool pool-or-uuid] [--offset bytes]
5797 [--length bytes] [--sparse]
5798 Upload the contents of local-file to a storage volume.
5800 vol-name-or-key-or-path is the name or key or path of the volume where
5802 the local-file will be uploaded.
5803 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5805 is in. If the volume name is provided instead of the key or path, then
5806 providing the pool is necessary to find the volume to be uploaded into;
5807 otherwise, the first volume found by the key or path will be used.
5808 --offset is the position in the storage volume at which to start writ‐
5810 ing the data. The value must be 0 or larger.
5811 --length is an upper bound of the amount of data to be uploaded. A
5813 negative value is interpreted as an unsigned long long value to essen‐
5814 tially include everything from the offset to the end of the volume.
5815 If --sparse is specified, this command will preserve volume sparseness.
5817 An error will occur if the local-file is greater than the specified
5819 length.
5820 See the description for the libvirt virStorageVolUpload API for details
5822 regarding possible target volume and pool changes as a result of the
5823 pool refresh when the upload is attempted.
5824 vol-download
5826 Syntax:
5827 vol-download vol-name-or-key-or-path local-file
5829 [--pool pool-or-uuid] [--offset bytes] [--length bytes]
5830 [--sparse]
5831 Download the contents of a storage volume to local-file.
5833 vol-name-or-key-or-path is the name or key or path of the volume to
5835 download into local-file.
5836 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5838 is in. If the volume name is provided instead of the key or path, then
5839 providing the pool is necessary to find the volume to be uploaded into;
5840 otherwise, the first volume found by the key or path will be used.
5841 --offset is the position in the storage volume at which to start read‐
5843 ing the data. The value must be 0 or larger.
5844 --length is an upper bound of the amount of data to be downloaded. A
5846 negative value is interpreted as an unsigned long long value to essen‐
5847 tially include everything from the offset to the end of the volume.
5848 If --sparse is specified, this command will preserve volume sparseness.
5850 vol-wipe
5852 Syntax:
5853 vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm]
5855 Wipe a volume, ensure data previously on the volume is not accessible
5857 to future reads.
5858 vol-name-or-key-or-path is the name or key or path of the volume to
5860 wipe. It is possible to choose different wiping algorithms instead of
5861 re-writing volume with zeroes.
5862 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5864 is in. If the volume name is provided instead of the key or path, then
5865 providing the pool is necessary to find the volume to be wiped; other‐
5866 wise, the first volume found by the key or path will be used.
5867 Use the --algorithm switch choosing from the list of the following al‐
5869 gorithms in order to define which algorithm to use for the wipe.
5870 Supported algorithms
5872 • zero - 1-pass all zeroes
5874 • nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for sani‐
5876 tizing removable and non-removable hard disks: random x2, 0x00, ver‐
5877 ify.
5878 • dod - 4-pass DoD 5220.22-M section 8-306 procedure for sani‐
5880 tizing removable and non-removable rigid disks: random, 0x00, 0xff,
5881 verify.
5882 • bsi - 9-pass method recommended by the German Center of Secu‐
5884 rity in Information Technologies (https://www.bsi.bund.de): 0xff,
5885 0xfe, 0xfd, 0xfb, 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
5886 • gutmann - The canonical 35-pass sequence described in Gutmann's
5888 paper.
5889 • schneier - 7-pass method described by Bruce Schneier in "Applied
5891 Cryptography" (1996): 0x00, 0xff, random x5.
5892 • pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7.
5894 • pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
5896 • random - 1-pass pattern: random.
5898 • trim - 1-pass trimming the volume using TRIM or DISCARD
5900 Note: The scrub binary will be used to handle the 'nnsa', 'dod', 'bsi',
5902 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33' algorithms. The
5903 availability of the algorithms may be limited by the version of the
5904 scrub binary installed on the host. The 'zero' algorithm will write ze‐
5905 roes to the entire volume. For some volumes, such as sparse or rbd vol‐
5906 umes, this may result in completely filling the volume with zeroes mak‐
5907 ing it appear to be completely full. As an alternative, the 'trim' al‐
5908 gorithm does not overwrite all the data in a volume, rather it expects
5909 the storage driver to be able to discard all bytes in a volume. It is
5910 up to the storage driver to handle how the discarding occurs. Not all
5911 storage drivers or volume types can support 'trim'.
5912 vol-dumpxml
5914 Syntax:
5915 vol-dumpxml [--pool pool-or-uuid] [--xpath EXPRESSION] [--wrap]
5917 vol-name-or-key-or-path
5918 Output the volume information as an XML dump to stdout.
5920 vol-name-or-key-or-path is the name or key or path of the volume to
5922 output the XML.
5923 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5925 is in. If the volume name is provided instead of the key or path, then
5926 providing the pool is necessary to find the volume to be uploaded into;
5927 otherwise, the first volume found by the key or path will be used.
5928 If the --xpath argument provides an XPath expression, it will be evalu‐
5930 ated against the output XML and only those matching nodes will be
5931 printed. The default behaviour is to print each matching node as a
5932 standalone document, however, for ease of additional processing, the
5933 --wrap argument will cause the matching node to be wrapped in a common
5934 root node.
5935 vol-info
5937 Syntax:
5938 vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical]
5940 Returns basic information about the given storage volume.
5942 vol-name-or-key-or-path is the name or key or path of the volume to re‐
5944 turn information for.
5945 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5947 is in. If the volume name is provided instead of the key or path, then
5948 providing the pool is necessary to find the volume to be uploaded into;
5949 otherwise, the first volume found by the key or path will be used.
5950 If --bytes is specified the sizes are not converted to human friendly
5952 units.
5953 If --physical is specified, then the host physical size is returned and
5955 displayed instead of the allocation value. The physical value for some
5956 file types, such as qcow2 may have a different (larger) physical value
5957 than is shown for allocation. Additionally sparse files will have dif‐
5958 ferent physical and allocation values.
5959 vol-list
5961 Syntax:
5962 vol-list [--pool pool-or-uuid] [--details]
5964 Return the list of volumes in the given storage pool.
5966 --pool pool-or-uuid is the name or UUID of the storage pool.
5968 The --details option instructs virsh to additionally display volume
5970 type and capacity related information where available.
5971 vol-pool
5973 Syntax:
5974 vol-pool vol-key-or-path [--uuid]
5976 Return the pool name or UUID for a given volume. By default, the pool
5978 name is returned.
5979 vol-key-or-path is the key or path of the volume to return the pool in‐
5981 formation.
5982 If the --uuid option is given, the pool UUID is returned instead.
5984 vol-path
5986 Syntax:
5987 vol-path vol-name-or-key [--pool pool-or-uuid]
5989 Return the path for a given volume.
5991 vol-name-or-key is the name or key of the volume to return the path.
5993 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5995 is in. If the volume name is provided instead of the key, then provid‐
5996 ing the pool is necessary to find the volume to be uploaded into; oth‐
5997 erwise, the first volume found by the key will be used.
5998 vol-name
6000 Syntax:
6001 vol-name vol-key-or-path
6003 Return the name for a given volume.
6005 vol-key-or-path is the key or path of the volume to return the name.
6007 vol-key
6009 Syntax:
6010 vol-key vol-name-or-path [--pool pool-or-uuid]
6012 Return the volume key for a given volume.
6014 vol-name-or-path is the name or path of the volume to return the volume
6016 key.
6017 --pool pool-or-uuid is the name or UUID of the storage pool the volume
6019 is in. If the volume name is provided instead of the path, then provid‐
6020 ing the pool is necessary to find the volume to be uploaded into; oth‐
6021 erwise, the first volume found by the path will be used.
6022 vol-resize
6024 Syntax:
6025 vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink]
6027 Resize the capacity of the given volume, in bytes.
6029 vol-name-or-key-or-path is the name or key or path of the volume to re‐
6031 size.
6032 capacity is a scaled integer (see NOTES above) for the volume, which
6034 defaults to bytes if there is no suffix.
6035 --pool pool-or-uuid is the name or UUID of the storage pool the volume
6037 is in. If the volume name is provided instead of the key or path, then
6038 providing the pool is necessary to find the volume to be uploaded into;
6039 otherwise, the first volume found by the key or path will be used.
6040 The new capacity might be sparse unless --allocate is specified.
6042 Normally, capacity is the new size, but if --delta is present, then it
6044 is added to the existing size.
6045 Attempts to shrink the volume will fail unless --shrink is present.
6047 The capacity cannot be negative unless --shrink is provided, but a neg‐
6048 ative sign is not necessary.
6049 This command is only safe for storage volumes not in use by an active
6051 guest; see also blockresize for live resizing.
6052
6054 The following commands manipulate "secrets" (e.g. passwords,
6055 passphrases and encryption keys). Libvirt can store secrets indepen‐
6056 dently from their use, and other objects (e.g. volumes or domains) can
6057 refer to the secrets for encryption or possibly other uses. Secrets
6058 are identified using a UUID. See https://libvirt.org/formatsecret.html
6059 for documentation of the XML format used to represent properties of se‐
6060 crets.
6061 secret-define
6063 Syntax:
6064 secret-define file [--validate]
6066 Create a secret with the properties specified in file, with no associ‐
6068 ated secret value. If file does not specify a UUID, choose one auto‐
6069 matically. If file specifies a UUID of an existing secret, replace its
6070 properties by properties defined in file, without affecting the secret
6071 value.
6072 Optionally, the format of the input XML file can be validated against
6074 an internal RNG schema with --validate.
6075 secret-dumpxml
6077 Syntax:
6078 secret-dumpxml [--xpath EXPRESSION] [--wrap] secret
6080 Output properties of secret (specified by its UUID) as an XML dump to
6082 stdout.
6083 If the --xpath argument provides an XPath expression, it will be evalu‐
6085 ated against the output XML and only those matching nodes will be
6086 printed. The default behaviour is to print each matching node as a
6087 standalone document, however, for ease of additional processing, the
6088 --wrap argument will cause the matching node to be wrapped in a common
6089 root node.
6090 secret-event
6092 Syntax:
6093 secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list}
6095 Wait for a class of secret events to occur, and print appropriate de‐
6097 tails of events as they happen. The events can optionally be filtered
6098 by secret. Using --list as the only argument will provide a list of
6099 possible event values known by this client, although the connection
6100 might not allow registering for all these events.
6101 By default, this command is one-shot, and returns success once an event
6103 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
6104 If --timeout is specified, the command gives up waiting for events af‐
6105 ter seconds have elapsed. With --loop, the command prints all events
6106 until a timeout or interrupt key.
6107 When --timestamp is used, a human-readable timestamp will be printed
6109 before the event.
6110 secret-set-value
6112 Syntax:
6113 secret-set-value secret (--file filename [--plain] | --interactive | base64)
6115 Set the value associated with secret (specified by its UUID) to the
6117 value Base64-encoded value base64 or Base-64-encoded contents of file
6118 named filename. Using the --plain flag is together with --file allows
6119 one to use the file contents directly as the secret value.
6120 If --interactive flag is used the secret value is read as a password
6122 from the terminal.
6123 Note that --file, --interactive and base64 options are mutually exclu‐
6125 sive.
6126 Passing secrets via the base64 option on command line is INSECURE and
6128 deprecated. Use the --file option instead.
6129 secret-get-value
6131 Syntax:
6132 secret-get-value [--plain] secret
6134 Output the value associated with secret (specified by its UUID) to std‐
6136 out, encoded using Base64.
6137 If the --plain flag is used the value is not base64 encoded, but rather
6139 printed raw. Note that unless virsh is started in quiet mode (virsh -q)
6140 it prints a newline at the end of the command. This newline is not part
6141 of the secret.
6142 secret-undefine
6144 Syntax:
6145 secret-undefine secret
6147 Delete a secret (specified by its UUID), including the associated
6149 value, if any.
6150 secret-list
6152 Syntax:
6153 secret-list [--ephemeral] [--no-ephemeral]
6155 [--private] [--no-private]
6156 Returns the list of secrets. You may also want to filter the returned
6158 secrets by --ephemeral to list the ephemeral ones, --no-ephemeral to
6159 list the non-ephemeral ones, --private to list the private ones, and
6160 --no-private to list the non-private ones.
6161
6163 The following commands manipulate domain snapshots. Snapshots take the
6164 disk, memory, and device state of a domain at a point-of-time, and save
6165 it for future use. They have many uses, from saving a "clean" copy of
6166 an OS image to saving a domain's state before a potentially destructive
6167 operation. Snapshots are identified with a unique name. See
6168 https://libvirt.org/formatsnapshot.html for documentation of the XML
6169 format used to represent properties of snapshots.
6170 snapshot-create
6172 Syntax:
6173 snapshot-create domain [xmlfile] {[--redefine [--current]] |
6175 [--no-metadata] [--halt] [--disk-only] [--reuse-external]
6176 [--quiesce] [--atomic] [--live]} [--validate]
6177 Create a snapshot for domain domain with the properties specified in
6179 xmlfile. Optionally, the --validate option can be passed to validate
6180 the format of the input XML file against an internal RNG schema (iden‐
6181 tical to using the virt-xml-validate(1) tool). Normally, the only prop‐
6182 erties settable for a domain snapshot are the <name> and <description>
6183 elements, as well as <disks> if --disk-only is given; the rest of the
6184 fields are ignored, and automatically filled in by libvirt. If xmlfile
6185 is completely omitted, then libvirt will choose a value for all fields.
6186 The new snapshot will become current, as listed by snapshot-current.
6187 If --halt is specified, the domain will be left in an inactive state
6189 after the snapshot is created.
6190 If --disk-only is specified, the snapshot will only include disk con‐
6192 tent rather than the usual full system snapshot with vm state. Disk
6193 snapshots are captured faster than full system snapshots, but reverting
6194 to a disk snapshot may require fsck or journal replays, since it is
6195 like the disk state at the point when the power cord is abruptly
6196 pulled; and mixing --halt and --disk-only loses any data that was not
6197 flushed to disk at the time.
6198 If --redefine is specified, then all XML elements produced by snap‐
6200 shot-dumpxml are valid; this can be used to migrate snapshot hierarchy
6201 from one machine to another, to recreate hierarchy for the case of a
6202 transient domain that goes away and is later recreated with the same
6203 name and UUID, or to make slight alterations in the snapshot metadata
6204 (such as host-specific aspects of the domain XML embedded in the snap‐
6205 shot). When this flag is supplied, the xmlfile argument is mandatory,
6206 and the domain's current snapshot will not be altered unless the --cur‐
6207 rent flag is also given.
6208 If --no-metadata is specified, then the snapshot data is created, but
6210 any metadata is immediately discarded (that is, libvirt does not treat
6211 the snapshot as current, and cannot revert to the snapshot unless --re‐
6212 define is later used to teach libvirt about the metadata again).
6213 If --reuse-external is specified, and the snapshot XML requests an ex‐
6215 ternal snapshot with a destination of an existing file, then the desti‐
6216 nation must exist and be pre-created with correct format and metadata.
6217 The file is then reused; otherwise, a snapshot is refused to avoid los‐
6218 ing contents of the existing files.
6219 If --quiesce is specified, libvirt will try to use guest agent to
6221 freeze and unfreeze domain's mounted file systems. However, if domain
6222 has no guest agent, snapshot creation will fail. Currently, this re‐
6223 quires --disk-only to be passed as well.
6224 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
6226 ther succeeds, or fails with no changes; not all hypervisors support
6227 this. If this flag is not specified, then some hypervisors may fail
6228 after partially performing the action, and dumpxml must be used to see
6229 whether any partial changes occurred.
6230 If --live is specified, libvirt takes the snapshot while the guest is
6232 running. Both disk snapshot and domain memory snapshot are taken. This
6233 increases the size of the memory image of the external snapshot. This
6234 is currently supported only for full system external snapshots.
6235 Existence of snapshot metadata will prevent attempts to undefine a per‐
6237 sistent guest. However, for transient domains, snapshot metadata is
6238 silently lost when the domain quits running (whether by command such as
6239 destroy or by internal guest action).
6240 For now, it is not possible to create snapshots in a domain that has
6242 checkpoints, although this restriction will be lifted in a future re‐
6243 lease.
6244 snapshot-create-as
6246 Syntax:
6247 snapshot-create-as domain {[--print-xml] [--no-metadata]
6249 [--halt] [--reuse-external]} [name]
6250 [description] [--disk-only [--quiesce]] [--atomic] [--validate]
6251 [[--live] [--memspec memspec]] [--diskspec] diskspec]...
6252 Create a snapshot for domain domain with the given <name> and <descrip‐
6254 tion>; if either value is omitted, libvirt will choose a value. If
6255 --print-xml is specified, then XML appropriate for snapshot-create is
6256 output, rather than actually creating a snapshot. Otherwise, if --halt
6257 is specified, the domain will be left in an inactive state after the
6258 snapshot is created, and if --disk-only is specified, the snapshot will
6259 not include vm state.
6260 The --memspec option can be used to control whether a full system snap‐
6262 shot is internal or external. The --memspec flag is mandatory, fol‐
6263 lowed by a memspec of the form [file=]name[,snapshot=type], where type
6264 can be no, internal, or external. To include a literal comma in
6265 file=name, escape it with a second comma. --memspec cannot be used to‐
6266 gether with --disk-only.
6267 The --diskspec option can be used to control how --disk-only and exter‐
6269 nal full system snapshots create external files. This option can occur
6270 multiple times, according to the number of <disk> elements in the do‐
6271 main xml. Each <diskspec> is in the form disk[,snap‐
6272 shot=type][,driver=type][,stype=type][,file=name]. A diskspec must be
6273 provided for disks backed by block devices as libvirt doesn't auto-gen‐
6274 erate file names for those. The optional stype parameter allows one to
6275 control the type of the source file. Supported values are 'file' (de‐
6276 fault) and 'block'. To exclude a disk from an external snapshot use
6277 --diskspec disk,snapshot=no.
6278 To include a literal comma in disk or in file=name, escape it with a
6280 second comma. A literal --diskspec must precede each diskspec unless
6281 all three of domain, name, and description are also present. For exam‐
6282 ple, a diskspec of "vda,snapshot=external,file=/path/to,,new" results
6283 in the following XML:
6284 <disk name='vda' snapshot='external'>
6286 <source file='/path/to,new'/>
6287 </disk>
6288 If --reuse-external is specified, and the domain XML or diskspec option
6290 requests an external snapshot with a destination of an existing file,
6291 then the destination must exist and be pre-created with correct format
6292 and metadata. The file is then reused; otherwise, a snapshot is refused
6293 to avoid losing contents of the existing files.
6294 If --quiesce is specified, libvirt will try to use guest agent to
6296 freeze and unfreeze domain's mounted file systems. However, if domain
6297 has no guest agent, snapshot creation will fail. Currently, this re‐
6298 quires --disk-only to be passed as well.
6299 If --no-metadata is specified, then the snapshot data is created, but
6301 any metadata is immediately discarded (that is, libvirt does not treat
6302 the snapshot as current, and cannot revert to the snapshot unless snap‐
6303 shot-create is later used to teach libvirt about the metadata again).
6304 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
6306 ther succeeds, or fails with no changes; not all hypervisors support
6307 this. If this flag is not specified, then some hypervisors may fail
6308 after partially performing the action, and dumpxml must be used to see
6309 whether any partial changes occurred.
6310 If --live is specified, libvirt takes the snapshot while the guest is
6312 running. This increases the size of the memory image of the external
6313 snapshot. This is currently supported only for external full system
6314 snapshots.
6315 For now, it is not possible to create snapshots in a domain that has
6317 checkpoints, although this restriction will be lifted in a future re‐
6318 lease.
6319 Optionally, the --validate option can be passed to validate XML docu‐
6321 ment which is internally generated by this command against the internal
6322 RNG schema.
6323 snapshot-current
6325 Syntax:
6326 snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
6328 Without snapshotname, this will output the snapshot XML for the do‐
6330 main's current snapshot (if any). If --name is specified, just the
6331 current snapshot name instead of the full xml. Otherwise, using --se‐
6332 curity-info will also include security sensitive information in the
6333 XML.
6334 With snapshotname, this is a request to make the existing named snap‐
6336 shot become the current snapshot, without reverting the domain.
6337 snapshot-edit
6339 Syntax:
6340 snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]}
6342 Edit the XML configuration file for snapshotname of a domain. If both
6344 snapshotname and --current are specified, also force the edited snap‐
6345 shot to become the current snapshot. If snapshotname is omitted, then
6346 --current must be supplied, to edit the current snapshot.
6347 This is equivalent to:
6349 virsh snapshot-dumpxml dom name > snapshot.xml
6351 vi snapshot.xml (or make changes with your other text editor)
6352 virsh snapshot-create dom snapshot.xml --redefine [--current]
6353 except that it does some error checking.
6355 The editor used can be supplied by the $VISUAL or $EDITOR environment
6357 variables, and defaults to vi.
6358 If --rename is specified, then the edits can change the snapshot name.
6360 If --clone is specified, then changing the snapshot name will create a
6361 clone of the snapshot metadata. If neither is specified, then the ed‐
6362 its must not change the snapshot name. Note that changing a snapshot
6363 name must be done with care, since the contents of some snapshots, such
6364 as internal snapshots within a single qcow2 file, are accessible only
6365 from the original name.
6366 snapshot-info
6368 Syntax:
6369 snapshot-info domain {snapshot | --current}
6371 Output basic information about a named <snapshot>, or the current snap‐
6373 shot with --current.
6374 snapshot-list
6376 Syntax:
6377 snapshot-list domain [--metadata] [--no-metadata]
6379 [{--parent | --roots | [{--tree | --name}]}] [--topological]
6380 [{[--from] snapshot | --current} [--descendants]]
6381 [--leaves] [--no-leaves] [--inactive] [--active]
6382 [--disk-only] [--internal] [--external]
6383 List all of the available snapshots for the given domain, defaulting to
6385 show columns for the snapshot name, creation time, and domain state.
6386 Normally, table form output is sorted by snapshot name; using --topo‐
6388 logical instead sorts so that no child is listed before its ancestors
6389 (although there may be more than one possible ordering with this prop‐
6390 erty).
6391 If --parent is specified, add a column to the output table giving the
6393 name of the parent of each snapshot. If --roots is specified, the list
6394 will be filtered to just snapshots that have no parents. If --tree is
6395 specified, the output will be in a tree format, listing just snapshot
6396 names. These three options are mutually exclusive. If --name is speci‐
6397 fied only the snapshot name is printed. This option is mutually exclu‐
6398 sive with --tree.
6399 If --from is provided, filter the list to snapshots which are children
6401 of the given snapshot; or if --current is provided, start at the cur‐
6402 rent snapshot. When used in isolation or with --parent, the list is
6403 limited to direct children unless --descendants is also present. When
6404 used with --tree, the use of --descendants is implied. This option is
6405 not compatible with --roots. Note that the starting point of --from or
6406 --current is not included in the list unless the --tree option is also
6407 present.
6408 If --leaves is specified, the list will be filtered to just snapshots
6410 that have no children. Likewise, if --no-leaves is specified, the list
6411 will be filtered to just snapshots with children. (Note that omitting
6412 both options does no filtering, while providing both options will ei‐
6413 ther produce the same list or error out depending on whether the server
6414 recognizes the flags). Filtering options are not compatible with
6415 --tree.
6416 If --metadata is specified, the list will be filtered to just snapshots
6418 that involve libvirt metadata, and thus would prevent undefine of a
6419 persistent guest, or be lost on destroy of a transient domain. Like‐
6420 wise, if --no-metadata is specified, the list will be filtered to just
6421 snapshots that exist without the need for libvirt metadata.
6422 If --inactive is specified, the list will be filtered to snapshots that
6424 were taken when the domain was shut off. If --active is specified, the
6425 list will be filtered to snapshots that were taken when the domain was
6426 running, and where the snapshot includes the memory state to revert to
6427 that running state. If --disk-only is specified, the list will be fil‐
6428 tered to snapshots that were taken when the domain was running, but
6429 where the snapshot includes only disk state.
6430 If --internal is specified, the list will be filtered to snapshots that
6432 use internal storage of existing disk images. If --external is speci‐
6433 fied, the list will be filtered to snapshots that use external files
6434 for disk images or memory state.
6435 snapshot-dumpxml
6437 Syntax:
6438 snapshot-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap]
6440 domain snapshot
6441 Output the snapshot XML for the domain's snapshot named snapshot. Us‐
6443 ing --security-info will also include security sensitive information.
6444 Use snapshot-current to easily access the XML of the current snapshot.
6445 If the --xpath argument provides an XPath expression, it will be evalu‐
6447 ated against the output XML and only those matching nodes will be
6448 printed. The default behaviour is to print each matching node as a
6449 standalone document, however, for ease of additional processing, the
6450 --wrap argument will cause the matching node to be wrapped in a common
6451 root node.
6452 snapshot-parent
6454 Syntax:
6455 snapshot-parent domain {snapshot | --current}
6457 Output the name of the parent snapshot, if any, for the given snapshot,
6459 or for the current snapshot with --current.
6460 snapshot-revert
6462 Syntax:
6463 snapshot-revert domain {snapshot | --current} [{--running | --paused}]
6465 [--force] [--reset-nvram]
6466 Revert the given domain to the snapshot specified by snapshot, or to
6468 the current snapshot with --current. Be aware that this is a destruc‐
6469 tive action; any changes in the domain since the last snapshot was
6470 taken will be lost. Also note that the state of the domain after snap‐
6471 shot-revert is complete will be the state of the domain at the time the
6472 original snapshot was taken.
6473 Normally, reverting to a snapshot leaves the domain in the state it was
6475 at the time the snapshot was created, except that a disk snapshot with
6476 no vm state leaves the domain in an inactive state. Passing either the
6477 --running or --paused flag will perform additional state changes (such
6478 as booting an inactive domain, or pausing a running domain). Since
6479 transient domains cannot be inactive, it is required to use one of
6480 these flags when reverting to a disk snapshot of a transient domain.
6481 Since libvirt 7.10.0 the VM process is always restarted so the follow‐
6483 ing paragraph is no longer valid. If the snapshot metadata lacks the
6484 full VM XML it's no longer possible to revert to such snapshot.
6485 There are a number of cases where a snapshot revert involves extra
6487 risk, which requires the use of --force to proceed:
6488 • One is the case of a snapshot that lacks full domain information
6490 for reverting configuration (such as snapshots created prior to
6491 libvirt 0.9.5); since libvirt cannot prove that the current con‐
6492 figuration matches what was in use at the time of the snapshot,
6493 supplying --force assures libvirt that the snapshot is compatible
6494 with the current configuration (and if it is not, the domain will
6495 likely fail to run).
6496 • Another is the case of reverting from a running domain to an ac‐
6498 tive state where a new hypervisor has to be created rather than
6499 reusing the existing hypervisor, because it implies drawbacks such
6500 as breaking any existing VNC or Spice connections; this condition
6501 happens with an active snapshot that uses a provably incompatible
6502 configuration, as well as with an inactive snapshot that is com‐
6503 bined with the --start or --pause flag.
6504 • Also, libvirt will refuse to restore snapshots of inactive QEMU
6506 domains while there is managed saved state. This is because those
6507 snapshots do not contain memory state and will therefore not re‐
6508 place the existing memory state. This ends up switching a disk un‐
6509 derneath a running system and will likely cause extensive filesys‐
6510 tem corruption or crashes due to swap content mismatches when run.
6511 If --reset-nvram is specified, any existing NVRAM file will be deleted
6513 and re-initialized from its pristine template.
6514 snapshot-delete
6516 Syntax:
6517 snapshot-delete domain {snapshot | --current}
6519 [--metadata] [{--children | --children-only}]
6520 Delete the snapshot for the domain named snapshot, or the current snap‐
6522 shot with --current. If this snapshot has child snapshots, changes
6523 from this snapshot will be merged into the children. If --children is
6524 passed, then delete this snapshot and any children of this snapshot.
6525 If --children-only is passed, then delete any children of this snap‐
6526 shot, but leave this snapshot intact. These two flags are mutually ex‐
6527 clusive.
6528 If --metadata is specified, then only delete the snapshot metadata
6530 maintained by libvirt, while leaving the snapshot contents intact for
6531 access by external tools; otherwise deleting a snapshot also removes
6532 the data contents from that point in time.
6533
6535 The following commands manipulate domain checkpoints. Checkpoints
6536 serve as a point in time to identify which portions of a guest's disks
6537 have changed after that time, making it possible to perform incremental
6538 and differential backups. Checkpoints are identified with a unique
6539 name. See https://libvirt.org/formatcheckpoint.html for documentation
6540 of the XML format used to represent properties of checkpoints.
6541 checkpoint-create
6543 Syntax:
6544 checkpoint-create domain [xmlfile] { --redefine [--redefine-validate] | [--quiesce]}
6546 Create a checkpoint for domain domain with the properties specified in
6548 xmlfile describing a <domaincheckpoint> top-level element. The format
6549 of the input XML file will be validated against an internal RNG schema
6550 (identical to using the virt-xml-validate(1) tool). If xmlfile is com‐
6551 pletely omitted, then libvirt will create a checkpoint with a name
6552 based on the current time.
6553 If --redefine is specified, then all XML elements produced by check‐
6555 point-dumpxml are valid; this can be used to migrate checkpoint hierar‐
6556 chy from one machine to another, to recreate hierarchy for the case of
6557 a transient domain that goes away and is later recreated with the same
6558 name and UUID, or to make slight alterations in the checkpoint metadata
6559 (such as host-specific aspects of the domain XML embedded in the check‐
6560 point). When this flag is supplied, the xmlfile argument is mandatory.
6561 If --redefine-validate is specified along with --redefine the hypervi‐
6563 sor performs validation of metadata associated with the checkpoint
6564 stored in places besides the checkpoint XML. Note that some hypervisors
6565 may require that the domain is running to perform validation.
6566 If --quiesce is specified, libvirt will try to use guest agent to
6568 freeze and unfreeze domain's mounted file systems. However, if domain
6569 has no guest agent, checkpoint creation will fail.
6570 Existence of checkpoint metadata will prevent attempts to undefine a
6572 persistent guest. However, for transient domains, checkpoint metadata
6573 is silently lost when the domain quits running (whether by command such
6574 as destroy or by internal guest action).
6575 For now, it is not possible to create checkpoints in a domain that has
6577 snapshots, although this restriction will be lifted in a future re‐
6578 lease.
6579 checkpoint-create-as
6581 Syntax:
6582 checkpoint-create-as domain [--print-xml] [name]
6584 [description] [--quiesce] [--diskspec] diskspec]...
6585 Create a checkpoint for domain domain with the given <name> and <de‐
6587 scription>; if either value is omitted, libvirt will choose a value.
6588 If --print-xml is specified, then XML appropriate for checkpoint-create
6589 is output, rather than actually creating a checkpoint.
6590 The --diskspec option can be used to control which guest disks partici‐
6592 pate in the checkpoint. This option can occur multiple times, according
6593 to the number of <disk> elements in the domain xml. Each <diskspec> is
6594 in the form disk[,checkpoint=type][,bitmap=name]. A literal --diskspec
6595 must precede each diskspec unless all three of domain, name, and de‐
6596 scription are also present. For example, a diskspec of "vda,check‐
6597 point=bitmap,bitmap=map1" results in the following XML:
6598 <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
6600 If --quiesce is specified, libvirt will try to use guest agent to
6602 freeze and unfreeze domain's mounted file systems. However, if domain
6603 has no guest agent, checkpoint creation will fail.
6604 For now, it is not possible to create checkpoints in a domain that has
6606 snapshots, although this restriction will be lifted in a future re‐
6607 lease.
6608 checkpoint-edit
6610 Syntax:
6611 checkpoint-edit domain checkpointname
6613 Edit the XML configuration file for checkpointname of a domain.
6615 This is equivalent to:
6617 virsh checkpoint-dumpxml dom name > checkpoint.xml
6619 vi checkpoint.xml (or make changes with your other text editor)
6620 virsh checkpoint-create dom checkpoint.xml --redefine
6621 except that it does some error checking, including that the edits
6623 should not attempt to change the checkpoint name.
6624 The editor used can be supplied by the $VISUAL or $EDITOR environment
6626 variables, and defaults to vi.
6627 checkpoint-info
6629 Syntax:
6630 checkpoint-info domain checkpoint
6632 Output basic information about a named <checkpoint>.
6634 checkpoint-list
6636 Syntax:
6637 checkpoint-list domain [{--parent | --roots |
6639 [{--tree | --name}]}] [--topological]
6640 [[--from] checkpoint | [--descendants]]
6641 [--leaves] [--no-leaves]
6642 List all of the available checkpoints for the given domain, defaulting
6644 to show columns for the checkpoint name and creation time.
6645 Normally, table form output is sorted by checkpoint name; using --topo‐
6647 logical instead sorts so that no child is listed before its ancestors
6648 (although there may be more than one possible ordering with this prop‐
6649 erty).
6650 If --parent is specified, add a column to the output table giving the
6652 name of the parent of each checkpoint. If --roots is specified, the
6653 list will be filtered to just checkpoints that have no parents. If
6654 --tree is specified, the output will be in a tree format, listing just
6655 checkpoint names. These three options are mutually exclusive. If
6656 --name is specified only the checkpoint name is printed. This option is
6657 mutually exclusive with --tree.
6658 If --from is provided, filter the list to checkpoints which are chil‐
6660 dren of the given checkpoint. When used in isolation or with --parent,
6661 the list is limited to direct children unless --descendants is also
6662 present. When used with --tree, the use of --descendants is implied.
6663 This option is not compatible with --roots. Note that the starting
6664 point of --from is not included in the list unless the --tree option is
6665 also present.
6666 If --leaves is specified, the list will be filtered to just checkpoints
6668 that have no children. Likewise, if --no-leaves is specified, the list
6669 will be filtered to just checkpoints with children. (Note that omit‐
6670 ting both options does no filtering, while providing both options will
6671 either produce the same list or error out depending on whether the
6672 server recognizes the flags). Filtering options are not compatible
6673 with --tree.
6674 checkpoint-dumpxml
6676 Syntax:
6677 checkpoint-dumpxml [--security-info] [--no-domain] [--size]
6679 [--xpath EXPRESSION] [--wrap] domain checkpoint
6680 Output the checkpoint XML for the domain's checkpoint named checkpoint.
6682 Using --security-info will also include security sensitive information.
6683 Using --size will add XML indicating the current size in bytes of guest
6685 data that has changed since the checkpoint was created (although remem‐
6686 ber that guest activity between a size check and actually creating a
6687 backup can result in the backup needing slightly more space). Note that
6688 some hypervisors may require that domain is running when --size is
6689 used.
6690 Using --no-domain will omit the <domain> element from the output for a
6692 more compact view.
6693 If the --xpath argument provides an XPath expression, it will be evalu‐
6695 ated against the output XML and only those matching nodes will be
6696 printed. The default behaviour is to print each matching node as a
6697 standalone document, however, for ease of additional processing, the
6698 --wrap argument will cause the matching node to be wrapped in a common
6699 root node.
6700 checkpoint-parent
6702 Syntax:
6703 checkpoint-parent domain checkpoint
6705 Output the name of the parent checkpoint, if any, for the given check‐
6707 point.
6708 checkpoint-delete
6710 Syntax:
6711 checkpoint-delete domain checkpoint
6713 [--metadata] [{--children | --children-only}]
6714 Delete the checkpoint for the domain named checkpoint. The record of
6716 which portions of the disk changed since the checkpoint are merged into
6717 the parent checkpoint (if any). If --children is passed, then delete
6718 this checkpoint and any children of this checkpoint. If --chil‐
6719 dren-only is passed, then delete any children of this checkpoint, but
6720 leave this checkpoint intact. These two flags are mutually exclusive.
6721 If --metadata is specified, then only delete the checkpoint metadata
6723 maintained by libvirt, while leaving the checkpoint contents intact for
6724 access by external tools; otherwise deleting a checkpoint also removes
6725 the ability to perform an incremental backup from that point in time.
6726
6728 The following commands manipulate network filters. Network filters al‐
6729 low filtering of the network traffic coming from and going to virtual
6730 machines. Individual network traffic filters are written in XML and
6731 may contain references to other network filters, describe traffic fil‐
6732 tering rules, or contain both. Network filters are referenced by vir‐
6733 tual machines from within their interface description. A network filter
6734 may be referenced by multiple virtual machines' interfaces.
6735 nwfilter-define
6737 Syntax:
6738 nwfilter-define xmlfile [--validate]
6740 Make a new network filter known to libvirt. If a network filter with
6742 the same name already exists, it will be replaced with the new XML.
6743 Any running virtual machine referencing this network filter will have
6744 its network traffic rules adapted. If for any reason the network traf‐
6745 fic filtering rules cannot be instantiated by any of the running vir‐
6746 tual machines, then the new XML will be rejected.
6747 Optionally, the format of the input XML file can be validated against
6749 an internal RNG schema with --validate.
6750 nwfilter-undefine
6752 Syntax:
6753 nwfilter-undefine nwfilter-name
6755 Delete a network filter. The deletion will fail if any running virtual
6757 machine is currently using this network filter.
6758 nwfilter-list
6760 Syntax:
6761 nwfilter-list
6763 List all of the available network filters.
6765 nwfilter-dumpxml
6767 Syntax:
6768 nwfilter-dumpxml [--xpath EXPRESSION] [--wrap] nwfilter-name
6770 Output the network filter XML.
6772 If the --xpath argument provides an XPath expression, it will be evalu‐
6774 ated against the output XML and only those matching nodes will be
6775 printed. The default behaviour is to print each matching node as a
6776 standalone document, however, for ease of additional processing, the
6777 --wrap argument will cause the matching node to be wrapped in a common
6778 root node.
6779 nwfilter-edit
6781 Syntax:
6782 nwfilter-edit nwfilter-name
6784 Edit the XML of a network filter.
6786 This is equivalent to:
6788 virsh nwfilter-dumpxml myfilter > myfilter.xml
6790 vi myfilter.xml (or make changes with your other text editor)
6791 virsh nwfilter-define myfilter.xml
6792 except that it does some error checking. The new network filter may be
6794 rejected due to the same reason as mentioned in nwfilter-define.
6795 The editor used can be supplied by the $VISUAL or $EDITOR environment
6797 variables, and defaults to vi.
6798
6800 The following commands manipulate network filter bindings. Network fil‐
6801 ter bindings track the association between a network port and a network
6802 filter. Generally the bindings are managed automatically by the hyper‐
6803 visor drivers when adding/removing NICs on a guest.
6804 If an admin is creating/deleting TAP devices for non-guest usage, how‐
6806 ever, the network filter binding commands provide a way to make use of
6807 the network filters directly.
6808 nwfilter-binding-create
6810 Syntax:
6811 nwfilter-binding-create xmlfile [--validate]
6813 Associate a network port with a network filter. The network filter
6815 backend will immediately attempt to instantiate the filter rules on the
6816 port. This command may be used to associate a filter with a currently
6817 running guest that does not have a filter defined for a specific net‐
6818 work port. Since the bindings are generally automatically managed by
6819 the hypervisor, using this command to define a filter for a network
6820 port and then starting the guest afterwards may prevent the guest from
6821 starting if it attempts to use the network port and finds a filter al‐
6822 ready defined.
6823 Optionally, the format of the input XML file can be validated against
6825 an internal RNG schema with --validate.
6826 nwfilter-binding-delete
6828 Syntax:
6829 nwfilter-binding-delete port-name
6831 Disassociate a network port from a network filter. The network filter
6833 backend will immediately tear down the filter rules that exist on the
6834 port. This command may be used to remove the network port binding for a
6835 filter currently in use for the guest while the guest is running with‐
6836 out needing to restart the guest. Restoring the network port binding
6837 filter for the running guest would be accomplished by using nwfil‐
6838 ter-binding-create.
6839 nwfilter-binding-list
6841 Syntax:
6842 nwfilter-binding-list
6844 List all of the network ports which have filters associated with them.
6846 nwfilter-binding-dumpxml
6848 Syntax:
6849 nwfilter-binding-dumpxml [--xpath EXPRESSION] [--wrap] port-name
6851 Output the network filter binding XML for the network device called
6853 port-name.
6854 If the --xpath argument provides an XPath expression, it will be evalu‐
6856 ated against the output XML and only those matching nodes will be
6857 printed. The default behaviour is to print each matching node as a
6858 standalone document, however, for ease of additional processing, the
6859 --wrap argument will cause the matching node to be wrapped in a common
6860 root node.
6861
6863 NOTE: Use of the following commands is strongly discouraged. They can
6864 cause libvirt to become confused and do the wrong thing on subsequent
6865 operations. Once you have used these commands, please do not report
6866 problems to the libvirt developers; the reports will be ignored. If
6867 you find that these commands are the only way to accomplish something,
6868 then it is better to request that the feature be added as a first-class
6869 citizen in the regular libvirt library.
6870 qemu-attach
6872 Syntax:
6873 qemu-attach pid
6875 Attach an externally launched QEMU process to the libvirt QEMU driver.
6877 The QEMU process must have been created with a monitor connection using
6878 the UNIX driver. Ideally the process will also have had the '-name' ar‐
6879 gument specified.
6880 $ qemu-kvm -cdrom ~/demo.iso \
6882 -monitor unix:/tmp/demo,server,nowait \
6883 -name foo \
6884 -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea &
6885 $ QEMUPID=$!
6886 $ virsh qemu-attach $QEMUPID
6887 Not all functions of libvirt are expected to work reliably after at‐
6889 taching to an externally launched QEMU process. There may be issues
6890 with the guest ABI changing upon migration and device hotplug or hotun‐
6891 plug may not work. The attached environment should be considered pri‐
6892 marily read-only.
6893 qemu-monitor-command
6895 Syntax:
6896 qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] }
6898 [--pass-fds N,M,...] command...
6899 Send an arbitrary monitor command command to domain domain through the
6901 QEMU monitor. The results of the command will be printed on stdout.
6902 If more than one argument is provided for command, they are concate‐
6904 nated with a space in between before passing the single command to the
6905 monitor.
6906 Note that libvirt uses the QMP to talk to qemu so command must be valid
6908 JSON in QMP format to work properly. If command is not a JSON object
6909 libvirt tries to wrap it as a JSON object to provide convenient inter‐
6910 face such as the groups of commands with identical handling:
6911 # simple command
6913 $ virsh qemu-monitor-command VM commandname
6914 $ virsh qemu-monitor-command VM '{"execute":"commandname"}'
6915 # with arguments
6917 $ virsh qemu-monitor-command VM commandname '"arg1":123' '"arg2":"test"'
6918 $ virsh qemu-monitor-command VM commandname '{"arg1":123,"arg2":"test"}'
6919 $ virsh qemu-monitor-command VM '{"execute":"commandname", "arguments":{"arg1":123,"arg2":"test"}}'
6920 If --pretty is given the QMP reply is pretty-printed.
6922 If --return-value is given the 'return' key of the QMP response object
6924 is extracted rather than passing through the full reply from QEMU.
6925 If --hmp is passed, the command is considered to be a human monitor
6927 command and libvirt will automatically convert it into QMP and convert
6928 the result back.
6929 If --pass-fds is specified, the argument is a comma separated list of
6931 open file descriptors which should be passed on to qemu along with the
6932 command.
6933 qemu-agent-command
6935 Syntax:
6936 qemu-agent-command domain [--timeout seconds | --async | --block] command...
6938 Send an arbitrary guest agent command command to domain domain through
6940 QEMU agent. --timeout, --async and --block options are exclusive.
6941 --timeout requires timeout seconds seconds and it must be positive.
6942 When --aysnc is given, the command waits for timeout whether success or
6943 failed. And when --block is given, the command waits forever with
6944 blocking timeout.
6945 qemu-monitor-event
6947 Syntax:
6948 qemu-monitor-event [domain] [--event event-name]
6950 [--loop] [--timeout seconds] [--pretty] [--regex] [--no-case]
6951 [--timestamp]
6952 Wait for arbitrary QEMU monitor events to occur, and print out the de‐
6954 tails of events as they happen. The events can optionally be filtered
6955 by domain or event-name. The 'query-events' QMP command can be used
6956 via qemu-monitor-command to learn what events are supported. If
6957 --regex is used, event-name is a basic regular expression instead of a
6958 literal string. If --no-case is used, event-name will match case-in‐
6959 sensitively.
6960 By default, this command is one-shot, and returns success once an event
6962 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
6963 If --timeout is specified, the command gives up waiting for events af‐
6964 ter seconds have elapsed. With --loop, the command prints all events
6965 until a timeout or interrupt key. If --pretty is specified, any JSON
6966 event details are pretty-printed for better legibility.
6967 When --timestamp is used, a human-readable timestamp will be printed
6969 before the event, and the timing information provided by QEMU will be
6970 omitted.
6971 lxc-enter-namespace
6973 Syntax:
6974 lxc-enter-namespace domain [--noseclabel] --
6976 /path/to/binary [arg1, [arg2, ...]]
6977 Enter the namespace of domain and execute the command /path/to/binary
6979 passing the requested args. The binary path is relative to the con‐
6980 tainer root filesystem, not the host root filesystem. The binary will
6981 inherit the environment variables / console visible to virsh. The com‐
6982 mand will be run with the same sVirt context and cgroups placement as
6983 processes within the container. This command only works when connected
6984 to the LXC hypervisor driver. This command succeeds only if
6985 /path/to/binary has 0 exit status.
6986 By default the new process will run with the security label of the new
6988 parent container. Use the --noseclabel option to instead have the
6989 process keep the same security label as virsh.
6990
6992 The following environment variables can be set to alter the behaviour
6993 of virsh
6994 • VIRSH_DEBUG=<0 to 4>
6996 Turn on verbose debugging of virsh commands. Valid levels are
6998 • VIRSH_DEBUG=0
7000 DEBUG - Messages at ALL levels get logged
7002 • VIRSH_DEBUG=1
7004 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
7006 • VIRSH_DEBUG=2
7008 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
7010 • VIRSH_DEBUG=3
7012 WARNING - Logs messages at levels WARNING and ERROR
7014 • VIRSH_DEBUG=4
7016 ERROR - Messages at only ERROR level gets logged.
7018 • VIRSH_LOG_FILE=``LOGFILE``
7020 The file to log virsh debug messages.
7022 • VIRSH_DEFAULT_CONNECT_URI
7024 The hypervisor to connect to by default. Set this to a URI, in the
7026 same format as accepted by the connect option. This environment vari‐
7027 able is deprecated in favour of the global LIBVIRT_DEFAULT_URI vari‐
7028 able which serves the same purpose.
7029 • LIBVIRT_DEFAULT_URI
7031 The hypervisor to connect to by default. Set this to a URI, in the
7033 same format as accepted by the connect option. This overrides the de‐
7034 fault URI set in any client config file and prevents libvirt from
7035 probing for drivers.
7036 • VISUAL
7038 The editor to use by the edit and related options.
7040 • EDITOR
7042 The editor to use by the edit and related options, if VISUAL is not
7044 set.
7045 • VIRSH_HISTSIZE
7047 The number of commands to remember in the command history. The de‐
7049 fault value is 500.
7050 • LIBVIRT_DEBUG=LEVEL
7052 Turn on verbose debugging of all libvirt API calls. Valid levels are
7054 • LIBVIRT_DEBUG=1
7056 Messages at level DEBUG or above
7058 • LIBVIRT_DEBUG=2
7060 Messages at level INFO or above
7062 • LIBVIRT_DEBUG=3
7064 Messages at level WARNING or above
7066 • LIBVIRT_DEBUG=4
7068 Messages at level ERROR
7070 For further information about debugging options consult
7072 https://libvirt.org/logging.html
7073
7075 Please report all bugs you discover. This should be done via either:
7076 1. the mailing list
7078 https://libvirt.org/contact.html
7080 2. the bug tracker
7082 https://libvirt.org/bugs.html
7084 Alternatively, you may report bugs to your software distributor / ven‐
7086 dor.
7087
7089 Please refer to the AUTHORS file distributed with libvirt.
7090
7092 Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in
7093 the libvirt AUTHORS file.
7094
7096 virsh is distributed under the terms of the GNU LGPL v2+. This is free
7097 software; see the source for copying conditions. There is NO warranty;
7098 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
7099
7101 virt-install(1), virt-xml-validate(1), virt-top(1), virt-df(1),
7102 https://libvirt.org/
7103 VIRSH(1)