1VIRSH(1) Virtualization Support VIRSH(1)
2
6 virsh - management user interface
7
9 virsh [OPTION]... [COMMAND_STRING]
10 virsh [OPTION]... COMMAND [ARG]...
12
14 The virsh program is the main interface for managing virsh guest do‐
15 mains. The program can be used to create, pause, and shutdown domains.
16 It can also be used to list current domains. Libvirt is a C toolkit to
17 interact with the virtualization capabilities of recent versions of
18 Linux (and other OSes). It is free software available under the GNU
19 Lesser General Public License. Virtualization of the Linux Operating
20 System means the ability to run multiple instances of Operating Systems
21 concurrently on a single hardware system where the basic resources are
22 driven by a Linux instance. The library aims at providing a long term
23 stable C API. It currently supports Xen, QEMU, KVM, LXC, OpenVZ, Vir‐
24 tualBox and VMware ESX.
25 The basic structure of most virsh usage is:
27 virsh [OPTION]... <command> <domain> [ARG]...
29 Where command is one of the commands listed below; domain is the nu‐
31 meric domain id, or the domain name, or the domain UUID; and ARGS are
32 command specific options. There are a few exceptions to this rule in
33 the cases where the command in question acts on all domains, the entire
34 machine, or directly on the xen hypervisor. Those exceptions will be
35 clear for each of those commands. Note: it is permissible to give nu‐
36 meric names to domains, however, doing so will result in a domain that
37 can only be identified by domain id. In other words, if a numeric value
38 is supplied it will be interpreted as a domain id, not as a name. Any
39 command starting with # is treated as a comment and silently ignored,
40 all other unrecognized commands are diagnosed.
41 The virsh program can be used either to run one COMMAND by giving the
43 command and its arguments on the shell command line, or a COM‐
44 MAND_STRING which is a single shell argument consisting of multiple
45 COMMAND actions and their arguments joined with whitespace and sepa‐
46 rated by semicolons or newlines between commands, where unquoted back‐
47 slash-newline pairs are elided. Within COMMAND_STRING, virsh under‐
48 stands the same single, double, and backslash escapes as the shell, al‐
49 though you must add another layer of shell escaping in creating the
50 single shell argument, and any word starting with unquoted # begins a
51 comment that ends at newline. If no command is given in the command
52 line, virsh will then start a minimal interpreter waiting for your com‐
53 mands, and the quit command will then exit the program.
54 The virsh program understands the following OPTIONS.
56 -c, --connect URI
58 Connect to the specified URI, as if by the connect command, instead of
60 the default connection.
61 -d, --debug LEVEL
63 Enable debug messages at integer LEVEL and above. LEVEL can range from
65 0 to 4 (default). See the documentation of VIRSH_DEBUG environment
66 variable below for the description of each LEVEL.
67 • -e, --escape string
69 Set alternative escape sequence for console command. By default, tel‐
71 net's ^] is used. Allowed characters when using hat notation are: al‐
72 phabetic character, @, [, ], , ^, _.
73 • -h, --help
75 Ignore all other arguments, and behave as if the help command were
77 given instead.
78 • -k, --keepalive-interval INTERVAL
80 Set an INTERVAL (in seconds) for sending keepalive messages to check
82 whether connection to the server is still alive. Setting the interval
83 to 0 disables client keepalive mechanism.
84 • -K, --keepalive-count COUNT
86 Set a number of times keepalive message can be sent without getting an
88 answer from the server without marking the connection dead. There is
89 no effect to this setting in case the INTERVAL is set to 0.
90 • -l, --log FILE
92 Output logging details to FILE.
94 • -q, --quiet
96 Avoid extra informational messages.
98 • -r, --readonly
100 Make the initial connection read-only, as if by the --readonly option
102 of the connect command.
103 • -t, --timing
105 Output elapsed time information for each command.
107 • -v, --version[=short]
109 Ignore all other arguments, and prints the version of the libvirt li‐
111 brary virsh is coming from
112 • -V, --version=long
114 Ignore all other arguments, and prints the version of the libvirt li‐
116 brary virsh is coming from and which options and driver are compiled
117 in.
118
120 Most virsh operations rely upon the libvirt library being able to con‐
121 nect to an already running libvirtd service. This can usually be done
122 using the command service libvirtd start.
123 Most virsh commands require root privileges to run due to the communi‐
125 cations channels used to talk to the hypervisor. Running as non root
126 will return an error.
127 Most virsh commands act synchronously, except maybe shutdown, setvcpus
129 and setmem. In those cases the fact that the virsh program returned,
130 may not mean the action is complete and you must poll periodically to
131 detect that the guest completed the operation.
132 virsh strives for backward compatibility. Although the help command
134 only lists the preferred usage of a command, if an older version of
135 virsh supported an alternate spelling of a command or option (such as
136 --tunnelled instead of --tunneled), then scripts using that older
137 spelling will continue to work.
138 Several virsh commands take an optionally scaled integer; if no scale
140 is provided, then the default is listed in the command (for historical
141 reasons, some commands default to bytes, while other commands default
142 to kibibytes). The following case-insensitive suffixes can be used to
143 select a specific scale:
144 b, byte byte 1
146 KB kilobyte 1,000
147 k, KiB kibibyte 1,024
148 MB megabyte 1,000,000
149 M, MiB mebibyte 1,048,576
150 GB gigabyte 1,000,000,000
151 G, GiB gibibyte 1,073,741,824
152 TB terabyte 1,000,000,000,000
153 T, TiB tebibyte 1,099,511,627,776
154 PB petabyte 1,000,000,000,000,000
155 P, PiB pebibyte 1,125,899,906,842,624
156 EB exabyte 1,000,000,000,000,000,000
157 E, EiB exbibyte 1,152,921,504,606,846,976
158
160 The following commands are generic i.e. not specific to a domain.
161 help
163 Syntax:
164 help [command-or-group]
166 This lists each of the virsh commands. When used without options, all
168 commands are listed, one per line, grouped into related categories,
169 displaying the keyword for each group.
170 To display only commands for a specific group, give the keyword for
172 that group as an option. For example:
173 Example 1:
175 virsh # help host
177 Host and Hypervisor (help keyword 'host'):
179 capabilities capabilities
180 cpu-models show the CPU models for an architecture
181 connect (re)connect to hypervisor
182 freecell NUMA free memory
183 hostname print the hypervisor hostname
184 qemu-attach Attach to existing QEMU process
185 qemu-monitor-command QEMU Monitor Command
186 qemu-agent-command QEMU Guest Agent Command
187 sysinfo print the hypervisor sysinfo
188 uri print the hypervisor canonical URI
189 To display detailed information for a specific command, give its name
191 as the option instead. For example:
192 Example 2:
194 virsh # help list
196 NAME
197 list - list domains
198 SYNOPSIS
200 list [--inactive] [--all]
201 DESCRIPTION
203 Returns list of domains.
204 OPTIONS
206 --inactive list inactive domains
207 --all list inactive & active domains
208 quit, exit
210 Syntax:
211 quit
213 exit
214 quit this interactive terminal
216 version
218 Syntax:
219 version [--daemon]
221 Will print out the major version info about what this built from. If
223 --daemon is specified then the version of the libvirt daemon is in‐
224 cluded in the output.
225 Example:
227 $ virsh version
229 Compiled against library: libvirt 1.2.3
230 Using library: libvirt 1.2.3
231 Using API: QEMU 1.2.3
232 Running hypervisor: QEMU 2.0.50
233 $ virsh version --daemon
235 Compiled against library: libvirt 1.2.3
236 Using library: libvirt 1.2.3
237 Using API: QEMU 1.2.3
238 Running hypervisor: QEMU 2.0.50
239 Running against daemon: 1.2.6
240 cd
242 Syntax:
243 cd [directory]
245 Will change current directory to directory. The default directory for
247 the cd command is the home directory or, if there is no HOME variable
248 in the environment, the root directory.
249 This command is only available in interactive mode.
251 pwd
253 Syntax:
254 pwd
256 Will print the current directory.
258 connect
260 Syntax:
261 connect [URI] [--readonly]
263 (Re)-Connect to the hypervisor. When the shell is first started, this
265 is automatically run with the URI parameter requested by the -c option
266 on the command line. The URI parameter specifies how to connect to the
267 hypervisor. The URI docs https://libvirt.org/uri.html list the values
268 supported, but the most common are:
269 • xen:///system
271 this is used to connect to the local Xen hypervisor
273 • qemu:///system
275 connect locally as root to the daemon supervising QEMU and KVM do‐
277 mains
278 • qemu:///session
280 connect locally as a normal user to his own set of QEMU and KVM do‐
282 mains
283 • lxc:///system
285 connect to a local linux container
287 To find the currently used URI, check the uri command documented below.
289 For remote access see the URI docs https://libvirt.org/uri.html on how
291 to make URIs. The --readonly option allows for read-only connection
292 uri
294 Syntax:
295 uri
297 Prints the hypervisor canonical URI, can be useful in shell mode.
299 hostname
301 Syntax:
302 hostname
304 Print the hypervisor hostname.
306 sysinfo
308 Syntax:
309 sysinfo
311 Print the XML representation of the hypervisor sysinfo, if available.
313 nodeinfo
315 Syntax:
316 nodeinfo
318 Returns basic information about the node, like number and type of CPU,
320 and size of the physical memory. The output corresponds to virNodeInfo
321 structure. Specifically, the "CPU socket(s)" field means number of CPU
322 sockets per NUMA cell. The information libvirt displays is dependent
323 upon what each architecture may provide.
324 nodecpumap
326 Syntax:
327 nodecpumap [--pretty]
329 Displays the node's total number of CPUs, the number of online CPUs and
331 the list of online CPUs.
332 With --pretty the online CPUs are printed as a range instead of a list.
334 nodecpustats
336 Syntax:
337 nodecpustats [cpu] [--percent]
339 Returns cpu stats of the node. If cpu is specified, this will print
341 the specified cpu statistics only. If --percent is specified, this
342 will print the percentage of each kind of cpu statistics during 1 sec‐
343 ond.
344 nodememstats
346 Syntax:
347 nodememstats [cell]
349 Returns memory stats of the node. If cell is specified, this will
351 print the specified cell statistics only.
352 nodesevinfo
354 Syntax:
355 nodesevinfo
357 Reports information about the AMD SEV launch security features for the
359 node, if any. Some of this information is also reported in the domain
360 capabilities XML document.
361 nodesuspend
363 Syntax:
364 nodesuspend [target] [duration]
366 Puts the node (host machine) into a system-wide sleep state and sched‐
368 ule the node's Real-Time-Clock interrupt to resume the node after the
369 time duration specified by duration is out. target specifies the state
370 to which the host will be suspended to, it can be "mem" (suspend to
371 RAM), "disk" (suspend to disk), or "hybrid" (suspend to both RAM and
372 disk). duration specifies the time duration in seconds for which the
373 host has to be suspended, it should be at least 60 seconds.
374 node-memory-tune
376 Syntax:
377 node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs] [shm-merge-across-nodes]
379 Allows you to display or set the node memory parameters.
381 shm-pages-to-scan can be used to set the number of pages to scan before
382 the shared memory service goes to sleep; shm-sleep-millisecs can be
383 used to set the number of millisecs the shared memory service should
384 sleep before next scan; shm-merge-across-nodes specifies if pages from
385 different numa nodes can be merged. When set to 0, only pages which
386 physically reside in the memory area of same NUMA node can be merged.
387 When set to 1, pages from all nodes can be merged. Default to 1.
388 Note: Currently the "shared memory service" only means KSM (Kernel
390 Samepage Merging).
391 capabilities
393 Syntax:
394 capabilities
396 Print an XML document describing the capabilities of the hypervisor we
398 are currently connected to. This includes a section on the host capa‐
399 bilities in terms of CPU and features, and a set of description for
400 each kind of guest which can be virtualized. For a more complete de‐
401 scription see:
402 https://libvirt.org/formatcaps.html
404 The XML also show the NUMA topology information if available.
406 domcapabilities
408 Syntax:
409 domcapabilities [virttype] [emulatorbin] [arch] [machine]
411 Print an XML document describing the domain capabilities for the hyper‐
413 visor we are connected to using information either sourced from an ex‐
414 isting domain or taken from the virsh capabilities output. This may be
415 useful if you intend to create a new domain and are curious if for in‐
416 stance it could make use of VFIO by creating a domain for the hypervi‐
417 sor with a specific emulator and architecture.
418 Each hypervisor will have different requirements regarding which op‐
420 tions are required and which are optional. A hypervisor can support
421 providing a default value for any of the options.
422 The virttype option specifies the virtualization type used. The value
424 to be used is either from the 'type' attribute of the <domain/> top
425 level element from the domain XML or the 'type' attribute found within
426 each <guest/> element from the virsh capabilities output. The emula‐
427 torbin option specifies the path to the emulator. The value to be used
428 is either the <emulator> element in the domain XML or the virsh capa‐
429 bilities output. The arch option specifies the architecture to be used
430 for the domain. The value to be used is either the "arch" attribute
431 from the domain's XML <os/> element and <type/> subelement or the
432 "name" attribute of an <arch/> element from the virsh capabililites
433 output. The machine specifies the machine type for the emulator. The
434 value to be used is either the "machine" attribute from the domain's
435 XML <os/> element and <type/> subelement or one from a list of machines
436 from the virsh capabilities output for a specific architecture and do‐
437 main type.
438 For the QEMU hypervisor, a virttype of either 'qemu' or 'kvm' must be
440 supplied along with either the emulatorbin or arch in order to generate
441 output for the default machine. Supplying a machine value will gener‐
442 ate output for the specific machine.
443 pool-capabilities
445 Syntax:
446 pool-capabilities
448 Print an XML document describing the storage pool capabilities for the
450 connected storage driver. This may be useful if you intend to create a
451 new storage pool and need to know the available pool types and sup‐
452 ported storage pool source and target volume formats as well as the re‐
453 quired source elements to create the pool.
454 inject-nmi
456 Syntax:
457 inject-nmi domain
459 Inject NMI to the guest.
461 list
463 Syntax:
464 list [--inactive | --all]
466 [--managed-save] [--title]
467 { [--table] | --name | --uuid | --id }
468 [--persistent] [--transient]
469 [--with-managed-save] [--without-managed-save]
470 [--autostart] [--no-autostart]
471 [--with-snapshot] [--without-snapshot]
472 [--with-checkpoint] [--without-checkpoint]
473 [--state-running] [--state-paused]
474 [--state-shutoff] [--state-other]
475 Prints information about existing domains. If no options are specified
477 it prints out information about running domains.
478 Example 1:
480 An example format for the list is as follows:
482 ``virsh`` list
484 Id Name State
485 ----------------------------------------------------
486 0 Domain-0 running
487 2 fedora paused
488 Name is the name of the domain. ID the domain numeric id. State is
490 the run state (see below).
491 STATES
493 The State field lists what state each domain is currently in. A domain
495 can be in one of the following possible states:
496 • running
498 The domain is currently running on a CPU
500 • idle
502 The domain is idle, and not running or runnable. This can be caused
504 because the domain is waiting on IO (a traditional wait state) or has
505 gone to sleep because there was nothing else for it to do.
506 • paused
508 The domain has been paused, usually occurring through the administra‐
510 tor running virsh suspend. When in a paused state the domain will
511 still consume allocated resources like memory, but will not be eligi‐
512 ble for scheduling by the hypervisor.
513 • in shutdown
515 The domain is in the process of shutting down, i.e. the guest operat‐
517 ing system has been notified and should be in the process of stopping
518 its operations gracefully.
519 • shut off
521 The domain is not running. Usually this indicates the domain has
523 been shut down completely, or has not been started.
524 • crashed
526 The domain has crashed, which is always a violent ending. Usually
528 this state can only occur if the domain has been configured not to
529 restart on crash.
530 • pmsuspended
532 The domain has been suspended by guest power management, e.g. entered
534 into s3 state.
535 Normally only active domains are listed. To list inactive domains spec‐
537 ify --inactive or --all to list both active and inactive domains.
538 Filtering
540 To further filter the list of domains you may specify one or more of
542 filtering flags supported by the list command. These flags are grouped
543 by function. Specifying one or more flags from a group enables the
544 filter group. Note that some combinations of flags may yield no re‐
545 sults. Supported filtering flags and groups:
546 Persistence
548 Flag --persistent is used to include persistent guests in the returned
549 list. To include transient guests specify --transient.
550 Existence of managed save image
552 To list domains having a managed save image specify flag --with-man‐
553 aged-save. For domains that don't have a managed save image specify
554 --without-managed-save.
555 Domain state
557 The following filter flags select a domain by its state: --state-run‐
558 ning for running domains, --state-paused for paused domains,
559 --state-shutoff for turned off domains and --state-other for all other
560 states as a fallback.
561 Autostarting domains
563 To list autostarting domains use the flag --autostart. To list domains
564 with this feature disabled use --no-autostart.
565 Snapshot existence
567 Domains that have snapshot images can be listed using flag --with-snap‐
568 shot, domains without a snapshot --without-snapshot.
569 Checkpoint existence
571 Domains that have checkpoints can be listed using flag --with-check‐
572 point, domains without a checkpoint --without-checkpoint.
573 When talking to older servers, this command is forced to use a series
575 of API calls with an inherent race, where a domain might not be listed
576 or might appear more than once if it changed state between calls while
577 the list was being collected. Newer servers do not have this problem.
578 If --managed-save is specified, then domains that have managed save
580 state (only possible if they are in the shut off state, so you need to
581 specify --inactive or --all to actually list them) will instead show as
582 saved in the listing. This flag is usable only with the default --table
583 output. Note that this flag does not filter the list of domains.
584 If --name is specified, domain names are printed instead of the table
586 formatted one per line. If --uuid is specified domain's UUID's are
587 printed instead of names. If --id is specified then domain's ID's are
588 printed indead of names. However, it is possible to combine --name,
589 --uuid and --id to select only desired fields for printing. Flag --ta‐
590 ble specifies that the legacy table-formatted output should be used,
591 but it is mutually exclusive with --name, --uuid and --id. This is the
592 default and will be used if neither of --name, --uuid or --id is speci‐
593 fied. If neither --name nor --uuid is specified, but --id is, then only
594 active domains are listed, even with the --all parameter as otherwise
595 the output would just contain bunch of lines with just -1.
596 If --title is specified, then the short domain description (title) is
598 printed in an extra column. This flag is usable only with the default
599 --table output.
600 Example 2:
602 $ virsh list --title
604 Id Name State Title
605 -------------------------------------------
606 0 Domain-0 running Mailserver 1
607 2 fedora paused
608 freecell
610 Syntax:
611 freecell [{ [--cellno] cellno | --all }]
613 Prints the available amount of memory on the machine or within a NUMA
615 cell. The freecell command can provide one of three different displays
616 of available memory on the machine depending on the options specified.
617 With no options, it displays the total free memory on the machine.
618 With the --all option, it displays the free memory in each cell and the
619 total free memory on the machine. Finally, with a numeric argument or
620 with --cellno plus a cell number it will display the free memory for
621 the specified cell only.
622 freepages
624 Syntax:
625 freepages [{ [--cellno] cellno [--pagesize] pagesize | --all }]
627 Prints the available amount of pages within a NUMA cell. cellno refers
629 to the NUMA cell you're interested in. pagesize is a scaled integer
630 (see NOTES above). Alternatively, if --all is used, info on each pos‐
631 sible combination of NUMA cell and page size is printed out.
632 allocpages
634 Syntax:
635 allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno] cellno] [--add] [--all]
637 Change the size of pages pool of pagesize on the host. If --add is
639 specified, then pagecount pages are added into the pool. However, if
640 --add wasn't specified, then the pagecount is taken as the new absolute
641 size of the pool (this may be used to free some pages and size the pool
642 down). The cellno modifier can be used to narrow the modification down
643 to a single host NUMA cell. On the other end of spectrum lies --all
644 which executes the modification on all NUMA cells.
645 cpu-baseline
647 Syntax:
648 cpu-baseline FILE [--features] [--migratable]
650 Compute baseline CPU which will be supported by all host CPUs given in
652 <file>. (See hypervisor-cpu-baseline command to get a CPU which can be
653 provided by a specific hypervisor.) The list of host CPUs is built by
654 extracting all <cpu> elements from the <file>. Thus, the <file> can
655 contain either a set of <cpu> elements separated by new lines or even a
656 set of complete <capabilities> elements printed by capabilities com‐
657 mand. If --features is specified, then the resulting XML description
658 will explicitly include all features that make up the CPU, without this
659 option features that are part of the CPU model will not be listed in
660 the XML description. If --migratable is specified, features that
661 block migration will not be included in the resulting CPU.
662 cpu-compare
664 Syntax:
665 cpu-compare FILE [--error] [--validate]
667 Compare CPU definition from XML <file> with host CPU. (See hypervi‐
669 sor-cpu-compare command for comparing the CPU definition with the CPU
670 which a specific hypervisor is able to provide on the host.) The XML
671 <file> may contain either host or guest CPU definition. The host CPU
672 definition is the <cpu> element and its contents as printed by capabil‐
673 ities command. The guest CPU definition is the <cpu> element and its
674 contents from domain XML definition or the CPU definition created from
675 the host CPU model found in domain capabilities XML (printed by domca‐
676 pabilities command). In addition to the <cpu> element itself, this com‐
677 mand accepts full domain XML, capabilities XML, or domain capabilities
678 XML containing the CPU definition. For more information on guest CPU
679 definition see: https://libvirt.org/formatdomain.html#elementsCPU. If
680 --error is specified, the command will return an error when the given
681 CPU is incompatible with host CPU and a message providing more details
682 about the incompatibility will be printed out. If --validate is speci‐
683 fied, validates the format of the XML document against an internal RNG
684 schema.
685 cpu-models
687 Syntax:
688 cpu-models arch
690 Print the list of CPU models known by libvirt for the specified archi‐
692 tecture. Whether a specific hypervisor is able to create a domain
693 which uses any of the printed CPU models is a separate question which
694 can be answered by looking at the domain capabilities XML returned by
695 domcapabilities command. Moreover, for some architectures libvirt does
696 not know any CPU models and the usable CPU models are only limited by
697 the hypervisor. This command will print that all CPU models are ac‐
698 cepted for these architectures and the actual list of supported CPU
699 models can be checked in the domain capabilities XML.
700 hypervisor-cpu-compare
702 Syntax:
703 hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine] [--error] [--validate]
705 Compare CPU definition from XML <file> with the CPU the hypervisor is
707 able to provide on the host. (This is different from cpu-compare which
708 compares the CPU definition with the host CPU without considering any
709 specific hypervisor and its abilities.)
710 The XML FILE may contain either a host or guest CPU definition. The
712 host CPU definition is the <cpu> element and its contents as printed by
713 the capabilities command. The guest CPU definition is the <cpu> element
714 and its contents from the domain XML definition or the CPU definition
715 created from the host CPU model found in the domain capabilities XML
716 (printed by the domcapabilities command). In addition to the <cpu> ele‐
717 ment itself, this command accepts full domain XML, capabilities XML, or
718 domain capabilities XML containing the CPU definition. For more infor‐
719 mation on guest CPU definition see:
720 https://libvirt.org/formatdomain.html#elementsCPU.
721 The virttype option specifies the virtualization type (usable in the
723 'type' attribute of the <domain> top level element from the domain
724 XML). emulator specifies the path to the emulator, arch specifies the
725 CPU architecture, and machine specifies the machine type. If --error is
726 specified, the command will return an error when the given CPU is in‐
727 compatible with the host CPU and a message providing more details about
728 the incompatibility will be printed out. If --validate is specified,
729 validates the format of the XML document against an internal RNG
730 schema.
731 hypervisor-cpu-baseline
733 Syntax:
734 hypervisor-cpu-baseline [FILE] [virttype] [emulator] [arch] [machine]
736 [--features] [--migratable] [model]
737 Compute a baseline CPU which will be compatible with all CPUs defined
739 in an XML file and with the CPU the hypervisor is able to provide on
740 the host. (This is different from cpu-baseline which does not consider
741 any hypervisor abilities when computing the baseline CPU.)
742 As an alternative for FILE in case the XML would only contain a CPU
744 model with no additional features the CPU model name itself can be
745 passed as model. Exactly one of FILE and model must be used.
746 The XML FILE may contain either host or guest CPU definitions describ‐
748 ing the host CPU model. The host CPU definition is the <cpu> element
749 and its contents as printed by capabilities command. The guest CPU def‐
750 inition may be created from the host CPU model found in domain capabil‐
751 ities XML (printed by domcapabilities command). In addition to the
752 <cpu> elements, this command accepts full capabilities XMLs, or domain
753 capabilities XMLs containing the CPU definitions. It is recommended to
754 use only the CPU definitions from domain capabilities, as on some ar‐
755 chitectures using the host CPU definition may either fail or provide
756 unexpected results.
757 When FILE contains only a single CPU definition, the command will print
759 the same CPU with restrictions imposed by the capabilities of the hy‐
760 pervisor. Specifically, running the virsh hypervisor-cpu-baseline com‐
761 mand with no additional options on the result of virsh domcapabilities
762 will transform the host CPU model from domain capabilities XML to a
763 form directly usable in domain XML. Running the command with model (or
764 FILE containing just a single CPU definition with model and no feature
765 elements) which is marked as unusable in virsh domcapabilities will
766 provide a list of features that block this CPU model from being usable.
767 The virttype option specifies the virtualization type (usable in the
769 'type' attribute of the <domain> top level element from the domain
770 XML). emulator specifies the path to the emulator, arch specifies the
771 CPU architecture, and machine specifies the machine type. If --features
772 is specified, then the resulting XML description will explicitly in‐
773 clude all features that make up the CPU, without this option features
774 that are part of the CPU model will not be listed in the XML descrip‐
775 tion. If --migratable is specified, features that block migration will
776 not be included in the resulting CPU.
777
779 The following commands manipulate domains directly, as stated previ‐
780 ously most commands take domain as the first parameter. The domain can
781 be specified as a short integer, a name or a full UUID.
782 autostart
784 Syntax:
785 autostart [--disable] domain
787 Configure a domain to be automatically started at boot.
789 The option --disable disables autostarting.
791 blkdeviotune
793 Syntax:
794 blkdeviotune domain device [[--config] [--live] | [--current]]
796 [[total-bytes-sec] | [read-bytes-sec] [write-bytes-sec]]
797 [[total-iops-sec] | [read-iops-sec] [write-iops-sec]]
798 [[total-bytes-sec-max] | [read-bytes-sec-max] [write-bytes-sec-max]]
799 [[total-iops-sec-max] | [read-iops-sec-max] [write-iops-sec-max]]
800 [[total-bytes-sec-max-length] |
801 [read-bytes-sec-max-length] [write-bytes-sec-max-length]]
802 [[total-iops-sec-max-length] |
803 [read-iops-sec-max-length] [write-iops-sec-max-length]]
804 [size-iops-sec] [group-name]
805 Set or query the block disk io parameters for a block device of domain.
807 device specifies a unique target name (<target dev='name'/>) or source
808 file (<source file='name'/>) for one of the disk devices attached to
809 domain (see also domblklist for listing these names).
810 If no limit is specified, it will query current I/O limits setting.
812 Otherwise, alter the limits with these flags: --total-bytes-sec speci‐
813 fies total throughput limit as a scaled integer, the default being
814 bytes per second if no suffix is specified. --read-bytes-sec specifies
815 read throughput limit as a scaled integer, the default being bytes per
816 second if no suffix is specified. --write-bytes-sec specifies write
817 throughput limit as a scaled integer, the default being bytes per sec‐
818 ond if no suffix is specified. --total-iops-sec specifies total I/O
819 operations limit per second. --read-iops-sec specifies read I/O opera‐
820 tions limit per second. --write-iops-sec specifies write I/O opera‐
821 tions limit per second. --total-bytes-sec-max specifies maximum total
822 throughput limit as a scaled integer, the default being bytes per sec‐
823 ond if no suffix is specified --read-bytes-sec-max specifies maximum
824 read throughput limit as a scaled integer, the default being bytes per
825 second if no suffix is specified. --write-bytes-sec-max specifies max‐
826 imum write throughput limit as a scaled integer, the default being
827 bytes per second if no suffix is specified. --total-iops-sec-max spec‐
828 ifies maximum total I/O operations limit per second.
829 --read-iops-sec-max specifies maximum read I/O operations limit per
830 second. --write-iops-sec-max specifies maximum write I/O operations
831 limit per second. --total-bytes-sec-max-length specifies duration in
832 seconds to allow maximum total throughput limit.
833 --read-bytes-sec-max-length specifies duration in seconds to allow max‐
834 imum read throughput limit. --write-bytes-sec-max-length specifies du‐
835 ration in seconds to allow maximum write throughput limit. --to‐
836 tal-iops-sec-max-length specifies duration in seconds to allow maximum
837 total I/O operations limit. --read-iops-sec-max-length specifies dura‐
838 tion in seconds to allow maximum read I/O operations limit.
839 --write-iops-sec-max-length specifies duration in seconds to allow max‐
840 imum write I/O operations limit. --size-iops-sec specifies size I/O
841 operations limit per second. --group-name specifies group name to
842 share I/O quota between multiple drives. For a QEMU domain, if no name
843 is provided, then the default is to have a single group for each de‐
844 vice.
845 Older versions of virsh only accepted these options with underscore in‐
847 stead of dash, as in --total_bytes_sec.
848 Bytes and iops values are independent, but setting only one value (such
850 as --read-bytes-sec) resets the other two in that category to unlim‐
851 ited. An explicit 0 also clears any limit. A non-zero value for a
852 given total cannot be mixed with non-zero values for read or write.
853 It is up to the hypervisor to determine how to handle the length val‐
855 ues. For the QEMU hypervisor, if an I/O limit value or maximum value
856 is set, then the default value of 1 second will be displayed. Supplying
857 a 0 will reset the value back to the default.
858 If --live is specified, affect a running guest. If --config is speci‐
860 fied, affect the next start of a persistent guest. If --current is
861 specified, it is equivalent to either --live or --config, depending on
862 the current state of the guest. When setting the disk io parameters
863 both --live and --config flags may be given, but --current is exclu‐
864 sive. For querying only one of --live, --config or --current can be
865 specified. If no flag is specified, behavior is different depending on
866 hypervisor.
867 blkiotune
869 Syntax:
870 blkiotune domain [--weight weight] [--device-weights device-weights]
872 [--device-read-iops-sec device-read-iops-sec]
873 [--device-write-iops-sec device-write-iops-sec]
874 [--device-read-bytes-sec device-read-bytes-sec]
875 [--device-write-bytes-sec device-write-bytes-sec]
876 [[--config] [--live] | [--current]]
877 Display or set the blkio parameters. QEMU/KVM supports --weight.
879 --weight is in range [100, 1000]. After kernel 2.6.39, the value could
880 be in the range [10, 1000].
881 device-weights is a single string listing one or more device/weight
883 pairs, in the format of /path/to/device,weight,/path/to/device,weight.
884 Each weight is in the range [100, 1000], [10, 1000] after kernel
885 2.6.39, or the value 0 to remove that device from per-device listings.
886 Only the devices listed in the string are modified; any existing
887 per-device weights for other devices remain unchanged.
888 device-read-iops-sec is a single string listing one or more de‐
890 vice/read_iops_sec pairs, int the format of /path/to/de‐
891 vice,read_iops_sec,/path/to/device,read_iops_sec. Each read_iops_sec
892 is a number which type is unsigned int, value 0 to remove that device
893 from per-device listing. Only the devices listed in the string are
894 modified; any existing per-device read_iops_sec for other devices re‐
895 main unchanged.
896 device-write-iops-sec is a single string listing one or more de‐
898 vice/write_iops_sec pairs, int the format of /path/to/de‐
899 vice,write_iops_sec,/path/to/device,write_iops_sec. Each
900 write_iops_sec is a number which type is unsigned int, value 0 to re‐
901 move that device from per-device listing. Only the devices listed in
902 the string are modified; any existing per-device write_iops_sec for
903 other devices remain unchanged.
904 device-read-bytes-sec is a single string listing one or more de‐
906 vice/read_bytes_sec pairs, int the format of /path/to/de‐
907 vice,read_bytes_sec,/path/to/device,read_bytes_sec. Each
908 read_bytes_sec is a number which type is unsigned long long, value 0 to
909 remove that device from per-device listing. Only the devices listed in
910 the string are modified; any existing per-device read_bytes_sec for
911 other devices remain unchanged.
912 device-write-bytes-sec is a single string listing one or more de‐
914 vice/write_bytes_sec pairs, int the format of /path/to/de‐
915 vice,write_bytes_sec,/path/to/device,write_bytes_sec. Each
916 write_bytes_sec is a number which type is unsigned long long, value 0
917 to remove that device from per-device listing. Only the devices listed
918 in the string are modified; any existing per-device write_bytes_sec for
919 other devices remain unchanged.
920 If --live is specified, affect a running guest. If --config is speci‐
922 fied, affect the next start of a persistent guest. If --current is
923 specified, it is equivalent to either --live or --config, depending on
924 the current state of the guest. Both --live and --config flags may be
925 given, but --current is exclusive. If no flag is specified, behavior is
926 different depending on hypervisor.
927 blockcommit
929 Syntax:
930 blockcommit domain path [bandwidth] [--bytes] [base]
932 [--shallow] [top] [--delete] [--keep-relative]
933 [--wait [--async] [--verbose]] [--timeout seconds]
934 [--active] [{--pivot | --keep-overlay}]
935 Reduce the length of a backing image chain, by committing changes at
937 the top of the chain (snapshot or delta files) into backing images. By
938 default, this command attempts to flatten the entire chain. If base
939 and/or top are specified as files within the backing chain, then the
940 operation is constrained to committing just that portion of the chain;
941 --shallow can be used instead of base to specify the immediate backing
942 file of the resulting top image to be committed. The files being com‐
943 mitted are rendered invalid, possibly as soon as the operation starts;
944 using the --delete flag will attempt to remove these invalidated files
945 at the successful completion of the commit operation. When the
946 --keep-relative flag is used, the backing file paths will be kept rela‐
947 tive.
948 When top is omitted or specified as the active image, it is also possi‐
950 ble to specify --active to trigger a two-phase active commit. In the
951 first phase, top is copied into base and the job can only be canceled,
952 with top still containing data not yet in base. In the second phase,
953 top and base remain identical until a call to blockjob with the --abort
954 flag (keeping top as the active image that tracks changes from that
955 point in time) or the --pivot flag (making base the new active image
956 and invalidating top).
957 By default, this command returns as soon as possible, and data for the
959 entire disk is committed in the background; the progress of the opera‐
960 tion can be checked with blockjob. However, if --wait is specified,
961 then this command will block until the operation completes (or for
962 --active, enters the second phase), or until the operation is canceled
963 because the optional timeout in seconds elapses or SIGINT is sent (usu‐
964 ally with Ctrl-C). Using --verbose along with --wait will produce pe‐
965 riodic status updates. If job cancellation is triggered, --async will
966 return control to the user as fast as possible, otherwise the command
967 may continue to block a little while longer until the job is done
968 cleaning up. Using --pivot is shorthand for combining --active --wait
969 with an automatic blockjob --pivot; and using --keep-overlay is short‐
970 hand for combining --active --wait with an automatic blockjob --abort.
971 path specifies fully-qualified path of the disk; it corresponds to a
973 unique target name (<target dev='name'/>) or source file (<source
974 file='name'/>) for one of the disk devices attached to domain (see also
975 domblklist for listing these names). bandwidth specifies copying band‐
976 width limit in MiB/s, although for QEMU, it may be non-zero only for an
977 online domain. For further information on the bandwidth argument see
978 the corresponding section for the blockjob command.
979 blockcopy
981 Syntax:
982 blockcopy domain path { dest [format] [--blockdev] | --xml file }
984 [--shallow] [--reuse-external] [bandwidth]
985 [--wait [--async] [--verbose]] [{--pivot | --finish}]
986 [--timeout seconds] [granularity] [buf-size] [--bytes]
987 [--transient-job] [--synchronous-writes] [--print-xml]
988 Copy a disk backing image chain to a destination. Either dest as the
990 destination file name, or --xml with the name of an XML file containing
991 a top-level <disk> element describing the destination, must be present.
992 Additionally, if dest is given, format should be specified to declare
993 the format of the destination (if format is omitted, then libvirt will
994 reuse the format of the source, or with --reuse-external will be forced
995 to probe the destination format, which could be a potential security
996 hole). The command supports --raw as a boolean flag synonym for --for‐
997 mat=raw. When using dest, the destination is treated as a regular file
998 unless --blockdev is used to signal that it is a block device. By de‐
999 fault, this command flattens the entire chain; but if --shallow is
1000 specified, the copy shares the backing chain.
1001 If --reuse-external is specified, then the destination must exist and
1003 have sufficient space to hold the copy. If --shallow is used in con‐
1004 junction with --reuse-external then the pre-created image must have
1005 guest visible contents identical to guest visible contents of the back‐
1006 ing file of the original image. This may be used to modify the backing
1007 file names on the destination.
1008 By default, the copy job runs in the background, and consists of two
1010 phases. Initially, the job must copy all data from the source, and
1011 during this phase, the job can only be canceled to revert back to the
1012 source disk, with no guarantees about the destination. After this
1013 phase completes, both the source and the destination remain mirrored
1014 until a call to blockjob with the --abort and --pivot flags pivots over
1015 to the copy, or a call without --pivot leaves the destination as a
1016 faithful copy of that point in time. However, if --wait is specified,
1017 then this command will block until the mirroring phase begins, or can‐
1018 cel the operation if the optional timeout in seconds elapses or SIGINT
1019 is sent (usually with Ctrl-C). Using --verbose along with --wait will
1020 produce periodic status updates. Using --pivot (similar to blockjob
1021 --pivot) or --finish (similar to blockjob --abort) implies --wait, and
1022 will additionally end the job cleanly rather than leaving things in the
1023 mirroring phase. If job cancellation is triggered by timeout or by
1024 --finish, --async will return control to the user as fast as possible,
1025 otherwise the command may continue to block a little while longer until
1026 the job has actually cancelled.
1027 path specifies fully-qualified path of the disk. bandwidth specifies
1029 copying bandwidth limit in MiB/s. Specifying a negative value is inter‐
1030 preted as an unsigned long long value that might be essentially unlim‐
1031 ited, but more likely would overflow; it is safer to use 0 for that
1032 purpose. For further information on the bandwidth argument see the cor‐
1033 responding section for the blockjob command. Specifying granularity
1034 allows fine-tuning of the granularity that will be copied when a dirty
1035 region is detected; larger values trigger less I/O overhead but may end
1036 up copying more data overall (the default value is usually correct);
1037 hypervisors may restrict this to be a power of two or fall within a
1038 certain range. Specifying buf-size will control how much data can be
1039 simultaneously in-flight during the copy; larger values use more memory
1040 but may allow faster completion (the default value is usually correct).
1041 --transient-job allows specifying that the user does not require the
1043 job to be recovered if the VM crashes or is turned off before the job
1044 completes. This flag removes the restriction of copy jobs to transient
1045 domains if that restriction is applied by the hypervisor.
1046 If --synchronous-writes is specified the block job will wait for guest
1048 writes to be propagated both to the original image and to the destina‐
1049 tion of the copy so that it's guaranteed that the job converges if the
1050 destination storage is slower. This may impact performance of writes
1051 while the blockjob is running.
1052 If --print-xml is specified, then the XML used to start the block copy
1054 job is printed instead of starting the job.
1055 blockjob
1057 Syntax:
1058 blockjob domain path { [--abort] [--async] [--pivot] |
1060 [--info] [--raw] [--bytes] | [bandwidth] }
1061 Manage active block operations. There are three mutually-exclusive
1063 modes: --info, bandwidth, and --abort. --async and --pivot imply abort
1064 mode; --raw implies info mode; and if no mode was given, --info mode is
1065 assumed.
1066 path specifies fully-qualified path of the disk; it corresponds to a
1068 unique target name (<target dev='name'/>) or source file (<source
1069 file='name'/>) for one of the disk devices attached to domain (see also
1070 domblklist for listing these names).
1071 In --abort mode, the active job on the specified disk will be aborted.
1073 If --async is also specified, this command will return immediately,
1074 rather than waiting for the cancellation to complete. If --pivot is
1075 specified, this requests that an active copy or active commit job be
1076 pivoted over to the new image.
1077 In --info mode, the active job information on the specified disk will
1079 be printed. By default, the output is a single human-readable summary
1080 line; this format may change in future versions. Adding --raw lists
1081 each field of the struct, in a stable format. If the --bytes flag is
1082 set, then the command errors out if the server could not supply bytes/s
1083 resolution; when omitting the flag, raw output is listed in MiB/s and
1084 human-readable output automatically selects the best resolution sup‐
1085 ported by the server.
1086 bandwidth can be used to set bandwidth limit for the active job in
1088 MiB/s. If --bytes is specified then the bandwidth value is interpreted
1089 in bytes/s. Specifying a negative value is interpreted as an unsigned
1090 long value or essentially unlimited. The hypervisor can choose whether
1091 to reject the value or convert it to the maximum value allowed. Option‐
1092 ally a scaled positive number may be used as bandwidth (see NOTES
1093 above). Using --bytes with a scaled value permits a finer granularity
1094 to be selected. A scaled value used without --bytes will be rounded
1095 down to MiB/s. Note that the --bytes may be unsupported by the hypervi‐
1096 sor.
1097 Note that the progress reported for blockjobs corresponding to a
1099 pull-mode backup don't report progress of the backup but rather usage
1100 of temporary space required for the backup.
1101 blockpull
1103 Syntax:
1104 blockpull domain path [bandwidth] [--bytes] [base]
1106 [--wait [--verbose] [--timeout seconds] [--async]]
1107 [--keep-relative]
1108 Populate a disk from its backing image chain. By default, this command
1110 flattens the entire chain; but if base is specified, containing the
1111 name of one of the backing files in the chain, then that file becomes
1112 the new backing file and only the intermediate portion of the chain is
1113 pulled. Once all requested data from the backing image chain has been
1114 pulled, the disk no longer depends on that portion of the backing
1115 chain.
1116 By default, this command returns as soon as possible, and data for the
1118 entire disk is pulled in the background; the progress of the operation
1119 can be checked with blockjob. However, if --wait is specified, then
1120 this command will block until the operation completes, or cancel the
1121 operation if the optional timeout in seconds elapses or SIGINT is sent
1122 (usually with Ctrl-C). Using --verbose along with --wait will produce
1123 periodic status updates. If job cancellation is triggered, --async
1124 will return control to the user as fast as possible, otherwise the com‐
1125 mand may continue to block a little while longer until the job is done
1126 cleaning up.
1127 Using the --keep-relative flag will keep the backing chain names rela‐
1129 tive.
1130 path specifies fully-qualified path of the disk; it corresponds to a
1132 unique target name (<target dev='name'/>) or source file (<source
1133 file='name'/>) for one of the disk devices attached to domain (see also
1134 domblklist for listing these names). bandwidth specifies copying band‐
1135 width limit in MiB/s. For further information on the bandwidth argument
1136 see the corresponding section for the blockjob command.
1137 blockresize
1139 Syntax:
1140 blockresize domain path size
1142 Resize a block device of domain while the domain is running, path spec‐
1144 ifies the absolute path of the block device; it corresponds to a unique
1145 target name (<target dev='name'/>) or source file (<source
1146 file='name'/>) for one of the disk devices attached to domain (see also
1147 domblklist for listing these names).
1148 size is a scaled integer (see NOTES above) which defaults to KiB
1150 (blocks of 1024 bytes) if there is no suffix. You must use a suffix of
1151 "B" to get bytes (note that for historical reasons, this differs from
1152 vol-resize which defaults to bytes without a suffix).
1153 console
1155 Syntax:
1156 console domain [devname] [--safe] [--force]
1158 Connect the virtual serial console for the guest. The optional devname
1160 parameter refers to the device alias of an alternate console, serial or
1161 parallel device configured for the guest. If omitted, the primary con‐
1162 sole will be opened.
1163 If the flag --safe is specified, the connection is only attempted if
1165 the driver supports safe console handling. This flag specifies that the
1166 server has to ensure exclusive access to console devices. Optionally
1167 the --force flag may be specified, requesting to disconnect any exist‐
1168 ing sessions, such as in a case of a broken connection.
1169 cpu-stats
1171 Syntax:
1172 cpu-stats domain [--total] [start] [count]
1174 Provide cpu statistics information of a domain. The domain should be
1176 running. Default it shows stats for all CPUs, and a total. Use --total
1177 for only the total stats, start for only the per-cpu stats of the CPUs
1178 from start, count for only count CPUs' stats.
1179 create
1181 Syntax:
1182 create FILE [--console] [--paused] [--autodestroy]
1184 [--pass-fds N,M,...] [--validate] [--reset-nvram]
1185 Create a domain from an XML <file>. Optionally, --validate option can
1187 be passed to validate the format of the input XML file against an in‐
1188 ternal RNG schema (identical to using virt-xml-validate(1) tool). Do‐
1189 mains created using this command are going to be either transient (tem‐
1190 porary ones that will vanish once destroyed) or existing persistent
1191 guests that will run with one-time use configuration, leaving the per‐
1192 sistent XML untouched (this can come handy during an automated testing
1193 of various configurations all based on the original XML). See the ex‐
1194 ample below for usage demonstration.
1195 The domain will be paused if the --paused option is used and supported
1197 by the driver; otherwise it will be running. If --console is requested,
1198 attach to the console after creation. If --autodestroy is requested,
1199 then the guest will be automatically destroyed when virsh closes its
1200 connection to libvirt, or otherwise exits.
1201 If --pass-fds is specified, the argument is a comma separated list of
1203 open file descriptors which should be pass on into the guest. The file
1204 descriptors will be re-numbered in the guest, starting from 3. This is
1205 only supported with container based virtualization.
1206 If --reset-nvram is specified, any existing NVRAM file will be deleted
1208 and re-initialized from its pristine template.
1209 Example:
1211 1. prepare a template from an existing domain (skip directly to 3a if
1213 writing one from scratch)
1214 # virsh dumpxml <domain> > domain.xml
1216 2. edit the template using an editor of your choice and:
1218 a. DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or
1220 b. DON'T CHANGE! either <name> or <uuid>
1222 # $EDITOR domain.xml
1224 3. create a domain from domain.xml, depending on whether following 2a
1226 or 2b respectively:
1227 a. the domain is going to be transient
1229 b. an existing persistent guest will run with a modified one-time
1231 configuration
1232 # virsh create domain.xml
1234 define
1236 Syntax:
1237 define FILE [--validate]
1239 Define a domain from an XML <file>. Optionally, the format of the input
1241 XML file can be validated against an internal RNG schema with --vali‐
1242 date (identical to using virt-xml-validate(1) tool). The domain defini‐
1243 tion is registered but not started. If domain is already running, the
1244 changes will take effect on the next boot.
1245 desc
1247 Syntax:
1248 desc domain [[--live] [--config] |
1250 [--current]] [--title] [--edit] [--new-desc
1251 New description or title message]
1252 Show or modify description and title of a domain. These values are user
1254 fields that allow storing arbitrary textual data to allow easy identi‐
1255 fication of domains. Title should be short, although it's not enforced.
1256 (See also metadata that works with XML based domain metadata.)
1257 Flags --live or --config select whether this command works on live or
1259 persistent definitions of the domain. If both --live and --config are
1260 specified, the --config option takes precedence on getting the current
1261 description and both live configuration and config are updated while
1262 setting the description. --current is exclusive and implied if none of
1263 these was specified.
1264 Flag --edit specifies that an editor with the contents of current de‐
1266 scription or title should be opened and the contents saved back after‐
1267 wards.
1268 Flag --title selects operation on the title field instead of descrip‐
1270 tion.
1271 If neither of --edit and --new-desc are specified the note or descrip‐
1273 tion is displayed instead of being modified.
1274 destroy
1276 Syntax:
1277 destroy domain [--graceful] [--remove-logs]
1279 Immediately terminate the domain domain. This doesn't give the domain
1281 OS any chance to react, and it's the equivalent of ripping the power
1282 cord out on a physical machine. In most cases you will want to use the
1283 shutdown command instead. However, this does not delete any storage
1284 volumes used by the guest, and if the domain is persistent, it can be
1285 restarted later.
1286 If domain is transient, then the metadata of any snapshots will be lost
1288 once the guest stops running, but the snapshot contents still exist,
1289 and a new domain with the same name and UUID can restore the snapshot
1290 metadata with snapshot-create. Similarly, the metadata of any check‐
1291 points will be lost, but can be restored with checkpoint-create.
1292 If --graceful is specified, don't resort to extreme measures (e.g.
1294 SIGKILL) when the guest doesn't stop after a reasonable timeout; return
1295 an error instead.
1296 If --remove-logs is specified, remove per domain log files. Not all de‐
1298 ployment configuration can be supported.
1299 In case of QEMU the flag is only supported if virlogd is used to handle
1301 QEMU process output. Otherwise the flag is ignored.
1302 domblkerror
1304 Syntax:
1305 domblkerror domain
1307 Show errors on block devices. This command usually comes handy when
1309 domstate command says that a domain was paused due to I/O error. The
1310 domblkerror command lists all block devices in error state and the er‐
1311 ror seen on each of them.
1312 domblkinfo
1314 Syntax:
1315 domblkinfo domain [block-device --all] [--human]
1317 Get block device size info for a domain. A block-device corresponds to
1319 a unique target name (<target dev='name'/>) or source file (<source
1320 file='name'/>) for one of the disk devices attached to domain (see also
1321 domblklist for listing these names). If --human is set, the output will
1322 have a human readable output. If --all is set, the output will be a
1323 table showing all block devices size info associated with domain. The
1324 --all option takes precedence of the others.
1325 domblklist
1327 Syntax:
1328 domblklist domain [--inactive] [--details]
1330 Print a table showing the brief information of all block devices asso‐
1332 ciated with domain. If --inactive is specified, query the block devices
1333 that will be used on the next boot, rather than those currently in use
1334 by a running domain. If --details is specified, disk type and device
1335 value will also be printed. Other contexts that require a block device
1336 name (such as domblkinfo or snapshot-create for disk snapshots) will
1337 accept either target or unique source names printed by this command.
1338 domblkstat
1340 Syntax:
1341 domblkstat domain [block-device] [--human]
1343 Get device block stats for a running domain. A block-device corre‐
1345 sponds to a unique target name (<target dev='name'/>) or source file
1346 (<source file='name'/>) for one of the disk devices attached to domain
1347 (see also domblklist for listing these names). On a LXC or QEMU domain,
1348 omitting the block-device yields device block stats summarily for the
1349 entire domain.
1350 Use --human for a more human readable output.
1352 Availability of these fields depends on hypervisor. Unsupported fields
1354 are missing from the output. Other fields may appear if communicating
1355 with a newer version of libvirtd.
1356 Explanation of fields (fields appear in the following order):
1358 • rd_req - count of read operations
1360 • rd_bytes - count of read bytes
1362 • wr_req - count of write operations
1364 • wr_bytes - count of written bytes
1366 • errs - error count
1368 • flush_operations - count of flush operations
1370 • rd_total_times - total time read operations took (ns)
1372 • wr_total_times - total time write operations took (ns)
1374 • flush_total_times - total time flush operations took (ns)
1376 • <-- other fields provided by hypervisor -->
1378 domblkthreshold
1380 Syntax:
1381 domblkthreshold domain dev threshold
1383 Set the threshold value for delivering the block-threshold event. dev
1385 specifies the disk device target or backing chain element of given de‐
1386 vice using the 'target[1]' syntax. threshold is a scaled value of the
1387 offset. If the block device should write beyond that offset the event
1388 will be delivered.
1389 domcontrol
1391 Syntax:
1392 domcontrol domain
1394 Returns state of an interface to VMM used to control a domain. For
1396 states other than "ok" or "error" the command also prints number of
1397 seconds elapsed since the control interface entered its current state.
1398 domdirtyrate-calc
1400 Syntax:
1401 domdirtyrate-calc <domain> [--seconds <sec>]
1403 --mode=[page-sampling | dirty-bitmap | dirty-ring]
1404 Calculate an active domain's memory dirty rate which may be expected by
1406 user in order to decide whether it's proper to be migrated out or not.
1407 The seconds parameter can be used to calculate dirty rate in a specific
1408 time which allows 60s at most now and would be default to 1s if miss‐
1409 ing. These three page-sampling, dirty-bitmap, dirty-ring modes are mu‐
1410 tually exclusive and alternative when specify calculation mode,
1411 page-sampling is the default mode if missing. The calculated dirty rate
1412 information is available by calling 'domstats --dirtyrate'.
1413 domdisplay
1415 Syntax:
1416 domdisplay domain [--include-password] [[--type] type] [--all]
1418 Output a URI which can be used to connect to the graphical display of
1420 the domain via VNC, SPICE or RDP. The particular graphical display
1421 type can be selected using the type parameter (e.g. "vnc", "spice",
1422 "rdp"). If --include-password is specified, the SPICE channel password
1423 will be included in the URI. If --all is specified, then all show all
1424 possible graphical displays, for a VM could have more than one graphi‐
1425 cal displays.
1426 domfsfreeze
1428 Syntax:
1429 domfsfreeze domain [[--mountpoint] mountpoint...]
1431 Freeze mounted filesystems within a running domain to prepare for con‐
1433 sistent snapshots.
1434 The --mountpoint option takes a parameter mountpoint, which is a mount
1436 point path of the filesystem to be frozen. This option can occur multi‐
1437 ple times. If this is not specified, every mounted filesystem is
1438 frozen.
1439 Note: snapshot-create command has a --quiesce option to freeze and thaw
1441 the filesystems automatically to keep snapshots consistent. domfs‐
1442 freeze command is only needed when a user wants to utilize the native
1443 snapshot features of storage devices not supported by libvirt.
1444 domfsinfo
1446 Syntax:
1447 domfsinfo domain
1449 Show a list of mounted filesystems within the running domain. The list
1451 contains mountpoints, names of a mounted device in the guest, filesys‐
1452 tem types, and unique target names used in the domain XML (<target
1453 dev='name'/>).
1454 Note that this command requires a guest agent configured and running in
1456 the domain's guest OS.
1457 domfsthaw
1459 Syntax:
1460 domfsthaw domain [[--mountpoint] mountpoint...]
1462 Thaw mounted filesystems within a running domain, which have been
1464 frozen by domfsfreeze command.
1465 The --mountpoint option takes a parameter mountpoint, which is a mount
1467 point path of the filesystem to be thawed. This option can occur multi‐
1468 ple times. If this is not specified, every mounted filesystem is
1469 thawed.
1470 domfstrim
1472 Syntax:
1473 domfstrim domain [--minimum bytes] [--mountpoint mountPoint]
1475 Issue a fstrim command on all mounted filesystems within a running do‐
1477 main. It discards blocks which are not in use by the filesystem. If
1478 --minimum bytes is specified, it tells guest kernel length of contigu‐
1479 ous free range. Smaller than this may be ignored (this is a hint and
1480 the guest may not respect it). By increasing this value, the fstrim op‐
1481 eration will complete more quickly for filesystems with badly frag‐
1482 mented free space, although not all blocks will be discarded. The de‐
1483 fault value is zero, meaning "discard every free block". Moreover, if a
1484 user wants to trim only one mount point, it can be specified via op‐
1485 tional --mountpoint parameter.
1486 domhostname
1488 Syntax:
1489 domhostname domain [--source lease|agent]
1491 Returns the hostname of a domain, if the hypervisor makes it available.
1493 The --source argument specifies what data source to use for the host‐
1495 names, currently 'lease' to read DHCP leases or 'agent' to query the
1496 guest OS via an agent. If unspecified, driver returns the default
1497 method available (some drivers support only one type of source).
1498 domid
1500 Syntax:
1501 domid domain-name-or-uuid
1503 Convert a domain name (or UUID) to a domain id
1505 domif-getlink
1507 Syntax:
1508 domif-getlink domain interface-device [--config]
1510 Query link state of the domain's virtual interface. If --config is
1512 specified, query the persistent configuration, for compatibility pur‐
1513 poses, --persistent is alias of --config.
1514 interface-device can be the interface's target name or the MAC address.
1516 domif-setlink
1518 Syntax:
1519 domif-setlink domain interface-device state [--config] [--print-xml]
1521 Modify link state of the domain's virtual interface. Possible values
1523 for state are "up" and "down". If --config is specified, only the per‐
1524 sistent configuration of the domain is modified, for compatibility pur‐
1525 poses, --persistent is alias of --config. interface-device can be the
1526 interface's target name or the MAC address.
1527 If --print-xml is specified, then the XML used to update the interface
1529 is printed instead.
1530 domifaddr
1532 Syntax:
1533 domifaddr domain [interface] [--full]
1535 [--source lease|agent|arp]
1536 Get a list of interfaces of a running domain along with their IP and
1538 MAC addresses, or limited output just for one interface if interface is
1539 specified. Note that interface can be driver dependent, it can be the
1540 name within guest OS or the name you would see in domain XML. Moreover,
1541 the whole command may require a guest agent to be configured for the
1542 queried domain under some hypervisors, notably QEMU.
1543 If --full is specified, the interface name and MAC address is always
1545 displayed when the interface has multiple IP addresses or aliases; oth‐
1546 erwise, only the interface name and MAC address is displayed for the
1547 first name and MAC address with "-" for the others using the same name
1548 and MAC address.
1549 The --source argument specifies what data source to use for the ad‐
1551 dresses, currently 'lease' to read DHCP leases, 'agent' to query the
1552 guest OS via an agent, or 'arp' to get IP from host's arp tables. If
1553 unspecified, 'lease' is the default.
1554 backup-begin
1556 Syntax:
1557 backup-begin domain [backupxml] [checkpointxml] [--reuse-external]
1559 Begin a new backup job. If backupxml is omitted, this defaults to a
1561 full backup using a push model to filenames generated by libvirt; sup‐
1562 plying XML allows fine-tuning such as requesting an incremental backup
1563 relative to an earlier checkpoint, controlling which disks participate
1564 or which filenames are involved, or requesting the use of a pull model
1565 backup. The backup-dumpxml command shows any resulting values assigned
1566 by libvirt. For more information on backup XML, see:
1567 https://libvirt.org/formatbackup.html
1568 If --reuse-external is used it instructs libvirt to reuse temporary and
1570 output files provided by the user in backupxml.
1571 If checkpointxml is specified, a second file with a top-level element
1573 of domaincheckpoint is used to create a simultaneous checkpoint, for
1574 doing a later incremental backup relative to the time the backup was
1575 created. See checkpoint-create for more details on checkpoints.
1576 This command returns as soon as possible, and the backup job runs in
1578 the background; the progress of a push model backup can be checked with
1579 domjobinfo or by waiting for an event with event (the progress of a
1580 pull model backup is under the control of whatever third party connects
1581 to the NBD export). The job is ended with domjobabort.
1582 backup-dumpxml
1584 Syntax:
1585 backup-dumpxml [--xpath EXPRESSION] [--wrap] domain
1587 Output XML describing the current backup job.
1589 If the --xpath argument provides an XPath expression, it will be evalu‐
1591 ated against the output XML and only those matching nodes will be
1592 printed. The default behaviour is to print each matching node as a
1593 standalone document, however, for ease of additional processing, the
1594 --wrap argument will cause the matching node to be wrapped in a common
1595 root node.
1596 domiflist
1598 Syntax:
1599 domiflist domain [--inactive]
1601 Print a table showing the brief information of all virtual interfaces
1603 associated with domain. If --inactive is specified, query the virtual
1604 interfaces that will be used on the next boot, rather than those cur‐
1605 rently in use by a running domain. Other contexts that require a MAC
1606 address of virtual interface (such as detach-interface or
1607 domif-setlink) will accept the MAC address printed by this command.
1608 domifstat
1610 Syntax:
1611 domifstat domain interface-device
1613 Get network interface stats for a running domain. The network interface
1615 stats are only available for interfaces that have a physical source in‐
1616 terface. This does not include, for example, a 'user' interface type
1617 since it is a virtual LAN with NAT to the outside world. interface-de‐
1618 vice can be the interface target by name or MAC address.
1619 domiftune
1621 Syntax:
1622 domiftune domain interface-device [[--config] [--live] | [--current]]
1624 [*--inbound average,peak,burst,floor*]
1625 [*--outbound average,peak,burst*]
1626 Set or query the domain's network interface's bandwidth parameters.
1628 interface-device can be the interface's target name (<target
1629 dev='name'/>), or the MAC address.
1630 If no --inbound or --outbound is specified, this command will query and
1632 show the bandwidth settings. Otherwise, it will set the inbound or out‐
1633 bound bandwidth. average,peak,burst,floor is the same as in command at‐
1634 tach-interface. Values for average, peak and floor are expressed in
1635 kilobytes per second, while burst is expressed in kilobytes in a single
1636 burst at peak speed as described in the Network XML documentation at
1637 https://libvirt.org/formatnetwork.html#quality-of-service.
1638 To clear inbound or outbound settings, use --inbound or --outbound re‐
1640 spectfully with average value of zero.
1641 If --live is specified, affect a running guest. If --config is speci‐
1643 fied, affect the next start of a persistent guest. If --current is
1644 specified, it is equivalent to either --live or --config, depending on
1645 the current state of the guest. Both --live and --config flags may be
1646 given, but --current is exclusive. If no flag is specified, behavior is
1647 different depending on hypervisor.
1648 dominfo
1650 Syntax:
1651 dominfo domain
1653 Returns basic information about the domain.
1655 domjobabort
1657 Syntax:
1658 domjobabort domain [--postcopy]
1660 Abort the currently running domain job.
1662 When the job to be aborted is a migration which entered post-copy mode,
1664 it cannot be aborted as none of the hosts involved in migration has a
1665 complete state of the domain. Optional --postcopy can be used to inter‐
1666 rupt such migration although doing so may effectively suspend the do‐
1667 main until the migration is resumed (see also --postcopy-resume option
1668 of migrate).
1669 domjobinfo
1671 Syntax:
1672 domjobinfo domain [--completed [--keep-completed]] [--anystats] [--rawstats]
1674 Returns information about jobs running on a domain. --completed tells
1676 virsh to return information about a recently finished job. Statistics
1677 of a completed job are automatically destroyed once read (unless
1678 --keep-completed is used) or when libvirtd is restarted.
1679 Normally only statistics for running and successful completed jobs are
1681 printed. --anystats can be used to also display statistics for failed
1682 jobs.
1683 In case --rawstats is used, all fields are printed as received from the
1685 server without any attempts to interpret the data. The "Job type:"
1686 field is special, since it's reported by the API and not part of stats.
1687 Note that time information returned for completed migrations may be
1689 completely irrelevant unless both source and destination hosts have
1690 synchronized time (i.e., NTP daemon is running on both of them).
1691 domlaunchsecinfo
1693 Syntax:
1694 domlaunchsecinfo domain
1696 Returns information about the launch security parameters associated
1698 with a running domain.
1699 The set of parameters reported will vary depending on which type of
1701 launch security protection is active. If none is active, no parameters
1702 will be reported.
1703 domsetlaunchsecstate
1705 Syntax:
1706 domsetlaunchsecstate domain --secrethdr hdr-filename
1708 --secret secret-filename [--set-address address]
1709 Set a launch security secret in the guest's memory. The guest must have
1711 a launchSecurity type enabled in its configuration and be in a paused
1712 state. On success, the guest can be transitioned to a running state.
1713 On failure, the guest should be destroyed.
1714 --secrethdr specifies a filename containing the base64-encoded secret
1716 header. The header includes artifacts needed by the hypervisor
1717 firmware to recover the plain text of the launch secret. --secret spec‐
1718 ifies the filename containing the base64-encoded encrypted launch se‐
1719 cret.
1720 The --set-address option can be used to specify a physical address
1722 within the guest's memory to set the secret. If not specified, the ad‐
1723 dress will be determined by the hypervisor.
1724 dommemstat
1726 Syntax:
1727 dommemstat domain [--period seconds] [[--config] [--live] | [--current]]
1729 Get memory stats for a running domain.
1731 Availability of these fields depends on hypervisor. Unsupported fields
1733 are missing from the output. Other fields may appear if communicating
1734 with a newer version of libvirtd.
1735 Explanation of fields:
1737 • swap_in - The amount of data read from swap space (in KiB)
1739 • swap_out - The amount of memory written out to swap space
1741 (in KiB)
1742 • major_fault - The number of page faults where disk IO was re‐
1744 quired
1745 • minor_fault - The number of other page faults
1747 • unused - The amount of memory left unused by the system
1749 (in KiB)
1750 • available - The amount of usable memory as seen by the domain
1752 (in KiB)
1753 • actual - Current balloon value (in KiB)
1755 • rss - Resident Set Size of the running domain's process
1757 (in KiB)
1758 • usable - The amount of memory which can be reclaimed by
1760 balloon without causing host swapping (in KiB)
1761 • last-update - Timestamp of the last update of statistics (in
1763 seconds)
1764 • disk_caches - The amount of memory that can be reclaimed with‐
1766 out additional I/O, typically disk caches (in KiB)
1767 • hugetlb_pgalloc - The number of successful huge page allocations
1769 initiated from within the domain
1770 • hugetlb_pgfail - The number of failed huge page allocations initi‐
1772 ated from within the domain
1773 For QEMU/KVM with a memory balloon, setting the optional --period to a
1775 value larger than 0 in seconds will allow the balloon driver to return
1776 additional statistics which will be displayed by subsequent dommemstat
1777 commands. Setting the --period to 0 will stop the balloon driver col‐
1778 lection, but does not clear the statistics in the balloon driver. Re‐
1779 quires at least QEMU/KVM 1.5 to be running on the host.
1780 The --live, --config, and --current flags are only valid when using the
1782 --period option in order to set the collection period for the balloon
1783 driver. If --live is specified, only the running guest collection pe‐
1784 riod is affected. If --config is specified, affect the next start of a
1785 persistent guest. If --current is specified, it is equivalent to either
1786 --live or --config, depending on the current state of the guest.
1787 Both --live and --config flags may be given, but --current is exclu‐
1789 sive. If no flag is specified, behavior is different depending on the
1790 guest state.
1791 domname
1793 Syntax:
1794 domname domain-id-or-uuid
1796 Convert a domain Id (or UUID) to domain name
1798 dompmsuspend
1800 Syntax:
1801 dompmsuspend domain target [--duration]
1803 Suspend a running domain into one of these states (possible target val‐
1805 ues):
1806 • mem - equivalent of S3 ACPI state
1808 • disk - equivalent of S4 ACPI state
1810 • hybrid - RAM is saved to disk but not powered off
1812 The --duration argument specifies number of seconds before the domain
1814 is woken up after it was suspended (see also dompmwakeup). Default is 0
1815 for unlimited suspend time. (This feature isn't currently supported by
1816 any hypervisor driver and 0 should be used.).
1817 Note that this command requires a guest agent configured and running in
1819 the domain's guest OS.
1820 Beware that at least for QEMU, the domain's process will be terminated
1822 when target disk is used and a new process will be launched when lib‐
1823 virt is asked to wake up the domain. As a result of this, any runtime
1824 changes, such as device hotplug or memory settings, are lost unless
1825 such changes were made with --config flag.
1826 dompmwakeup
1828 Syntax:
1829 dompmwakeup domain
1831 Wakeup a domain from pmsuspended state (either suspended by dompmsus‐
1833 pend or from the guest itself). Injects a wakeup into the guest that is
1834 in pmsuspended state, rather than waiting for the previously requested
1835 duration (if any) to elapse. This operation does not necessarily fail
1836 if the domain is running.
1837 domrename
1839 Syntax:
1840 domrename domain new-name
1842 Rename a domain. This command changes current domain name to the new
1844 name specified in the second argument.
1845 Note: Domain must be inactive.
1847 domstate
1849 Syntax:
1850 domstate domain [--reason]
1852 Returns state about a domain. --reason tells virsh to also print rea‐
1854 son for the state.
1855 domstats
1857 Syntax:
1858 domstats [--raw] [--enforce] [--backing] [--nowait] [--state]
1860 [--cpu-total] [--balloon] [--vcpu] [--interface]
1861 [--block] [--perf] [--iothread] [--memory] [--dirtyrate] [--vm]
1862 [[--list-active] [--list-inactive]
1863 [--list-persistent] [--list-transient] [--list-running]y
1864 [--list-paused] [--list-shutoff] [--list-other]] | [domain ...]
1865 Get statistics for multiple or all domains. Without any argument this
1867 command prints all available statistics for all domains.
1868 The list of domains to gather stats for can be either limited by list‐
1870 ing the domains as a space separated list, or by specifying one of the
1871 filtering flags --list-NNN. (The approaches can't be combined.)
1872 By default some of the returned fields may be converted to more human
1874 friendly values by a set of pretty-printers. To suppress this behavior
1875 use the --raw flag.
1876 The individual statistics groups are selectable via specific flags. By
1878 default all supported statistics groups are returned. Supported statis‐
1879 tics groups flags are: --state, --cpu-total, --balloon, --vcpu, --in‐
1880 terface, --block, --perf, --iothread, --memory, --dirtyrate, --vm.
1881 Note that - depending on the hypervisor type and version or the domain
1883 state - not all of the following statistics may be returned.
1884 When selecting the --state group the following fields are returned:
1886 • state.state - state of the VM, returned as number from virDomainState
1888 enum
1889 • state.reason - reason for entering given state, returned as int from
1891 virDomain*Reason enum corresponding to given state
1892 --cpu-total returns:
1894 • cpu.time - total cpu time spent for this domain in nanoseconds
1896 • cpu.user - user cpu time spent in nanoseconds
1898 • cpu.system - system cpu time spent in nanoseconds
1900 • cpu.haltpoll.success.time - cpu halt polling success time spent in
1902 nanoseconds
1903 • cpu.haltpoll.fail.time - cpu halt polling fail time spent in nanosec‐
1905 onds
1906 • cpu.cache.monitor.count - the number of cache monitors for this do‐
1908 main
1909 • cpu.cache.monitor.<num>.name - the name of cache monitor <num>
1911 • cpu.cache.monitor.<num>.vcpus - vcpu list of cache monitor <num>
1913 • cpu.cache.monitor.<num>.bank.count - the number of cache banks in
1915 cache monitor <num>
1916 • cpu.cache.monitor.<num>.bank.<index>.id - host allocated cache id for
1918 bank <index> in cache monitor <num>
1919 • cpu.cache.monitor.<num>.bank.<index>.bytes - the number of bytes of
1921 last level cache that the domain is using on cache bank <index>
1922 --balloon returns:
1924 • balloon.current - the memory in KiB currently used
1926 • balloon.maximum - the maximum memory in KiB allowed
1928 • balloon.swap_in - the amount of data read from swap space (in KiB)
1930 • balloon.swap_out - the amount of memory written out to swap space (in
1932 KiB)
1933 • balloon.major_fault - the number of page faults when disk IO was re‐
1935 quired
1936 • balloon.minor_fault - the number of other page faults
1938 • balloon.unused - the amount of memory left unused by the system (in
1940 KiB)
1941 • balloon.available - the amount of usable memory as seen by the domain
1943 (in KiB)
1944 • balloon.rss - Resident Set Size of running domain's process (in KiB)
1946 • balloon.usable - the amount of memory which can be reclaimed by bal‐
1948 loon without causing host swapping (in KiB)
1949 • balloon.last-update - timestamp of the last update of statistics (in
1951 seconds)
1952 • balloon.disk_caches - the amount of memory that can be reclaimed
1954 without additional I/O, typically disk (in KiB)
1955 • balloon.hugetlb_pgalloc - the number of successful huge page alloca‐
1957 tions from inside the domain via virtio balloon
1958 • balloon.hugetlb_pgfail - the number of failed huge page allocations
1960 from inside the domain via virtio balloon
1961 --vcpu returns:
1963 • vcpu.current - current number of online virtual CPUs
1965 • vcpu.maximum - maximum number of online virtual CPUs
1967 • vcpu.<num>.state - state of the virtual CPU <num>, as number from
1969 virVcpuState enum
1970 • vcpu.<num>.time - virtual cpu time spent by virtual CPU <num> (in mi‐
1972 croseconds)
1973 • vcpu.<num>.wait - virtual cpu time spent by virtual CPU <num> waiting
1975 on I/O (in microseconds)
1976 • vcpu.<num>.halted - virtual CPU <num> is halted: yes or no (may indi‐
1978 cate the processor is idle or even disabled, depending on the archi‐
1979 tecture)
1980 • vcpu.<num>.delay - time the vCPU <num> thread was enqueued by the
1982 host scheduler, but was waiting in the queue instead of running. Ex‐
1983 posed to the VM as a steal time.
1984 This group of statistics also reports additional hypervisor-originating
1986 per-vCPU stats. The hypervisor-specific statistics in this group have
1987 the following naming scheme:
1988 vcpu.<num>.$NAME.$TYPE
1989 $NAME name of the statistics field provided by the hypervisor
1991 $TYPE Type of the value. The following types are returned:
1993 cur current instant value
1995 sum aggregate value
1997 max peak value
1999 The returned value may be either an unsigned long long or a boolean.
2001 Meaning is hypervisor specific. Please see the disclaimer for the
2002 --vm group which also consists of hypervisor-specific stats.
2003 --interface returns:
2005 • net.count - number of network interfaces on this domain
2007 • net.<num>.name - name of the interface <num>
2009 • net.<num>.rx.bytes - number of bytes received
2011 • net.<num>.rx.pkts - number of packets received
2013 • net.<num>.rx.errs - number of receive errors
2015 • net.<num>.rx.drop - number of receive packets dropped
2017 • net.<num>.tx.bytes - number of bytes transmitted
2019 • net.<num>.tx.pkts - number of packets transmitted
2021 • net.<num>.tx.errs - number of transmission errors
2023 • net.<num>.tx.drop - number of transmit packets dropped
2025 --perf returns the statistics of all enabled perf events:
2027 • perf.cmt - the cache usage in Byte currently used
2029 • perf.mbmt - total system bandwidth from one level of cache
2031 • perf.mbml - bandwidth of memory traffic for a memory controller
2033 • perf.cpu_cycles - the count of cpu cycles (total/elapsed)
2035 • perf.instructions - the count of instructions
2037 • perf.cache_references - the count of cache hits
2039 • perf.cache_misses - the count of caches misses
2041 • perf.branch_instructions - the count of branch instructions
2043 • perf.branch_misses - the count of branch misses
2045 • perf.bus_cycles - the count of bus cycles
2047 • perf.stalled_cycles_frontend - the count of stalled frontend cpu cy‐
2049 cles
2050 • perf.stalled_cycles_backend - the count of stalled backend cpu cycles
2052 • perf.ref_cpu_cycles - the count of ref cpu cycles
2054 • perf.cpu_clock - the count of cpu clock time
2056 • perf.task_clock - the count of task clock time
2058 • perf.page_faults - the count of page faults
2060 • perf.context_switches - the count of context switches
2062 • perf.cpu_migrations - the count of cpu migrations
2064 • perf.page_faults_min - the count of minor page faults
2066 • perf.page_faults_maj - the count of major page faults
2068 • perf.alignment_faults - the count of alignment faults
2070 • perf.emulation_faults - the count of emulation faults
2072 See the perf command for more details about each event.
2074 --block returns information about disks associated with each domain.
2076 Using the --backing flag extends this information to cover all re‐
2077 sources in the backing chain, rather than the default of limiting in‐
2078 formation to the active layer for each guest disk. Information listed
2079 includes:
2080 • block.count - number of block devices being listed
2082 • block.<num>.name - name of the target of the block device <num> (the
2084 same name for multiple entries if --backing is present)
2085 • block.<num>.backingIndex - when --backing is present, matches up with
2087 the <backingStore> index listed in domain XML for backing files
2088 • block.<num>.path - file source of block device <num>, if it is a lo‐
2090 cal file or block device
2091 • block.<num>.rd.reqs - number of read requests
2093 • block.<num>.rd.bytes - number of read bytes
2095 • block.<num>.rd.times - total time (ns) spent on reads
2097 • block.<num>.wr.reqs - number of write requests
2099 • block.<num>.wr.bytes - number of written bytes
2101 • block.<num>.wr.times - total time (ns) spent on writes
2103 • block.<num>.fl.reqs - total flush requests
2105 • block.<num>.fl.times - total time (ns) spent on cache flushing
2107 • block.<num>.errors - Xen only: the 'oo_req' value
2109 • block.<num>.allocation - offset of highest written sector in bytes
2111 • block.<num>.capacity - logical size of source file in bytes
2113 • block.<num>.physical - physical size of source file in bytes
2115 • block.<num>.threshold - threshold (in bytes) for delivering the
2117 VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event. See domblkthreshold.
2118 --iothread returns information about IOThreads on the running guest if
2120 supported by the hypervisor.
2121 The "poll-max-ns" for each thread is the maximum nanoseconds to allow
2123 each polling interval to occur. A polling interval is a period of time
2124 allowed for a thread to process data before being the guest gives up
2125 its CPU quantum back to the host. A value set too small will not allow
2126 the IOThread to run long enough on a CPU to process data. A value set
2127 too high will consume too much CPU time per IOThread failing to allow
2128 other threads running on the CPU to get time. The polling interval is
2129 not available for statistical purposes.
2130 •
2132 iothread.count - maximum number of IOThreads in the subsequent list
2134 as unsigned int. Each IOThread in the list will will use it's
2135 iothread_id value as the <id>. There may be fewer <id> entries
2136 than the iothread.count value if the polling values are not
2137 supported.
2138 • iothread.<id>.poll-max-ns - maximum polling time in nanoseconds used
2140 by the <id> IOThread. A value of 0 (zero) indicates polling is dis‐
2141 abled.
2142 • iothread.<id>.poll-grow - polling time grow value. A value of 0
2144 (zero) growth is managed by the hypervisor.
2145 • iothread.<id>.poll-shrink - polling time shrink value. A value of
2147 (zero) indicates shrink is managed by hypervisor.
2148 --memory returns:
2150 • memory.bandwidth.monitor.count - the number of memory bandwidth moni‐
2152 tors for this domain
2153 • memory.bandwidth.monitor.<num>.name - the name of monitor <num>
2155 • memory.bandwidth.monitor.<num>.vcpus - the vcpu list of monitor <num>
2157 •
2159 memory.bandwidth.monitor.<num>.node.count - the number of memory
2161 controller in monitor <num>
2162 • memory.bandwidth.monitor.<num>.node.<index>.id - host allocated mem‐
2164 ory controller id for controller <index> of monitor <num>
2165 • memory.bandwidth.monitor.<num>.node.<index>.bytes.local - the accumu‐
2167 lative bytes consumed by @vcpus that passing through the memory con‐
2168 troller in the same processor that the scheduled host CPU belongs to.
2169 • memory.bandwidth.monitor.<num>.node.<index>.bytes.total - the total
2171 bytes consumed by @vcpus that passing through all memory controllers,
2172 either local or remote controller.
2173 --dirtyrate returns:
2175 • dirtyrate.calc_status - the status of last memory dirty rate calcula‐
2177 tion, returned as number from virDomainDirtyRateStatus enum.
2178 • dirtyrate.calc_start_time - the start time of last memory dirty rate
2180 calculation.
2181 • dirtyrate.calc_period - the period of last memory dirty rate calcula‐
2183 tion.
2184 • dirtyrate.megabytes_per_second - the calculated memory dirty rate in
2186 MiB/s.
2187 • dirtyrate.calc_mode - the calculation mode used last measurement
2189 (page-sampling/dirty-bitmap/dirty-ring)
2190 • dirtyrate.vcpu.<num>.megabytes_per_second - the calculated memory
2192 dirty rate for a virtual cpu in MiB/s
2193 --vm returns:
2195 The --vm option enables reporting of hypervisor-specific statistics.
2197 Naming and meaning of the fields is entirely hypervisor dependent.
2198 The statistics in this group have the following naming scheme:
2200 vm.$NAME.$TYPE
2201 $NAME name of the statistics field provided by the hypervisor
2203 $TYPE Type of the value. The following types are returned:
2205 cur current instant value
2207 sum aggregate value
2209 max peak value
2211 The returned value may be either an unsigned long long or a boolean.
2213 WARNING: The stats reported in this group are runtime-collected and
2215 hypervisor originated, thus fall outside of the usual stable API
2216 policies of libvirt.
2217 Libvirt can't guarantee that the statistics reported from the out‐
2219 side source will be present in further versions of the hypervisor,
2220 or that naming or meaning will stay consistent. Changes to existing
2221 fields, however, are expected to be rare.
2222 Selecting a specific statistics groups doesn't guarantee that the dae‐
2224 mon supports the selected group of stats. Flag --enforce forces the
2225 command to fail if the daemon doesn't support the selected group.
2226 When collecting stats libvirtd may wait for some time if there's al‐
2228 ready another job running on given domain for it to finish. This may
2229 cause unnecessary delay in delivering stats. Using --nowait suppresses
2230 this behaviour. On the other hand some statistics might be missing for
2231 such domain.
2232 domtime
2234 Syntax:
2235 domtime domain { [--now] [--pretty] [--sync] [--time time] }
2237 Gets or sets the domain's system time. When run without any arguments
2239 (but domain), the current domain's system time is printed out. The
2240 --pretty modifier can be used to print the time in more human readable
2241 form.
2242 When --time time is specified, the domain's time is not gotten but set
2244 instead. The --now modifier acts like if it was an alias for --time
2245 $now, which means it sets the time that is currently on the host virsh
2246 is running at. In both cases (setting and getting), time is in seconds
2247 relative to Epoch of 1970-01-01 in UTC. The --sync modifies the set
2248 behavior a bit: The time passed is ignored, but the time to set is read
2249 from domain's RTC instead. Please note, that some hypervisors may re‐
2250 quire a guest agent to be configured in order to get or set the guest
2251 time.
2252 domuuid
2254 Syntax:
2255 domuuid domain-name-or-id
2257 Convert a domain name or id to domain UUID
2259 domxml-from-native
2261 Syntax:
2262 domxml-from-native format config
2264 Convert the file config in the native guest configuration format named
2266 by format to a domain XML format. For QEMU/KVM hypervisor, the format
2267 argument must be qemu-argv. For Xen hypervisor, the format argument may
2268 be xen-xm, xen-xl, or xen-sxpr. For LXC hypervisor, the format argument
2269 must be lxc-tools. For VMware/ESX hypervisor, the format argument must
2270 be vmware-vmx. For the Bhyve hypervisor, the format argument must be
2271 bhyve-argv.
2272 domxml-to-native
2274 Syntax:
2275 domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-uuid }
2277 Convert the file xml into domain XML format or convert an existing
2279 --domain to the native guest configuration format named by format. The
2280 xml and --domain arguments are mutually exclusive. For the types of
2281 format argument, refer to domxml-from-native.
2282 dump
2284 Syntax:
2285 dump domain corefilepath [--bypass-cache]
2287 { [--live] | [--crash] | [--reset] }
2288 [--verbose] [--memory-only] [--format string]
2289 Dumps the core of a domain to a file for analysis. If --live is speci‐
2291 fied, the domain continues to run until the core dump is complete,
2292 rather than pausing up front. If --crash is specified, the domain is
2293 halted with a crashed status, rather than merely left in a paused
2294 state. If --reset is specified, the domain is reset after successful
2295 dump. Note, these three switches are mutually exclusive. If --by‐
2296 pass-cache is specified, the save will avoid the file system cache, al‐
2297 though this may slow down the operation. If --memory-only is speci‐
2298 fied, the file is elf file, and will only include domain's memory and
2299 cpu common register value. It is very useful if the domain uses host
2300 devices directly. --format string is used to specify the format of
2301 'memory-only' dump, and string can be one of: elf,
2302 kdump-zlib(kdump-compressed format with zlib-compressed),
2303 kdump-lzo(kdump-compressed format with lzo-compressed),
2304 kdump-snappy(kdump-compressed format with snappy-compressed),
2305 win-dmp(Windows full crashdump format).
2306 The progress may be monitored using domjobinfo virsh command and can‐
2308 celed with domjobabort command (sent by another virsh instance). An‐
2309 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2310 process running dump command. --verbose displays the progress of dump.
2311 NOTE: Some hypervisors may require the user to manually ensure proper
2313 permissions on file and path specified by argument corefilepath.
2314 NOTE: Crash dump in a old kvmdump format is being obsolete and cannot
2316 be loaded and processed by crash utility since its version 6.1.0. A
2317 --memory-only option is required in order to produce valid ELF file
2318 which can be later processed by the crash utility.
2319 dumpxml
2321 Syntax:
2322 dumpxml [--inactive] [--security-info] [--update-cpu] [--migratable]
2324 [--xpath EXPRESSION] [--wrap] domain
2325 Output the domain information as an XML dump to stdout, this format can
2327 be used by the create command. Additional options affecting the XML
2328 dump may be used. --inactive tells virsh to dump domain configuration
2329 that will be used on next start of the domain as opposed to the current
2330 domain configuration. Using --security-info will also include security
2331 sensitive information in the XML dump. --update-cpu updates domain CPU
2332 requirements according to host CPU. With --migratable one can request
2333 an XML that is suitable for migrations, i.e., compatible with older
2334 libvirt releases and possibly amended with internal run-time options.
2335 This option may automatically enable other options (--update-cpu, --se‐
2336 curity-info, ...) as necessary.
2337 If the --xpath argument provides an XPath expression, it will be evalu‐
2339 ated against the output XML and only those matching nodes will be
2340 printed. The default behaviour is to print each matching node as a
2341 standalone document, however, for ease of additional processing, the
2342 --wrap argument will cause the matching node to be wrapped in a common
2343 root node.
2344 edit
2346 Syntax:
2347 edit domain
2349 Edit the XML configuration file for a domain, which will affect the
2351 next boot of the guest.
2352 This is equivalent to:
2354 virsh dumpxml --inactive --security-info domain > domain.xml
2356 vi domain.xml (or make changes with your other text editor)
2357 virsh define domain.xml
2358 except that it does some error checking.
2360 The editor used can be supplied by the $VISUAL or $EDITOR environment
2362 variables, and defaults to vi.
2363 emulatorpin
2365 Syntax:
2366 emulatorpin domain [cpulist] [[--live] [--config] | [--current]]
2368 Query or change the pinning of domain's emulator threads to host physi‐
2370 cal CPUs.
2371 See vcpupin for cpulist.
2373 If --live is specified, affect a running guest. If --config is speci‐
2375 fied, affect the next start of a persistent guest. If --current is
2376 specified, it is equivalent to either --live or --config, depending on
2377 the current state of the guest. Both --live and --config flags may be
2378 given if cpulist is present, but --current is exclusive. If no flag is
2379 specified, behavior is different depending on hypervisor.
2380 event
2382 Syntax:
2383 event {[domain] { event | --all } [--loop] [--timeout seconds] [--timestamp] | --list}
2385 Wait for a class of domain events to occur, and print appropriate de‐
2387 tails of events as they happen. The events can optionally be filtered
2388 by domain. Using --list as the only argument will provide a list of
2389 possible event values known by this client, although the connection
2390 might not allow registering for all these events. It is also possible
2391 to use --all instead of event to register for all possible event types
2392 at once.
2393 By default, this command is one-shot, and returns success once an event
2395 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
2396 If --timeout is specified, the command gives up waiting for events af‐
2397 ter seconds have elapsed. With --loop, the command prints all events
2398 until a timeout or interrupt key.
2399 When --timestamp is used, a human-readable timestamp will be printed
2401 before the event.
2402 get-user-sshkeys
2404 Syntax:
2405 get-user-sshkeys domain user
2407 Print SSH authorized keys for given user in the guest domain. Please
2409 note, that an entry in the file has internal structure as defined by
2410 sshd(8) and virsh/libvirt does handle keys as opaque strings, i.e. does
2411 not interpret them.
2412 guest-agent-timeout
2414 Syntax:
2415 guest-agent-timeout domain [--timeout value]
2417 Set how long to wait for a response from guest agent commands. By de‐
2419 fault, agent commands block forever waiting for a response. value must
2420 be a positive value (wait for given amount of seconds) or one of the
2421 following values:
2422 • -2 - block forever waiting for a result (used when --timeout is omit‐
2424 ted),
2425 • -1 - reset timeout to the default value (currently defined as 5 sec‐
2427 onds in libvirt daemon),
2428 • 0 - do not wait at all,
2430 guestinfo
2432 Syntax:
2433 guestinfo domain [--user] [--os] [--timezone] [--hostname] [--filesystem]
2435 [--disk] [--interface]
2436 Print information about the guest from the point of view of the guest
2438 agent. Note that this command requires a guest agent to be configured
2439 and running in the domain's guest OS.
2440 When run without any arguments, this command prints all information
2442 types that are supported by the guest agent at that point, omitting un‐
2443 available ones. Success is always reported in this case.
2444 You can limit the types of information that are returned by specifying
2446 one or more flags. Available information types flags are --user, --os,
2447 --timezone, --hostname, --filesystem, --disk and --interface. If an
2448 explicitly requested information type is not supported by the guest
2449 agent at that point, the processes will provide an exit code of 1.
2450 Note that depending on the hypervisor type and the version of the guest
2452 agent running within the domain, not all of the following information
2453 may be returned.
2454 When selecting the --user information type, the following fields may be
2456 returned:
2457 • user.count - the number of active users on this domain
2459 • user.<num>.name - username of user <num>
2461 • user.<num>.domain - domain of the user <num> (may only be present on
2463 certain guets types)
2464 • user.<num>.login-time - the login time of user <num> in milliseconds
2466 since the epoch
2467 --os returns:
2469 • os.id - a string identifying the operating system
2471 • os.name - the name of the operating system
2473 • os.pretty-name - a pretty name for the operating system
2475 • os.version - the version of the operating system
2477 • os.version-id - the version id of the operating system
2479 • os.kernel-release - the release of the operating system kernel
2481 • os.kernel-version - the version of the operating system kernel
2483 • os.machine - the machine hardware name
2485 • os.variant - a specific variant or edition of the operating system
2487 • os.variant-id - the id for a specific variant or edition of the oper‐
2489 ating system
2490 --timezone returns:
2492 • timezone.name - the name of the timezone
2494 • timezone.offset - the offset to UTC in seconds
2496 --hostname returns:
2498 • hostname - the hostname of the domain
2500 --filesystem returns:
2502 • fs.count - the number of filesystems defined on this domain
2504 • fs.<num>.mountpoint - the path to the mount point for filesystem
2506 <num>
2507 • fs.<num>.name - device name in the guest (e.g. sda1) for filesystem
2509 <num>
2510 • fs.<num>.fstype - the type of filesystem <num>
2512 • fs.<num>.total-bytes - the total size of filesystem <num>
2514 • fs.<num>.used-bytes - the number of bytes used in filesystem <num>
2516 • fs.<num>.disk.count - the number of disks targeted by filesystem
2518 <num>
2519 • fs.<num>.disk.<num>.alias - the device alias of disk <num> (e.g. sda)
2521 • fs.<num>.disk.<num>.serial - the serial number of disk <num>
2523 • fs.<num>.disk.<num>.device - the device node of disk <num>
2525 --disk returns:
2527 • disk.count - the number of disks defined on this domain
2529 • disk.<num>.name - device node (Linux) or device UNC (Windows)
2531 • disk.<num>.partition - whether this is a partition or disk
2533 • disk.<num>.dependency.count - the number of device dependencies
2535 • disk.<num>.dependency.<num>.name - a dependency name
2537 • disk.<num>.serial - optional disk serial number
2539 • disk.<num>.alias - the device alias of the disk (e.g. sda)
2541 • disk.<num>.guest_alias - optional alias assigned to the disk
2543 --interface returns: * if.count - the number of interfaces defined on
2545 this domain * if.<num>.name - name in the guest (e.g. eth0) for inter‐
2546 face <num> * if.<num>.hwaddr - hardware address in the guest for inter‐
2547 face <num> * if.<num>.addr.count - the number of IP addresses of inter‐
2548 face <num> * if.<num>.addr.<num1>.type - the IP address type of addr
2549 <num1> (e.g. ipv4) * if.<num>.addr.<num1>.addr - the IP address of addr
2550 <num1> * if.<num>.addr.<num1>.prefix - the prefix of IP address of addr
2551 <num1>
2552 guestvcpus
2554 Syntax:
2555 guestvcpus domain [[--enable] | [--disable]] [cpulist]
2557 Query or change state of vCPUs from guest's point of view using the
2559 guest agent. When invoked without cpulist the guest is queried for
2560 available guest vCPUs, their state and possibility to be offlined.
2561 If cpulist is provided then one of --enable or --disable must be pro‐
2563 vided too. The desired operation is then executed on the domain.
2564 See vcpupin for information on cpulist.
2566 iothreadadd
2568 Syntax:
2569 iothreadadd domain iothread_id [[--config] [--live] | [--current]]
2571 Add a new IOThread to the domain using the specified iothread_id. If
2573 the iothread_id already exists, the command will fail. The iothread_id
2574 must be greater than zero.
2575 If --live is specified, affect a running guest. If the guest is not
2577 running an error is returned. If --config is specified, affect the
2578 next start of a persistent guest. If --current is specified, it is
2579 equivalent to either --live or --config, depending on the current state
2580 of the guest.
2581 iothreaddel
2583 Syntax:
2584 iothreaddel domain iothread_id [[--config] [--live] | [--current]]
2586 Delete an IOThread from the domain using the specified iothread_id. If
2588 an IOThread is currently assigned to a disk resource such as via the
2589 attach-disk command, then the attempt to remove the IOThread will fail.
2590 If the iothread_id does not exist an error will occur.
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 iothreadinfo
2599 Syntax:
2600 iothreadinfo domain [[--live] [--config] | [--current]]
2602 Display basic domain IOThreads information including the IOThread ID
2604 and the CPU Affinity for each IOThread.
2605 If --live is specified, get the IOThreads data from the running guest.
2607 If the guest is not running, an error is returned. If --config is
2608 specified, get the IOThreads data from the next start of a persistent
2609 guest. If --current is specified or --live and --config are not speci‐
2610 fied, then get the IOThread data based on the current guest state,
2611 which can either be live or offline.
2612 iothreadpin
2614 Syntax:
2615 iothreadpin domain iothread cpulist [[--live] [--config] | [--current]]
2617 Change the pinning of a domain IOThread to host physical CPUs. In order
2619 to retrieve a list of all IOThreads, use iothreadinfo. To pin an io‐
2620 thread specify the cpulist desired for the IOThread ID as listed in the
2621 iothreadinfo output.
2622 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
2624 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
2625 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
2626 clusive. If you want to reset iothreadpin setting, that is, to pin an
2627 iothread to all physical cpus, simply specify 'r' as a cpulist.
2628 If --live is specified, affect a running guest. If the guest is not
2630 running, an error is returned. If --config is specified, affect the
2631 next start of a persistent guest. If --current is specified, it is
2632 equivalent to either --live or --config, depending on the current state
2633 of the guest. Both --live and --config flags may be given if cpulist
2634 is present, but --current is exclusive. If no flag is specified, be‐
2635 havior is different depending on hypervisor.
2636 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
2638 cal to "9-14,0-7,15" but not identical to "^8,0-15".
2639 iothreadset
2641 Syntax:
2642 iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor]
2644 [--poll-shrink divisor] [--thread-pool-min value]
2645 [--thread-pool-max value]]
2646 [[--config] [--live] | [--current]]
2647 Modifies an existing iothread of the domain using the specified io‐
2649 thread_id. The --poll-max-ns provides the maximum polling interval to
2650 be allowed for an IOThread in ns. If a 0 (zero) is provided, then
2651 polling for the IOThread is disabled. The --poll-grow is the factor by
2652 which the current polling time will be adjusted in order to reach the
2653 maximum polling time. If a 0 (zero) is provided, then the default fac‐
2654 tor will be used. The --poll-shrink is the quotient by which the cur‐
2655 rent polling time will be reduced in order to get below the maximum
2656 polling interval. If a 0 (zero) is provided, then the default quotient
2657 will be used. The polling values are purely dynamic for a running
2658 guest. Saving, destroying, stopping, etc. the guest will result in the
2659 polling values returning to hypervisor defaults at the next start, re‐
2660 store, etc.
2661 The --thread-pool-min and --thread-pool-max options then set lower and
2663 upper bound, respectively of number of threads in worker pool of given
2664 iothread. For changes to an inactive configuration -1 can be specified
2665 to remove corresponding boundary from the domain configuration. For
2666 changes to a running guest it's recommended to set the upper boundary
2667 first (--thread-pool-max) and only after that set the lower boundary
2668 (--thread-pool-min). It is allowed for the lower boundary to be the
2669 same as the upper boundary, however it's not allowed for the upper
2670 boundary to be value of zero.
2671 If --live is specified, affect a running guest. If the guest is not
2673 running an error is returned. If --current is specified or --live is
2674 not specified, then handle as if --live was specified. (Where "cur‐
2675 rent" here means whatever the present guest state is: live or offline.)
2676 managedsave
2678 Syntax:
2679 managedsave domain [--bypass-cache] [{--running | --paused}] [--verbose]
2681 Save and destroy (stop) a running domain, so it can be restarted from
2683 the same state at a later time. When the virsh start command is next
2684 run for the domain, it will automatically be started from this saved
2685 state. If --bypass-cache is specified, the save will avoid the file
2686 system cache, although this may slow down the operation.
2687 The progress may be monitored using domjobinfo virsh command and can‐
2689 celed with domjobabort command (sent by another virsh instance). An‐
2690 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2691 process running managedsave command. --verbose displays the progress of
2692 save.
2693 Normally, starting a managed save will decide between running or paused
2695 based on the state the domain was in when the save was done; passing
2696 either the --running or --paused flag will allow overriding which state
2697 the start should use.
2698 The dominfo command can be used to query whether a domain currently has
2700 any managed save image.
2701 managedsave-define
2703 Syntax:
2704 managedsave-define domain xml [{--running | --paused}]
2706 Update the domain XML that will be used when domain is later started.
2708 The xml argument must be a file name containing the alternative XML,
2709 with changes only in the host-specific portions of the domain XML. For
2710 example, it can be used to change disk file paths.
2711 The managed save image records whether the domain should be started to
2713 a running or paused state. Normally, this command does not alter the
2714 recorded state; passing either the --running or --paused flag will al‐
2715 low overriding which state the start should use.
2716 managedsave-dumpxml
2718 Syntax:
2719 managedsave-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap] domain
2721 Extract the domain XML that was in effect at the time the saved state
2723 file file was created with the managedsave command. Using --secu‐
2724 rity-info will also include security sensitive information.
2725 If the --xpath argument provides an XPath expression, it will be evalu‐
2727 ated against the output XML and only those matching nodes will be
2728 printed. The default behaviour is to print each matching node as a
2729 standalone document, however, for ease of additional processing, the
2730 --wrap argument will cause the matching node to be wrapped in a common
2731 root node.
2732 managedsave-edit
2734 Syntax:
2735 managedsave-edit domain [{--running | --paused}]
2737 Edit the XML configuration associated with a saved state file of a do‐
2739 main was created by the managedsave command.
2740 The managed save image records whether the domain should be started to
2742 a running or paused state. Normally, this command does not alter the
2743 recorded state; passing either the --running or --paused flag will al‐
2744 low overriding which state the restore should use.
2745 This is equivalent to:
2747 virsh managedsave-dumpxml domain-name > state-file.xml
2749 vi state-file.xml (or make changes with your other text editor)
2750 virsh managedsave-define domain-name state-file-xml
2751 except that it does some error checking.
2753 The editor used can be supplied by the $VISUAL or $EDITOR environment
2755 variables, and defaults to vi.
2756 managedsave-remove
2758 Syntax:
2759 managedsave-remove domain
2761 Remove the managedsave state file for a domain, if it exists. This en‐
2763 sures the domain will do a full boot the next time it is started.
2764 maxvcpus
2766 Syntax:
2767 maxvcpus [type]
2769 Provide the maximum number of virtual CPUs supported for a guest VM on
2771 this connection. If provided, the type parameter must be a valid type
2772 attribute for the <domain> element of XML.
2773 memtune
2775 Syntax:
2776 memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-limit size]
2778 [--min-guarantee size] [[--config] [--live] | [--current]]
2779 Allows you to display or set the domain memory parameters. Without
2781 flags, the current settings are displayed; with a flag, the appropriate
2782 limit is adjusted if supported by the hypervisor. LXC and QEMU/KVM
2783 support --hard-limit, --soft-limit, and --swap-hard-limit. --min-guar‐
2784 antee is supported only by ESX hypervisor. Each of these limits are
2785 scaled integers (see NOTES above), with a default of kibibytes (blocks
2786 of 1024 bytes) if no suffix is present. Libvirt rounds up to the near‐
2787 est kibibyte. Some hypervisors require a larger granularity than KiB,
2788 and requests that are not an even multiple will be rounded up. For ex‐
2789 ample, vSphere/ESX rounds the parameter up to mebibytes (1024
2790 kibibytes).
2791 If --live is specified, affect a running guest. If --config is speci‐
2793 fied, affect the next start of a persistent guest. If --current is
2794 specified, it is equivalent to either --live or --config, depending on
2795 the current state of the guest. Both --live and --config flags may be
2796 given, but --current is exclusive. If no flag is specified, behavior is
2797 different depending on hypervisor.
2798 For QEMU/KVM, the parameters are applied to the QEMU process as a
2800 whole. Thus, when counting them, one needs to add up guest RAM, guest
2801 video RAM, and some memory overhead of QEMU itself. The last piece is
2802 hard to determine so one needs guess and try.
2803 For LXC, the displayed hard_limit value is the current memory setting
2805 from the XML or the results from a virsh setmem command.
2806 • --hard-limit
2808 The maximum memory the guest can use.
2810 • --soft-limit
2812 The memory limit to enforce during memory contention.
2814 • --swap-hard-limit
2816 The maximum memory plus swap the guest can use. This has to be more
2818 than hard-limit value provided.
2819 • --min-guarantee
2821 The guaranteed minimum memory allocation for the guest.
2823 Specifying -1 as a value for these limits is interpreted as unlimited.
2825 metadata
2827 Syntax:
2828 metadata domain [[--live] [--config] | [--current]]
2830 [--edit] [uri] [key] [set] [--remove]
2831 Show or modify custom XML metadata of a domain. The metadata is a user
2833 defined XML that allows storing arbitrary XML data in the domain defi‐
2834 nition. Multiple separate custom metadata pieces can be stored in the
2835 domain XML. The pieces are identified by a private XML namespace pro‐
2836 vided via the uri argument. (See also desc that works with textual
2837 metadata of a domain.)
2838 Flags --live or --config select whether this command works on live or
2840 persistent definitions of the domain. If both --live and --config are
2841 specified, the --config option takes precedence on getting the current
2842 description and both live configuration and config are updated while
2843 setting the description. --current is exclusive and implied if none of
2844 these was specified.
2845 Flag --remove specifies that the metadata element specified by the uri
2847 argument should be removed rather than updated.
2848 Flag --edit specifies that an editor with the metadata identified by
2850 the uri argument should be opened and the contents saved back after‐
2851 wards. Otherwise the new contents can be provided via the set argu‐
2852 ment.
2853 When setting metadata via --edit or set the key argument must be speci‐
2855 fied and is used to prefix the custom elements to bind them to the pri‐
2856 vate namespace.
2857 If neither of --edit and set are specified the XML metadata correspond‐
2859 ing to the uri namespace is displayed instead of being modified.
2860 migrate
2862 Syntax:
2863 migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]]
2865 [--persistent] [--undefinesource] [--suspend] [--copy-storage-all]
2866 [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose]
2867 [--rdma-pin-all] [--abort-on-error] [--postcopy]
2868 [--postcopy-after-precopy] [--postcopy-resume] [--zerocopy]
2869 domain desturi [migrateuri] [graphicsuri] [listen-address] [dname]
2870 [--timeout seconds [--timeout-suspend | --timeout-postcopy]]
2871 [--xml file] [--migrate-disks disk-list] [--disks-port port]
2872 [--compressed] [--comp-methods method-list]
2873 [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads]
2874 [--comp-xbzrle-cache] [--auto-converge] [auto-converge-initial]
2875 [auto-converge-increment] [--persistent-xml file] [--tls]
2876 [--postcopy-bandwidth bandwidth]
2877 [--parallel [--parallel-connections connections]]
2878 [--bandwidth bandwidth] [--tls-destination hostname]
2879 [--disks-uri URI] [--copy-storage-synchronous-writes]
2880 Migrate domain to another host. Add --live for live migration; <--p2p>
2882 for peer-2-peer migration; --direct for direct migration; or --tun‐
2883 nelled for tunnelled migration. --offline migrates domain definition
2884 without starting the domain on destination and without stopping it on
2885 source host. Offline migration may be used with inactive domains and
2886 it must be used with --persistent option.
2887 --persistent leaves the domain persistent on destination host, --unde‐
2889 finesource undefines the domain on the source host, and --suspend
2890 leaves the domain paused on the destination host.
2891 --copy-storage-all indicates migration with non-shared storage with
2893 full disk copy, --copy-storage-inc indicates migration with non-shared
2894 storage with incremental copy (same base image shared between source
2895 and destination). In both cases the disk images have to exist on des‐
2896 tination host, the --copy-storage-... options only tell libvirt to
2897 transfer data from the images on source host to the images found at the
2898 same place on the destination host. By default only non-shared
2899 non-readonly images are transferred. Use --migrate-disks to explicitly
2900 specify a list of disk targets to transfer via the comma separated
2901 disk-list argument. With --copy-storage-synchronous-writes flag used
2902 the disk data migration will synchronously handle guest disk writes to
2903 both the original source and the destination to ensure that the disk
2904 migration converges at the price of possibly decreased burst perfor‐
2905 mance.
2906 --change-protection enforces that no incompatible configuration changes
2908 will be made to the domain while the migration is underway; this flag
2909 is implicitly enabled when supported by the hypervisor, but can be ex‐
2910 plicitly used to reject the migration if the hypervisor lacks change
2911 protection support.
2912 --verbose displays the progress of migration.
2914 --abort-on-error cancels the migration if a soft error (for example I/O
2916 error) happens during the migration.
2917 --postcopy enables post-copy logic in migration, but does not actually
2919 start post-copy, i.e., migration is started in pre-copy mode. Once mi‐
2920 gration is running, the user may switch to post-copy using the mi‐
2921 grate-postcopy command sent from another virsh instance or use --post‐
2922 copy-after-precopy along with --postcopy to let libvirt automatically
2923 switch to post-copy after the first pass of pre-copy is finished. The
2924 maximum bandwidth consumed during the post-copy phase may be limited
2925 using --postcopy-bandwidth. The maximum bandwidth consumed during the
2926 pre-copy phase may be limited using --bandwidth. In case connection be‐
2927 tween the hosts breaks while migration is in post-copy mode, the domain
2928 cannot be resumed on either source or destination host and the migrate
2929 command will report an error leaving the domain active on both hosts.
2930 To recover from such situation repeat the original migrate command with
2931 an additional --postcopy-resume flag.
2932 --auto-converge forces convergence during live migration. The initial
2934 guest CPU throttling rate can be set with auto-converge-initial. If the
2935 initial throttling rate is not enough to ensure convergence, the rate
2936 is periodically increased by auto-converge-increment.
2937 --rdma-pin-all can be used with RDMA migration (i.e., when migrateuri
2939 starts with rdma://) to tell the hypervisor to pin all domain's memory
2940 at once before migration starts rather than letting it pin memory pages
2941 as needed. For QEMU/KVM this requires hard_limit memory tuning element
2942 (in the domain XML) to be used and set to the maximum memory configured
2943 for the domain plus any memory consumed by the QEMU process itself. Be‐
2944 ware of setting the memory limit too high (and thus allowing the domain
2945 to lock most of the host's memory). Doing so may be dangerous to both
2946 the domain and the host itself since the host's kernel may run out of
2947 memory.
2948 --zerocopy requests zero-copy mechanism to be used for migrating memory
2950 pages. For QEMU/KVM this means QEMU will be temporarily allowed to
2951 lock all guest pages in host's memory, although only those that are
2952 queued for transfer will be locked at the same time.
2953 Note: Individual hypervisors usually do not support all possible types
2955 of migration. For example, QEMU does not support direct migration.
2956 In some cases libvirt may refuse to migrate the domain because doing so
2958 may lead to potential problems such as data corruption, and thus the
2959 migration is considered unsafe. For QEMU domain, this may happen if the
2960 domain uses disks without explicitly setting cache mode to "none". Mi‐
2961 grating such domains is unsafe unless the disk images are stored on co‐
2962 herent clustered filesystem, such as GFS2 or GPFS. If you are sure the
2963 migration is safe or you just do not care, use --unsafe to force the
2964 migration.
2965 dname is used for renaming the domain to new name during migration,
2967 which also usually can be omitted. Likewise, --xml file is usually
2968 omitted, but can be used to supply an alternative XML file for use on
2969 the destination to supply a larger set of changes to any host-specific
2970 portions of the domain XML, such as accounting for naming differences
2971 between source and destination in accessing underlying storage. If
2972 --persistent is enabled, --persistent-xml file can be used to supply an
2973 alternative XML file which will be used as the persistent guest defini‐
2974 tion on the destination host.
2975 --timeout seconds tells virsh to run a specified action when live mi‐
2977 gration exceeds that many seconds. It can only be used with --live.
2978 If --timeout-suspend is specified, the domain will be suspended after
2979 the timeout and the migration will complete offline; this is the de‐
2980 fault if no --timeout-\`` option is specified on the command line.
2981 When *--timeout-postcopy is used, virsh will switch migration from
2982 pre-copy to post-copy upon timeout; migration has to be started with
2983 --postcopy option for this to work.
2984 --compressed activates compression, the compression method is chosen
2986 with --comp-methods. Supported methods are "mt" and "xbzrle" and can be
2987 used in any combination. When no methods are specified, a hypervisor
2988 default methods will be used. QEMU defaults to "xbzrle". Compression
2989 methods can be tuned further. --comp-mt-level sets compression level.
2990 Values are in range from 0 to 9, where 1 is maximum speed and 9 is max‐
2991 imum compression. --comp-mt-threads and --comp-mt-dthreads set the num‐
2992 ber of compress threads on source and the number of decompress threads
2993 on target respectively. --comp-xbzrle-cache sets size of page cache in
2994 bytes.
2995 Providing --tls causes the migration to use the host configured TLS
2997 setup (see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in or‐
2998 der to perform the migration of the domain. Usage requires proper TLS
2999 setup for both source and target. Normally the TLS certificate from the
3000 destination host must match the host's name for TLS verification to
3001 succeed. When the certificate does not match the destination hostname
3002 and the expected certificate's hostname is known, --tls-destination can
3003 be used to pass the expected hostname when starting the migration.
3004 --parallel option will cause migration data to be sent over multiple
3006 parallel connections. The number of such connections can be set using
3007 --parallel-connections. Parallel connections may help with saturating
3008 the network link between the source and the target and thus speeding up
3009 the migration.
3010 Running migration can be canceled by interrupting virsh (usually using
3012 Ctrl-C) or by domjobabort command sent from another virsh instance.
3013 The desturi and migrateuri parameters can be used to control which des‐
3015 tination the migration uses. desturi is important for managed migra‐
3016 tion, but unused for direct migration; migrateuri is required for di‐
3017 rect migration, but can usually be automatically determined for managed
3018 migration.
3019 Note: The desturi parameter for normal migration and peer2peer migra‐
3021 tion has different semantics:
3022 • normal migration: the desturi is an address of the target host as
3024 seen from the client machine.
3025 • peer2peer migration: the desturi is an address of the target host as
3027 seen from the source machine.
3028 In a special circumstance where you require a complete control of the
3030 connection and/or libvirt does not have network access to the remote
3031 side you can use a UNIX transport in the URI and specify a socket path
3032 in the query, for example with the qemu driver you could use this:
3033 qemu+unix:///system?socket=/path/to/socket
3035 When migrateuri is not specified, libvirt will automatically determine
3037 the hypervisor specific URI. Some hypervisors, including QEMU, have an
3038 optional "migration_host" configuration parameter (useful when the host
3039 has multiple network interfaces). If this is unspecified, libvirt de‐
3040 termines a name by looking up the target host's configured hostname.
3041 There are a few scenarios where specifying migrateuri may help:
3043 • The configured hostname is incorrect, or DNS is broken. If a host
3045 has a hostname which will not resolve to match one of its public IP
3046 addresses, then libvirt will generate an incorrect URI. In this case
3047 migrateuri should be explicitly specified, using an IP address, or a
3048 correct hostname.
3049 • The host has multiple network interfaces. If a host has multiple
3051 network interfaces, it might be desirable for the migration data
3052 stream to be sent over a specific interface for either security or
3053 performance reasons. In this case migrateuri should be explicitly
3054 specified, using an IP address associated with the network to be
3055 used.
3056 • The firewall restricts what ports are available. When libvirt gener‐
3058 ates a migration URI, it will pick a port number using hypervisor
3059 specific rules. Some hypervisors only require a single port to be
3060 open in the firewalls, while others require a whole range of port
3061 numbers. In the latter case migrateuri might be specified to choose
3062 a specific port number outside the default range in order to comply
3063 with local firewall policies.
3064 • The desturi uses UNIX transport method. In this advanced case lib‐
3066 virt should not guess a migrateuri and it should be specified using
3067 UNIX socket path URI:
3068 unix:///path/to/socket
3070 See https://libvirt.org/migration.html#uris for more details on migra‐
3072 tion URIs.
3073 Optional graphicsuri overrides connection parameters used for automati‐
3075 cally reconnecting a graphical clients at the end of migration. If
3076 omitted, libvirt will compute the parameters based on target host IP
3077 address. In case the client does not have a direct access to the net‐
3078 work virtualization hosts are connected to and needs to connect through
3079 a proxy, graphicsuri may be used to specify the address the client
3080 should connect to. The URI is formed as follows:
3081 protocol://hostname[:port]/[?parameters]
3083 where protocol is either "spice" or "vnc" and parameters is a list of
3085 protocol specific parameters separated by '&'. Currently recognized pa‐
3086 rameters are "tlsPort" and "tlsSubject". For example,
3087 spice://target.host.com:1234/?tlsPort=4567
3089 Optional listen-address sets the listen address that hypervisor on the
3091 destination side should bind to for incoming migration. Both IPv4 and
3092 IPv6 addresses are accepted as well as hostnames (the resolving is done
3093 on destination). Some hypervisors do not support specifying the listen
3094 address and will return an error if this parameter is used. This param‐
3095 eter cannot be used if desturi uses UNIX transport method.
3096 Optional disks-port sets the port that hypervisor on destination side
3098 should bind to for incoming disks traffic. Currently it is supported
3099 only by QEMU.
3100 Optional disks-uri can also be specified (mutually exclusive with
3102 disks-port) to specify what the remote hypervisor should bind/connect
3103 to when migrating disks. This can be tcp://address:port to specify a
3104 listen address (which overrides --migrate-uri and --listen-address for
3105 the disk migration) and a port or unix:///path/to/socket in case you
3106 need the disk migration to happen over a UNIX socket with that speci‐
3107 fied path. In this case you need to make sure the same socket path is
3108 accessible to both source and destination hypervisors and connecting to
3109 the socket on the source (after hypervisor creates it on the destina‐
3110 tion) will actually connect to the destination. If you are using
3111 SELinux (at least on the source host) you need to make sure the socket
3112 on the source is accessible to libvirtd/QEMU for connection. Libvirt
3113 cannot change the context of the existing socket because it is differ‐
3114 ent from the file representation of the socket and the context is cho‐
3115 sen by its creator (usually by using setsockcreatecon{,_raw}() func‐
3116 tions).
3117 migrate-compcache
3119 Syntax:
3120 migrate-compcache domain [--size bytes]
3122 Sets and/or gets size of the cache (in bytes) used for compressing re‐
3124 peatedly transferred memory pages during live migration. When called
3125 without size, the command just prints current size of the compression
3126 cache. When size is specified, the hypervisor is asked to change com‐
3127 pression cache to size bytes and then the current size is printed (the
3128 result may differ from the requested size due to rounding done by the
3129 hypervisor). The size option is supposed to be used while the domain is
3130 being live-migrated as a reaction to migration progress and increasing
3131 number of compression cache misses obtained from domjobinfo.
3132 migrate-getmaxdowntime
3134 Syntax:
3135 migrate-getmaxdowntime domain
3137 Get the maximum tolerable downtime for a domain which is being live-mi‐
3139 grated to another host. This is the number of milliseconds the guest
3140 is allowed to be down at the end of live migration.
3141 migrate-getspeed
3143 Syntax:
3144 migrate-getspeed domain [--postcopy]
3146 Get the maximum migration bandwidth (in MiB/s) for a domain. If the
3148 --postcopy option is specified, the command will get the maximum band‐
3149 width allowed during a post-copy migration phase.
3150 migrate-postcopy
3152 Syntax:
3153 migrate-postcopy domain
3155 Switch the current migration from pre-copy to post-copy. This is only
3157 supported for a migration started with --postcopy option.
3158 migrate-setmaxdowntime
3160 Syntax:
3161 migrate-setmaxdowntime domain downtime
3163 Set maximum tolerable downtime for a domain which is being live-mi‐
3165 grated to another host. The downtime is a number of milliseconds the
3166 guest is allowed to be down at the end of live migration.
3167 migrate-setspeed
3169 Syntax:
3170 migrate-setspeed domain bandwidth [--postcopy]
3172 Set the maximum migration bandwidth (in MiB/s) for a domain which is
3174 being migrated to another host. bandwidth is interpreted as an unsigned
3175 long long value. Specifying a negative value results in an essentially
3176 unlimited value being provided to the hypervisor. The hypervisor can
3177 choose whether to reject the value or convert it to the maximum value
3178 allowed. If the --postcopy option is specified, the command will set
3179 the maximum bandwidth allowed during a post-copy migration phase.
3180 numatune
3182 Syntax:
3183 numatune domain [--mode mode] [--nodeset nodeset]
3185 [[--config] [--live] | [--current]]
3186 Set or get a domain's numa parameters, corresponding to the <numatune>
3188 element of domain XML. Without flags, the current settings are dis‐
3189 played.
3190 mode can be one of `strict', `interleave', `preferred' and 'restric‐
3192 tive' or any valid number from the virDomainNumatuneMemMode enum in
3193 case the daemon supports it. For a running domain, the mode can't be
3194 changed, and the nodeset can be changed only if the domain was started
3195 with `restrictive' mode.
3196 nodeset is a list of numa nodes used by the host for running the do‐
3198 main. Its syntax is a comma separated list, with '-' for ranges and
3199 '^' for excluding a node.
3200 If --live is specified, set scheduler information of a running guest.
3202 If --config is specified, affect the next start of a persistent guest.
3203 If --current is specified, it is equivalent to either --live or --con‐
3204 fig, depending on the current state of the guest.
3205 For running guests in Linux hosts, the changes made in the domain's
3207 numa parameters does not imply that the guest memory will be moved to a
3208 different nodeset immediately. The memory migration depends on the
3209 guest activity, and the memory of an idle guest will remain in its pre‐
3210 vious nodeset for longer. The presence of VFIO devices will also lock
3211 parts of the guest memory in the same nodeset used to start the guest,
3212 regardless of nodeset changes.
3213 perf
3215 Syntax:
3216 perf domain [--enable eventSpec] [--disable eventSpec]
3218 [[--config] [--live] | [--current]]
3219 Get the current perf events setting or enable/disable specific perf
3221 events for a guest domain.
3222 Perf is a performance analyzing tool in Linux, and it can instrument
3224 CPU performance counters, tracepoints, kprobes, and uprobes (dynamic
3225 tracing). Perf supports a list of measurable events, and can measure
3226 events coming from different sources. For instance, some event are pure
3227 kernel counters, in this case they are called software events, includ‐
3228 ing context-switches, minor-faults, etc.. Now dozens of events from
3229 different sources can be supported by perf.
3230 Currently only QEMU/KVM supports this command. The --enable and --dis‐
3232 able option combined with eventSpec can be used to enable or disable
3233 specific performance event. eventSpec is a string list of one or more
3234 events separated by commas. Valid event names are as follows:
3235 Valid perf event names
3237 • cmt - A PQos (Platform Qos) feature to monitor the usage of cache by
3239 applications running on the platform.
3240 • mbmt - Provides a way to monitor the total system memory bandwidth
3242 between one level of cache and another.
3243 • mbml - Provides a way to limit the amount of data (bytes/s) send
3245 through the memory controller on the socket.
3246 • cache_misses - Provides the count of cache misses by applications
3248 running on the platform.
3249 • cache_references - Provides the count of cache hits by applications
3251 running on th e platform.
3252 • instructions - Provides the count of instructions executed by appli‐
3254 cations running on the platform.
3255 • cpu_cycles - Provides the count of cpu cycles (total/elapsed). May be
3257 used with instructions in order to get a cycles per instruction.
3258 • branch_instructions - Provides the count of branch instructions exe‐
3260 cuted by applications running on the platform.
3261 • branch_misses - Provides the count of branch misses executed by ap‐
3263 plications running on the platform.
3264 • bus_cycles - Provides the count of bus cycles executed by applica‐
3266 tions running on the platform.
3267 • stalled_cycles_frontend - Provides the count of stalled cpu cycles in
3269 the frontend of the instruction processor pipeline by applications
3270 running on the platform.
3271 • stalled_cycles_backend - Provides the count of stalled cpu cycles in
3273 the backend of the instruction processor pipeline by applications
3274 running on the platform.
3275 • ref_cpu_cycles - Provides the count of total cpu cycles not affected
3277 by CPU frequency scaling by applications running on the platform.
3278 • cpu_clock - Provides the cpu clock time consumed by applications run‐
3280 ning on the platform.
3281 • task_clock - Provides the task clock time consumed by applications
3283 running on the platform.
3284 • page_faults - Provides the count of page faults by applications run‐
3286 ning on the platform.
3287 • context_switches - Provides the count of context switches by applica‐
3289 tions running on the platform.
3290 • cpu_migrations - Provides the count cpu migrations by applications
3292 running on the platform.
3293 • page_faults_min - Provides the count minor page faults by applica‐
3295 tions running on the platform.
3296 • page_faults_maj - Provides the count major page faults by applica‐
3298 tions running on the platform.
3299 • alignment_faults - Provides the count alignment faults by applica‐
3301 tions running on the platform.
3302 • emulation_faults - Provides the count emulation faults by applica‐
3304 tions running on the platform.
3305 Note: The statistics can be retrieved using the domstats command using
3307 the --perf flag.
3308 If --live is specified, affect a running guest. If --config is speci‐
3310 fied, affect the next start of a persistent guest. If --current is
3311 specified, it is equivalent to either --live or --config, depending on
3312 the current state of the guest. Both --live and --config flags may be
3313 given, but --current is exclusive. If no flag is specified, behavior is
3314 different depending on hypervisor.
3315 reboot
3317 Syntax:
3318 reboot domain [--mode MODE-LIST]
3320 Reboot a domain. This acts just as if the domain had the reboot com‐
3322 mand run from the console. The command returns as soon as it has exe‐
3323 cuted the reboot action, which may be significantly before the domain
3324 actually reboots.
3325 The exact behavior of a domain when it reboots is set by the on_reboot
3327 parameter in the domain's XML definition.
3328 By default the hypervisor will try to pick a suitable shutdown method.
3330 To specify an alternative method, the --mode parameter can specify a
3331 comma separated list which includes acpi, agent, initctl, signal and
3332 paravirt. The order in which drivers will try each mode is undefined,
3333 and not related to the order specified to virsh. For strict control
3334 over ordering, use a single mode at a time and repeat the command.
3335 reset
3337 Syntax:
3338 reset domain
3340 Reset a domain immediately without any guest shutdown. reset emulates
3342 the power reset button on a machine, where all guest hardware sees the
3343 RST line set and reinitializes internal state.
3344 Note: Reset without any guest OS shutdown risks data loss.
3346 restore
3348 Syntax:
3349 restore state-file [--bypass-cache] [--xml file]
3351 [{--running | --paused}] [--reset-nvram]
3352 Restores a domain from a virsh save state file. See save for more info.
3354 If --bypass-cache is specified, the restore will avoid the file system
3356 cache, although this may slow down the operation.
3357 --xml file is usually omitted, but can be used to supply an alternative
3359 XML file for use on the restored guest with changes only in the
3360 host-specific portions of the domain XML. For example, it can be used
3361 to account for file naming differences in underlying storage due to
3362 disk snapshots taken after the guest was saved.
3363 Normally, restoring a saved image will use the state recorded in the
3365 save image to decide between running or paused; passing either the
3366 --running or --paused flag will allow overriding which state the domain
3367 should be started in.
3368 If --reset-nvram is specified, any existing NVRAM file will be deleted
3370 and re-initialized from its pristine template.
3371 Note: To avoid corrupting file system contents within the domain, you
3373 should not reuse the saved state file for a second restore unless you
3374 have also reverted all storage volumes back to the same contents as
3375 when the state file was created.
3376 resume
3378 Syntax:
3379 resume domain
3381 Moves a domain out of the suspended state. This will allow a previ‐
3383 ously suspended domain to now be eligible for scheduling by the under‐
3384 lying hypervisor.
3385 save
3387 Syntax:
3388 save domain state-file [--bypass-cache] [--xml file]
3390 [{--running | --paused}] [--verbose]
3391 Saves a running domain (RAM, but not disk state) to a state file so
3393 that it can be restored later. Once saved, the domain will no longer
3394 be running on the system, thus the memory allocated for the domain will
3395 be free for other domains to use. virsh restore restores from this
3396 state file. If --bypass-cache is specified, the save will avoid the
3397 file system cache, although this may slow down the operation.
3398 The progress may be monitored using domjobinfo virsh command and can‐
3400 celed with domjobabort command (sent by another virsh instance). An‐
3401 other option is to send SIGINT (usually with Ctrl-C) to the virsh
3402 process running save command. --verbose displays the progress of save.
3403 This is roughly equivalent to doing a hibernate on a running computer,
3405 with all the same limitations. Open network connections may be severed
3406 upon restore, as TCP timeouts may have expired.
3407 --xml file is usually omitted, but can be used to supply an alternative
3409 XML file for use on the restored guest with changes only in the
3410 host-specific portions of the domain XML. For example, it can be used
3411 to account for file naming differences that are planned to be made via
3412 disk snapshots of underlying storage after the guest is saved.
3413 Normally, restoring a saved image will decide between running or paused
3415 based on the state the domain was in when the save was done; passing
3416 either the --running or --paused flag will allow overriding which state
3417 the restore should use.
3418 Domain saved state files assume that disk images will be unchanged be‐
3420 tween the creation and restore point. For a more complete system re‐
3421 store point, where the disk state is saved alongside the memory state,
3422 see the snapshot family of commands.
3423 save-image-define
3425 Syntax:
3426 save-image-define file xml [{--running | --paused}]
3428 Update the domain XML that will be used when file is later used in the
3430 restore command. The xml argument must be a file name containing the
3431 alternative XML, with changes only in the host-specific portions of the
3432 domain XML. For example, it can be used to account for file naming
3433 differences resulting from creating disk snapshots of underlying stor‐
3434 age after the guest was saved.
3435 The save image records whether the domain should be restored to a run‐
3437 ning or paused state. Normally, this command does not alter the
3438 recorded state; passing either the --running or --paused flag will al‐
3439 low overriding which state the restore should use.
3440 save-image-dumpxml
3442 Syntax:
3443 save-image-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap] file
3445 Extract the domain XML that was in effect at the time the saved state
3447 file file was created with the save command. Using --security-info
3448 will also include security sensitive information.
3449 If the --xpath argument provides an XPath expression, it will be evalu‐
3451 ated against the output XML and only those matching nodes will be
3452 printed. The default behaviour is to print each matching node as a
3453 standalone document, however, for ease of additional processing, the
3454 --wrap argument will cause the matching node to be wrapped in a common
3455 root node.
3456 save-image-edit
3458 Syntax:
3459 save-image-edit file [{--running | --paused}]
3461 Edit the XML configuration associated with a saved state file file cre‐
3463 ated by the save command.
3464 The save image records whether the domain should be restored to a run‐
3466 ning or paused state. Normally, this command does not alter the
3467 recorded state; passing either the --running or --paused flag will al‐
3468 low overriding which state the restore should use.
3469 This is equivalent to:
3471 virsh save-image-dumpxml state-file > state-file.xml
3473 vi state-file.xml (or make changes with your other text editor)
3474 virsh save-image-define state-file state-file-xml
3475 except that it does some error checking.
3477 The editor used can be supplied by the $VISUAL or $EDITOR environment
3479 variables, and defaults to vi.
3480 schedinfo
3482 Syntax:
3483 schedinfo domain [[--config] [--live] | [--current]] [[--set] parameter=value]...
3485 schedinfo [--weight number] [--cap number] domain
3486 Allows you to show (and set) the domain scheduler parameters. The pa‐
3488 rameters available for each hypervisor are:
3489 LXC (posix scheduler) : cpu_shares, vcpu_period, vcpu_quota
3491 QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota, emula‐
3493 tor_period, emulator_quota, global_period, global_quota, iothread_pe‐
3494 riod, iothread_quota
3495 Xen (credit scheduler): weight, cap
3497 ESX (allocation scheduler): reservation, limit, shares
3499 If --live is specified, set scheduler information of a running guest.
3501 If --config is specified, affect the next start of a persistent guest.
3502 If --current is specified, it is equivalent to either --live or --con‐
3503 fig, depending on the current state of the guest.
3504 Note: The cpu_shares parameter has a valid value range of 2-262144.
3506 Note: The weight and cap parameters are defined only for the XEN_CREDIT
3508 scheduler.
3509 Note: The vcpu_period, emulator_period, and iothread_period parameters
3511 have a valid value range of 1000-1000000 or 0, and the vcpu_quota, emu‐
3512 lator_quota, and iothread_quota parameters have a valid value range of
3513 1000-17592186044415 or less than 0. The value 0 for either parameter is
3514 the same as not specifying that parameter.
3515 screenshot
3517 Syntax:
3518 screenshot domain [imagefilepath] [--screen screenID]
3520 Takes a screenshot of a current domain console and stores it into a
3522 file. Optionally, if the hypervisor supports more displays for a do‐
3523 main, screenID allows specifying which screen will be captured. It is
3524 the sequential number of screen. In case of multiple graphics cards,
3525 heads are enumerated before devices, e.g. having two graphics cards,
3526 both with four heads, screen ID 5 addresses the second head on the sec‐
3527 ond card.
3528 send-key
3530 Syntax:
3531 send-key domain [--codeset codeset] [--holdtime holdtime] keycode...
3533 Parse the keycode sequence as keystrokes to send to domain. Each key‐
3535 code can either be a numeric value or a symbolic name from the corre‐
3536 sponding codeset. If --holdtime is given, each keystroke will be held
3537 for that many milliseconds. The default codeset is linux, but use of
3538 the --codeset option allows other codesets to be chosen.
3539 If multiple keycodes are specified, they are all sent simultaneously to
3541 the guest, and they may be received in random order. If you need dis‐
3542 tinct keypresses, you must use multiple send-key invocations.
3543 • linux
3545 The numeric values are those defined by the Linux generic input event
3547 subsystem. The symbolic names match the corresponding Linux key con‐
3548 stant macro names.
3549 See virkeycode-linux(7) and virkeyname-linux(7)
3551 • xt
3553 The numeric values are those defined by the original XT keyboard con‐
3555 troller. No symbolic names are provided
3556 See virkeycode-xt(7)
3558 • atset1
3560 The numeric values are those defined by the AT keyboard controller,
3562 set 1 (aka XT compatible set). Extended keycoes from atset1 may dif‐
3563 fer from extended keycodes in the xt codeset. No symbolic names are
3564 provided
3565 See virkeycode-atset1(7)
3567 • atset2
3569 The numeric values are those defined by the AT keyboard controller,
3571 set 2. No symbolic names are provided
3572 See virkeycode-atset2(7)
3574 • atset3
3576 The numeric values are those defined by the AT keyboard controller,
3578 set 3 (aka PS/2 compatible set). No symbolic names are provided
3579 See virkeycode-atset3(7)
3581 • os_x
3583 The numeric values are those defined by the macOS keyboard input sub‐
3585 system. The symbolic names match the corresponding macOS key constant
3586 macro names
3587 See virkeycode-osx(7) and virkeyname-osx(7)
3589 • xt_kbd
3591 The numeric values are those defined by the Linux KBD device. These
3593 are a variant on the original XT codeset, but often with different
3594 encoding for extended keycodes. No symbolic names are provided.
3595 See virkeycode-xtkbd(7)
3597 • win32
3599 The numeric values are those defined by the Win32 keyboard input sub‐
3601 system. The symbolic names match the corresponding Win32 key constant
3602 macro names
3603 See virkeycode-win32(7) and virkeyname-win32(7)
3605 • usb
3607 The numeric values are those defined by the USB HID specification for
3609 keyboard input. No symbolic names are provided
3610 See virkeycode-usb(7)
3612 • qnum
3614 The numeric values are those defined by the QNUM extension for send‐
3616 ing raw keycodes. These are a variant on the XT codeset, but extended
3617 keycodes have the low bit of the second byte set, instead of the high
3618 bit of the first byte. No symbolic names are provided.
3619 See virkeycode-qnum(7)
3621 Examples:
3623 # send three strokes 'k', 'e', 'y', using xt codeset. these
3625 # are all pressed simultaneously and may be received by the guest
3626 # in random order
3627 virsh send-key dom --codeset xt 37 18 21
3628 # send one stroke 'right-ctrl+C'
3630 virsh send-key dom KEY_RIGHTCTRL KEY_C
3631 # send a tab, held for 1 second
3633 virsh send-key --holdtime 1000 0xf
3634 send-process-signal
3636 Syntax:
3637 send-process-signal domain-id pid signame
3639 Send a signal signame to the process identified by pid running in the
3641 virtual domain domain-id. The pid is a process ID in the virtual domain
3642 namespace.
3643 The signame argument may be either an integer signal constant number,
3645 or one of the symbolic names:
3646 "nop", "hup", "int", "quit", "ill",
3648 "trap", "abrt", "bus", "fpe", "kill",
3649 "usr1", "segv", "usr2", "pipe", "alrm",
3650 "term", "stkflt", "chld", "cont", "stop",
3651 "tstp", "ttin", "ttou", "urg", "xcpu",
3652 "xfsz", "vtalrm", "prof", "winch", "poll",
3653 "pwr", "sys", "rt0", "rt1", "rt2", "rt3",
3654 "rt4", "rt5", "rt6", "rt7", "rt8", "rt9",
3655 "rt10", "rt11", "rt12", "rt13", "rt14", "rt15",
3656 "rt16", "rt17", "rt18", "rt19", "rt20", "rt21",
3657 "rt22", "rt23", "rt24", "rt25", "rt26", "rt27",
3658 "rt28", "rt29", "rt30", "rt31", "rt32"
3659 The symbol name may optionally be prefixed with sig or sig_ and may be
3661 in uppercase or lowercase.
3662 Examples:
3664 virsh send-process-signal myguest 1 15
3666 virsh send-process-signal myguest 1 term
3667 virsh send-process-signal myguest 1 sigterm
3668 virsh send-process-signal myguest 1 SIG_HUP
3669 set-lifecycle-action
3671 Syntax:
3672 set-lifecycle-action domain type action
3674 [[--config] [--live] | [--current]]
3675 Set the lifecycle action for specified lifecycle type. The valid types
3677 are "poweroff", "reboot" and "crash", and for each of them valid action
3678 is one of "destroy", "restart", "rename-restart", "preserve". For type
3679 "crash", additional actions "coredump-destroy" and "coredump-restart"
3680 are supported.
3681 set-user-password
3683 Syntax:
3684 set-user-password domain user password [--encrypted]
3686 Set the password for the user account in the guest domain.
3688 If --encrypted is specified, the password is assumed to be already en‐
3690 crypted by the method required by the guest OS.
3691 For QEMU/KVM, this requires the guest agent to be configured and run‐
3693 ning.
3694 set-user-sshkeys
3696 Syntax:
3697 set-user-sshkeys domain user [--file FILE] [{--reset | --remove}]
3699 Append keys read from FILE into user's SSH authorized keys file in the
3701 guest domain. In the FILE keys must be on separate lines and each line
3702 must follow authorized keys format as defined by sshd(8).
3703 If --reset is specified, then the guest authorized keys file content is
3705 removed before appending new keys. As a special case, if --reset is
3706 provided and no FILE was provided then no new keys are added and the
3707 authorized keys file is cleared out.
3708 If --remove is specified, then instead of adding any new keys then keys
3710 read from FILE are removed from the authorized keys file. It is not
3711 considered an error if the key does not exist in the file.
3712 setmaxmem
3714 Syntax:
3715 setmaxmem domain size [[--config] [--live] | [--current]]
3717 Change the maximum memory allocation limit for a guest domain. If
3719 --live is specified, affect a running guest. If --config is specified,
3720 affect the next start of a persistent guest. If --current is speci‐
3721 fied, it is equivalent to either --live or --config, depending on the
3722 current state of the guest. Both --live and --config flags may be
3723 given, but --current is exclusive. If no flag is specified, behavior is
3724 different depending on hypervisor.
3725 Some hypervisors such as QEMU/KVM don't support live changes (espe‐
3727 cially increasing) of the maximum memory limit. Even persistent con‐
3728 figuration changes might not be performed with some hypervisors/config‐
3729 uration (e.g. on NUMA enabled domains on QEMU). For complex configura‐
3730 tion changes use command edit instead).
3731 size is a scaled integer (see NOTES above); it defaults to kibibytes
3733 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3734 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3735 rounds up to the nearest kibibyte. Some hypervisors require a larger
3736 granularity than KiB, and requests that are not an even multiple will
3737 be rounded up. For example, vSphere/ESX rounds the parameter up to
3738 mebibytes (1024 kibibytes).
3739 setmem
3741 Syntax:
3742 setmem domain size [[--config] [--live] | [--current]]
3744 Change the memory allocation for a guest domain. If --live is speci‐
3746 fied, perform a memory balloon of a running guest. If --config is
3747 specified, affect the next start of a persistent guest. If --current
3748 is specified, it is equivalent to either --live or --config, depending
3749 on the current state of the guest. Both --live and --config flags may
3750 be given, but --current is exclusive. If no flag is specified, behavior
3751 is different depending on hypervisor.
3752 size is a scaled integer (see NOTES above); it defaults to kibibytes
3754 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3755 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3756 rounds up to the nearest kibibyte. Some hypervisors require a larger
3757 granularity than KiB, and requests that are not an even multiple will
3758 be rounded up. For example, vSphere/ESX rounds the parameter up to
3759 mebibytes (1024 kibibytes).
3760 For Xen, you can only adjust the memory of a running domain if the do‐
3762 main is paravirtualized or running the PV balloon driver.
3763 For LXC, the value being set is the cgroups value for limit_in_bytes or
3765 the maximum amount of user memory (including file cache). When viewing
3766 memory inside the container, this is the /proc/meminfo "MemTotal"
3767 value. When viewing the value from the host, use the virsh memtune com‐
3768 mand. In order to view the current memory in use and the maximum value
3769 allowed to set memory, use the virsh dominfo command.
3770 setvcpus
3772 Syntax:
3773 setvcpus domain count [--maximum] [[--config] [--live] | [--current]] [--guest] [--hotpluggable]
3775 Change the number of virtual CPUs active in a guest domain. By de‐
3777 fault, this command works on active guest domains. To change the set‐
3778 tings for an inactive guest domain, use the --config flag.
3779 The count value may be limited by host, hypervisor, or a limit coming
3781 from the original description of the guest domain. For Xen, you can
3782 only adjust the virtual CPUs of a running domain if the domain is par‐
3783 avirtualized.
3784 If the --config flag is specified, the change is made to the stored XML
3786 configuration for the guest domain, and will only take effect when the
3787 guest domain is next started.
3788 If --live is specified, the guest domain must be active, and the change
3790 takes place immediately. Both the --config and --live flags may be
3791 specified together if supported by the hypervisor. If this command is
3792 run before the guest has finished booting, the guest may fail to
3793 process the change.
3794 If --current is specified, it is equivalent to either --live or --con‐
3796 fig, depending on the current state of the guest.
3797 When no flags are given, the --live flag is assumed and the guest do‐
3799 main must be active. In this situation it is up to the hypervisor
3800 whether the --config flag is also assumed, and therefore whether the
3801 XML configuration is adjusted to make the change persistent.
3802 If --guest is specified, then the count of cpus is modified in the
3804 guest instead of the hypervisor. This flag is usable only for live do‐
3805 mains and may require guest agent to be configured in the guest.
3806 To allow adding vcpus to persistent definitions that can be later ho‐
3808 tunplugged after the domain is booted it is necessary to specify the
3809 --hotpluggable flag. Vcpus added to live domains supporting vcpu unplug
3810 are automatically marked as hotpluggable.
3811 The --maximum flag controls the maximum number of virtual cpus that can
3813 be hot-plugged the next time the domain is booted. As such, it must
3814 only be used with the --config flag, and not with the --live or the
3815 --current flag. Note that it may not be possible to change the maximum
3816 vcpu count if the processor topology is specified for the guest.
3817 setvcpu
3819 Syntax:
3820 setvcpu domain vcpulist [--enable] | [--disable]
3822 [[--live] [--config] | [--current]]
3823 Change state of individual vCPUs using hot(un)plug mechanism.
3825 See vcpupin for information on format of vcpulist. Hypervisor drivers
3827 may require that vcpulist contains exactly vCPUs belonging to one hot‐
3828 pluggable entity. This is usually just a single vCPU but certain archi‐
3829 tectures such as ppc64 require a full core to be specified at once.
3830 Note that hypervisors may refuse to disable certain vcpus such as vcpu
3832 0 or others.
3833 If --live is specified, affect a running domain. If --config is speci‐
3835 fied, affect the next startup of a persistent guest. If --current is
3836 specified, it is equivalent to either --live or --config, depending on
3837 the current state of the guest. This is the default. Both --live and
3838 --config flags may be given, but --current is exclusive.
3839 shutdown
3841 Syntax:
3842 shutdown domain [--mode MODE-LIST]
3844 Gracefully shuts down a domain. This coordinates with the domain OS to
3846 perform graceful shutdown, so there is no guarantee that it will suc‐
3847 ceed, and may take a variable length of time depending on what services
3848 must be shutdown in the domain.
3849 The exact behavior of a domain when it shuts down is set by the
3851 on_poweroff parameter in the domain's XML definition.
3852 If domain is transient, then the metadata of any snapshots and check‐
3854 points will be lost once the guest stops running, but the underlying
3855 contents still exist, and a new domain with the same name and UUID can
3856 restore the snapshot metadata with snapshot-create, and the checkpoint
3857 metadata with checkpoint-create.
3858 By default the hypervisor will try to pick a suitable shutdown method.
3860 To specify an alternative method, the --mode parameter can specify a
3861 comma separated list which includes acpi, agent, initctl, signal and
3862 paravirt. The order in which drivers will try each mode is undefined,
3863 and not related to the order specified to virsh. For strict control
3864 over ordering, use a single mode at a time and repeat the command.
3865 start
3867 Syntax:
3868 start domain-name-or-uuid [--console] [--paused]
3870 [--autodestroy] [--bypass-cache] [--force-boot]
3871 [--pass-fds N,M,...] [--reset-nvram]
3872 Start a (previously defined) inactive domain, either from the last man‐
3874 agedsave state, or via a fresh boot if no managedsave state is present.
3875 The domain will be paused if the --paused option is used and supported
3876 by the driver; otherwise it will be running. If --console is re‐
3877 quested, attach to the console after creation. If --autodestroy is re‐
3878 quested, then the guest will be automatically destroyed when virsh
3879 closes its connection to libvirt, or otherwise exits. If --by‐
3880 pass-cache is specified, and managedsave state exists, the restore will
3881 avoid the file system cache, although this may slow down the operation.
3882 If --force-boot is specified, then any managedsave state is discarded
3883 and a fresh boot occurs.
3884 If --pass-fds is specified, the argument is a comma separated list of
3886 open file descriptors which should be pass on into the guest. The file
3887 descriptors will be re-numbered in the guest, starting from 3. This is
3888 only supported with container based virtualization.
3889 If --reset-nvram is specified, any existing NVRAM file will be deleted
3891 and re-initialized from its pristine template.
3892 suspend
3894 Syntax:
3895 suspend domain
3897 Suspend a running domain. It is kept in memory but won't be scheduled
3899 anymore.
3900 ttyconsole
3902 Syntax:
3903 ttyconsole domain
3905 Output the device used for the TTY console of the domain. If the infor‐
3907 mation is not available the processes will provide an exit code of 1.
3908 undefine
3910 Syntax:
3911 undefine domain [--managed-save] [--snapshots-metadata]
3913 [--checkpoints-metadata] [--nvram] [--keep-nvram]
3914 [ {--storage volumes | --remove-all-storage
3915 [--delete-storage-volume-snapshots]} --wipe-storage]
3916 [--tpm] [--keep-tpm]
3917 Undefine a domain. If the domain is running, this converts it to a
3919 transient domain, without stopping it. If the domain is inactive, the
3920 domain configuration is removed.
3921 The --managed-save flag guarantees that any managed save image (see the
3923 managedsave command) is also cleaned up. Without the flag, attempts to
3924 undefine a domain with a managed save image will fail.
3925 The --snapshots-metadata flag guarantees that any snapshots (see the
3927 snapshot-list command) are also cleaned up when undefining an inactive
3928 domain. Without the flag, attempts to undefine an inactive domain with
3929 snapshot metadata will fail. If the domain is active, this flag is ig‐
3930 nored.
3931 The --checkpoints-metadata flag guarantees that any checkpoints (see
3933 the checkpoint-list command) are also cleaned up when undefining an in‐
3934 active domain. Without the flag, attempts to undefine an inactive do‐
3935 main with checkpoint metadata will fail. If the domain is active, this
3936 flag is ignored.
3937 --nvram and --keep-nvram specify accordingly to delete or keep nvram
3939 (/domain/os/nvram/) file. If the domain has an nvram file and the flags
3940 are omitted, the undefine will fail.
3941 The --storage flag takes a parameter volumes, which is a comma sepa‐
3943 rated list of volume target names or source paths of storage volumes to
3944 be removed along with the undefined domain. Volumes can be undefined
3945 and thus removed only on inactive domains. Volume deletion is only at‐
3946 tempted after the domain is undefined; if not all of the requested vol‐
3947 umes could be deleted, the error message indicates what still remains
3948 behind. If a volume path is not found in the domain definition, it's
3949 treated as if the volume was successfully deleted. Only volumes managed
3950 by libvirt in storage pools can be removed this way. (See domblklist
3951 for list of target names associated to a domain). Example: --storage
3952 vda,/path/to/storage.img
3953 The --remove-all-storage flag specifies that all of the domain's stor‐
3955 age volumes should be deleted.
3956 The --delete-storage-volume-snapshots (previously --delete-snapshots)
3958 flag specifies that any snapshots associated with the storage volume
3959 should be deleted as well. Requires the --remove-all-storage flag to be
3960 provided. Not all storage drivers support this option, presently only
3961 rbd. Using this when also removing volumes handled by a storage driver
3962 which does not support the flag will result in failure.
3963 The flag --wipe-storage specifies that the storage volumes should be
3965 wiped before removal.
3966 --tpm and --keep-tpm specify accordingly to delete or keep a TPM's per‐
3968 sistent state directory structure and files. If the flags are omitted
3969 then the persistent_state attribute in the TPM emulator definition in
3970 the domain XML determines whether the TPM state is kept.
3971 NOTE: For an inactive domain, the domain name or UUID must be used as
3973 the domain.
3974 vcpucount
3976 Syntax:
3977 vcpucount domain [{--maximum | --active}
3979 {--config | --live | --current}] [--guest]
3980 Print information about the virtual cpu counts of the given domain. If
3982 no flags are specified, all possible counts are listed in a table; oth‐
3983 erwise, the output is limited to just the numeric value requested. For
3984 historical reasons, the table lists the label "current" on the rows
3985 that can be queried in isolation via the --active flag, rather than re‐
3986 lating to the --current flag.
3987 --maximum requests information on the maximum cap of vcpus that a do‐
3989 main can add via setvcpus, while --active shows the current usage;
3990 these two flags cannot both be specified. --config requires a persis‐
3991 tent guest and requests information regarding the next time the domain
3992 will be booted, --live requires a running domain and lists current val‐
3993 ues, and --current queries according to the current state of the domain
3994 (corresponding to --live if running, or --config if inactive); these
3995 three flags are mutually exclusive.
3996 If --guest is specified, then the count of cpus is reported from the
3998 perspective of the guest. This flag is usable only for live domains and
3999 may require guest agent to be configured in the guest.
4000 vcpuinfo
4002 Syntax:
4003 vcpuinfo domain [--pretty]
4005 Returns basic information about the domain virtual CPUs, like the num‐
4007 ber of vCPUs, the running time, the affinity to physical processors.
4008 With --pretty, cpu affinities are shown as ranges.
4010 Example:
4012 $ virsh vcpuinfo fedora
4014 VCPU: 0
4015 CPU: 0
4016 State: running
4017 CPU time: 7,0s
4018 CPU Affinity: yyyy
4019 VCPU: 1
4021 CPU: 1
4022 State: running
4023 CPU time: 0,7s
4024 CPU Affinity: yyyy
4025 STATES
4027 The State field displays the current operating state of a virtual CPU
4029 • offline
4031 The virtual CPU is offline and not usable by the domain. This state
4033 is not supported by all hypervisors.
4034 • running
4036 The virtual CPU is available to the domain and is operating.
4038 • blocked
4040 The virtual CPU is available to the domain but is waiting for a re‐
4042 source. This state is not supported by all hypervisors, in which
4043 case running may be reported instead.
4044 • no state
4046 The virtual CPU state could not be determined. This could happen if
4048 the hypervisor is newer than virsh.
4049 • N/A
4051 There's no information about the virtual CPU state available. This
4053 can be the case if the domain is not running or the hypervisor does
4054 not report the virtual CPU state.
4055 vcpupin
4057 Syntax:
4058 vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]]
4060 Query or change the pinning of domain VCPUs to host physical CPUs. To
4062 pin a single vcpu, specify cpulist; otherwise, you can query one vcpu
4063 or omit vcpu to list all at once.
4064 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
4066 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
4067 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
4068 clusive. For pinning the vcpu to all physical cpus specify 'r' as a
4069 cpulist. If --live is specified, affect a running guest. If --config
4070 is specified, affect the next start of a persistent guest. If --cur‐
4071 rent is specified, it is equivalent to either --live or --config, de‐
4072 pending on the current state of the guest. Both --live and --config
4073 flags may be given if cpulist is present, but --current is exclusive.
4074 If no flag is specified, behavior is different depending on hypervisor.
4075 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
4077 cal to "9-14,0-7,15" but not identical to "^8,0-15".
4078 vncdisplay
4080 Syntax:
4081 vncdisplay domain
4083 Output the IP address and port number for the VNC display. If the in‐
4085 formation is not available the processes will provide an exit code of
4086 1.
4087
4089 The following commands manipulate devices associated to domains. The
4090 domain can be specified as a short integer, a name or a full UUID. To
4091 better understand the values allowed as options for the command reading
4092 the documentation at https://libvirt.org/formatdomain.html on the for‐
4093 mat of the device sections to get the most accurate set of accepted
4094 values.
4095 attach-device
4097 Syntax:
4098 attach-device domain FILE [[[--live] [--config] | [--current]] | [--persistent]]
4100 Attach a device to the domain, using a device definition in an XML file
4102 using a device definition element such as <disk> or <interface> as the
4103 top-level element. See the documentation at
4104 https://libvirt.org/formatdomain.html#elementsDevices to learn about
4105 libvirt XML format for a device. If --config is specified the command
4106 alters the persistent guest configuration with the device attach taking
4107 effect the next time libvirt starts the domain. For cdrom and floppy
4108 devices, this command only replaces the media within an existing de‐
4109 vice; consider using update-device for this usage. For passthrough
4110 host devices, see also nodedev-detach, needed if the PCI device does
4111 not use managed mode.
4112 If --live is specified, affect a running domain. If --config is speci‐
4114 fied, affect the next startup of a persistent guest. If --current is
4115 specified, it is equivalent to either --live or --config, depending on
4116 the current state of the guest. Both --live and --config flags may be
4117 given, but --current is exclusive. When no flag is specified legacy API
4118 is used whose behavior depends on the hypervisor driver.
4119 For compatibility purposes, --persistent behaves like --config for an
4121 offline domain, and like --live --config for a running domain.
4122 Note: using of partial device definition XML files may lead to unex‐
4124 pected results as some fields may be autogenerated and thus match de‐
4125 vices other than expected.
4126 attach-disk
4128 Syntax:
4129 attach-disk domain source target [[[--live] [--config] |
4131 [--current]] | [--persistent]] [--targetbus bus]
4132 [--driver driver] [--subdriver subdriver] [--iothread iothread]
4133 [--cache cache] [--io io] [--type type] [--alias alias]
4134 [--mode mode] [--sourcetype sourcetype]
4135 [--source-protocol protocol] [--source-host-name hostname:port]
4136 [--source-host-transport transport] [--source-host-socket socket]
4137 [--serial serial] [--wwn wwn] [--rawio] [--address address]
4138 [--multifunction] [--print-xml]
4139 Attach a new disk device to the domain. source is path for the files
4141 and devices unless --source-protocol is specified, in which case source
4142 is the name of a network disk. target controls the bus or device under
4143 which the disk is exposed to the guest OS. It indicates the "logical"
4144 device name; the optional targetbus attribute specifies the type of
4145 disk device to emulate; possible values are driver specific, with typi‐
4146 cal values being ide, scsi, virtio, xen, usb, sata, or sd, if omitted,
4147 the bus type is inferred from the style of the device name (e.g. a de‐
4148 vice named 'sda' will typically be exported using a SCSI bus). driver
4149 can be file, tap or phy for the Xen hypervisor depending on the kind of
4150 access; or qemu for the QEMU emulator. Further details to the driver
4151 can be passed using subdriver. For Xen subdriver can be aio, while for
4152 QEMU subdriver should match the format of the disk source, such as raw
4153 or qcow2. Hypervisor default will be used if subdriver is not speci‐
4154 fied. However, the default may not be correct, esp. for QEMU as for
4155 security reasons it is configured not to detect disk formats. type can
4156 indicate lun, cdrom or floppy as alternative to the disk default, al‐
4157 though this use only replaces the media within the existing virtual
4158 cdrom or floppy device; consider using update-device for this usage in‐
4159 stead. alias can set user supplied alias. mode can specify the two
4160 specific mode readonly or shareable. sourcetype can indicate the type
4161 of source (block|file|network) cache can be one of "default", "none",
4162 "writethrough", "writeback", "directsync" or "unsafe". io controls
4163 specific policies on I/O; QEMU guests support "threads", "native" and
4164 "io_uring". iothread is the number within the range of domain IO‐
4165 Threads to which this disk may be attached (QEMU only). serial is the
4166 serial of disk device. wwn is the wwn of disk device. rawio indicates
4167 the disk needs rawio capability. address is the address of disk device
4168 in the form of pci:domain.bus.slot.function, scsi:controller.bus.unit,
4169 ide:controller.bus.unit, usb:bus.port, sata:controller.bus.unit or
4170 ccw:cssid.ssid.devno. Virtio-ccw devices must have their cssid set to
4171 0xfe. multifunction indicates specified pci address is a multifunction
4172 pci device address.
4173 There is also support for using a network disk. As specified, the user
4175 can provide a --source-protocol in which case the source parameter will
4176 be interpreted as the source name. --source-protocol must be provided
4177 if the user intends to provide a network disk or host information.
4178 Host information can be provided using the tags --source-host-name,
4179 --source-host-transport, and --source-host-socket, which respectively
4180 denote the name of the host, the host's transport method, and the
4181 socket that the host uses. --source-host-socket and --source-host-name
4182 cannot both be provided, and the user must provide a
4183 --source-host-transport if they want to provide a --source-host-socket.
4184 The --source-host-name parameter supports host:port syntax if the user
4185 wants to provide a port as well.
4186 If --print-xml is specified, then the XML of the disk that would be at‐
4188 tached is printed instead.
4189 If --live is specified, affect a running domain. If --config is speci‐
4191 fied, affect the next startup of a persistent guest. If --current is
4192 specified, it is equivalent to either --live or --config, depending on
4193 the current state of the guest. Both --live and --config flags may be
4194 given, but --current is exclusive. When no flag is specified legacy API
4195 is used whose behavior depends on the hypervisor driver.
4196 For compatibility purposes, --persistent behaves like --config for an
4198 offline domain, and like --live --config for a running domain. Like‐
4199 wise, --shareable is an alias for --mode shareable.
4200 attach-interface
4202 Syntax:
4203 attach-interface domain type source [[[--live]
4205 [--config] | [--current]] | [--persistent]]
4206 [--target target] [--mac mac] [--script script] [--model model]
4207 [--inbound average,peak,burst,floor] [--outbound average,peak,burst]
4208 [--alias alias] [--managed] [--print-xml]
4209 [--source-mode mode]
4210 Attach a new network interface to the domain.
4212 type can be one of the:
4214 network to indicate connection via a libvirt virtual network,
4216 bridge to indicate connection via a bridge device on the host,
4218 direct to indicate connection directly to one of the host's network in‐
4220 terfaces or bridges,
4221 hostdev to indicate connection using a passthrough of PCI device on the
4223 host,
4224 vhostuser to indicate connection using a virtio transport protocol.
4226 source indicates the source of the connection. The source depends on
4228 the type of the interface:
4229 network name of the virtual network,
4231 bridge the name of the bridge device,
4233 direct the name of the host's interface or bridge,
4235 hostdev the PCI address of the host's interface formatted as do‐
4237 main:bus:slot.function.
4238 vhostuser the path to UNIX socket (control plane)
4240 --target is used to specify the tap/macvtap device to be used to con‐
4242 nect the domain to the source. Names starting with 'vnet' are consid‐
4243 ered as auto-generated and are blanked out/regenerated each time the
4244 interface is attached.
4245 --mac specifies the MAC address of the network interface; if a MAC ad‐
4247 dress is not given, a new address will be automatically generated (and
4248 stored in the persistent configuration if "--config" is given on the
4249 command line).
4250 --script is used to specify a path to a custom script to be called
4252 while attaching to a bridge - this will be called instead of the de‐
4253 fault script not in addition to it. This is valid only for interfaces
4254 of bridge type and only for Xen domains.
4255 --model specifies the network device model to be presented to the do‐
4257 main.
4258 alias can set user supplied alias.
4260 --inbound and --outbound control the bandwidth of the interface. At
4262 least one from the average, floor pair must be specified. The other
4263 two peak and burst are optional, so "average,peak", "average,,burst",
4264 "average,,,floor", "average" and ",,,floor" are also legal. Values for
4265 average, floor and peak are expressed in kilobytes per second, while
4266 burst is expressed in kilobytes in a single burst at peak speed as de‐
4267 scribed in the Network XML documentation at
4268 https://libvirt.org/formatnetwork.html#quality-of-service.
4269 --managed is usable only for hostdev type and tells libvirt that the
4271 interface should be managed, which means detached and reattached
4272 from/to the host by libvirt.
4273 --source-mode is mandatory for vhostuser interface and accepts values
4275 server and client that control whether hypervisor waits for the other
4276 process to connect, or initiates connection, respectively.
4277 If --print-xml is specified, then the XML of the interface that would
4279 be attached is printed instead.
4280 If --live is specified, affect a running domain. If --config is speci‐
4282 fied, affect the next startup of a persistent guest. If --current is
4283 specified, affect the current domain state, which can either be live or
4284 offline. Both --live and --config flags may be given, but --current is
4285 exclusive. When no flag is specified legacy API is used whose behavior
4286 depends on the hypervisor driver.
4287 For compatibility purposes, --persistent behaves like --config for an
4289 offline domain, and like --live --config for a running domain.
4290 Note: the optional target value is the name of a device to be created
4292 as the back-end on the node. If not provided a device named "vnetN" or
4293 "vifN" will be created automatically.
4294 detach-device
4296 Syntax:
4297 detach-device domain FILE [[[--live] [--config] |
4299 [--current]] | [--persistent]]
4300 Detach a device from the domain, takes the same kind of XML descrip‐
4302 tions as command attach-device. For passthrough host devices, see also
4303 nodedev-reattach, needed if the device does not use managed mode.
4304 Note: The supplied XML description of the device should be as specific
4306 as its definition in the domain XML. The set of attributes used to
4307 match the device are internal to the drivers. Using a partial defini‐
4308 tion, or attempting to detach a device that is not present in the do‐
4309 main XML, but shares some specific attributes with one that is present,
4310 may lead to unexpected results.
4311 Quirk: Device unplug is asynchronous in most cases and requires guest
4313 cooperation. This means that it's up to the discretion of the guest to
4314 disallow or delay the unplug arbitrarily. As the libvirt API used in
4315 this command was designed as synchronous it returns success after some
4316 timeout even if the device was not unplugged yet to allow further in‐
4317 teractions with the domain e.g. if the guest is unresponsive. Callers
4318 which need to make sure that the device was unplugged can use libvirt
4319 events (see virsh event) to be notified when the device is removed.
4320 Note that the event may arrive before the command returns.
4321 If --live is specified, affect a running domain. If --config is speci‐
4323 fied, affect the next startup of a persistent guest. If --current is
4324 specified, it is equivalent to either --live or --config, depending on
4325 the current state of the guest. Both --live and --config flags may be
4326 given, but --current is exclusive. When no flag is specified legacy API
4327 is used whose behavior depends on the hypervisor driver.
4328 For compatibility purposes, --persistent behaves like --config for an
4330 offline domain, and like --live --config for a running domain.
4331 Note that older versions of virsh used --config as an alias for --per‐
4333 sistent.
4334 detach-device-alias
4336 Syntax:
4337 detach-device-alias domain alias [[[--live] [--config] | [--current]]]]
4339 Detach a device with given alias from the domain. This command returns
4341 successfully after the unplug request was sent to the hypervisor. The
4342 actual removal of the device is notified asynchronously via libvirt
4343 events (see virsh event).
4344 If --live is specified, affect a running domain. If --config is speci‐
4346 fied, affect the next startup of a persistent guest. If --current is
4347 specified, it is equivalent to either --live or --config, depending on
4348 the current state of the guest. Both --live and --config flags may be
4349 given, but --current is exclusive.
4350 detach-disk
4352 Syntax:
4353 detach-disk domain target [[[--live] [--config] |
4355 [--current]] | [--persistent]] [--print-xml]
4356 Detach a disk device from a domain. The target is the device as seen
4358 from the domain.
4359 If --live is specified, affect a running domain. If --config is speci‐
4361 fied, affect the next startup of a persistent guest. If --current is
4362 specified, it is equivalent to either --live or --config, depending on
4363 the current state of the guest. Both --live and --config flags may be
4364 given, but --current is exclusive. When no flag is specified legacy API
4365 is used whose behavior depends on the hypervisor driver.
4366 For compatibility purposes, --persistent behaves like --config for an
4368 offline domain, and like --live --config for a running domain.
4369 Note that older versions of virsh used --config as an alias for --per‐
4371 sistent.
4372 If --print-xml is specified, then the XML which would be used to detach
4374 the disk is printed instead.
4375 Please see documentation for detach-device for known quirks.
4377 detach-interface
4379 Syntax:
4380 detach-interface domain type [--mac mac]
4382 [[[--live] [--config] | [--current]] | [--persistent]] [--print-xml]
4383 Detach a network interface from a domain. type can be either network
4385 to indicate a physical network device or bridge to indicate a bridge to
4386 a device. It is recommended to use the mac option to distinguish be‐
4387 tween the interfaces if more than one are present on 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 used to detach the interface
4403 is printed instead.
4404 Please see documentation for detach-device for known quirks.
4406 update-device
4408 Syntax:
4409 update-device domain file [--force] [[[--live]
4411 [--config] | [--current]] | [--persistent]]
4412 Update the characteristics of a device associated with domain, based on
4414 the device definition in an XML file. The --force option can be used
4415 to force device update, e.g., to eject a CD-ROM even if it is
4416 locked/mounted in the domain. See the documentation at
4417 https://libvirt.org/formatdomain.html#elementsDevices to learn about
4418 libvirt XML format for a device.
4419 If --live is specified, affect a running domain. If --config is speci‐
4421 fied, affect the next startup of a persistent guest. If --current is
4422 specified, it is equivalent to either --live or --config, depending on
4423 the current state of the guest. Both --live and --config flags may be
4424 given, but --current is exclusive. Not specifying any flag is the same
4425 as specifying --current.
4426 For compatibility purposes, --persistent behaves like --config for an
4428 offline domain, and like --live --config for a running domain.
4429 Note that older versions of virsh used --config as an alias for --per‐
4431 sistent.
4432 Note: using of partial device definition XML files may lead to unex‐
4434 pected results as some fields may be autogenerated and thus match de‐
4435 vices other than expected.
4436 update-memory-device
4438 Syntax:
4439 update-memory-device domain [--print-xml] [[--alias alias] | [--node node]]
4441 [[--live] [--config] | [--current]]
4442 [--requested-size size]
4443 This command finds <memory/> device inside given domain, changes re‐
4445 quested values and passes updated device XML to daemon. If --print-xml
4446 is specified then the device is not changed, but the updated device XML
4447 is printed to stdout. If there are more than one <memory/> devices in
4448 domain use --alias or --node to select the desired one.
4449 If --live is specified, affect a running domain. If --config is speci‐
4451 fied, affect the next startup of a persistent guest. If --current is
4452 specified, it is equivalent to either --live or --config, depending on
4453 the current state of the guest. Both --live and --config flags may be
4454 given, but --current is exclusive. Not specifying any flag is the same
4455 as specifying --current.
4456 If --requested-size is specified then <requested/> under memory target
4458 is changed to requested size (as scaled integer, see NOTES above). It
4459 defaults to kibibytes if no suffix is provided. The option is valid
4460 only for virtio-mem memory device model.
4461 change-media
4463 Syntax:
4464 change-media domain path [--eject] [--insert]
4466 [--update] [source] [--force] [[--live] [--config] |
4467 [--current]] [--print-xml] [--block]
4468 Change media of CDROM or floppy drive. path can be the fully-qualified
4470 path or the unique target name (<target dev='hdc'>) of the disk device.
4471 source specifies the path of the media to be inserted or updated. The
4472 --block flag allows setting the backing type in case a block device is
4473 used as media for the CDROM or floppy drive instead of a file.
4474 --eject indicates the media will be ejected. --insert indicates the
4476 media will be inserted. source must be specified. If the device has
4477 source (e.g. <source file='media'>), and source is not specified, --up‐
4478 date is equal to --eject. If the device has no source, and source is
4479 specified, --update is equal to --insert. If the device has source, and
4480 source is specified, --update behaves like combination of --eject and
4481 --insert. If none of --eject, --insert, and --update is specified,
4482 --update is used by default. The --force option can be used to force
4483 media changing. If --live is specified, alter live configuration of
4484 running guest. If --config is specified, alter persistent configura‐
4485 tion, effect observed on next startup of the guest. --current can be
4486 either or both of live and config, depends on the hypervisor's imple‐
4487 mentation. Both --live and --config flags may be given, but --current
4488 is exclusive. If no flag is specified, behavior is different depending
4489 on hypervisor. If --print-xml is specified, the XML that would be used
4490 to change media is printed instead of changing the media.
4491 dom-fd-associate
4493 Syntax:
4494 dom-fd-associate domain --name FDGROUPNAME --pass-fds M,N,....
4496 [--seclabel-writable] [--seclabel-restore]
4497 Associate one or more fds described via --pass-fds argument to domain
4499 as --name. The lifetime of the passed fd group is the same as the con‐
4500 nection, thus exitting virsh un-registers them afterwards.
4501 By default security labels are applied if needed but they are not re‐
4503 stored after use to avoid keeping them open unnecessarily. Best-effort
4504 security label restore may be requested by using the --seclabel-restore
4505 flag.
4506
4508 The following commands manipulate host devices that are intended to be
4509 passed through to guest domains via <hostdev> elements in a domain's
4510 <devices> section. A node device key is generally specified by the bus
4511 name followed by its address, using underscores between all components,
4512 such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
4513 The nodedev-list gives the full list of host devices that are known to
4514 libvirt, although this includes devices that cannot be assigned to a
4515 guest (for example, attempting to detach the PCI device that controls
4516 the host's hard disk controller where the guest's disk images live
4517 could cause the host system to lock up or reboot).
4518 For more information on node device definition see:
4520 https://libvirt.org/formatnode.html.
4521 Passthrough devices cannot be simultaneously used by the host and its
4523 guest domains, nor by multiple active guests at once. If the <hostdev>
4524 description of a PCI device includes the attribute managed='yes', and
4525 the hypervisor driver supports it, then the device is in managed mode,
4526 and attempts to use that passthrough device in an active guest will au‐
4527 tomatically behave as if nodedev-detach (guest start, device hot-plug)
4528 and nodedev-reattach (guest stop, device hot-unplug) were called at the
4529 right points. If a PCI device is not marked as managed, then it must
4530 manually be detached before guests can use it, and manually reattached
4531 to be returned to the host. Also, if a device is manually detached,
4532 then the host does not regain control of the device without a matching
4533 reattach, even if the guests use the device in managed mode.
4534 nodedev-create
4536 Syntax:
4537 nodedev-create FILE [--validate]
4539 Create a device on the host node that can then be assigned to virtual
4541 machines. Normally, libvirt is able to automatically determine which
4542 host nodes are available for use, but this allows registration of host
4543 hardware that libvirt did not automatically detect. file contains xml
4544 for a top-level <device> description of a node device.
4545 If --validate is specified, validates the format of the XML document
4547 against an internal RNG schema.
4548 nodedev-destroy
4550 Syntax:
4551 nodedev-destroy device
4553 Destroy (stop) a device on the host. device can be either device name
4555 or wwn pair in "wwnn,wwpn" format (only works for vHBA currently).
4556 Note that this makes libvirt quit managing a host device, and may even
4557 make that device unusable by the rest of the physical host until a re‐
4558 boot.
4559 nodedev-define
4561 Syntax:
4562 nodedev-define FILE [--validate]
4564 Define an inactive persistent device or modify an existing persistent
4566 one from the XML FILE.
4567 If --validate is specified, validates the format of the XML document
4569 against an internal RNG schema.
4570 nodedev-undefine
4572 Syntax:
4573 nodedev-undefine device
4575 Undefine the configuration for a persistent device. If the device is
4577 active, make it transient.
4578 nodedev-start
4580 Syntax:
4581 nodedev-start device
4583 Start a (previously defined) inactive device.
4585 nodedev-detach
4587 Syntax:
4588 nodedev-detach nodedev [--driver backend_driver]
4590 Detach nodedev from the host, so that it can safely be used by guests
4592 via <hostdev> passthrough. This is reversed with nodedev-reattach, and
4593 is done automatically for managed devices.
4594 Different backend drivers expect the device to be bound to different
4596 dummy devices. For example, QEMU's "vfio" backend driver expects the
4597 device to be bound to vfio-pci. The --driver parameter can be used to
4598 specify the desired backend driver.
4599 nodedev-dumpxml
4601 Syntax:
4602 nodedev-dumpxml [--xpath EXPRESSION] [--wrap] device
4604 Dump a <device> XML representation for the given node device, including
4606 such information as the device name, which bus owns the device, the
4607 vendor and product id, and any capabilities of the device usable by
4608 libvirt (such as whether device reset is supported). device can be ei‐
4609 ther device name or wwn pair in "wwnn,wwpn" format (only works for
4610 HBA).
4611 If the --xpath argument provides an XPath expression, it will be evalu‐
4613 ated against the output XML and only those matching nodes will be
4614 printed. The default behaviour is to print each matching node as a
4615 standalone document, however, for ease of additional processing, the
4616 --wrap argument will cause the matching node to be wrapped in a common
4617 root node.
4618 nodedev-info
4620 Syntax:
4621 nodedev-info device
4623 Returns basic information about the device object.
4625 nodedev-list
4627 Syntax:
4628 nodedev-list [--cap capability] [--tree] [--inactive | --all]
4630 List all of the devices available on the node that are known by lib‐
4632 virt. cap is used to filter the list by capability types, the types
4633 must be separated by comma, e.g. --cap pci,scsi. Valid capability types
4634 include 'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host',
4635 'scsi_target', 'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic',
4636 'drm', 'mdev', 'mdev_types', 'ccw', 'css', 'ap_card', 'ap_queue',
4637 'ap_matrix'. By default, only active devices are listed. --inactive is
4638 used to list only inactive devices, and -all is used to list both ac‐
4639 tive and inactive devices. If --tree is used, the output is formatted
4640 in a tree representing parents of each node. --tree is mutually exclu‐
4641 sive with all other options.
4642 nodedev-reattach
4644 Syntax:
4645 nodedev-reattach nodedev
4647 Declare that nodedev is no longer in use by any guests, and that the
4649 host can resume normal use of the device. This is done automatically
4650 for PCI devices in managed mode and USB devices, but must be done ex‐
4651 plicitly to match any explicit nodedev-detach.
4652 nodedev-reset
4654 Syntax:
4655 nodedev-reset nodedev
4657 Trigger a device reset for nodedev, useful prior to transferring a node
4659 device between guest passthrough or the host. Libvirt will often do
4660 this action implicitly when required, but this command allows an ex‐
4661 plicit reset when needed.
4662 nodedev-event
4664 Syntax:
4665 nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list}
4667 Wait for a class of node device events to occur, and print appropriate
4669 details of events as they happen. The events can optionally be fil‐
4670 tered by nodedev. Using --list as the only argument will provide a
4671 list of possible event values known by this client, although the con‐
4672 nection might not allow registering for all these events.
4673 By default, this command is one-shot, and returns success once an event
4675 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4676 If --timeout is specified, the command gives up waiting for events af‐
4677 ter seconds have elapsed. With --loop, the command prints all events
4678 until a timeout or interrupt key.
4679 When --timestamp is used, a human-readable timestamp will be printed
4681 before the event.
4682 nodedev-autostart
4684 Syntax:
4685 nodedev-autostart [--disable] device
4687 Configure a device to be automatically started when the host machine
4689 boots or the parent device becomes available. With --disable, the de‐
4690 vice will be set to manual mode and will no longer be automatically
4691 started by the host. This command is only supported for persis‐
4692 tently-defined mediated devices.
4693
4695 The following commands manipulate networks. Libvirt has the capability
4696 to define virtual networks which can then be used by domains and linked
4697 to actual network devices. For more detailed information about this
4698 feature see the documentation at https://libvirt.org/formatnetwork.html
4699 . Many of the commands for virtual networks are similar to the ones
4700 used for domains, but the way to name a virtual network is either by
4701 its name or UUID.
4702 net-autostart
4704 Syntax:
4705 net-autostart network [--disable]
4707 Configure a virtual network to be automatically started at boot. The
4709 --disable option disable autostarting.
4710 net-create
4712 Syntax:
4713 net-create file [--validate]
4715 Create a transient (temporary) virtual network from an XML file and in‐
4717 stantiate (start) the network. See the documentation at
4718 https://libvirt.org/formatnetwork.html to get a description of the XML
4719 network format used by libvirt.
4720 Optionally, the format of the input XML file can be validated against
4722 an internal RNG schema with --validate.
4723 net-define
4725 Syntax:
4726 net-define file [--validate]
4728 Define an inactive persistent virtual network or modify an existing
4730 persistent one from the XML file. Optionally, the format of the input
4731 XML file can be validated against an internal RNG schema with --vali‐
4732 date.
4733 net-destroy
4735 Syntax:
4736 net-destroy network
4738 Destroy (stop) a given transient or persistent virtual network speci‐
4740 fied by its name or UUID. This takes effect immediately.
4741 net-dumpxml
4743 Syntax:
4744 net-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] network
4746 Output the virtual network information as an XML dump to stdout. If
4748 --inactive is specified, then physical functions are not expanded into
4749 their associated virtual functions.
4750 If the --xpath argument provides an XPath expression, it will be evalu‐
4752 ated against the output XML and only those matching nodes will be
4753 printed. The default behaviour is to print each matching node as a
4754 standalone document, however, for ease of additional processing, the
4755 --wrap argument will cause the matching node to be wrapped in a common
4756 root node.
4757 net-edit
4759 Syntax:
4760 net-edit network
4762 Edit the XML configuration file for a network.
4764 This is equivalent to:
4766 virsh net-dumpxml --inactive network > network.xml
4768 vi network.xml (or make changes with your other text editor)
4769 virsh net-define network.xml
4770 except that it does some error checking.
4772 The editor used can be supplied by the $VISUAL or $EDITOR environment
4774 variables, and defaults to vi.
4775 net-event
4777 Syntax:
4778 net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list}
4780 Wait for a class of network events to occur, and print appropriate de‐
4782 tails of events as they happen. The events can optionally be filtered
4783 by network. Using --list as the only argument will provide a list of
4784 possible event values known by this client, although the connection
4785 might not allow registering for all these events.
4786 By default, this command is one-shot, and returns success once an event
4788 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4789 If --timeout is specified, the command gives up waiting for events af‐
4790 ter seconds have elapsed. With --loop, the command prints all events
4791 until a timeout or interrupt key.
4792 When --timestamp is used, a human-readable timestamp will be printed
4794 before the event.
4795 net-info
4797 Syntax:
4798 net-info network
4800 Returns basic information about the network object.
4802 net-list
4804 Syntax:
4805 net-list [--inactive | --all]
4807 { [--table] | --name | --uuid }
4808 [--persistent] [<--transient>]
4809 [--autostart] [<--no-autostart>]
4810 Returns the list of active networks, if --all is specified this will
4812 also include defined but inactive networks, if --inactive is specified
4813 only the inactive ones will be listed. You may also want to filter the
4814 returned networks by --persistent to list the persistent ones, --tran‐
4815 sient to list the transient ones, --autostart to list the ones with au‐
4816 tostart enabled, and --no-autostart to list the ones with autostart
4817 disabled.
4818 If --name is specified, network names are printed instead of the table
4820 formatted one per line. If --uuid is specified network's UUID's are
4821 printed instead of names. Flag --table specifies that the legacy ta‐
4822 ble-formatted output should be used. This is the default. All of these
4823 are mutually exclusive.
4824 NOTE: When talking to older servers, this command is forced to use a
4826 series of API calls with an inherent race, where a pool might not be
4827 listed or might appear more than once if it changed state between calls
4828 while the list was being collected. Newer servers do not have this
4829 problem.
4830 net-name
4832 Syntax:
4833 net-name network-UUID
4835 Convert a network UUID to network name.
4837 net-start
4839 Syntax:
4840 net-start network
4842 Start a (previously defined) inactive network.
4844 net-undefine
4846 Syntax:
4847 net-undefine network
4849 Undefine the configuration for a persistent network. If the network is
4851 active, make it transient.
4852 net-uuid
4854 Syntax:
4855 net-uuid network-name
4857 Convert a network name to network UUID.
4859 net-update
4861 Syntax:
4862 net-update network command section xml
4864 [--parent-index index] [[--live] [--config] | [--current]]
4865 Update the given section of an existing network definition, with the
4867 changes optionally taking effect immediately, without needing to de‐
4868 stroy and re-start the network.
4869 command is one of "add-first", "add-last", "add" (a synonym for
4871 add-last), "delete", or "modify".
4872 section is one of "bridge", "domain", "ip", "ip-dhcp-host",
4874 "ip-dhcp-range", "forward", "forward-interface", "forward-pf", "port‐
4875 group", "dns-host", "dns-txt", or "dns-srv", each section being named
4876 by a concatenation of the xml element hierarchy leading to the element
4877 being changed. For example, "ip-dhcp-host" will change a <host> element
4878 that is contained inside a <dhcp> element inside an <ip> element of the
4879 network.
4880 xml is either the text of a complete xml element of the type being
4882 changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the
4883 name of a file that contains a complete xml element. Disambiguation is
4884 done by looking at the first character of the provided text - if the
4885 first character is "<", it is xml text, if the first character is not
4886 "<", it is the name of a file that contains the xml text to be used.
4887 The --parent-index option is used to specify which of several parent
4889 elements the requested element is in (0-based). For example, a dhcp
4890 <host> element could be in any one of multiple <ip> elements in the
4891 network; if a parent-index isn't provided, the "most appropriate" <ip>
4892 element will be selected (usually the only one that already has a
4893 <dhcp> element), but if --parent-index is given, that particular in‐
4894 stance of <ip> will get the modification.
4895 If --live is specified, affect a running network. If --config is spec‐
4897 ified, affect the next startup of a persistent network. If --current
4898 is specified, it is equivalent to either --live or --config, depending
4899 on the current state of the guest. Both --live and --config flags may
4900 be given, but --current is exclusive. Not specifying any flag is the
4901 same as specifying --current.
4902 net-dhcp-leases
4904 Syntax:
4905 net-dhcp-leases network [mac]
4907 Get a list of dhcp leases for all network interfaces connected to the
4909 given virtual network or limited output just for one interface if mac
4910 is specified.
4911
4913 The following commands manipulate network ports. Libvirt virtual net‐
4914 works have ports created when a virtual machine has a virtual network
4915 interface added. In general there should be no need to use any of the
4916 commands here, since the hypervisor drivers run these commands are the
4917 right point in a virtual machine's lifecycle. They can be useful for
4918 debugging problems and / or recovering from bugs / stale state.
4919 net-port-list
4921 Syntax:
4922 net-port-list { [--table] | --uuid } network
4924 List all network ports recorded against the network.
4926 If --uuid is specified network ports' UUID's are printed instead of a
4928 table. Flag --table specifies that the legacy table-formatted output
4929 should be used. This is the default. All of these are mutually exclu‐
4930 sive.
4931 net-port-create
4933 Syntax:
4934 net-port-create network file [--validate]
4936 Allocate a new network port reserving resources based on the port de‐
4938 scription. Optionally, the format of the input XML file can be vali‐
4939 dated against an internal RNG schema with --validate.
4940 net-port-dumpxml
4942 Syntax:
4943 net-port-dumpxml [--xpath EXPRESSION] [--wrap] network port
4945 Output the network port information as an XML dump to stdout.
4947 If the --xpath argument provides an XPath expression, it will be evalu‐
4949 ated against the output XML and only those matching nodes will be
4950 printed. The default behaviour is to print each matching node as a
4951 standalone document, however, for ease of additional processing, the
4952 --wrap argument will cause the matching node to be wrapped in a common
4953 root node.
4954 net-port-delete
4956 Syntax:
4957 net-port-delete network port
4959 Delete record of the network port and release its resources
4961
4963 The following commands manipulate host interfaces. Often, these host
4964 interfaces can then be used by name within domain <interface> elements
4965 (such as a system-created bridge interface), but there is no require‐
4966 ment that host interfaces be tied to any particular guest configuration
4967 XML at all.
4968 Many of the commands for host interfaces are similar to the ones used
4970 for domains, and the way to name an interface is either by its name or
4971 its MAC address. However, using a MAC address for an iface argument
4972 only works when that address is unique (if an interface and a bridge
4973 share the same MAC address, which is often the case, then using that
4974 MAC address results in an error due to ambiguity, and you must resort
4975 to a name instead).
4976 iface-bridge
4978 Syntax:
4979 iface-bridge interface bridge [--no-stp] [delay] [--no-start]
4981 Create a bridge device named bridge, and attach the existing network
4983 device interface to the new bridge. The new bridge defaults to start‐
4984 ing immediately, with STP enabled and a delay of 0; these settings can
4985 be altered with --no-stp, --no-start, and an integer number of seconds
4986 for delay. All IP address configuration of interface will be moved to
4987 the new bridge device.
4988 See also iface-unbridge for undoing this operation.
4990 iface-define
4992 Syntax:
4993 iface-define file [--validate]
4995 Define an inactive persistent physical host interface or modify an ex‐
4997 isting persistent one from the XML file. Optionally, the format of the
4998 input XML file can be validated against an internal RNG schema with
4999 --validate.
5000 iface-destroy
5002 Syntax:
5003 iface-destroy interface
5005 Destroy (stop) a given host interface, such as by running "if-down" to
5007 disable that interface from active use. This takes effect immediately.
5008 iface-dumpxml
5010 Syntax:
5011 iface-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] interface
5013 Output the host interface information as an XML dump to stdout. If
5015 --inactive is specified, then the output reflects the persistent state
5016 of the interface that will be used the next time it is started.
5017 If the --xpath argument provides an XPath expression, it will be evalu‐
5019 ated against the output XML and only those matching nodes will be
5020 printed. The default behaviour is to print each matching node as a
5021 standalone document, however, for ease of additional processing, the
5022 --wrap argument will cause the matching node to be wrapped in a common
5023 root node.
5024 iface-edit
5026 Syntax:
5027 iface-edit interface
5029 Edit the XML configuration file for a host interface.
5031 This is equivalent to:
5033 virsh iface-dumpxml iface > iface.xml
5035 vi iface.xml (or make changes with your other text editor)
5036 virsh iface-define iface.xml
5037 except that it does some error checking.
5039 The editor used can be supplied by the $VISUAL or $EDITOR environment
5041 variables, and defaults to vi.
5042 iface-list
5044 Syntax:
5045 iface-list [--inactive | --all]
5047 Returns the list of active host interfaces. If --all is specified this
5049 will also include defined but inactive interfaces. If --inactive is
5050 specified only the inactive ones will be listed.
5051 iface-name
5053 Syntax:
5054 iface-name interface
5056 Convert a host interface MAC to interface name, if the MAC address is
5058 unique among the host's interfaces.
5059 interface specifies the interface MAC address.
5061 iface-mac
5063 Syntax:
5064 iface-mac interface
5066 Convert a host interface name to MAC address.
5068 interface specifies the interface name.
5070 iface-start
5072 Syntax:
5073 iface-start interface
5075 Start a (previously defined) host interface, such as by running
5077 "if-up".
5078 iface-unbridge
5080 Syntax:
5081 iface-unbridge bridge [--no-start]
5083 Tear down a bridge device named bridge, releasing its underlying inter‐
5085 face back to normal usage, and moving all IP address configuration from
5086 the bridge device to the underlying device. The underlying interface
5087 is restarted unless --no-start is present; this flag is present for
5088 symmetry, but generally not recommended.
5089 See also iface-bridge for creating a bridge.
5091 iface-undefine
5093 Syntax:
5094 iface-undefine interface
5096 Undefine the configuration for an inactive host interface.
5098 iface-begin
5100 Syntax:
5101 iface-begin
5103 Create a snapshot of current host interface settings, which can later
5105 be committed (iface-commit) or restored (iface-rollback). If a snap‐
5106 shot already exists, then this command will fail until the previous
5107 snapshot has been committed or restored. Undefined behavior results if
5108 any external changes are made to host interfaces outside of the libvirt
5109 API between the beginning of a snapshot and its eventual commit or
5110 rollback.
5111 iface-commit
5113 Syntax:
5114 iface-commit
5116 Declare all changes since the last iface-begin as working, and delete
5118 the rollback point. If no interface snapshot has already been started,
5119 then this command will fail.
5120 iface-rollback
5122 Syntax:
5123 iface-rollback
5125 Revert all host interface settings back to the state recorded in the
5127 last iface-begin. If no interface snapshot has already been started,
5128 then this command will fail. Rebooting the host also serves as an im‐
5129 plicit rollback point.
5130
5132 The following commands manipulate storage pools. Libvirt has the capa‐
5133 bility to manage various storage solutions, including files, raw parti‐
5134 tions, and domain-specific formats, used to provide the storage volumes
5135 visible as devices within virtual machines. For more detailed informa‐
5136 tion about this feature, see the documentation at
5137 https://libvirt.org/formatstorage.html . Many of the commands for pools
5138 are similar to the ones used for domains.
5139 find-storage-pool-sources
5141 Syntax:
5142 find-storage-pool-sources type [srcSpec]
5144 Returns XML describing all possible available storage pool sources that
5146 could be used to create or define a storage pool of a given type. If
5147 srcSpec is provided, it is a file that contains XML to further restrict
5148 the query for pools.
5149 Not all storage pools support discovery in this manner. Furthermore,
5151 for those that do support discovery, only specific XML elements are re‐
5152 quired in order to return valid data, while other elements and even at‐
5153 tributes of some elements are ignored since they are not necessary to
5154 find the pool based on the search criteria. The following lists the
5155 supported type options and the expected minimal XML elements used to
5156 perform the search.
5157 For a "netfs" or "gluster" pool, the minimal expected XML required is
5159 the <host> element with a "name" attribute describing the IP address or
5160 hostname to be used to find the pool. The "port" attribute will be ig‐
5161 nored as will any other provided XML elements in srcSpec.
5162 For a "logical" pool, the contents of the srcSpec file are ignored, al‐
5164 though if provided the file must at least exist.
5165 For an "iscsi" or "iscsi-direct" pool, the minimal expect XML required
5167 is the <host> element with a "name" attribute describing the IP address
5168 or hostname to be used to find the pool (the iSCSI server address). Op‐
5169 tionally, the "port" attribute may be provided, although it will de‐
5170 fault to 3260. Optionally, an <initiator> XML element with a "name" at‐
5171 tribute may be provided to further restrict the iSCSI target search to
5172 a specific initiator for multi-iqn iSCSI storage pools.
5173 find-pool-sources-as
5175 Syntax:
5176 find-storage-pool-sources-as type [host] [port] [initiator]
5178 Rather than providing srcSpec XML file for find-storage-pool-sources
5180 use this command option in order to have virsh generate the query XML
5181 file using the optional arguments. The command will return the same
5182 output XML as find-storage-pool-sources.
5183 Use host to describe a specific host to use for networked storage, such
5185 as netfs, gluster, and iscsi type pools.
5186 Use port to further restrict which networked port to utilize for the
5188 connection if required by the specific storage backend, such as iscsi.
5189 Use initiator to further restrict the iscsi type pool searches to spe‐
5191 cific target initiators.
5192 pool-autostart
5194 Syntax:
5195 pool-autostart pool-or-uuid [--disable]
5197 Configure whether pool should automatically start at boot.
5199 pool-build
5201 Syntax:
5202 pool-build pool-or-uuid [--overwrite] [--no-overwrite]
5204 Build a given pool.
5206 Options --overwrite and --no-overwrite can only be used for pool-build
5208 a filesystem, disk, or logical pool.
5209 For a file system pool if neither flag is specified, then pool-build
5211 just makes the target path directory and no attempt to run mkfs on the
5212 target volume device. If --no-overwrite is specified, it probes to de‐
5213 termine if a filesystem already exists on the target device, returning
5214 an error if one exists or using mkfs to format the target device if
5215 not. If --overwrite is specified, mkfs is always executed and any ex‐
5216 isting data on the target device is overwritten unconditionally.
5217 For a disk pool, if neither of them is specified or --no-overwrite is
5219 specified, pool-build will check the target volume device for existing
5220 filesystems or partitions before attempting to write a new label on the
5221 target volume device. If the target volume device already has a label,
5222 the command will fail. If --overwrite is specified, then no check will
5223 be made on the target volume device prior to writing a new label. Writ‐
5224 ing of the label uses the pool source format type or "dos" if not spec‐
5225 ified.
5226 For a logical pool, if neither of them is specified or --no-overwrite
5228 is specified, pool-build will check the target volume devices for ex‐
5229 isting filesystems or partitions before attempting to initialize and
5230 format each device for usage by the logical pool. If any target volume
5231 device already has a label, the command will fail. If --overwrite is
5232 specified, then no check will be made on the target volume devices
5233 prior to initializing and formatting each device. Once all the target
5234 volume devices are properly formatted via pvcreate, the volume group
5235 will be created using all the devices.
5236 pool-create
5238 Syntax:
5239 pool-create file [--build] [[--overwrite] | [--no-overwrite]]
5241 Create and start a pool object from the XML file.
5243 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
5245 creation in order to remove the need for a follow-up command to build
5246 the pool. The --overwrite and --no-overwrite flags follow the same
5247 rules as pool-build. If just --build is provided, then pool-build is
5248 called with no flags.
5249 pool-create-as
5251 Syntax:
5252 pool-create-as name type
5254 [--source-host hostname] [--source-path path] [--source-dev path]
5255 [--source-name name] [--target path] [--source-format format]
5256 [--source-initiator initiator-iqn]
5257 [--auth-type authtype --auth-username username
5258 [--secret-usage usage | --secret-uuid uuid]]
5259 [--source-protocol-ver ver]
5260 [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn]
5261 [--adapter-parent parent |
5262 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
5263 --adapter-parent-fabric-wwn parent_fabric_wwn]]
5264 [--build] [[--overwrite] | [--no-overwrite]] [--print-xml]
5265 Create and start a pool object name from the raw parameters. If
5267 --print-xml is specified, then print the XML of the pool object without
5268 creating the pool. Otherwise, the pool has the specified type. When
5269 using pool-create-as for a pool of type "disk", the existing partitions
5270 found on the --source-dev path will be used to populate the disk pool.
5271 Therefore, it is suggested to use pool-define-as and pool-build with
5272 the --overwrite in order to properly initialize the disk pool.
5273 [--source-host hostname] provides the source hostname for pools backed
5275 by storage from a remote server (pool types netfs, iscsi, rbd, sheep‐
5276 dog, gluster).
5277 [--source-path path] provides the source directory path for pools
5279 backed by directories (pool type dir).
5280 [--source-dev path] provides the source path for pools backed by physi‐
5282 cal devices (pool types fs, logical, disk, iscsi, zfs).
5283 [--source-name name] provides the source name for pools backed by stor‐
5285 age from a named element (pool types logical, rbd, sheepdog, gluster).
5286 [--target path] is the path for the mapping of the storage pool into
5288 the host file system.
5289 [--source-format format] provides information about the format of the
5291 pool (pool types fs, netfs, disk, logical).
5292 [--source-initiator initiator-iqn] provides the initiator iqn for iscsi
5294 connection of the pool (pool type iscsi-direct).
5295 [--auth-type authtype --auth-username username [--secret-usage usage |
5297 --secret-uuid uuid]] provides the elements required to generate authen‐
5298 tication credentials for the storage pool. The authtype is either chap
5299 for iscsi type pools or ceph for rbd type pools. Either the secret us‐
5300 age or uuid value may be provided, but not both.
5301 [--source-protocol-ver ver] provides the NFS protocol version number
5303 used to contact the server's NFS service via nfs mount option
5304 'nfsvers=n'. It is expect the ver value is an unsigned integer.
5305 [--adapter-name name] defines the scsi_hostN adapter name to be used
5307 for the scsi_host adapter type pool.
5308 [--adapter-wwnn wwnn --adapter-wwpn wwpn [--adapter-parent parent |
5310 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
5311 --adapter-parent-fabric-wwn parent_fabric_wwn]] defines the wwnn and
5312 wwpn to be used for the fc_host adapter type pool. Optionally provide
5313 the parent scsi_hostN node device to be used for the vHBA either by
5314 parent name, parent_wwnn and parent_wwpn, or parent_fabric_wwn. The
5315 parent name could change between reboots if the hardware environment
5316 changes, so providing the parent_wwnn and parent_wwpn ensure usage of
5317 the same physical HBA even if the scsi_hostN node device changes. Usage
5318 of the parent_fabric_wwn allows a bit more flexibility to choose an HBA
5319 on the same storage fabric in order to define the pool.
5320 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
5322 creation in order to remove the need for a follow-up command to build
5323 the pool. The --overwrite and --no-overwrite flags follow the same
5324 rules as pool-build. If just --build is provided, then pool-build is
5325 called with no flags.
5326 For a "logical" pool only [--name] needs to be provided. The
5328 [--source-name] if provided must match the Volume Group name. If not
5329 provided, one will be generated using the [--name]. If provided the
5330 [--target] is ignored and a target source is generated using the
5331 [--source-name] (or as generated from the [--name]).
5332 pool-define
5334 Syntax:
5335 pool-define file [--validate]
5337 Define an inactive persistent storage pool or modify an existing per‐
5339 sistent one from the XML file. Optionally, the format of the input XML
5340 file can be validated against an internal RNG schema with --validate.
5341 pool-define-as
5343 Syntax:
5344 pool-define-as name type
5346 [--source-host hostname] [--source-path path] [--source-dev path]
5347 [*--source-name name*] [*--target path*] [*--source-format format*]
5348 [--source-initiator initiator-iqn]
5349 [*--auth-type authtype* *--auth-username username*
5350 [*--secret-usage usage* | *--secret-uuid uuid*]]
5351 [*--source-protocol-ver ver*]
5352 [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*]
5353 [*--adapter-parent parent*]] [*--print-xml*]
5354 Create, but do not start, a pool object name from the raw parameters.
5356 If --print-xml is specified, then print the XML of the pool object
5357 without defining the pool. Otherwise, the pool has the specified type.
5358 Use the same arguments as pool-create-as, except for the --build,
5360 --overwrite, and --no-overwrite options.
5361 pool-destroy
5363 Syntax:
5364 pool-destroy pool-or-uuid
5366 Destroy (stop) a given pool object. Libvirt will no longer manage the
5368 storage described by the pool object, but the raw data contained in the
5369 pool is not changed, and can be later recovered with pool-create.
5370 pool-delete
5372 Syntax:
5373 pool-delete pool-or-uuid
5375 Destroy the resources used by a given pool object. This operation is
5377 non-recoverable. The pool object will still exist after this command,
5378 ready for the creation of new storage volumes.
5379 pool-dumpxml
5381 Syntax:
5382 pool-dumpxml [--inactive] [--xpath EXPRESSION] [--wrap] pool-or-uuid
5384 Returns the XML information about the pool object. --inactive tells
5386 virsh to dump pool configuration that will be used on next start of the
5387 pool as opposed to the current pool configuration.
5388 If the --xpath argument provides an XPath expression, it will be evalu‐
5390 ated against the output XML and only those matching nodes will be
5391 printed. The default behaviour is to print each matching node as a
5392 standalone document, however, for ease of additional processing, the
5393 --wrap argument will cause the matching node to be wrapped in a common
5394 root node.
5395 pool-edit
5397 Syntax:
5398 pool-edit pool-or-uuid
5400 Edit the XML configuration file for a storage pool.
5402 This is equivalent to:
5404 virsh pool-dumpxml pool > pool.xml
5406 vi pool.xml (or make changes with your other text editor)
5407 virsh pool-define pool.xml
5408 except that it does some error checking.
5410 The editor used can be supplied by the $VISUAL or $EDITOR environment
5412 variables, and defaults to vi.
5413 pool-info
5415 Syntax:
5416 pool-info [--bytes] pool-or-uuid
5418 Returns basic information about the pool object. If --bytes is speci‐
5420 fied the sizes of basic info are not converted to human friendly units.
5421 pool-list
5423 Syntax:
5424 pool-list [--inactive] [--all]
5426 [--persistent] [--transient]
5427 [--autostart] [--no-autostart]
5428 [[--details] [--uuid]
5429 [--name] [<type>]
5430 List pool objects known to libvirt. By default, only active pools are
5432 listed; --inactive lists just the inactive pools, and --all lists all
5433 pools.
5434 In addition, there are several sets of filtering flags. --persistent is
5436 to list the persistent pools, --transient is to list the transient
5437 pools. --autostart lists the autostarting pools, --no-autostart lists
5438 the pools with autostarting disabled. If --uuid is specified only
5439 pool's UUIDs are printed. If --name is specified only pool's names are
5440 printed. If both --name and --uuid are specified, pool's UUID and names
5441 are printed side by side without any header. Option --details is mutu‐
5442 ally exclusive with options --uuid and --name.
5443 You may also want to list pools with specified types using type, the
5445 pool types must be separated by comma, e.g. --type dir,disk. The valid
5446 pool types include 'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi',
5447 'scsi', 'mpath', 'rbd', 'sheepdog', 'gluster', 'zfs', 'vstorage' and
5448 'iscsi-direct'.
5449 The --details option instructs virsh to additionally display pool per‐
5451 sistence and capacity related information where available.
5452 NOTE: When talking to older servers, this command is forced to use a
5454 series of API calls with an inherent race, where a pool might not be
5455 listed or might appear more than once if it changed state between calls
5456 while the list was being collected. Newer servers do not have this
5457 problem.
5458 pool-name
5460 Syntax:
5461 pool-name uuid
5463 Convert the uuid to a pool name.
5465 pool-refresh
5467 Syntax:
5468 pool-refresh pool-or-uuid
5470 Refresh the list of volumes contained in pool.
5472 pool-start
5474 Syntax:
5475 pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]
5477 Start the storage pool, which is previously defined but inactive.
5479 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build prior
5481 to pool-start to ensure the pool environment is in an expected state
5482 rather than needing to run the build command prior to startup. The
5483 --overwrite and --no-overwrite flags follow the same rules as
5484 pool-build. If just --build is provided, then pool-build is called with
5485 no flags.
5486 Note: A storage pool that relies on remote resources such as an "iscsi"
5488 or a (v)HBA backed "scsi" pool may need to be refreshed multiple times
5489 in order to have all the volumes detected (see pool-refresh). This is
5490 because the corresponding volume devices may not be present in the
5491 host's filesystem during the initial pool startup or the current re‐
5492 fresh attempt. The number of refresh retries is dependent upon the net‐
5493 work connection and the time the host takes to export the corresponding
5494 devices.
5495 pool-undefine
5497 Syntax:
5498 pool-undefine pool-or-uuid
5500 Undefine the configuration for an inactive pool.
5502 pool-uuid
5504 Syntax:
5505 pool-uuid pool
5507 Returns the UUID of the named pool.
5509 pool-event
5511 Syntax:
5512 pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list}
5514 Wait for a class of storage pool events to occur, and print appropriate
5516 details of events as they happen. The events can optionally be fil‐
5517 tered by pool. Using --list as the only argument will provide a list
5518 of possible event values known by this client, although the connection
5519 might not allow registering for all these events.
5520 By default, this command is one-shot, and returns success once an event
5522 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
5523 If --timeout is specified, the command gives up waiting for events af‐
5524 ter seconds have elapsed. With --loop, the command prints all events
5525 until a timeout or interrupt key.
5526 When --timestamp is used, a human-readable timestamp will be printed
5528 before the event.
5529
5531 vol-create
5532 Syntax:
5533 vol-create pool-or-uuid FILE [--prealloc-metadata] [--validate]
5535 Create a volume from an XML <file>.
5537 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5539 ume in.
5540 FILE is the XML <file> with the volume definition. An easy way to cre‐
5542 ate the XML <file> is to use the vol-dumpxml command to obtain the def‐
5543 inition of a pre-existing volume.
5544 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5546 don't support full allocation). This option creates a sparse image file
5547 with metadata, resulting in higher performance compared to images with
5548 no preallocation and only slightly higher initial disk space usage.
5549 If --validate is specified, validates the format of the XML document
5551 against an internal RNG schema.
5552 Example:
5554 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
5556 vi newvolume.xml (or make changes with your other text editor)
5557 virsh vol-create differentstoragepool newvolume.xml
5558 vol-create-from
5560 Syntax:
5561 vol-create-from pool-or-uuid FILE vol-name-or-key-or-path
5563 [--inputpool pool-or-uuid] [--prealloc-metadata] [--reflink] [--validate]
5564 Create a volume, using another volume as input.
5566 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5568 ume in.
5569 FILE is the XML <file> with the volume definition.
5571 vol-name-or-key-or-path is the name or key or path of the source vol‐
5573 ume.
5574 --inputpool pool-or-uuid is the name or uuid of the storage pool the
5576 source volume is in.
5577 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5579 don't support full allocation). This option creates a sparse image file
5580 with metadata, resulting in higher performance compared to images with
5581 no preallocation and only slightly higher initial disk space usage.
5582 When --reflink is specified, perform a COW lightweight copy, where the
5584 data blocks are copied only when modified. If this is not possible,
5585 the copy fails.
5586 If --validate is specified, validates the format of the XML document
5588 against an internal RNG schema.
5589 vol-create-as
5591 Syntax:
5592 vol-create-as pool-or-uuid name capacity [--allocation size] [--format string]
5594 [--backing-vol vol-name-or-key-or-path]
5595 [--backing-vol-format string] [--prealloc-metadata] [--print-xml]
5596 Create a volume from a set of arguments unless --print-xml is speci‐
5598 fied, in which case just the XML of the volume object is printed out
5599 without any actual object creation.
5600 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5602 ume in.
5603 name is the name of the new volume. For a disk pool, this must match
5605 the partition name as determined from the pool's source device path and
5606 the next available partition. For example, a source device path of
5607 /dev/sdb and there are no partitions on the disk, then the name must be
5608 sdb1 with the next name being sdb2 and so on.
5609 capacity is the size of the volume to be created, as a scaled integer
5611 (see NOTES above), defaulting to bytes if there is no suffix.
5612 --allocation size is the initial size to be allocated in the volume,
5614 also as a scaled integer defaulting to bytes.
5615 --format string is used in file based storage pools to specify the vol‐
5617 ume file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use ex‐
5618 tended for disk storage pools in order to create an extended partition
5619 (other values are validity checked but not preserved when libvirtd is
5620 restarted or the pool is refreshed).
5621 --backing-vol vol-name-or-key-or-path is the source backing volume to
5623 be used if taking a snapshot of an existing volume.
5624 --backing-vol-format string is the format of the snapshot backing vol‐
5626 ume; raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, how‐
5627 ever, meant for file based storage pools.
5628 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5630 don't support full allocation). This option creates a sparse image file
5631 with metadata, resulting in higher performance compared to images with
5632 no preallocation and only slightly higher initial disk space usage.
5633 vol-clone
5635 Syntax:
5636 vol-clone vol-name-or-key-or-path name
5638 [--pool pool-or-uuid] [--prealloc-metadata] [--reflink] [--print-xml]
5639 Clone an existing volume within the parent pool. Less powerful, but
5641 easier to type, version of vol-create-from.
5642 vol-name-or-key-or-path is the name or key or path of the source vol‐
5644 ume.
5645 name is the name of the new volume.
5647 --pool pool-or-uuid is the name or UUID of the storage pool that con‐
5649 tains the source volume and will contain the new volume. If the source
5650 volume name is provided instead of the key or path, then providing the
5651 pool is necessary to find the volume to be cloned; otherwise, the first
5652 volume found by the key or path will be used.
5653 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5655 don't support full allocation). This option creates a sparse image file
5656 with metadata, resulting in higher performance compared to images with
5657 no preallocation and only slightly higher initial disk space usage.
5658 When --reflink is specified, perform a COW lightweight copy, where the
5660 data blocks are copied only when modified. If this is not possible,
5661 the copy fails.
5662 If --print-xml is specified, then the XML used to clone the volume is
5664 printed instead.
5665 vol-delete
5667 Syntax:
5668 vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots]
5670 Delete a given volume.
5672 vol-name-or-key-or-path is the volume name or key or path of the volume
5674 to delete.
5675 [--pool pool-or-uuid] is the name or UUID of the storage pool the vol‐
5677 ume is in. If the volume name is provided instead of the key or path,
5678 then providing the pool is necessary to find the volume to be deleted;
5679 otherwise, the first volume found by the key or path will be used.
5680 The --delete-snapshots flag specifies that any snapshots associated
5682 with the storage volume should be deleted as well. Not all storage
5683 drivers support this option, presently only rbd.
5684 vol-upload
5686 Syntax:
5687 vol-upload vol-name-or-key-or-path local-file
5689 [--pool pool-or-uuid] [--offset bytes]
5690 [--length bytes] [--sparse]
5691 Upload the contents of local-file to a storage volume.
5693 vol-name-or-key-or-path is the name or key or path of the volume where
5695 the local-file will be uploaded.
5696 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5698 is in. If the volume name is provided instead of the key or path, then
5699 providing the pool is necessary to find the volume to be uploaded into;
5700 otherwise, the first volume found by the key or path will be used.
5701 --offset is the position in the storage volume at which to start writ‐
5703 ing the data. The value must be 0 or larger.
5704 --length is an upper bound of the amount of data to be uploaded. A
5706 negative value is interpreted as an unsigned long long value to essen‐
5707 tially include everything from the offset to the end of the volume.
5708 If --sparse is specified, this command will preserve volume sparseness.
5710 An error will occur if the local-file is greater than the specified
5712 length.
5713 See the description for the libvirt virStorageVolUpload API for details
5715 regarding possible target volume and pool changes as a result of the
5716 pool refresh when the upload is attempted.
5717 vol-download
5719 Syntax:
5720 vol-download vol-name-or-key-or-path local-file
5722 [--pool pool-or-uuid] [--offset bytes] [--length bytes]
5723 [--sparse]
5724 Download the contents of a storage volume to local-file.
5726 vol-name-or-key-or-path is the name or key or path of the volume to
5728 download into local-file.
5729 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5731 is in. If the volume name is provided instead of the key or path, then
5732 providing the pool is necessary to find the volume to be uploaded into;
5733 otherwise, the first volume found by the key or path will be used.
5734 --offset is the position in the storage volume at which to start read‐
5736 ing the data. The value must be 0 or larger.
5737 --length is an upper bound of the amount of data to be downloaded. A
5739 negative value is interpreted as an unsigned long long value to essen‐
5740 tially include everything from the offset to the end of the volume.
5741 If --sparse is specified, this command will preserve volume sparseness.
5743 vol-wipe
5745 Syntax:
5746 vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm]
5748 Wipe a volume, ensure data previously on the volume is not accessible
5750 to future reads.
5751 vol-name-or-key-or-path is the name or key or path of the volume to
5753 wipe. It is possible to choose different wiping algorithms instead of
5754 re-writing volume with zeroes.
5755 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5757 is in. If the volume name is provided instead of the key or path, then
5758 providing the pool is necessary to find the volume to be wiped; other‐
5759 wise, the first volume found by the key or path will be used.
5760 Use the --algorithm switch choosing from the list of the following al‐
5762 gorithms in order to define which algorithm to use for the wipe.
5763 Supported algorithms
5765 • zero - 1-pass all zeroes
5767 • nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for sani‐
5769 tizing removable and non-removable hard disks: random x2, 0x00, ver‐
5770 ify.
5771 • dod - 4-pass DoD 5220.22-M section 8-306 procedure for sani‐
5773 tizing removable and non-removable rigid disks: random, 0x00, 0xff,
5774 verify.
5775 • bsi - 9-pass method recommended by the German Center of Secu‐
5777 rity in Information Technologies (https://www.bsi.bund.de): 0xff,
5778 0xfe, 0xfd, 0xfb, 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
5779 • gutmann - The canonical 35-pass sequence described in Gutmann's
5781 paper.
5782 • schneier - 7-pass method described by Bruce Schneier in "Applied
5784 Cryptography" (1996): 0x00, 0xff, random x5.
5785 • pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7.
5787 • pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
5789 • random - 1-pass pattern: random.
5791 • trim - 1-pass trimming the volume using TRIM or DISCARD
5793 Note: The scrub binary will be used to handle the 'nnsa', 'dod', 'bsi',
5795 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33' algorithms. The
5796 availability of the algorithms may be limited by the version of the
5797 scrub binary installed on the host. The 'zero' algorithm will write ze‐
5798 roes to the entire volume. For some volumes, such as sparse or rbd vol‐
5799 umes, this may result in completely filling the volume with zeroes mak‐
5800 ing it appear to be completely full. As an alternative, the 'trim' al‐
5801 gorithm does not overwrite all the data in a volume, rather it expects
5802 the storage driver to be able to discard all bytes in a volume. It is
5803 up to the storage driver to handle how the discarding occurs. Not all
5804 storage drivers or volume types can support 'trim'.
5805 vol-dumpxml
5807 Syntax:
5808 vol-dumpxml [--pool pool-or-uuid] [--xpath EXPRESSION] [--wrap]
5810 vol-name-or-key-or-path
5811 Output the volume information as an XML dump to stdout.
5813 vol-name-or-key-or-path is the name or key or path of the volume to
5815 output the XML.
5816 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5818 is in. If the volume name is provided instead of the key or path, then
5819 providing the pool is necessary to find the volume to be uploaded into;
5820 otherwise, the first volume found by the key or path will be used.
5821 If the --xpath argument provides an XPath expression, it will be evalu‐
5823 ated against the output XML and only those matching nodes will be
5824 printed. The default behaviour is to print each matching node as a
5825 standalone document, however, for ease of additional processing, the
5826 --wrap argument will cause the matching node to be wrapped in a common
5827 root node.
5828 vol-info
5830 Syntax:
5831 vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical]
5833 Returns basic information about the given storage volume.
5835 vol-name-or-key-or-path is the name or key or path of the volume to re‐
5837 turn information for.
5838 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5840 is in. If the volume name is provided instead of the key or path, then
5841 providing the pool is necessary to find the volume to be uploaded into;
5842 otherwise, the first volume found by the key or path will be used.
5843 If --bytes is specified the sizes are not converted to human friendly
5845 units.
5846 If --physical is specified, then the host physical size is returned and
5848 displayed instead of the allocation value. The physical value for some
5849 file types, such as qcow2 may have a different (larger) physical value
5850 than is shown for allocation. Additionally sparse files will have dif‐
5851 ferent physical and allocation values.
5852 vol-list
5854 Syntax:
5855 vol-list [--pool pool-or-uuid] [--details]
5857 Return the list of volumes in the given storage pool.
5859 --pool pool-or-uuid is the name or UUID of the storage pool.
5861 The --details option instructs virsh to additionally display volume
5863 type and capacity related information where available.
5864 vol-pool
5866 Syntax:
5867 vol-pool vol-key-or-path [--uuid]
5869 Return the pool name or UUID for a given volume. By default, the pool
5871 name is returned.
5872 vol-key-or-path is the key or path of the volume to return the pool in‐
5874 formation.
5875 If the --uuid option is given, the pool UUID is returned instead.
5877 vol-path
5879 Syntax:
5880 vol-path vol-name-or-key [--pool pool-or-uuid]
5882 Return the path for a given volume.
5884 vol-name-or-key is the name or key of the volume to return the path.
5886 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5888 is in. If the volume name is provided instead of the key, then provid‐
5889 ing the pool is necessary to find the volume to be uploaded into; oth‐
5890 erwise, the first volume found by the key will be used.
5891 vol-name
5893 Syntax:
5894 vol-name vol-key-or-path
5896 Return the name for a given volume.
5898 vol-key-or-path is the key or path of the volume to return the name.
5900 vol-key
5902 Syntax:
5903 vol-key vol-name-or-path [--pool pool-or-uuid]
5905 Return the volume key for a given volume.
5907 vol-name-or-path is the name or path of the volume to return the volume
5909 key.
5910 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5912 is in. If the volume name is provided instead of the path, then provid‐
5913 ing the pool is necessary to find the volume to be uploaded into; oth‐
5914 erwise, the first volume found by the path will be used.
5915 vol-resize
5917 Syntax:
5918 vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink]
5920 Resize the capacity of the given volume, in bytes.
5922 vol-name-or-key-or-path is the name or key or path of the volume to re‐
5924 size.
5925 capacity is a scaled integer (see NOTES above) for the volume, which
5927 defaults to bytes if there is no suffix.
5928 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5930 is in. If the volume name is provided instead of the key or path, then
5931 providing the pool is necessary to find the volume to be uploaded into;
5932 otherwise, the first volume found by the key or path will be used.
5933 The new capacity might be sparse unless --allocate is specified.
5935 Normally, capacity is the new size, but if --delta is present, then it
5937 is added to the existing size.
5938 Attempts to shrink the volume will fail unless --shrink is present.
5940 The capacity cannot be negative unless --shrink is provided, but a neg‐
5941 ative sign is not necessary.
5942 This command is only safe for storage volumes not in use by an active
5944 guest; see also blockresize for live resizing.
5945
5947 The following commands manipulate "secrets" (e.g. passwords,
5948 passphrases and encryption keys). Libvirt can store secrets indepen‐
5949 dently from their use, and other objects (e.g. volumes or domains) can
5950 refer to the secrets for encryption or possibly other uses. Secrets
5951 are identified using a UUID. See https://libvirt.org/formatsecret.html
5952 for documentation of the XML format used to represent properties of se‐
5953 crets.
5954 secret-define
5956 Syntax:
5957 secret-define file [--validate]
5959 Create a secret with the properties specified in file, with no associ‐
5961 ated secret value. If file does not specify a UUID, choose one auto‐
5962 matically. If file specifies a UUID of an existing secret, replace its
5963 properties by properties defined in file, without affecting the secret
5964 value.
5965 Optionally, the format of the input XML file can be validated against
5967 an internal RNG schema with --validate.
5968 secret-dumpxml
5970 Syntax:
5971 secret-dumpxml [--xpath EXPRESSION] [--wrap] secret
5973 Output properties of secret (specified by its UUID) as an XML dump to
5975 stdout.
5976 If the --xpath argument provides an XPath expression, it will be evalu‐
5978 ated against the output XML and only those matching nodes will be
5979 printed. The default behaviour is to print each matching node as a
5980 standalone document, however, for ease of additional processing, the
5981 --wrap argument will cause the matching node to be wrapped in a common
5982 root node.
5983 secret-event
5985 Syntax:
5986 secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list}
5988 Wait for a class of secret events to occur, and print appropriate de‐
5990 tails of events as they happen. The events can optionally be filtered
5991 by secret. Using --list as the only argument will provide a list of
5992 possible event values known by this client, although the connection
5993 might not allow registering for all these events.
5994 By default, this command is one-shot, and returns success once an event
5996 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
5997 If --timeout is specified, the command gives up waiting for events af‐
5998 ter seconds have elapsed. With --loop, the command prints all events
5999 until a timeout or interrupt key.
6000 When --timestamp is used, a human-readable timestamp will be printed
6002 before the event.
6003 secret-set-value
6005 Syntax:
6006 secret-set-value secret (--file filename [--plain] | --interactive | base64)
6008 Set the value associated with secret (specified by its UUID) to the
6010 value Base64-encoded value base64 or Base-64-encoded contents of file
6011 named filename. Using the --plain flag is together with --file allows
6012 one to use the file contents directly as the secret value.
6013 If --interactive flag is used the secret value is read as a password
6015 from the terminal.
6016 Note that --file, --interactive and base64 options are mutually exclu‐
6018 sive.
6019 Passing secrets via the base64 option on command line is INSECURE and
6021 deprecated. Use the --file option instead.
6022 secret-get-value
6024 Syntax:
6025 secret-get-value [--plain] secret
6027 Output the value associated with secret (specified by its UUID) to std‐
6029 out, encoded using Base64.
6030 If the --plain flag is used the value is not base64 encoded, but rather
6032 printed raw. Note that unless virsh is started in quiet mode (virsh -q)
6033 it prints a newline at the end of the command. This newline is not part
6034 of the secret.
6035 secret-undefine
6037 Syntax:
6038 secret-undefine secret
6040 Delete a secret (specified by its UUID), including the associated
6042 value, if any.
6043 secret-list
6045 Syntax:
6046 secret-list [--ephemeral] [--no-ephemeral]
6048 [--private] [--no-private]
6049 Returns the list of secrets. You may also want to filter the returned
6051 secrets by --ephemeral to list the ephemeral ones, --no-ephemeral to
6052 list the non-ephemeral ones, --private to list the private ones, and
6053 --no-private to list the non-private ones.
6054
6056 The following commands manipulate domain snapshots. Snapshots take the
6057 disk, memory, and device state of a domain at a point-of-time, and save
6058 it for future use. They have many uses, from saving a "clean" copy of
6059 an OS image to saving a domain's state before a potentially destructive
6060 operation. Snapshots are identified with a unique name. See
6061 https://libvirt.org/formatsnapshot.html for documentation of the XML
6062 format used to represent properties of snapshots.
6063 snapshot-create
6065 Syntax:
6066 snapshot-create domain [xmlfile] {[--redefine [--current]] |
6068 [--no-metadata] [--halt] [--disk-only] [--reuse-external]
6069 [--quiesce] [--atomic] [--live]} [--validate]
6070 Create a snapshot for domain domain with the properties specified in
6072 xmlfile. Optionally, the --validate option can be passed to validate
6073 the format of the input XML file against an internal RNG schema (iden‐
6074 tical to using the virt-xml-validate(1) tool). Normally, the only prop‐
6075 erties settable for a domain snapshot are the <name> and <description>
6076 elements, as well as <disks> if --disk-only is given; the rest of the
6077 fields are ignored, and automatically filled in by libvirt. If xmlfile
6078 is completely omitted, then libvirt will choose a value for all fields.
6079 The new snapshot will become current, as listed by snapshot-current.
6080 If --halt is specified, the domain will be left in an inactive state
6082 after the snapshot is created.
6083 If --disk-only is specified, the snapshot will only include disk con‐
6085 tent rather than the usual full system snapshot with vm state. Disk
6086 snapshots are captured faster than full system snapshots, but reverting
6087 to a disk snapshot may require fsck or journal replays, since it is
6088 like the disk state at the point when the power cord is abruptly
6089 pulled; and mixing --halt and --disk-only loses any data that was not
6090 flushed to disk at the time.
6091 If --redefine is specified, then all XML elements produced by snap‐
6093 shot-dumpxml are valid; this can be used to migrate snapshot hierarchy
6094 from one machine to another, to recreate hierarchy for the case of a
6095 transient domain that goes away and is later recreated with the same
6096 name and UUID, or to make slight alterations in the snapshot metadata
6097 (such as host-specific aspects of the domain XML embedded in the snap‐
6098 shot). When this flag is supplied, the xmlfile argument is mandatory,
6099 and the domain's current snapshot will not be altered unless the --cur‐
6100 rent flag is also given.
6101 If --no-metadata is specified, then the snapshot data is created, but
6103 any metadata is immediately discarded (that is, libvirt does not treat
6104 the snapshot as current, and cannot revert to the snapshot unless --re‐
6105 define is later used to teach libvirt about the metadata again).
6106 If --reuse-external is specified, and the snapshot XML requests an ex‐
6108 ternal snapshot with a destination of an existing file, then the desti‐
6109 nation must exist and be pre-created with correct format and metadata.
6110 The file is then reused; otherwise, a snapshot is refused to avoid los‐
6111 ing contents of the existing files.
6112 If --quiesce is specified, libvirt will try to use guest agent to
6114 freeze and unfreeze domain's mounted file systems. However, if domain
6115 has no guest agent, snapshot creation will fail. Currently, this re‐
6116 quires --disk-only to be passed as well.
6117 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
6119 ther succeeds, or fails with no changes; not all hypervisors support
6120 this. If this flag is not specified, then some hypervisors may fail
6121 after partially performing the action, and dumpxml must be used to see
6122 whether any partial changes occurred.
6123 If --live is specified, libvirt takes the snapshot while the guest is
6125 running. Both disk snapshot and domain memory snapshot are taken. This
6126 increases the size of the memory image of the external snapshot. This
6127 is currently supported only for full system external snapshots.
6128 Existence of snapshot metadata will prevent attempts to undefine a per‐
6130 sistent guest. However, for transient domains, snapshot metadata is
6131 silently lost when the domain quits running (whether by command such as
6132 destroy or by internal guest action).
6133 For now, it is not possible to create snapshots in a domain that has
6135 checkpoints, although this restriction will be lifted in a future re‐
6136 lease.
6137 snapshot-create-as
6139 Syntax:
6140 snapshot-create-as domain {[--print-xml] [--no-metadata]
6142 [--halt] [--reuse-external]} [name]
6143 [description] [--disk-only [--quiesce]] [--atomic] [--validate]
6144 [[--live] [--memspec memspec]] [--diskspec] diskspec]...
6145 Create a snapshot for domain domain with the given <name> and <descrip‐
6147 tion>; if either value is omitted, libvirt will choose a value. If
6148 --print-xml is specified, then XML appropriate for snapshot-create is
6149 output, rather than actually creating a snapshot. Otherwise, if --halt
6150 is specified, the domain will be left in an inactive state after the
6151 snapshot is created, and if --disk-only is specified, the snapshot will
6152 not include vm state.
6153 The --memspec option can be used to control whether a full system snap‐
6155 shot is internal or external. The --memspec flag is mandatory, fol‐
6156 lowed by a memspec of the form [file=]name[,snapshot=type], where type
6157 can be no, internal, or external. To include a literal comma in
6158 file=name, escape it with a second comma. --memspec cannot be used to‐
6159 gether with --disk-only.
6160 The --diskspec option can be used to control how --disk-only and exter‐
6162 nal full system snapshots create external files. This option can occur
6163 multiple times, according to the number of <disk> elements in the do‐
6164 main xml. Each <diskspec> is in the form disk[,snap‐
6165 shot=type][,driver=type][,stype=type][,file=name]. A diskspec must be
6166 provided for disks backed by block devices as libvirt doesn't auto-gen‐
6167 erate file names for those. The optional stype parameter allows one to
6168 control the type of the source file. Supported values are 'file' (de‐
6169 fault) and 'block'. To exclude a disk from an external snapshot use
6170 --diskspec disk,snapshot=no.
6171 To include a literal comma in disk or in file=name, escape it with a
6173 second comma. A literal --diskspec must precede each diskspec unless
6174 all three of domain, name, and description are also present. For exam‐
6175 ple, a diskspec of "vda,snapshot=external,file=/path/to,,new" results
6176 in the following XML:
6177 <disk name='vda' snapshot='external'>
6179 <source file='/path/to,new'/>
6180 </disk>
6181 If --reuse-external is specified, and the domain XML or diskspec option
6183 requests an external snapshot with a destination of an existing file,
6184 then the destination must exist and be pre-created with correct format
6185 and metadata. The file is then reused; otherwise, a snapshot is refused
6186 to avoid losing contents of the existing files.
6187 If --quiesce is specified, libvirt will try to use guest agent to
6189 freeze and unfreeze domain's mounted file systems. However, if domain
6190 has no guest agent, snapshot creation will fail. Currently, this re‐
6191 quires --disk-only to be passed as well.
6192 If --no-metadata is specified, then the snapshot data is created, but
6194 any metadata is immediately discarded (that is, libvirt does not treat
6195 the snapshot as current, and cannot revert to the snapshot unless snap‐
6196 shot-create is later used to teach libvirt about the metadata again).
6197 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
6199 ther succeeds, or fails with no changes; not all hypervisors support
6200 this. If this flag is not specified, then some hypervisors may fail
6201 after partially performing the action, and dumpxml must be used to see
6202 whether any partial changes occurred.
6203 If --live is specified, libvirt takes the snapshot while the guest is
6205 running. This increases the size of the memory image of the external
6206 snapshot. This is currently supported only for external full system
6207 snapshots.
6208 For now, it is not possible to create snapshots in a domain that has
6210 checkpoints, although this restriction will be lifted in a future re‐
6211 lease.
6212 Optionally, the --validate option can be passed to validate XML docu‐
6214 ment which is internally generated by this command against the internal
6215 RNG schema.
6216 snapshot-current
6218 Syntax:
6219 snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
6221 Without snapshotname, this will output the snapshot XML for the do‐
6223 main's current snapshot (if any). If --name is specified, just the
6224 current snapshot name instead of the full xml. Otherwise, using --se‐
6225 curity-info will also include security sensitive information in the
6226 XML.
6227 With snapshotname, this is a request to make the existing named snap‐
6229 shot become the current snapshot, without reverting the domain.
6230 snapshot-edit
6232 Syntax:
6233 snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]}
6235 Edit the XML configuration file for snapshotname of a domain. If both
6237 snapshotname and --current are specified, also force the edited snap‐
6238 shot to become the current snapshot. If snapshotname is omitted, then
6239 --current must be supplied, to edit the current snapshot.
6240 This is equivalent to:
6242 virsh snapshot-dumpxml dom name > snapshot.xml
6244 vi snapshot.xml (or make changes with your other text editor)
6245 virsh snapshot-create dom snapshot.xml --redefine [--current]
6246 except that it does some error checking.
6248 The editor used can be supplied by the $VISUAL or $EDITOR environment
6250 variables, and defaults to vi.
6251 If --rename is specified, then the edits can change the snapshot name.
6253 If --clone is specified, then changing the snapshot name will create a
6254 clone of the snapshot metadata. If neither is specified, then the ed‐
6255 its must not change the snapshot name. Note that changing a snapshot
6256 name must be done with care, since the contents of some snapshots, such
6257 as internal snapshots within a single qcow2 file, are accessible only
6258 from the original name.
6259 snapshot-info
6261 Syntax:
6262 snapshot-info domain {snapshot | --current}
6264 Output basic information about a named <snapshot>, or the current snap‐
6266 shot with --current.
6267 snapshot-list
6269 Syntax:
6270 snapshot-list domain [--metadata] [--no-metadata]
6272 [{--parent | --roots | [{--tree | --name}]}] [--topological]
6273 [{[--from] snapshot | --current} [--descendants]]
6274 [--leaves] [--no-leaves] [--inactive] [--active]
6275 [--disk-only] [--internal] [--external]
6276 List all of the available snapshots for the given domain, defaulting to
6278 show columns for the snapshot name, creation time, and domain state.
6279 Normally, table form output is sorted by snapshot name; using --topo‐
6281 logical instead sorts so that no child is listed before its ancestors
6282 (although there may be more than one possible ordering with this prop‐
6283 erty).
6284 If --parent is specified, add a column to the output table giving the
6286 name of the parent of each snapshot. If --roots is specified, the list
6287 will be filtered to just snapshots that have no parents. If --tree is
6288 specified, the output will be in a tree format, listing just snapshot
6289 names. These three options are mutually exclusive. If --name is speci‐
6290 fied only the snapshot name is printed. This option is mutually exclu‐
6291 sive with --tree.
6292 If --from is provided, filter the list to snapshots which are children
6294 of the given snapshot; or if --current is provided, start at the cur‐
6295 rent snapshot. When used in isolation or with --parent, the list is
6296 limited to direct children unless --descendants is also present. When
6297 used with --tree, the use of --descendants is implied. This option is
6298 not compatible with --roots. Note that the starting point of --from or
6299 --current is not included in the list unless the --tree option is also
6300 present.
6301 If --leaves is specified, the list will be filtered to just snapshots
6303 that have no children. Likewise, if --no-leaves is specified, the list
6304 will be filtered to just snapshots with children. (Note that omitting
6305 both options does no filtering, while providing both options will ei‐
6306 ther produce the same list or error out depending on whether the server
6307 recognizes the flags). Filtering options are not compatible with
6308 --tree.
6309 If --metadata is specified, the list will be filtered to just snapshots
6311 that involve libvirt metadata, and thus would prevent undefine of a
6312 persistent guest, or be lost on destroy of a transient domain. Like‐
6313 wise, if --no-metadata is specified, the list will be filtered to just
6314 snapshots that exist without the need for libvirt metadata.
6315 If --inactive is specified, the list will be filtered to snapshots that
6317 were taken when the domain was shut off. If --active is specified, the
6318 list will be filtered to snapshots that were taken when the domain was
6319 running, and where the snapshot includes the memory state to revert to
6320 that running state. If --disk-only is specified, the list will be fil‐
6321 tered to snapshots that were taken when the domain was running, but
6322 where the snapshot includes only disk state.
6323 If --internal is specified, the list will be filtered to snapshots that
6325 use internal storage of existing disk images. If --external is speci‐
6326 fied, the list will be filtered to snapshots that use external files
6327 for disk images or memory state.
6328 snapshot-dumpxml
6330 Syntax:
6331 snapshot-dumpxml [--security-info] [--xpath EXPRESSION] [--wrap]
6333 domain snapshot
6334 Output the snapshot XML for the domain's snapshot named snapshot. Us‐
6336 ing --security-info will also include security sensitive information.
6337 Use snapshot-current to easily access the XML of the current snapshot.
6338 If the --xpath argument provides an XPath expression, it will be evalu‐
6340 ated against the output XML and only those matching nodes will be
6341 printed. The default behaviour is to print each matching node as a
6342 standalone document, however, for ease of additional processing, the
6343 --wrap argument will cause the matching node to be wrapped in a common
6344 root node.
6345 snapshot-parent
6347 Syntax:
6348 snapshot-parent domain {snapshot | --current}
6350 Output the name of the parent snapshot, if any, for the given snapshot,
6352 or for the current snapshot with --current.
6353 snapshot-revert
6355 Syntax:
6356 snapshot-revert domain {snapshot | --current} [{--running | --paused}]
6358 [--force] [--reset-nvram]
6359 Revert the given domain to the snapshot specified by snapshot, or to
6361 the current snapshot with --current. Be aware that this is a destruc‐
6362 tive action; any changes in the domain since the last snapshot was
6363 taken will be lost. Also note that the state of the domain after snap‐
6364 shot-revert is complete will be the state of the domain at the time the
6365 original snapshot was taken.
6366 Normally, reverting to a snapshot leaves the domain in the state it was
6368 at the time the snapshot was created, except that a disk snapshot with
6369 no vm state leaves the domain in an inactive state. Passing either the
6370 --running or --paused flag will perform additional state changes (such
6371 as booting an inactive domain, or pausing a running domain). Since
6372 transient domains cannot be inactive, it is required to use one of
6373 these flags when reverting to a disk snapshot of a transient domain.
6374 Since libvirt 7.10.0 the VM process is always restarted so the follow‐
6376 ing paragraph is no longer valid. If the snapshot metadata lacks the
6377 full VM XML it's no longer possible to revert to such snapshot.
6378 There are a number of cases where a snapshot revert involves extra
6380 risk, which requires the use of --force to proceed:
6381 • One is the case of a snapshot that lacks full domain information
6383 for reverting configuration (such as snapshots created prior to
6384 libvirt 0.9.5); since libvirt cannot prove that the current con‐
6385 figuration matches what was in use at the time of the snapshot,
6386 supplying --force assures libvirt that the snapshot is compatible
6387 with the current configuration (and if it is not, the domain will
6388 likely fail to run).
6389 • Another is the case of reverting from a running domain to an ac‐
6391 tive state where a new hypervisor has to be created rather than
6392 reusing the existing hypervisor, because it implies drawbacks such
6393 as breaking any existing VNC or Spice connections; this condition
6394 happens with an active snapshot that uses a provably incompatible
6395 configuration, as well as with an inactive snapshot that is com‐
6396 bined with the --start or --pause flag.
6397 • Also, libvirt will refuse to restore snapshots of inactive QEMU
6399 domains while there is managed saved state. This is because those
6400 snapshots do not contain memory state and will therefore not re‐
6401 place the existing memory state. This ends up switching a disk un‐
6402 derneath a running system and will likely cause extensive filesys‐
6403 tem corruption or crashes due to swap content mismatches when run.
6404 If --reset-nvram is specified, any existing NVRAM file will be deleted
6406 and re-initialized from its pristine template.
6407 snapshot-delete
6409 Syntax:
6410 snapshot-delete domain {snapshot | --current}
6412 [--metadata] [{--children | --children-only}]
6413 Delete the snapshot for the domain named snapshot, or the current snap‐
6415 shot with --current. If this snapshot has child snapshots, changes
6416 from this snapshot will be merged into the children. If --children is
6417 passed, then delete this snapshot and any children of this snapshot.
6418 If --children-only is passed, then delete any children of this snap‐
6419 shot, but leave this snapshot intact. These two flags are mutually ex‐
6420 clusive.
6421 If --metadata is specified, then only delete the snapshot metadata
6423 maintained by libvirt, while leaving the snapshot contents intact for
6424 access by external tools; otherwise deleting a snapshot also removes
6425 the data contents from that point in time.
6426
6428 The following commands manipulate domain checkpoints. Checkpoints
6429 serve as a point in time to identify which portions of a guest's disks
6430 have changed after that time, making it possible to perform incremental
6431 and differential backups. Checkpoints are identified with a unique
6432 name. See https://libvirt.org/formatcheckpoint.html for documentation
6433 of the XML format used to represent properties of checkpoints.
6434 checkpoint-create
6436 Syntax:
6437 checkpoint-create domain [xmlfile] { --redefine [--redefine-validate] | [--quiesce]}
6439 Create a checkpoint for domain domain with the properties specified in
6441 xmlfile describing a <domaincheckpoint> top-level element. The format
6442 of the input XML file will be validated against an internal RNG schema
6443 (identical to using the virt-xml-validate(1) tool). If xmlfile is com‐
6444 pletely omitted, then libvirt will create a checkpoint with a name
6445 based on the current time.
6446 If --redefine is specified, then all XML elements produced by check‐
6448 point-dumpxml are valid; this can be used to migrate checkpoint hierar‐
6449 chy from one machine to another, to recreate hierarchy for the case of
6450 a transient domain that goes away and is later recreated with the same
6451 name and UUID, or to make slight alterations in the checkpoint metadata
6452 (such as host-specific aspects of the domain XML embedded in the check‐
6453 point). When this flag is supplied, the xmlfile argument is mandatory.
6454 If --redefine-validate is specified along with --redefine the hypervi‐
6456 sor performs validation of metadata associated with the checkpoint
6457 stored in places besides the checkpoint XML. Note that some hypervisors
6458 may require that the domain is running to perform validation.
6459 If --quiesce is specified, libvirt will try to use guest agent to
6461 freeze and unfreeze domain's mounted file systems. However, if domain
6462 has no guest agent, checkpoint creation will fail.
6463 Existence of checkpoint metadata will prevent attempts to undefine a
6465 persistent guest. However, for transient domains, checkpoint metadata
6466 is silently lost when the domain quits running (whether by command such
6467 as destroy or by internal guest action).
6468 For now, it is not possible to create checkpoints in a domain that has
6470 snapshots, although this restriction will be lifted in a future re‐
6471 lease.
6472 checkpoint-create-as
6474 Syntax:
6475 checkpoint-create-as domain [--print-xml] [name]
6477 [description] [--quiesce] [--diskspec] diskspec]...
6478 Create a checkpoint for domain domain with the given <name> and <de‐
6480 scription>; if either value is omitted, libvirt will choose a value.
6481 If --print-xml is specified, then XML appropriate for checkpoint-create
6482 is output, rather than actually creating a checkpoint.
6483 The --diskspec option can be used to control which guest disks partici‐
6485 pate in the checkpoint. This option can occur multiple times, according
6486 to the number of <disk> elements in the domain xml. Each <diskspec> is
6487 in the form disk[,checkpoint=type][,bitmap=name]. A literal --diskspec
6488 must precede each diskspec unless all three of domain, name, and de‐
6489 scription are also present. For example, a diskspec of "vda,check‐
6490 point=bitmap,bitmap=map1" results in the following XML:
6491 <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
6493 If --quiesce is specified, libvirt will try to use guest agent to
6495 freeze and unfreeze domain's mounted file systems. However, if domain
6496 has no guest agent, checkpoint creation will fail.
6497 For now, it is not possible to create checkpoints in a domain that has
6499 snapshots, although this restriction will be lifted in a future re‐
6500 lease.
6501 checkpoint-edit
6503 Syntax:
6504 checkpoint-edit domain checkpointname
6506 Edit the XML configuration file for checkpointname of a domain.
6508 This is equivalent to:
6510 virsh checkpoint-dumpxml dom name > checkpoint.xml
6512 vi checkpoint.xml (or make changes with your other text editor)
6513 virsh checkpoint-create dom checkpoint.xml --redefine
6514 except that it does some error checking, including that the edits
6516 should not attempt to change the checkpoint name.
6517 The editor used can be supplied by the $VISUAL or $EDITOR environment
6519 variables, and defaults to vi.
6520 checkpoint-info
6522 Syntax:
6523 checkpoint-info domain checkpoint
6525 Output basic information about a named <checkpoint>.
6527 checkpoint-list
6529 Syntax:
6530 checkpoint-list domain [{--parent | --roots |
6532 [{--tree | --name}]}] [--topological]
6533 [[--from] checkpoint | [--descendants]]
6534 [--leaves] [--no-leaves]
6535 List all of the available checkpoints for the given domain, defaulting
6537 to show columns for the checkpoint name and creation time.
6538 Normally, table form output is sorted by checkpoint name; using --topo‐
6540 logical instead sorts so that no child is listed before its ancestors
6541 (although there may be more than one possible ordering with this prop‐
6542 erty).
6543 If --parent is specified, add a column to the output table giving the
6545 name of the parent of each checkpoint. If --roots is specified, the
6546 list will be filtered to just checkpoints that have no parents. If
6547 --tree is specified, the output will be in a tree format, listing just
6548 checkpoint names. These three options are mutually exclusive. If
6549 --name is specified only the checkpoint name is printed. This option is
6550 mutually exclusive with --tree.
6551 If --from is provided, filter the list to checkpoints which are chil‐
6553 dren of the given checkpoint. When used in isolation or with --parent,
6554 the list is limited to direct children unless --descendants is also
6555 present. When used with --tree, the use of --descendants is implied.
6556 This option is not compatible with --roots. Note that the starting
6557 point of --from is not included in the list unless the --tree option is
6558 also present.
6559 If --leaves is specified, the list will be filtered to just checkpoints
6561 that have no children. Likewise, if --no-leaves is specified, the list
6562 will be filtered to just checkpoints with children. (Note that omit‐
6563 ting both options does no filtering, while providing both options will
6564 either produce the same list or error out depending on whether the
6565 server recognizes the flags). Filtering options are not compatible
6566 with --tree.
6567 checkpoint-dumpxml
6569 Syntax:
6570 checkpoint-dumpxml [--security-info] [--no-domain] [--size]
6572 [--xpath EXPRESSION] [--wrap] domain checkpoint
6573 Output the checkpoint XML for the domain's checkpoint named checkpoint.
6575 Using --security-info will also include security sensitive information.
6576 Using --size will add XML indicating the current size in bytes of guest
6578 data that has changed since the checkpoint was created (although remem‐
6579 ber that guest activity between a size check and actually creating a
6580 backup can result in the backup needing slightly more space). Note that
6581 some hypervisors may require that domain is running when --size is
6582 used.
6583 Using --no-domain will omit the <domain> element from the output for a
6585 more compact view.
6586 If the --xpath argument provides an XPath expression, it will be evalu‐
6588 ated against the output XML and only those matching nodes will be
6589 printed. The default behaviour is to print each matching node as a
6590 standalone document, however, for ease of additional processing, the
6591 --wrap argument will cause the matching node to be wrapped in a common
6592 root node.
6593 checkpoint-parent
6595 Syntax:
6596 checkpoint-parent domain checkpoint
6598 Output the name of the parent checkpoint, if any, for the given check‐
6600 point.
6601 checkpoint-delete
6603 Syntax:
6604 checkpoint-delete domain checkpoint
6606 [--metadata] [{--children | --children-only}]
6607 Delete the checkpoint for the domain named checkpoint. The record of
6609 which portions of the disk changed since the checkpoint are merged into
6610 the parent checkpoint (if any). If --children is passed, then delete
6611 this checkpoint and any children of this checkpoint. If --chil‐
6612 dren-only is passed, then delete any children of this checkpoint, but
6613 leave this checkpoint intact. These two flags are mutually exclusive.
6614 If --metadata is specified, then only delete the checkpoint metadata
6616 maintained by libvirt, while leaving the checkpoint contents intact for
6617 access by external tools; otherwise deleting a checkpoint also removes
6618 the ability to perform an incremental backup from that point in time.
6619
6621 The following commands manipulate network filters. Network filters al‐
6622 low filtering of the network traffic coming from and going to virtual
6623 machines. Individual network traffic filters are written in XML and
6624 may contain references to other network filters, describe traffic fil‐
6625 tering rules, or contain both. Network filters are referenced by vir‐
6626 tual machines from within their interface description. A network filter
6627 may be referenced by multiple virtual machines' interfaces.
6628 nwfilter-define
6630 Syntax:
6631 nwfilter-define xmlfile [--validate]
6633 Make a new network filter known to libvirt. If a network filter with
6635 the same name already exists, it will be replaced with the new XML.
6636 Any running virtual machine referencing this network filter will have
6637 its network traffic rules adapted. If for any reason the network traf‐
6638 fic filtering rules cannot be instantiated by any of the running vir‐
6639 tual machines, then the new XML will be rejected.
6640 Optionally, the format of the input XML file can be validated against
6642 an internal RNG schema with --validate.
6643 nwfilter-undefine
6645 Syntax:
6646 nwfilter-undefine nwfilter-name
6648 Delete a network filter. The deletion will fail if any running virtual
6650 machine is currently using this network filter.
6651 nwfilter-list
6653 Syntax:
6654 nwfilter-list
6656 List all of the available network filters.
6658 nwfilter-dumpxml
6660 Syntax:
6661 nwfilter-dumpxml [--xpath EXPRESSION] [--wrap] nwfilter-name
6663 Output the network filter XML.
6665 If the --xpath argument provides an XPath expression, it will be evalu‐
6667 ated against the output XML and only those matching nodes will be
6668 printed. The default behaviour is to print each matching node as a
6669 standalone document, however, for ease of additional processing, the
6670 --wrap argument will cause the matching node to be wrapped in a common
6671 root node.
6672 nwfilter-edit
6674 Syntax:
6675 nwfilter-edit nwfilter-name
6677 Edit the XML of a network filter.
6679 This is equivalent to:
6681 virsh nwfilter-dumpxml myfilter > myfilter.xml
6683 vi myfilter.xml (or make changes with your other text editor)
6684 virsh nwfilter-define myfilter.xml
6685 except that it does some error checking. The new network filter may be
6687 rejected due to the same reason as mentioned in nwfilter-define.
6688 The editor used can be supplied by the $VISUAL or $EDITOR environment
6690 variables, and defaults to vi.
6691
6693 The following commands manipulate network filter bindings. Network fil‐
6694 ter bindings track the association between a network port and a network
6695 filter. Generally the bindings are managed automatically by the hyper‐
6696 visor drivers when adding/removing NICs on a guest.
6697 If an admin is creating/deleting TAP devices for non-guest usage, how‐
6699 ever, the network filter binding commands provide a way to make use of
6700 the network filters directly.
6701 nwfilter-binding-create
6703 Syntax:
6704 nwfilter-binding-create xmlfile [--validate]
6706 Associate a network port with a network filter. The network filter
6708 backend will immediately attempt to instantiate the filter rules on the
6709 port. This command may be used to associate a filter with a currently
6710 running guest that does not have a filter defined for a specific net‐
6711 work port. Since the bindings are generally automatically managed by
6712 the hypervisor, using this command to define a filter for a network
6713 port and then starting the guest afterwards may prevent the guest from
6714 starting if it attempts to use the network port and finds a filter al‐
6715 ready defined.
6716 Optionally, the format of the input XML file can be validated against
6718 an internal RNG schema with --validate.
6719 nwfilter-binding-delete
6721 Syntax:
6722 nwfilter-binding-delete port-name
6724 Disassociate a network port from a network filter. The network filter
6726 backend will immediately tear down the filter rules that exist on the
6727 port. This command may be used to remove the network port binding for a
6728 filter currently in use for the guest while the guest is running with‐
6729 out needing to restart the guest. Restoring the network port binding
6730 filter for the running guest would be accomplished by using nwfil‐
6731 ter-binding-create.
6732 nwfilter-binding-list
6734 Syntax:
6735 nwfilter-binding-list
6737 List all of the network ports which have filters associated with them.
6739 nwfilter-binding-dumpxml
6741 Syntax:
6742 nwfilter-binding-dumpxml [--xpath EXPRESSION] [--wrap] port-name
6744 Output the network filter binding XML for the network device called
6746 port-name.
6747 If the --xpath argument provides an XPath expression, it will be evalu‐
6749 ated against the output XML and only those matching nodes will be
6750 printed. The default behaviour is to print each matching node as a
6751 standalone document, however, for ease of additional processing, the
6752 --wrap argument will cause the matching node to be wrapped in a common
6753 root node.
6754
6756 NOTE: Use of the following commands is strongly discouraged. They can
6757 cause libvirt to become confused and do the wrong thing on subsequent
6758 operations. Once you have used these commands, please do not report
6759 problems to the libvirt developers; the reports will be ignored. If
6760 you find that these commands are the only way to accomplish something,
6761 then it is better to request that the feature be added as a first-class
6762 citizen in the regular libvirt library.
6763 qemu-attach
6765 Syntax:
6766 qemu-attach pid
6768 Attach an externally launched QEMU process to the libvirt QEMU driver.
6770 The QEMU process must have been created with a monitor connection using
6771 the UNIX driver. Ideally the process will also have had the '-name' ar‐
6772 gument specified.
6773 $ qemu-kvm -cdrom ~/demo.iso \
6775 -monitor unix:/tmp/demo,server,nowait \
6776 -name foo \
6777 -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea &
6778 $ QEMUPID=$!
6779 $ virsh qemu-attach $QEMUPID
6780 Not all functions of libvirt are expected to work reliably after at‐
6782 taching to an externally launched QEMU process. There may be issues
6783 with the guest ABI changing upon migration and device hotplug or hotun‐
6784 plug may not work. The attached environment should be considered pri‐
6785 marily read-only.
6786 qemu-monitor-command
6788 Syntax:
6789 qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] }
6791 [--pass-fds N,M,...] command...
6792 Send an arbitrary monitor command command to domain domain through the
6794 QEMU monitor. The results of the command will be printed on stdout.
6795 If more than one argument is provided for command, they are concate‐
6797 nated with a space in between before passing the single command to the
6798 monitor.
6799 Note that libvirt uses the QMP to talk to qemu so command must be valid
6801 JSON in QMP format to work properly. If command is not a JSON object
6802 libvirt tries to wrap it as a JSON object to provide convenient inter‐
6803 face such as the groups of commands with identical handling:
6804 # simple command
6806 $ virsh qemu-monitor-command VM commandname
6807 $ virsh qemu-monitor-command VM '{"execute":"commandname"}'
6808 # with arguments
6810 $ virsh qemu-monitor-command VM commandname '"arg1":123' '"arg2":"test"'
6811 $ virsh qemu-monitor-command VM commandname '{"arg1":123,"arg2":"test"}'
6812 $ virsh qemu-monitor-command VM '{"execute":"commandname", "arguments":{"arg1":123,"arg2":"test"}}'
6813 If --pretty is given the QMP reply is pretty-printed.
6815 If --return-value is given the 'return' key of the QMP response object
6817 is extracted rather than passing through the full reply from QEMU.
6818 If --hmp is passed, the command is considered to be a human monitor
6820 command and libvirt will automatically convert it into QMP and convert
6821 the result back.
6822 If --pass-fds is specified, the argument is a comma separated list of
6824 open file descriptors which should be passed on to qemu along with the
6825 command.
6826 qemu-agent-command
6828 Syntax:
6829 qemu-agent-command domain [--timeout seconds | --async | --block] command...
6831 Send an arbitrary guest agent command command to domain domain through
6833 QEMU agent. --timeout, --async and --block options are exclusive.
6834 --timeout requires timeout seconds seconds and it must be positive.
6835 When --aysnc is given, the command waits for timeout whether success or
6836 failed. And when --block is given, the command waits forever with
6837 blocking timeout.
6838 qemu-monitor-event
6840 Syntax:
6841 qemu-monitor-event [domain] [--event event-name]
6843 [--loop] [--timeout seconds] [--pretty] [--regex] [--no-case]
6844 [--timestamp]
6845 Wait for arbitrary QEMU monitor events to occur, and print out the de‐
6847 tails of events as they happen. The events can optionally be filtered
6848 by domain or event-name. The 'query-events' QMP command can be used
6849 via qemu-monitor-command to learn what events are supported. If
6850 --regex is used, event-name is a basic regular expression instead of a
6851 literal string. If --no-case is used, event-name will match case-in‐
6852 sensitively.
6853 By default, this command is one-shot, and returns success once an event
6855 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
6856 If --timeout is specified, the command gives up waiting for events af‐
6857 ter seconds have elapsed. With --loop, the command prints all events
6858 until a timeout or interrupt key. If --pretty is specified, any JSON
6859 event details are pretty-printed for better legibility.
6860 When --timestamp is used, a human-readable timestamp will be printed
6862 before the event, and the timing information provided by QEMU will be
6863 omitted.
6864 lxc-enter-namespace
6866 Syntax:
6867 lxc-enter-namespace domain [--noseclabel] --
6869 /path/to/binary [arg1, [arg2, ...]]
6870 Enter the namespace of domain and execute the command /path/to/binary
6872 passing the requested args. The binary path is relative to the con‐
6873 tainer root filesystem, not the host root filesystem. The binary will
6874 inherit the environment variables / console visible to virsh. The com‐
6875 mand will be run with the same sVirt context and cgroups placement as
6876 processes within the container. This command only works when connected
6877 to the LXC hypervisor driver. This command succeeds only if
6878 /path/to/binary has 0 exit status.
6879 By default the new process will run with the security label of the new
6881 parent container. Use the --noseclabel option to instead have the
6882 process keep the same security label as virsh.
6883
6885 The following environment variables can be set to alter the behaviour
6886 of virsh
6887 • VIRSH_DEBUG=<0 to 4>
6889 Turn on verbose debugging of virsh commands. Valid levels are
6891 • VIRSH_DEBUG=0
6893 DEBUG - Messages at ALL levels get logged
6895 • VIRSH_DEBUG=1
6897 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
6899 • VIRSH_DEBUG=2
6901 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
6903 • VIRSH_DEBUG=3
6905 WARNING - Logs messages at levels WARNING and ERROR
6907 • VIRSH_DEBUG=4
6909 ERROR - Messages at only ERROR level gets logged.
6911 • VIRSH_LOG_FILE=``LOGFILE``
6913 The file to log virsh debug messages.
6915 • VIRSH_DEFAULT_CONNECT_URI
6917 The hypervisor to connect to by default. Set this to a URI, in the
6919 same format as accepted by the connect option. This environment vari‐
6920 able is deprecated in favour of the global LIBVIRT_DEFAULT_URI vari‐
6921 able which serves the same purpose.
6922 • LIBVIRT_DEFAULT_URI
6924 The hypervisor to connect to by default. Set this to a URI, in the
6926 same format as accepted by the connect option. This overrides the de‐
6927 fault URI set in any client config file and prevents libvirt from
6928 probing for drivers.
6929 • VISUAL
6931 The editor to use by the edit and related options.
6933 • EDITOR
6935 The editor to use by the edit and related options, if VISUAL is not
6937 set.
6938 • VIRSH_HISTSIZE
6940 The number of commands to remember in the command history. The de‐
6942 fault value is 500.
6943 • LIBVIRT_DEBUG=LEVEL
6945 Turn on verbose debugging of all libvirt API calls. Valid levels are
6947 • LIBVIRT_DEBUG=1
6949 Messages at level DEBUG or above
6951 • LIBVIRT_DEBUG=2
6953 Messages at level INFO or above
6955 • LIBVIRT_DEBUG=3
6957 Messages at level WARNING or above
6959 • LIBVIRT_DEBUG=4
6961 Messages at level ERROR
6963 For further information about debugging options consult
6965 https://libvirt.org/logging.html
6966
6968 Please report all bugs you discover. This should be done via either:
6969 1. the mailing list
6971 https://libvirt.org/contact.html
6973 2. the bug tracker
6975 https://libvirt.org/bugs.html
6977 Alternatively, you may report bugs to your software distributor / ven‐
6979 dor.
6980
6982 Please refer to the AUTHORS file distributed with libvirt.
6983
6985 Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in
6986 the libvirt AUTHORS file.
6987
6989 virsh is distributed under the terms of the GNU LGPL v2+. This is free
6990 software; see the source for copying conditions. There is NO warranty;
6991 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
6992
6994 virt-install(1), virt-xml-validate(1), virt-top(1), virt-df(1),
6995 https://libvirt.org/
6996 VIRSH(1)