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 nodesuspend
354 Syntax:
355 nodesuspend [target] [duration]
357 Puts the node (host machine) into a system-wide sleep state and sched‐
359 ule the node's Real-Time-Clock interrupt to resume the node after the
360 time duration specified by duration is out. target specifies the state
361 to which the host will be suspended to, it can be "mem" (suspend to
362 RAM), "disk" (suspend to disk), or "hybrid" (suspend to both RAM and
363 disk). duration specifies the time duration in seconds for which the
364 host has to be suspended, it should be at least 60 seconds.
365 node-memory-tune
367 Syntax:
368 node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs] [shm-merge-across-nodes]
370 Allows you to display or set the node memory parameters.
372 shm-pages-to-scan can be used to set the number of pages to scan before
373 the shared memory service goes to sleep; shm-sleep-millisecs can be
374 used to set the number of millisecs the shared memory service should
375 sleep before next scan; shm-merge-across-nodes specifies if pages from
376 different numa nodes can be merged. When set to 0, only pages which
377 physically reside in the memory area of same NUMA node can be merged.
378 When set to 1, pages from all nodes can be merged. Default to 1.
379 Note: Currently the "shared memory service" only means KSM (Kernel
381 Samepage Merging).
382 capabilities
384 Syntax:
385 capabilities
387 Print an XML document describing the capabilities of the hypervisor we
389 are currently connected to. This includes a section on the host capa‐
390 bilities in terms of CPU and features, and a set of description for
391 each kind of guest which can be virtualized. For a more complete de‐
392 scription see:
393 https://libvirt.org/formatcaps.html
395 The XML also show the NUMA topology information if available.
397 domcapabilities
399 Syntax:
400 domcapabilities [virttype] [emulatorbin] [arch] [machine]
402 Print an XML document describing the domain capabilities for the hyper‐
404 visor we are connected to using information either sourced from an ex‐
405 isting domain or taken from the virsh capabilities output. This may be
406 useful if you intend to create a new domain and are curious if for in‐
407 stance it could make use of VFIO by creating a domain for the hypervi‐
408 sor with a specific emulator and architecture.
409 Each hypervisor will have different requirements regarding which op‐
411 tions are required and which are optional. A hypervisor can support
412 providing a default value for any of the options.
413 The virttype option specifies the virtualization type used. The value
415 to be used is either from the 'type' attribute of the <domain/> top
416 level element from the domain XML or the 'type' attribute found within
417 each <guest/> element from the virsh capabilities output. The emula‐
418 torbin option specifies the path to the emulator. The value to be used
419 is either the <emulator> element in the domain XML or the virsh capa‐
420 bilities output. The arch option specifies the architecture to be used
421 for the domain. The value to be used is either the "arch" attribute
422 from the domain's XML <os/> element and <type/> subelement or the
423 "name" attribute of an <arch/> element from the virsh capabililites
424 output. The machine specifies the machine type for the emulator. The
425 value to be used is either the "machine" attribute from the domain's
426 XML <os/> element and <type/> subelement or one from a list of machines
427 from the virsh capabilities output for a specific architecture and do‐
428 main type.
429 For the QEMU hypervisor, a virttype of either 'qemu' or 'kvm' must be
431 supplied along with either the emulatorbin or arch in order to generate
432 output for the default machine. Supplying a machine value will gener‐
433 ate output for the specific machine.
434 pool-capabilities
436 Syntax:
437 pool-capabilities
439 Print an XML document describing the storage pool capabilities for the
441 connected storage driver. This may be useful if you intend to create a
442 new storage pool and need to know the available pool types and sup‐
443 ported storage pool source and target volume formats as well as the re‐
444 quired source elements to create the pool.
445 inject-nmi
447 Syntax:
448 inject-nmi domain
450 Inject NMI to the guest.
452 list
454 Syntax:
455 list [--inactive | --all]
457 [--managed-save] [--title]
458 { [--table] | --name | --uuid | --id }
459 [--persistent] [--transient]
460 [--with-managed-save] [--without-managed-save]
461 [--autostart] [--no-autostart]
462 [--with-snapshot] [--without-snapshot]
463 [--with-checkpoint] [--without-checkpoint]
464 [--state-running] [--state-paused]
465 [--state-shutoff] [--state-other]
466 Prints information about existing domains. If no options are specified
468 it prints out information about running domains.
469 Example 1:
471 An example format for the list is as follows:
473 ``virsh`` list
475 Id Name State
476 ----------------------------------------------------
477 0 Domain-0 running
478 2 fedora paused
479 Name is the name of the domain. ID the domain numeric id. State is
481 the run state (see below).
482 STATES
484 The State field lists what state each domain is currently in. A domain
486 can be in one of the following possible states:
487 • running
489 The domain is currently running on a CPU
491 • idle
493 The domain is idle, and not running or runnable. This can be caused
495 because the domain is waiting on IO (a traditional wait state) or has
496 gone to sleep because there was nothing else for it to do.
497 • paused
499 The domain has been paused, usually occurring through the administra‐
501 tor running virsh suspend. When in a paused state the domain will
502 still consume allocated resources like memory, but will not be eligi‐
503 ble for scheduling by the hypervisor.
504 • in shutdown
506 The domain is in the process of shutting down, i.e. the guest operat‐
508 ing system has been notified and should be in the process of stopping
509 its operations gracefully.
510 • shut off
512 The domain is not running. Usually this indicates the domain has
514 been shut down completely, or has not been started.
515 • crashed
517 The domain has crashed, which is always a violent ending. Usually
519 this state can only occur if the domain has been configured not to
520 restart on crash.
521 • pmsuspended
523 The domain has been suspended by guest power management, e.g. entered
525 into s3 state.
526 Normally only active domains are listed. To list inactive domains spec‐
528 ify --inactive or --all to list both active and inactive domains.
529 Filtering
531 To further filter the list of domains you may specify one or more of
533 filtering flags supported by the list command. These flags are grouped
534 by function. Specifying one or more flags from a group enables the
535 filter group. Note that some combinations of flags may yield no re‐
536 sults. Supported filtering flags and groups:
537 Persistence
539 Flag --persistent is used to include persistent guests in the returned
540 list. To include transient guests specify --transient.
541 Existence of managed save image
543 To list domains having a managed save image specify flag --with-man‐
544 aged-save. For domains that don't have a managed save image specify
545 --without-managed-save.
546 Domain state
548 The following filter flags select a domain by its state: --state-run‐
549 ning for running domains, --state-paused for paused domains,
550 --state-shutoff for turned off domains and --state-other for all other
551 states as a fallback.
552 Autostarting domains
554 To list autostarting domains use the flag --autostart. To list domains
555 with this feature disabled use --no-autostart.
556 Snapshot existence
558 Domains that have snapshot images can be listed using flag --with-snap‐
559 shot, domains without a snapshot --without-snapshot.
560 Checkpoint existence
562 Domains that have checkpoints can be listed using flag --with-check‐
563 point, domains without a checkpoint --without-checkpoint.
564 When talking to older servers, this command is forced to use a series
566 of API calls with an inherent race, where a domain might not be listed
567 or might appear more than once if it changed state between calls while
568 the list was being collected. Newer servers do not have this problem.
569 If --managed-save is specified, then domains that have managed save
571 state (only possible if they are in the shut off state, so you need to
572 specify --inactive or --all to actually list them) will instead show as
573 saved in the listing. This flag is usable only with the default --table
574 output. Note that this flag does not filter the list of domains.
575 If --name is specified, domain names are printed instead of the table
577 formatted one per line. If --uuid is specified domain's UUID's are
578 printed instead of names. If --id is specified then domain's ID's are
579 printed indead of names. However, it is possible to combine --name,
580 --uuid and --id to select only desired fields for printing. Flag --ta‐
581 ble specifies that the legacy table-formatted output should be used,
582 but it is mutually exclusive with --name, --uuid and --id. This is the
583 default and will be used if neither of --name, --uuid or --id is speci‐
584 fied. If neither --name nor --uuid is specified, but --id is, then only
585 active domains are listed, even with the --all parameter as otherwise
586 the output would just contain bunch of lines with just -1.
587 If --title is specified, then the short domain description (title) is
589 printed in an extra column. This flag is usable only with the default
590 --table output.
591 Example 2:
593 $ virsh list --title
595 Id Name State Title
596 -------------------------------------------
597 0 Domain-0 running Mailserver 1
598 2 fedora paused
599 freecell
601 Syntax:
602 freecell [{ [--cellno] cellno | --all }]
604 Prints the available amount of memory on the machine or within a NUMA
606 cell. The freecell command can provide one of three different displays
607 of available memory on the machine depending on the options specified.
608 With no options, it displays the total free memory on the machine.
609 With the --all option, it displays the free memory in each cell and the
610 total free memory on the machine. Finally, with a numeric argument or
611 with --cellno plus a cell number it will display the free memory for
612 the specified cell only.
613 freepages
615 Syntax:
616 freepages [{ [--cellno] cellno [--pagesize] pagesize | --all }]
618 Prints the available amount of pages within a NUMA cell. cellno refers
620 to the NUMA cell you're interested in. pagesize is a scaled integer
621 (see NOTES above). Alternatively, if --all is used, info on each pos‐
622 sible combination of NUMA cell and page size is printed out.
623 allocpages
625 Syntax:
626 allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno] cellno] [--add] [--all]
628 Change the size of pages pool of pagesize on the host. If --add is
630 specified, then pagecount pages are added into the pool. However, if
631 --add wasn't specified, then the pagecount is taken as the new absolute
632 size of the pool (this may be used to free some pages and size the pool
633 down). The cellno modifier can be used to narrow the modification down
634 to a single host NUMA cell. On the other end of spectrum lies --all
635 which executes the modification on all NUMA cells.
636 cpu-baseline
638 Syntax:
639 cpu-baseline FILE [--features] [--migratable]
641 Compute baseline CPU which will be supported by all host CPUs given in
643 <file>. (See hypervisor-cpu-baseline command to get a CPU which can be
644 provided by a specific hypervisor.) The list of host CPUs is built by
645 extracting all <cpu> elements from the <file>. Thus, the <file> can
646 contain either a set of <cpu> elements separated by new lines or even a
647 set of complete <capabilities> elements printed by capabilities com‐
648 mand. If --features is specified, then the resulting XML description
649 will explicitly include all features that make up the CPU, without this
650 option features that are part of the CPU model will not be listed in
651 the XML description. If --migratable is specified, features that
652 block migration will not be included in the resulting CPU.
653 cpu-compare
655 Syntax:
656 cpu-compare FILE [--error] [--validate]
658 Compare CPU definition from XML <file> with host CPU. (See hypervi‐
660 sor-cpu-compare command for comparing the CPU definition with the CPU
661 which a specific hypervisor is able to provide on the host.) The XML
662 <file> may contain either host or guest CPU definition. The host CPU
663 definition is the <cpu> element and its contents as printed by capabil‐
664 ities command. The guest CPU definition is the <cpu> element and its
665 contents from domain XML definition or the CPU definition created from
666 the host CPU model found in domain capabilities XML (printed by domca‐
667 pabilities command). In addition to the <cpu> element itself, this com‐
668 mand accepts full domain XML, capabilities XML, or domain capabilities
669 XML containing the CPU definition. For more information on guest CPU
670 definition see: https://libvirt.org/formatdomain.html#elementsCPU. If
671 --error is specified, the command will return an error when the given
672 CPU is incompatible with host CPU and a message providing more details
673 about the incompatibility will be printed out. If --validate is speci‐
674 fied, validates the format of the XML document against an internal RNG
675 schema.
676 cpu-models
678 Syntax:
679 cpu-models arch
681 Print the list of CPU models known by libvirt for the specified archi‐
683 tecture. Whether a specific hypervisor is able to create a domain
684 which uses any of the printed CPU models is a separate question which
685 can be answered by looking at the domain capabilities XML returned by
686 domcapabilities command. Moreover, for some architectures libvirt does
687 not know any CPU models and the usable CPU models are only limited by
688 the hypervisor. This command will print that all CPU models are ac‐
689 cepted for these architectures and the actual list of supported CPU
690 models can be checked in the domain capabilities XML.
691 echo
693 Syntax:
694 echo [--shell] [--xml] [err...] [arg...]
696 Echo back each arg, separated by space. If --shell is specified, then
698 the output will be single-quoted where needed, so that it is suitable
699 for reuse in a shell context. If --xml is specified, then the output
700 will be escaped for use in XML. If --err is specified, prefix "error:
701 " and output to stderr instead of stdout.
702 hypervisor-cpu-compare
704 Syntax:
705 hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine] [--error] [--validate]
707 Compare CPU definition from XML <file> with the CPU the hypervisor is
709 able to provide on the host. (This is different from cpu-compare which
710 compares the CPU definition with the host CPU without considering any
711 specific hypervisor and its abilities.)
712 The XML FILE may contain either a host or guest CPU definition. The
714 host CPU definition is the <cpu> element and its contents as printed by
715 the capabilities command. The guest CPU definition is the <cpu> element
716 and its contents from the domain XML definition or the CPU definition
717 created from the host CPU model found in the domain capabilities XML
718 (printed by the domcapabilities command). In addition to the <cpu> ele‐
719 ment itself, this command accepts full domain XML, capabilities XML, or
720 domain capabilities XML containing the CPU definition. For more infor‐
721 mation on guest CPU definition see:
722 https://libvirt.org/formatdomain.html#elementsCPU.
723 The virttype option specifies the virtualization type (usable in the
725 'type' attribute of the <domain> top level element from the domain
726 XML). emulator specifies the path to the emulator, arch specifies the
727 CPU architecture, and machine specifies the machine type. If --error is
728 specified, the command will return an error when the given CPU is in‐
729 compatible with the host CPU and a message providing more details about
730 the incompatibility will be printed out. If --validate is specified,
731 validates the format of the XML document against an internal RNG
732 schema.
733 hypervisor-cpu-baseline
735 Syntax:
736 hypervisor-cpu-baseline FILE [virttype] [emulator] [arch] [machine] [--features] [--migratable]
738 Compute a baseline CPU which will be compatible with all CPUs defined
740 in an XML file and with the CPU the hypervisor is able to provide on
741 the host. (This is different from cpu-baseline which does not consider
742 any hypervisor abilities when computing the baseline CPU.)
743 The XML FILE may contain either host or guest CPU definitions describ‐
745 ing the host CPU model. The host CPU definition is the <cpu> element
746 and its contents as printed by capabilities command. The guest CPU def‐
747 inition may be created from the host CPU model found in domain capabil‐
748 ities XML (printed by domcapabilities command). In addition to the
749 <cpu> elements, this command accepts full capabilities XMLs, or domain
750 capabilities XMLs containing the CPU definitions. It is recommended to
751 use only the CPU definitions from domain capabilities, as on some ar‐
752 chitectures using the host CPU definition may either fail or provide
753 unexpected results.
754 When FILE contains only a single CPU definition, the command will print
756 the same CPU with restrictions imposed by the capabilities of the hy‐
757 pervisor. Specifically, running th virsh hypervisor-cpu-baseline com‐
758 mand with no additional options on the result of virsh domcapabilities
759 will transform the host CPU model from domain capabilities XML to a
760 form directly usable in domain XML.
761 The virttype option specifies the virtualization type (usable in the
763 'type' attribute of the <domain> top level element from the domain
764 XML). emulator specifies the path to the emulator, arch specifies the
765 CPU architecture, and machine specifies the machine type. If --features
766 is specified, then the resulting XML description will explicitly in‐
767 clude all features that make up the CPU, without this option features
768 that are part of the CPU model will not be listed in the XML descrip‐
769 tion. If --migratable is specified, features that block migration will
770 not be included in the resulting CPU.
771
773 The following commands manipulate domains directly, as stated previ‐
774 ously most commands take domain as the first parameter. The domain can
775 be specified as a short integer, a name or a full UUID.
776 autostart
778 Syntax:
779 autostart [--disable] domain
781 Configure a domain to be automatically started at boot.
783 The option --disable disables autostarting.
785 blkdeviotune
787 Syntax:
788 blkdeviotune domain device [[--config] [--live] | [--current]]
790 [[total-bytes-sec] | [read-bytes-sec] [write-bytes-sec]]
791 [[total-iops-sec] | [read-iops-sec] [write-iops-sec]]
792 [[total-bytes-sec-max] | [read-bytes-sec-max] [write-bytes-sec-max]]
793 [[total-iops-sec-max] | [read-iops-sec-max] [write-iops-sec-max]]
794 [[total-bytes-sec-max-length] |
795 [read-bytes-sec-max-length] [write-bytes-sec-max-length]]
796 [[total-iops-sec-max-length] |
797 [read-iops-sec-max-length] [write-iops-sec-max-length]]
798 [size-iops-sec] [group-name]
799 Set or query the block disk io parameters for a block device of domain.
801 device specifies a unique target name (<target dev='name'/>) or source
802 file (<source file='name'/>) for one of the disk devices attached to
803 domain (see also domblklist for listing these names).
804 If no limit is specified, it will query current I/O limits setting.
806 Otherwise, alter the limits with these flags: --total-bytes-sec speci‐
807 fies total throughput limit as a scaled integer, the default being
808 bytes per second if no suffix is specified. --read-bytes-sec specifies
809 read throughput limit as a scaled integer, the default being bytes per
810 second if no suffix is specified. --write-bytes-sec specifies write
811 throughput limit as a scaled integer, the default being bytes per sec‐
812 ond if no suffix is specified. --total-iops-sec specifies total I/O
813 operations limit per second. --read-iops-sec specifies read I/O opera‐
814 tions limit per second. --write-iops-sec specifies write I/O opera‐
815 tions limit per second. --total-bytes-sec-max specifies maximum total
816 throughput limit as a scaled integer, the default being bytes per sec‐
817 ond if no suffix is specified --read-bytes-sec-max specifies maximum
818 read throughput limit as a scaled integer, the default being bytes per
819 second if no suffix is specified. --write-bytes-sec-max specifies max‐
820 imum write throughput limit as a scaled integer, the default being
821 bytes per second if no suffix is specified. --total-iops-sec-max spec‐
822 ifies maximum total I/O operations limit per second.
823 --read-iops-sec-max specifies maximum read I/O operations limit per
824 second. --write-iops-sec-max specifies maximum write I/O operations
825 limit per second. --total-bytes-sec-max-length specifies duration in
826 seconds to allow maximum total throughput limit.
827 --read-bytes-sec-max-length specifies duration in seconds to allow max‐
828 imum read throughput limit. --write-bytes-sec-max-length specifies du‐
829 ration in seconds to allow maximum write throughput limit. --to‐
830 tal-iops-sec-max-length specifies duration in seconds to allow maximum
831 total I/O operations limit. --read-iops-sec-max-length specifies dura‐
832 tion in seconds to allow maximum read I/O operations limit.
833 --write-iops-sec-max-length specifies duration in seconds to allow max‐
834 imum write I/O operations limit. --size-iops-sec specifies size I/O
835 operations limit per second. --group-name specifies group name to
836 share I/O quota between multiple drives. For a QEMU domain, if no name
837 is provided, then the default is to have a single group for each de‐
838 vice.
839 Older versions of virsh only accepted these options with underscore in‐
841 stead of dash, as in --total_bytes_sec.
842 Bytes and iops values are independent, but setting only one value (such
844 as --read-bytes-sec) resets the other two in that category to unlim‐
845 ited. An explicit 0 also clears any limit. A non-zero value for a
846 given total cannot be mixed with non-zero values for read or write.
847 It is up to the hypervisor to determine how to handle the length val‐
849 ues. For the QEMU hypervisor, if an I/O limit value or maximum value
850 is set, then the default value of 1 second will be displayed. Supplying
851 a 0 will reset the value back to the default.
852 If --live is specified, affect a running guest. If --config is speci‐
854 fied, affect the next start of a persistent guest. If --current is
855 specified, it is equivalent to either --live or --config, depending on
856 the current state of the guest. When setting the disk io parameters
857 both --live and --config flags may be given, but --current is exclu‐
858 sive. For querying only one of --live, --config or --current can be
859 specified. If no flag is specified, behavior is different depending on
860 hypervisor.
861 blkiotune
863 Syntax:
864 blkiotune domain [--weight weight] [--device-weights device-weights]
866 [--device-read-iops-sec device-read-iops-sec]
867 [--device-write-iops-sec device-write-iops-sec]
868 [--device-read-bytes-sec device-read-bytes-sec]
869 [--device-write-bytes-sec device-write-bytes-sec]
870 [[--config] [--live] | [--current]]
871 Display or set the blkio parameters. QEMU/KVM supports --weight.
873 --weight is in range [100, 1000]. After kernel 2.6.39, the value could
874 be in the range [10, 1000].
875 device-weights is a single string listing one or more device/weight
877 pairs, in the format of /path/to/device,weight,/path/to/device,weight.
878 Each weight is in the range [100, 1000], [10, 1000] after kernel
879 2.6.39, or the value 0 to remove that device from per-device listings.
880 Only the devices listed in the string are modified; any existing
881 per-device weights for other devices remain unchanged.
882 device-read-iops-sec is a single string listing one or more de‐
884 vice/read_iops_sec pairs, int the format of /path/to/de‐
885 vice,read_iops_sec,/path/to/device,read_iops_sec. Each read_iops_sec
886 is a number which type is unsigned int, value 0 to remove that device
887 from per-device listing. Only the devices listed in the string are
888 modified; any existing per-device read_iops_sec for other devices re‐
889 main unchanged.
890 device-write-iops-sec is a single string listing one or more de‐
892 vice/write_iops_sec pairs, int the format of /path/to/de‐
893 vice,write_iops_sec,/path/to/device,write_iops_sec. Each
894 write_iops_sec is a number which type is unsigned int, value 0 to re‐
895 move that device from per-device listing. Only the devices listed in
896 the string are modified; any existing per-device write_iops_sec for
897 other devices remain unchanged.
898 device-read-bytes-sec is a single string listing one or more de‐
900 vice/read_bytes_sec pairs, int the format of /path/to/de‐
901 vice,read_bytes_sec,/path/to/device,read_bytes_sec. Each
902 read_bytes_sec is a number which type is unsigned long long, value 0 to
903 remove that device from per-device listing. Only the devices listed in
904 the string are modified; any existing per-device read_bytes_sec for
905 other devices remain unchanged.
906 device-write-bytes-sec is a single string listing one or more de‐
908 vice/write_bytes_sec pairs, int the format of /path/to/de‐
909 vice,write_bytes_sec,/path/to/device,write_bytes_sec. Each
910 write_bytes_sec is a number which type is unsigned long long, value 0
911 to remove that device from per-device listing. Only the devices listed
912 in the string are modified; any existing per-device write_bytes_sec for
913 other devices remain unchanged.
914 If --live is specified, affect a running guest. If --config is speci‐
916 fied, affect the next start of a persistent guest. If --current is
917 specified, it is equivalent to either --live or --config, depending on
918 the current state of the guest. Both --live and --config flags may be
919 given, but --current is exclusive. If no flag is specified, behavior is
920 different depending on hypervisor.
921 blockcommit
923 Syntax:
924 blockcommit domain path [bandwidth] [--bytes] [base]
926 [--shallow] [top] [--delete] [--keep-relative]
927 [--wait [--async] [--verbose]] [--timeout seconds]
928 [--active] [{--pivot | --keep-overlay}]
929 Reduce the length of a backing image chain, by committing changes at
931 the top of the chain (snapshot or delta files) into backing images. By
932 default, this command attempts to flatten the entire chain. If base
933 and/or top are specified as files within the backing chain, then the
934 operation is constrained to committing just that portion of the chain;
935 --shallow can be used instead of base to specify the immediate backing
936 file of the resulting top image to be committed. The files being com‐
937 mitted are rendered invalid, possibly as soon as the operation starts;
938 using the --delete flag will attempt to remove these invalidated files
939 at the successful completion of the commit operation. When the
940 --keep-relative flag is used, the backing file paths will be kept rela‐
941 tive.
942 When top is omitted or specified as the active image, it is also possi‐
944 ble to specify --active to trigger a two-phase active commit. In the
945 first phase, top is copied into base and the job can only be canceled,
946 with top still containing data not yet in base. In the second phase,
947 top and base remain identical until a call to blockjob with the --abort
948 flag (keeping top as the active image that tracks changes from that
949 point in time) or the --pivot flag (making base the new active image
950 and invalidating top).
951 By default, this command returns as soon as possible, and data for the
953 entire disk is committed in the background; the progress of the opera‐
954 tion can be checked with blockjob. However, if --wait is specified,
955 then this command will block until the operation completes (or for
956 --active, enters the second phase), or until the operation is canceled
957 because the optional timeout in seconds elapses or SIGINT is sent (usu‐
958 ally with Ctrl-C). Using --verbose along with --wait will produce pe‐
959 riodic status updates. If job cancellation is triggered, --async will
960 return control to the user as fast as possible, otherwise the command
961 may continue to block a little while longer until the job is done
962 cleaning up. Using --pivot is shorthand for combining --active --wait
963 with an automatic blockjob --pivot; and using --keep-overlay is short‐
964 hand for combining --active --wait with an automatic blockjob --abort.
965 path specifies fully-qualified path of the disk; it corresponds to a
967 unique target name (<target dev='name'/>) or source file (<source
968 file='name'/>) for one of the disk devices attached to domain (see also
969 domblklist for listing these names). bandwidth specifies copying band‐
970 width limit in MiB/s, although for QEMU, it may be non-zero only for an
971 online domain. For further information on the bandwidth argument see
972 the corresponding section for the blockjob command.
973 blockcopy
975 Syntax:
976 blockcopy domain path { dest [format] [--blockdev] | --xml file }
978 [--shallow] [--reuse-external] [bandwidth]
979 [--wait [--async] [--verbose]] [{--pivot | --finish}]
980 [--timeout seconds] [granularity] [buf-size] [--bytes]
981 [--transient-job]
982 Copy a disk backing image chain to a destination. Either dest as the
984 destination file name, or --xml with the name of an XML file containing
985 a top-level <disk> element describing the destination, must be present.
986 Additionally, if dest is given, format should be specified to declare
987 the format of the destination (if format is omitted, then libvirt will
988 reuse the format of the source, or with --reuse-external will be forced
989 to probe the destination format, which could be a potential security
990 hole). The command supports --raw as a boolean flag synonym for --for‐
991 mat=raw. When using dest, the destination is treated as a regular file
992 unless --blockdev is used to signal that it is a block device. By de‐
993 fault, this command flattens the entire chain; but if --shallow is
994 specified, the copy shares the backing chain.
995 If --reuse-external is specified, then the destination must exist and
997 have sufficient space to hold the copy. If --shallow is used in con‐
998 junction with --reuse-external then the pre-created image must have
999 guest visible contents identical to guest visible contents of the back‐
1000 ing file of the original image. This may be used to modify the backing
1001 file names on the destination.
1002 By default, the copy job runs in the background, and consists of two
1004 phases. Initially, the job must copy all data from the source, and
1005 during this phase, the job can only be canceled to revert back to the
1006 source disk, with no guarantees about the destination. After this
1007 phase completes, both the source and the destination remain mirrored
1008 until a call to blockjob with the --abort and --pivot flags pivots over
1009 to the copy, or a call without --pivot leaves the destination as a
1010 faithful copy of that point in time. However, if --wait is specified,
1011 then this command will block until the mirroring phase begins, or can‐
1012 cel the operation if the optional timeout in seconds elapses or SIGINT
1013 is sent (usually with Ctrl-C). Using --verbose along with --wait will
1014 produce periodic status updates. Using --pivot (similar to blockjob
1015 --pivot) or --finish (similar to blockjob --abort) implies --wait, and
1016 will additionally end the job cleanly rather than leaving things in the
1017 mirroring phase. If job cancellation is triggered by timeout or by
1018 --finish, --async will return control to the user as fast as possible,
1019 otherwise the command may continue to block a little while longer until
1020 the job has actually cancelled.
1021 path specifies fully-qualified path of the disk. bandwidth specifies
1023 copying bandwidth limit in MiB/s. Specifying a negative value is inter‐
1024 preted as an unsigned long long value that might be essentially unlim‐
1025 ited, but more likely would overflow; it is safer to use 0 for that
1026 purpose. For further information on the bandwidth argument see the cor‐
1027 responding section for the blockjob command. Specifying granularity
1028 allows fine-tuning of the granularity that will be copied when a dirty
1029 region is detected; larger values trigger less I/O overhead but may end
1030 up copying more data overall (the default value is usually correct);
1031 hypervisors may restrict this to be a power of two or fall within a
1032 certain range. Specifying buf-size will control how much data can be
1033 simultaneously in-flight during the copy; larger values use more memory
1034 but may allow faster completion (the default value is usually correct).
1035 --transient-job allows specifying that the user does not require the
1037 job to be recovered if the VM crashes or is turned off before the job
1038 completes. This flag removes the restriction of copy jobs to transient
1039 domains if that restriction is applied by the hypervisor.
1040 blockjob
1042 Syntax:
1043 blockjob domain path { [--abort] [--async] [--pivot] |
1045 [--info] [--raw] [--bytes] | [bandwidth] }
1046 Manage active block operations. There are three mutually-exclusive
1048 modes: --info, bandwidth, and --abort. --async and --pivot imply abort
1049 mode; --raw implies info mode; and if no mode was given, --info mode is
1050 assumed.
1051 path specifies fully-qualified path of the disk; it corresponds to a
1053 unique target name (<target dev='name'/>) or source file (<source
1054 file='name'/>) for one of the disk devices attached to domain (see also
1055 domblklist for listing these names).
1056 In --abort mode, the active job on the specified disk will be aborted.
1058 If --async is also specified, this command will return immediately,
1059 rather than waiting for the cancellation to complete. If --pivot is
1060 specified, this requests that an active copy or active commit job be
1061 pivoted over to the new image.
1062 In --info mode, the active job information on the specified disk will
1064 be printed. By default, the output is a single human-readable summary
1065 line; this format may change in future versions. Adding --raw lists
1066 each field of the struct, in a stable format. If the --bytes flag is
1067 set, then the command errors out if the server could not supply bytes/s
1068 resolution; when omitting the flag, raw output is listed in MiB/s and
1069 human-readable output automatically selects the best resolution sup‐
1070 ported by the server.
1071 bandwidth can be used to set bandwidth limit for the active job in
1073 MiB/s. If --bytes is specified then the bandwidth value is interpreted
1074 in bytes/s. Specifying a negative value is interpreted as an unsigned
1075 long value or essentially unlimited. The hypervisor can choose whether
1076 to reject the value or convert it to the maximum value allowed. Option‐
1077 ally a scaled positive number may be used as bandwidth (see NOTES
1078 above). Using --bytes with a scaled value permits a finer granularity
1079 to be selected. A scaled value used without --bytes will be rounded
1080 down to MiB/s. Note that the --bytes may be unsupported by the hypervi‐
1081 sor.
1082 Note that the progress reported for blockjobs corresponding to a
1084 pull-mode backup don't report progress of the backup but rather usage
1085 of temporary space required for the backup.
1086 blockpull
1088 Syntax:
1089 blockpull domain path [bandwidth] [--bytes] [base]
1091 [--wait [--verbose] [--timeout seconds] [--async]]
1092 [--keep-relative]
1093 Populate a disk from its backing image chain. By default, this command
1095 flattens the entire chain; but if base is specified, containing the
1096 name of one of the backing files in the chain, then that file becomes
1097 the new backing file and only the intermediate portion of the chain is
1098 pulled. Once all requested data from the backing image chain has been
1099 pulled, the disk no longer depends on that portion of the backing
1100 chain.
1101 By default, this command returns as soon as possible, and data for the
1103 entire disk is pulled in the background; the progress of the operation
1104 can be checked with blockjob. However, if --wait is specified, then
1105 this command will block until the operation completes, or cancel the
1106 operation if the optional timeout in seconds elapses or SIGINT is sent
1107 (usually with Ctrl-C). Using --verbose along with --wait will produce
1108 periodic status updates. If job cancellation is triggered, --async
1109 will return control to the user as fast as possible, otherwise the com‐
1110 mand may continue to block a little while longer until the job is done
1111 cleaning up.
1112 Using the --keep-relative flag will keep the backing chain names rela‐
1114 tive.
1115 path specifies fully-qualified path of the disk; it corresponds to a
1117 unique target name (<target dev='name'/>) or source file (<source
1118 file='name'/>) for one of the disk devices attached to domain (see also
1119 domblklist for listing these names). bandwidth specifies copying band‐
1120 width limit in MiB/s. For further information on the bandwidth argument
1121 see the corresponding section for the blockjob command.
1122 blockresize
1124 Syntax:
1125 blockresize domain path size
1127 Resize a block device of domain while the domain is running, path spec‐
1129 ifies the absolute path of the block device; it corresponds to a unique
1130 target name (<target dev='name'/>) or source file (<source
1131 file='name'/>) for one of the disk devices attached to domain (see also
1132 domblklist for listing these names).
1133 size is a scaled integer (see NOTES above) which defaults to KiB
1135 (blocks of 1024 bytes) if there is no suffix. You must use a suffix of
1136 "B" to get bytes (note that for historical reasons, this differs from
1137 vol-resize which defaults to bytes without a suffix).
1138 console
1140 Syntax:
1141 console domain [devname] [--safe] [--force]
1143 Connect the virtual serial console for the guest. The optional devname
1145 parameter refers to the device alias of an alternate console, serial or
1146 parallel device configured for the guest. If omitted, the primary con‐
1147 sole will be opened.
1148 If the flag --safe is specified, the connection is only attempted if
1150 the driver supports safe console handling. This flag specifies that the
1151 server has to ensure exclusive access to console devices. Optionally
1152 the --force flag may be specified, requesting to disconnect any exist‐
1153 ing sessions, such as in a case of a broken connection.
1154 cpu-stats
1156 Syntax:
1157 cpu-stats domain [--total] [start] [count]
1159 Provide cpu statistics information of a domain. The domain should be
1161 running. Default it shows stats for all CPUs, and a total. Use --total
1162 for only the total stats, start for only the per-cpu stats of the CPUs
1163 from start, count for only count CPUs' stats.
1164 create
1166 Syntax:
1167 create FILE [--console] [--paused] [--autodestroy]
1169 [--pass-fds N,M,...] [--validate]
1170 Create a domain from an XML <file>. Optionally, --validate option can
1172 be passed to validate the format of the input XML file against an in‐
1173 ternal RNG schema (identical to using virt-xml-validate(1) tool). Do‐
1174 mains created using this command are going to be either transient (tem‐
1175 porary ones that will vanish once destroyed) or existing persistent
1176 guests that will run with one-time use configuration, leaving the per‐
1177 sistent XML untouched (this can come handy during an automated testing
1178 of various configurations all based on the original XML). See the ex‐
1179 ample below for usage demonstration.
1180 The domain will be paused if the --paused option is used and supported
1182 by the driver; otherwise it will be running. If --console is requested,
1183 attach to the console after creation. If --autodestroy is requested,
1184 then the guest will be automatically destroyed when virsh closes its
1185 connection to libvirt, or otherwise exits.
1186 If --pass-fds is specified, the argument is a comma separated list of
1188 open file descriptors which should be pass on into the guest. The file
1189 descriptors will be re-numbered in the guest, starting from 3. This is
1190 only supported with container based virtualization.
1191 Example:
1193 1. prepare a template from an existing domain (skip directly to 3a if
1195 writing one from scratch)
1196 # virsh dumpxml <domain> > domain.xml
1198 2. edit the template using an editor of your choice and:
1200 a. DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or
1202 b. DON'T CHANGE! either <name> or <uuid>
1204 # $EDITOR domain.xml
1206 3. create a domain from domain.xml, depending on whether following 2a
1208 or 2b respectively:
1209 a. the domain is going to be transient
1211 b. an existing persistent guest will run with a modified one-time
1213 configuration
1214 # virsh create domain.xml
1216 define
1218 Syntax:
1219 define FILE [--validate]
1221 Define a domain from an XML <file>. Optionally, the format of the input
1223 XML file can be validated against an internal RNG schema with --vali‐
1224 date (identical to using virt-xml-validate(1) tool). The domain defini‐
1225 tion is registered but not started. If domain is already running, the
1226 changes will take effect on the next boot.
1227 desc
1229 Syntax:
1230 desc domain [[--live] [--config] |
1232 [--current]] [--title] [--edit] [--new-desc
1233 New description or title message]
1234 Show or modify description and title of a domain. These values are user
1236 fields that allow storing arbitrary textual data to allow easy identi‐
1237 fication of domains. Title should be short, although it's not enforced.
1238 (See also metadata that works with XML based domain metadata.)
1239 Flags --live or --config select whether this command works on live or
1241 persistent definitions of the domain. If both --live and --config are
1242 specified, the --config option takes precedence on getting the current
1243 description and both live configuration and config are updated while
1244 setting the description. --current is exclusive and implied if none of
1245 these was specified.
1246 Flag --edit specifies that an editor with the contents of current de‐
1248 scription or title should be opened and the contents saved back after‐
1249 wards.
1250 Flag --title selects operation on the title field instead of descrip‐
1252 tion.
1253 If neither of --edit and --new-desc are specified the note or descrip‐
1255 tion is displayed instead of being modified.
1256 destroy
1258 Syntax:
1259 destroy domain [--graceful]
1261 Immediately terminate the domain domain. This doesn't give the domain
1263 OS any chance to react, and it's the equivalent of ripping the power
1264 cord out on a physical machine. In most cases you will want to use the
1265 shutdown command instead. However, this does not delete any storage
1266 volumes used by the guest, and if the domain is persistent, it can be
1267 restarted later.
1268 If domain is transient, then the metadata of any snapshots will be lost
1270 once the guest stops running, but the snapshot contents still exist,
1271 and a new domain with the same name and UUID can restore the snapshot
1272 metadata with snapshot-create. Similarly, the metadata of any check‐
1273 points will be lost, but can be restored with checkpoint-create.
1274 If --graceful is specified, don't resort to extreme measures (e.g.
1276 SIGKILL) when the guest doesn't stop after a reasonable timeout; return
1277 an error instead.
1278 domblkerror
1280 Syntax:
1281 domblkerror domain
1283 Show errors on block devices. This command usually comes handy when
1285 domstate command says that a domain was paused due to I/O error. The
1286 domblkerror command lists all block devices in error state and the er‐
1287 ror seen on each of them.
1288 domblkinfo
1290 Syntax:
1291 domblkinfo domain [block-device --all] [--human]
1293 Get block device size info for a domain. A block-device corresponds to
1295 a unique target name (<target dev='name'/>) or source file (<source
1296 file='name'/>) for one of the disk devices attached to domain (see also
1297 domblklist for listing these names). If --human is set, the output will
1298 have a human readable output. If --all is set, the output will be a
1299 table showing all block devices size info associated with domain. The
1300 --all option takes precedence of the others.
1301 domblklist
1303 Syntax:
1304 domblklist domain [--inactive] [--details]
1306 Print a table showing the brief information of all block devices asso‐
1308 ciated with domain. If --inactive is specified, query the block devices
1309 that will be used on the next boot, rather than those currently in use
1310 by a running domain. If --details is specified, disk type and device
1311 value will also be printed. Other contexts that require a block device
1312 name (such as domblkinfo or snapshot-create for disk snapshots) will
1313 accept either target or unique source names printed by this command.
1314 domblkstat
1316 Syntax:
1317 domblkstat domain [block-device] [--human]
1319 Get device block stats for a running domain. A block-device corre‐
1321 sponds to a unique target name (<target dev='name'/>) or source file
1322 (<source file='name'/>) for one of the disk devices attached to domain
1323 (see also domblklist for listing these names). On a LXC or QEMU domain,
1324 omitting the block-device yields device block stats summarily for the
1325 entire domain.
1326 Use --human for a more human readable output.
1328 Availability of these fields depends on hypervisor. Unsupported fields
1330 are missing from the output. Other fields may appear if communicating
1331 with a newer version of libvirtd.
1332 Explanation of fields (fields appear in the following order):
1334 • rd_req - count of read operations
1336 • rd_bytes - count of read bytes
1338 • wr_req - count of write operations
1340 • wr_bytes - count of written bytes
1342 • errs - error count
1344 • flush_operations - count of flush operations
1346 • rd_total_times - total time read operations took (ns)
1348 • wr_total_times - total time write operations took (ns)
1350 • flush_total_times - total time flush operations took (ns)
1352 • <-- other fields provided by hypervisor -->
1354 domblkthreshold
1356 Syntax:
1357 domblkthreshold domain dev threshold
1359 Set the threshold value for delivering the block-threshold event. dev
1361 specifies the disk device target or backing chain element of given de‐
1362 vice using the 'target[1]' syntax. threshold is a scaled value of the
1363 offset. If the block device should write beyond that offset the event
1364 will be delivered.
1365 domcontrol
1367 Syntax:
1368 domcontrol domain
1370 Returns state of an interface to VMM used to control a domain. For
1372 states other than "ok" or "error" the command also prints number of
1373 seconds elapsed since the control interface entered its current state.
1374 domdisplay
1376 Syntax:
1377 domdisplay domain [--include-password] [[--type] type] [--all]
1379 Output a URI which can be used to connect to the graphical display of
1381 the domain via VNC, SPICE or RDP. The particular graphical display
1382 type can be selected using the type parameter (e.g. "vnc", "spice",
1383 "rdp"). If --include-password is specified, the SPICE channel password
1384 will be included in the URI. If --all is specified, then all show all
1385 possible graphical displays, for a VM could have more than one graphi‐
1386 cal displays.
1387 domfsfreeze
1389 Syntax:
1390 domfsfreeze domain [[--mountpoint] mountpoint...]
1392 Freeze mounted filesystems within a running domain to prepare for con‐
1394 sistent snapshots.
1395 The --mountpoint option takes a parameter mountpoint, which is a mount
1397 point path of the filesystem to be frozen. This option can occur multi‐
1398 ple times. If this is not specified, every mounted filesystem is
1399 frozen.
1400 Note: snapshot-create command has a --quiesce option to freeze and thaw
1402 the filesystems automatically to keep snapshots consistent. domfs‐
1403 freeze command is only needed when a user wants to utilize the native
1404 snapshot features of storage devices not supported by libvirt.
1405 domfsinfo
1407 Syntax:
1408 domfsinfo domain
1410 Show a list of mounted filesystems within the running domain. The list
1412 contains mountpoints, names of a mounted device in the guest, filesys‐
1413 tem types, and unique target names used in the domain XML (<target
1414 dev='name'/>).
1415 Note that this command requires a guest agent configured and running in
1417 the domain's guest OS.
1418 domfsthaw
1420 Syntax:
1421 domfsthaw domain [[--mountpoint] mountpoint...]
1423 Thaw mounted filesystems within a running domain, which have been
1425 frozen by domfsfreeze command.
1426 The --mountpoint option takes a parameter mountpoint, which is a mount
1428 point path of the filesystem to be thawed. This option can occur multi‐
1429 ple times. If this is not specified, every mounted filesystem is
1430 thawed.
1431 domfstrim
1433 Syntax:
1434 domfstrim domain [--minimum bytes] [--mountpoint mountPoint]
1436 Issue a fstrim command on all mounted filesystems within a running do‐
1438 main. It discards blocks which are not in use by the filesystem. If
1439 --minimum bytes is specified, it tells guest kernel length of contigu‐
1440 ous free range. Smaller than this may be ignored (this is a hint and
1441 the guest may not respect it). By increasing this value, the fstrim op‐
1442 eration will complete more quickly for filesystems with badly frag‐
1443 mented free space, although not all blocks will be discarded. The de‐
1444 fault value is zero, meaning "discard every free block". Moreover, if a
1445 user wants to trim only one mount point, it can be specified via op‐
1446 tional --mountpoint parameter.
1447 domhostname
1449 Syntax:
1450 domhostname domain [--source lease|agent]
1452 Returns the hostname of a domain, if the hypervisor makes it available.
1454 The --source argument specifies what data source to use for the host‐
1456 names, currently 'lease' to read DHCP leases or 'agent' to query the
1457 guest OS via an agent. If unspecified, driver returns the default
1458 method available (some drivers support only one type of source).
1459 domid
1461 Syntax:
1462 domid domain-name-or-uuid
1464 Convert a domain name (or UUID) to a domain id
1466 domif-getlink
1468 Syntax:
1469 domif-getlink domain interface-device [--config]
1471 Query link state of the domain's virtual interface. If --config is
1473 specified, query the persistent configuration, for compatibility pur‐
1474 poses, --persistent is alias of --config.
1475 interface-device can be the interface's target name or the MAC address.
1477 domif-setlink
1479 Syntax:
1480 domif-setlink domain interface-device state [--config]
1482 Modify link state of the domain's virtual interface. Possible values
1484 for state are "up" and "down". If --config is specified, only the per‐
1485 sistent configuration of the domain is modified, for compatibility pur‐
1486 poses, --persistent is alias of --config. interface-device can be the
1487 interface's target name or the MAC address.
1488 domifaddr
1490 Syntax:
1491 domifaddr domain [interface] [--full]
1493 [--source lease|agent|arp]
1494 Get a list of interfaces of a running domain along with their IP and
1496 MAC addresses, or limited output just for one interface if interface is
1497 specified. Note that interface can be driver dependent, it can be the
1498 name within guest OS or the name you would see in domain XML. Moreover,
1499 the whole command may require a guest agent to be configured for the
1500 queried domain under some hypervisors, notably QEMU.
1501 If --full is specified, the interface name and MAC address is always
1503 displayed when the interface has multiple IP addresses or aliases; oth‐
1504 erwise, only the interface name and MAC address is displayed for the
1505 first name and MAC address with "-" for the others using the same name
1506 and MAC address.
1507 The --source argument specifies what data source to use for the ad‐
1509 dresses, currently 'lease' to read DHCP leases, 'agent' to query the
1510 guest OS via an agent, or 'arp' to get IP from host's arp tables. If
1511 unspecified, 'lease' is the default.
1512 backup-begin
1514 Syntax:
1515 backup-begin domain [backupxml] [checkpointxml] [--reuse-external]
1517 Begin a new backup job. If backupxml is omitted, this defaults to a
1519 full backup using a push model to filenames generated by libvirt; sup‐
1520 plying XML allows fine-tuning such as requesting an incremental backup
1521 relative to an earlier checkpoint, controlling which disks participate
1522 or which filenames are involved, or requesting the use of a pull model
1523 backup. The backup-dumpxml command shows any resulting values assigned
1524 by libvirt. For more information on backup XML, see:
1525 https://libvirt.org/formatbackup.html
1526 If --reuse-external is used it instructs libvirt to reuse temporary and
1528 output files provided by the user in backupxml.
1529 If checkpointxml is specified, a second file with a top-level element
1531 of domaincheckpoint is used to create a simultaneous checkpoint, for
1532 doing a later incremental backup relative to the time the backup was
1533 created. See checkpoint-create for more details on checkpoints.
1534 This command returns as soon as possible, and the backup job runs in
1536 the background; the progress of a push model backup can be checked with
1537 domjobinfo or by waiting for an event with event (the progress of a
1538 pull model backup is under the control of whatever third party connects
1539 to the NBD export). The job is ended with domjobabort.
1540 backup-dumpxml
1542 Syntax:
1543 backup-dumpxml domain
1545 Output XML describing the current backup job.
1547 domiflist
1549 Syntax:
1550 domiflist domain [--inactive]
1552 Print a table showing the brief information of all virtual interfaces
1554 associated with domain. If --inactive is specified, query the virtual
1555 interfaces that will be used on the next boot, rather than those cur‐
1556 rently in use by a running domain. Other contexts that require a MAC
1557 address of virtual interface (such as detach-interface or
1558 domif-setlink) will accept the MAC address printed by this command.
1559 domifstat
1561 Syntax:
1562 domifstat domain interface-device
1564 Get network interface stats for a running domain. The network interface
1566 stats are only available for interfaces that have a physical source in‐
1567 terface. This does not include, for example, a 'user' interface type
1568 since it is a virtual LAN with NAT to the outside world. interface-de‐
1569 vice can be the interface target by name or MAC address.
1570 domiftune
1572 Syntax:
1573 domiftune domain interface-device [[--config] [--live] | [--current]]
1575 [*--inbound average,peak,burst,floor*]
1576 [*--outbound average,peak,burst*]
1577 Set or query the domain's network interface's bandwidth parameters.
1579 interface-device can be the interface's target name (<target
1580 dev='name'/>), or the MAC address.
1581 If no --inbound or --outbound is specified, this command will query and
1583 show the bandwidth settings. Otherwise, it will set the inbound or out‐
1584 bound bandwidth. average,peak,burst,floor is the same as in command at‐
1585 tach-interface. Values for average, peak and floor are expressed in
1586 kilobytes per second, while burst is expressed in kilobytes in a single
1587 burst at peak speed as described in the Network XML documentation at
1588 https://libvirt.org/formatnetwork.html#elementQoS.
1589 To clear inbound or outbound settings, use --inbound or --outbound re‐
1591 spectfully with average value of zero.
1592 If --live is specified, affect a running guest. If --config is speci‐
1594 fied, affect the next start of a persistent guest. If --current is
1595 specified, it is equivalent to either --live or --config, depending on
1596 the current state of the guest. Both --live and --config flags may be
1597 given, but --current is exclusive. If no flag is specified, behavior is
1598 different depending on hypervisor.
1599 dominfo
1601 Syntax:
1602 dominfo domain
1604 Returns basic information about the domain.
1606 domjobabort
1608 Syntax:
1609 domjobabort domain
1611 Abort the currently running domain job.
1613 domjobinfo
1615 Syntax:
1616 domjobinfo domain [--completed [--keep-completed]] [--anystats] [--rawstats]
1618 Returns information about jobs running on a domain. --completed tells
1620 virsh to return information about a recently finished job. Statistics
1621 of a completed job are automatically destroyed once read (unless
1622 --keep-completed is used) or when libvirtd is restarted.
1623 Normally only statistics for running and successful completed jobs are
1625 printed. --anystats can be used to also display statistics for failed
1626 jobs.
1627 In case --rawstats is used, all fields are printed as received from the
1629 server without any attempts to interpret the data. The "Job type:"
1630 field is special, since it's reported by the API and not part of stats.
1631 Note that time information returned for completed migrations may be
1633 completely irrelevant unless both source and destination hosts have
1634 synchronized time (i.e., NTP daemon is running on both of them).
1635 dommemstat
1637 Syntax:
1638 dommemstat domain [--period seconds] [[--config] [--live] | [--current]]
1640 Get memory stats for a running domain.
1642 Availability of these fields depends on hypervisor. Unsupported fields
1644 are missing from the output. Other fields may appear if communicating
1645 with a newer version of libvirtd.
1646 Explanation of fields:
1648 • swap_in - The amount of data read from swap space (in KiB)
1650 • swap_out - The amount of memory written out to swap space
1652 (in KiB)
1653 • major_fault - The number of page faults where disk IO was re‐
1655 quired
1656 • minor_fault - The number of other page faults
1658 • unused - The amount of memory left unused by the system
1660 (in KiB)
1661 • available - The amount of usable memory as seen by the domain
1663 (in KiB)
1664 • actual - Current balloon value (in KiB)
1666 • rss - Resident Set Size of the running domain's process
1668 (in KiB)
1669 • usable - The amount of memory which can be reclaimed by
1671 balloon without causing host swapping (in KiB)
1672 • last-update - Timestamp of the last update of statistics (in
1674 seconds)
1675 • disk_caches - The amount of memory that can be reclaimed with‐
1677 out additional I/O, typically disk caches (in KiB)
1678 • hugetlb_pgalloc - The number of successful huge page allocations
1680 initiated from within the domain
1681 • hugetlb_pgfail - The number of failed huge page allocations initi‐
1683 ated from within the domain
1684 For QEMU/KVM with a memory balloon, setting the optional --period to a
1686 value larger than 0 in seconds will allow the balloon driver to return
1687 additional statistics which will be displayed by subsequent dommemstat
1688 commands. Setting the --period to 0 will stop the balloon driver col‐
1689 lection, but does not clear the statistics in the balloon driver. Re‐
1690 quires at least QEMU/KVM 1.5 to be running on the host.
1691 The --live, --config, and --current flags are only valid when using the
1693 --period option in order to set the collection period for the balloon
1694 driver. If --live is specified, only the running guest collection pe‐
1695 riod is affected. If --config is specified, affect the next start of a
1696 persistent guest. If --current is specified, it is equivalent to either
1697 --live or --config, depending on the current state of the guest.
1698 Both --live and --config flags may be given, but --current is exclu‐
1700 sive. If no flag is specified, behavior is different depending on the
1701 guest state.
1702 domname
1704 Syntax:
1705 domname domain-id-or-uuid
1707 Convert a domain Id (or UUID) to domain name
1709 dompmsuspend
1711 Syntax:
1712 dompmsuspend domain target [--duration]
1714 Suspend a running domain into one of these states (possible target val‐
1716 ues):
1717 • mem - equivalent of S3 ACPI state
1719 • disk - equivalent of S4 ACPI state
1721 • hybrid - RAM is saved to disk but not powered off
1723 The --duration argument specifies number of seconds before the domain
1725 is woken up after it was suspended (see also dompmwakeup). Default is 0
1726 for unlimited suspend time. (This feature isn't currently supported by
1727 any hypervisor driver and 0 should be used.).
1728 Note that this command requires a guest agent configured and running in
1730 the domain's guest OS.
1731 Beware that at least for QEMU, the domain's process will be terminated
1733 when target disk is used and a new process will be launched when lib‐
1734 virt is asked to wake up the domain. As a result of this, any runtime
1735 changes, such as device hotplug or memory settings, are lost unless
1736 such changes were made with --config flag.
1737 dompmwakeup
1739 Syntax:
1740 dompmwakeup domain
1742 Wakeup a domain from pmsuspended state (either suspended by dompmsus‐
1744 pend or from the guest itself). Injects a wakeup into the guest that is
1745 in pmsuspended state, rather than waiting for the previously requested
1746 duration (if any) to elapse. This operation does not necessarily fail
1747 if the domain is running.
1748 domrename
1750 Syntax:
1751 domrename domain new-name
1753 Rename a domain. This command changes current domain name to the new
1755 name specified in the second argument.
1756 Note: Domain must be inactive.
1758 domstate
1760 Syntax:
1761 domstate domain [--reason]
1763 Returns state about a domain. --reason tells virsh to also print rea‐
1765 son for the state.
1766 domstats
1768 Syntax:
1769 domstats [--raw] [--enforce] [--backing] [--nowait] [--state]
1771 [--cpu-total] [--balloon] [--vcpu] [--interface]
1772 [--block] [--perf] [--iothread] [--memory]
1773 [[--list-active] [--list-inactive]
1774 [--list-persistent] [--list-transient] [--list-running]y
1775 [--list-paused] [--list-shutoff] [--list-other]] | [domain ...]
1776 Get statistics for multiple or all domains. Without any argument this
1778 command prints all available statistics for all domains.
1779 The list of domains to gather stats for can be either limited by list‐
1781 ing the domains as a space separated list, or by specifying one of the
1782 filtering flags --list-NNN. (The approaches can't be combined.)
1783 By default some of the returned fields may be converted to more human
1785 friendly values by a set of pretty-printers. To suppress this behavior
1786 use the --raw flag.
1787 The individual statistics groups are selectable via specific flags. By
1789 default all supported statistics groups are returned. Supported statis‐
1790 tics groups flags are: --state, --cpu-total, --balloon, --vcpu, --in‐
1791 terface, --block, --perf, --iothread, --memory.
1792 Note that - depending on the hypervisor type and version or the domain
1794 state - not all of the following statistics may be returned.
1795 When selecting the --state group the following fields are returned:
1797 • state.state - state of the VM, returned as number from virDomainState
1799 enum
1800 • state.reason - reason for entering given state, returned as int from
1802 virDomain*Reason enum corresponding to given state
1803 --cpu-total returns:
1805 • cpu.time - total cpu time spent for this domain in nanoseconds
1807 • cpu.user - user cpu time spent in nanoseconds
1809 • cpu.system - system cpu time spent in nanoseconds
1811 • cpu.cache.monitor.count - the number of cache monitors for this do‐
1813 main
1814 • cpu.cache.monitor.<num>.name - the name of cache monitor <num>
1816 • cpu.cache.monitor.<num>.vcpus - vcpu list of cache monitor <num>
1818 • cpu.cache.monitor.<num>.bank.count - the number of cache banks in
1820 cache monitor <num>
1821 • cpu.cache.monitor.<num>.bank.<index>.id - host allocated cache id for
1823 bank <index> in cache monitor <num>
1824 • cpu.cache.monitor.<num>.bank.<index>.bytes - the number of bytes of
1826 last level cache that the domain is using on cache bank <index>
1827 --balloon returns:
1829 • balloon.current - the memory in KiB currently used
1831 • balloon.maximum - the maximum memory in KiB allowed
1833 • balloon.swap_in - the amount of data read from swap space (in KiB)
1835 • balloon.swap_out - the amount of memory written out to swap space (in
1837 KiB)
1838 • balloon.major_fault - the number of page faults when disk IO was re‐
1840 quired
1841 • balloon.minor_fault - the number of other page faults
1843 • balloon.unused - the amount of memory left unused by the system (in
1845 KiB)
1846 • balloon.available - the amount of usable memory as seen by the domain
1848 (in KiB)
1849 • balloon.rss - Resident Set Size of running domain's process (in KiB)
1851 • balloon.usable - the amount of memory which can be reclaimed by bal‐
1853 loon without causing host swapping (in KiB)
1854 • balloon.last-update - timestamp of the last update of statistics (in
1856 seconds)
1857 • balloon.disk_caches - the amount of memory that can be reclaimed
1859 without additional I/O, typically disk (in KiB)
1860 • balloon.hugetlb_pgalloc - the number of successful huge page alloca‐
1862 tions from inside the domain via virtio balloon
1863 • balloon.hugetlb_pgfail - the number of failed huge page allocations
1865 from inside the domain via virtio balloon
1866 --vcpu returns:
1868 • vcpu.current - current number of online virtual CPUs
1870 • vcpu.maximum - maximum number of online virtual CPUs
1872 • vcpu.<num>.state - state of the virtual CPU <num>, as number from
1874 virVcpuState enum
1875 • vcpu.<num>.time - virtual cpu time spent by virtual CPU <num> (in mi‐
1877 croseconds)
1878 • vcpu.<num>.wait - virtual cpu time spent by virtual CPU <num> waiting
1880 on I/O (in microseconds)
1881 • vcpu.<num>.halted - virtual CPU <num> is halted: yes or no (may indi‐
1883 cate the processor is idle or even disabled, depending on the archi‐
1884 tecture)
1885 --interface returns:
1887 • net.count - number of network interfaces on this domain
1889 • net.<num>.name - name of the interface <num>
1891 • net.<num>.rx.bytes - number of bytes received
1893 • net.<num>.rx.pkts - number of packets received
1895 • net.<num>.rx.errs - number of receive errors
1897 • net.<num>.rx.drop - number of receive packets dropped
1899 • net.<num>.tx.bytes - number of bytes transmitted
1901 • net.<num>.tx.pkts - number of packets transmitted
1903 • net.<num>.tx.errs - number of transmission errors
1905 • net.<num>.tx.drop - number of transmit packets dropped
1907 --perf returns the statistics of all enabled perf events:
1909 • perf.cmt - the cache usage in Byte currently used
1911 • perf.mbmt - total system bandwidth from one level of cache
1913 • perf.mbml - bandwidth of memory traffic for a memory controller
1915 • perf.cpu_cycles - the count of cpu cycles (total/elapsed)
1917 • perf.instructions - the count of instructions
1919 • perf.cache_references - the count of cache hits
1921 • perf.cache_misses - the count of caches misses
1923 • perf.branch_instructions - the count of branch instructions
1925 • perf.branch_misses - the count of branch misses
1927 • perf.bus_cycles - the count of bus cycles
1929 • perf.stalled_cycles_frontend - the count of stalled frontend cpu cy‐
1931 cles
1932 • perf.stalled_cycles_backend - the count of stalled backend cpu cycles
1934 • perf.ref_cpu_cycles - the count of ref cpu cycles
1936 • perf.cpu_clock - the count of cpu clock time
1938 • perf.task_clock - the count of task clock time
1940 • perf.page_faults - the count of page faults
1942 • perf.context_switches - the count of context switches
1944 • perf.cpu_migrations - the count of cpu migrations
1946 • perf.page_faults_min - the count of minor page faults
1948 • perf.page_faults_maj - the count of major page faults
1950 • perf.alignment_faults - the count of alignment faults
1952 • perf.emulation_faults - the count of emulation faults
1954 See the perf command for more details about each event.
1956 --block returns information about disks associated with each domain.
1958 Using the --backing flag extends this information to cover all re‐
1959 sources in the backing chain, rather than the default of limiting in‐
1960 formation to the active layer for each guest disk. Information listed
1961 includes:
1962 • block.count - number of block devices being listed
1964 • block.<num>.name - name of the target of the block device <num> (the
1966 same name for multiple entries if --backing is present)
1967 • block.<num>.backingIndex - when --backing is present, matches up with
1969 the <backingStore> index listed in domain XML for backing files
1970 • block.<num>.path - file source of block device <num>, if it is a lo‐
1972 cal file or block device
1973 • block.<num>.rd.reqs - number of read requests
1975 • block.<num>.rd.bytes - number of read bytes
1977 • block.<num>.rd.times - total time (ns) spent on reads
1979 • block.<num>.wr.reqs - number of write requests
1981 • block.<num>.wr.bytes - number of written bytes
1983 • block.<num>.wr.times - total time (ns) spent on writes
1985 • block.<num>.fl.reqs - total flush requests
1987 • block.<num>.fl.times - total time (ns) spent on cache flushing
1989 • block.<num>.errors - Xen only: the 'oo_req' value
1991 • block.<num>.allocation - offset of highest written sector in bytes
1993 • block.<num>.capacity - logical size of source file in bytes
1995 • block.<num>.physical - physical size of source file in bytes
1997 • block.<num>.threshold - threshold (in bytes) for delivering the
1999 VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event. See domblkthreshold.
2000 --iothread returns information about IOThreads on the running guest if
2002 supported by the hypervisor.
2003 The "poll-max-ns" for each thread is the maximum nanoseconds to allow
2005 each polling interval to occur. A polling interval is a period of time
2006 allowed for a thread to process data before being the guest gives up
2007 its CPU quantum back to the host. A value set too small will not allow
2008 the IOThread to run long enough on a CPU to process data. A value set
2009 too high will consume too much CPU time per IOThread failing to allow
2010 other threads running on the CPU to get time. The polling interval is
2011 not available for statistical purposes.
2012 •
2014 iothread.count - maximum number of IOThreads in the subsequent list
2016 as unsigned int. Each IOThread in the list will will use it's
2017 iothread_id value as the <id>. There may be fewer <id> entries
2018 than the iothread.count value if the polling values are not
2019 supported.
2020 • iothread.<id>.poll-max-ns - maximum polling time in nanoseconds used
2022 by the <id> IOThread. A value of 0 (zero) indicates polling is dis‐
2023 abled.
2024 • iothread.<id>.poll-grow - polling time grow value. A value of 0
2026 (zero) growth is managed by the hypervisor.
2027 • iothread.<id>.poll-shrink - polling time shrink value. A value of
2029 (zero) indicates shrink is managed by hypervisor.
2030 --memory returns:
2032 • memory.bandwidth.monitor.count - the number of memory bandwidth moni‐
2034 tors for this domain
2035 • memory.bandwidth.monitor.<num>.name - the name of monitor <num>
2037 • memory.bandwidth.monitor.<num>.vcpus - the vcpu list of monitor <num>
2039 •
2041 memory.bandwidth.monitor.<num>.node.count - the number of memory
2043 controller in monitor <num>
2044 • memory.bandwidth.monitor.<num>.node.<index>.id - host allocated mem‐
2046 ory controller id for controller <index> of monitor <num>
2047 • memory.bandwidth.monitor.<num>.node.<index>.bytes.local - the accumu‐
2049 lative bytes consumed by @vcpus that passing through the memory con‐
2050 troller in the same processor that the scheduled host CPU belongs to.
2051 • memory.bandwidth.monitor.<num>.node.<index>.bytes.total - the total
2053 bytes consumed by @vcpus that passing through all memory controllers,
2054 either local or remote controller.
2055 Selecting a specific statistics groups doesn't guarantee that the dae‐
2057 mon supports the selected group of stats. Flag --enforce forces the
2058 command to fail if the daemon doesn't support the selected group.
2059 When collecting stats libvirtd may wait for some time if there's al‐
2061 ready another job running on given domain for it to finish. This may
2062 cause unnecessary delay in delivering stats. Using --nowait suppresses
2063 this behaviour. On the other hand some statistics might be missing for
2064 such domain.
2065 domtime
2067 Syntax:
2068 domtime domain { [--now] [--pretty] [--sync] [--time time] }
2070 Gets or sets the domain's system time. When run without any arguments
2072 (but domain), the current domain's system time is printed out. The
2073 --pretty modifier can be used to print the time in more human readable
2074 form.
2075 When --time time is specified, the domain's time is not gotten but set
2077 instead. The --now modifier acts like if it was an alias for --time
2078 $now, which means it sets the time that is currently on the host virsh
2079 is running at. In both cases (setting and getting), time is in seconds
2080 relative to Epoch of 1970-01-01 in UTC. The --sync modifies the set
2081 behavior a bit: The time passed is ignored, but the time to set is read
2082 from domain's RTC instead. Please note, that some hypervisors may re‐
2083 quire a guest agent to be configured in order to get or set the guest
2084 time.
2085 domuuid
2087 Syntax:
2088 domuuid domain-name-or-id
2090 Convert a domain name or id to domain UUID
2092 domxml-from-native
2094 Syntax:
2095 domxml-from-native format config
2097 Convert the file config in the native guest configuration format named
2099 by format to a domain XML format. For QEMU/KVM hypervisor, the format
2100 argument must be qemu-argv. For Xen hypervisor, the format argument may
2101 be xen-xm, xen-xl, or xen-sxpr. For LXC hypervisor, the format argument
2102 must be lxc-tools. For VMware/ESX hypervisor, the format argument must
2103 be vmware-vmx. For the Bhyve hypervisor, the format argument must be
2104 bhyve-argv.
2105 domxml-to-native
2107 Syntax:
2108 domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-uuid }
2110 Convert the file xml into domain XML format or convert an existing
2112 --domain to the native guest configuration format named by format. The
2113 xml and --domain arguments are mutually exclusive. For the types of
2114 format argument, refer to domxml-from-native.
2115 dump
2117 Syntax:
2118 dump domain corefilepath [--bypass-cache]
2120 { [--live] | [--crash] | [--reset] }
2121 [--verbose] [--memory-only] [--format string]
2122 Dumps the core of a domain to a file for analysis. If --live is speci‐
2124 fied, the domain continues to run until the core dump is complete,
2125 rather than pausing up front. If --crash is specified, the domain is
2126 halted with a crashed status, rather than merely left in a paused
2127 state. If --reset is specified, the domain is reset after successful
2128 dump. Note, these three switches are mutually exclusive. If --by‐
2129 pass-cache is specified, the save will avoid the file system cache, al‐
2130 though this may slow down the operation. If --memory-only is speci‐
2131 fied, the file is elf file, and will only include domain's memory and
2132 cpu common register value. It is very useful if the domain uses host
2133 devices directly. --format string is used to specify the format of
2134 'memory-only' dump, and string can be one of them: elf,
2135 kdump-zlib(kdump-compressed format with zlib-compressed),
2136 kdump-lzo(kdump-compressed format with lzo-compressed),
2137 kdump-snappy(kdump-compressed format with snappy-compressed).
2138 The progress may be monitored using domjobinfo virsh command and can‐
2140 celed with domjobabort command (sent by another virsh instance). An‐
2141 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2142 process running dump command. --verbose displays the progress of dump.
2143 NOTE: Some hypervisors may require the user to manually ensure proper
2145 permissions on file and path specified by argument corefilepath.
2146 NOTE: Crash dump in a old kvmdump format is being obsolete and cannot
2148 be loaded and processed by crash utility since its version 6.1.0. A
2149 --memory-only option is required in order to produce valid ELF file
2150 which can be later processed by the crash utility.
2151 dumpxml
2153 Syntax:
2154 dumpxml domain [--inactive] [--security-info] [--update-cpu] [--migratable]
2156 Output the domain information as an XML dump to stdout, this format can
2158 be used by the create command. Additional options affecting the XML
2159 dump may be used. --inactive tells virsh to dump domain configuration
2160 that will be used on next start of the domain as opposed to the current
2161 domain configuration. Using --security-info will also include security
2162 sensitive information in the XML dump. --update-cpu updates domain CPU
2163 requirements according to host CPU. With --migratable one can request
2164 an XML that is suitable for migrations, i.e., compatible with older
2165 libvirt releases and possibly amended with internal run-time options.
2166 This option may automatically enable other options (--update-cpu, --se‐
2167 curity-info, ...) as necessary.
2168 edit
2170 Syntax:
2171 edit domain
2173 Edit the XML configuration file for a domain, which will affect the
2175 next boot of the guest.
2176 This is equivalent to:
2178 virsh dumpxml --inactive --security-info domain > domain.xml
2180 vi domain.xml (or make changes with your other text editor)
2181 virsh define domain.xml
2182 except that it does some error checking.
2184 The editor used can be supplied by the $VISUAL or $EDITOR environment
2186 variables, and defaults to vi.
2187 emulatorpin
2189 Syntax:
2190 emulatorpin domain [cpulist] [[--live] [--config] | [--current]]
2192 Query or change the pinning of domain's emulator threads to host physi‐
2194 cal CPUs.
2195 See vcpupin for cpulist.
2197 If --live is specified, affect a running guest. If --config is speci‐
2199 fied, affect the next start of a persistent guest. If --current is
2200 specified, it is equivalent to either --live or --config, depending on
2201 the current state of the guest. Both --live and --config flags may be
2202 given if cpulist is present, but --current is exclusive. If no flag is
2203 specified, behavior is different depending on hypervisor.
2204 event
2206 Syntax:
2207 event {[domain] { event | --all } [--loop] [--timeout seconds] [--timestamp] | --list}
2209 Wait for a class of domain events to occur, and print appropriate de‐
2211 tails of events as they happen. The events can optionally be filtered
2212 by domain. Using --list as the only argument will provide a list of
2213 possible event values known by this client, although the connection
2214 might not allow registering for all these events. It is also possible
2215 to use --all instead of event to register for all possible event types
2216 at once.
2217 By default, this command is one-shot, and returns success once an event
2219 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
2220 If --timeout is specified, the command gives up waiting for events af‐
2221 ter seconds have elapsed. With --loop, the command prints all events
2222 until a timeout or interrupt key.
2223 When --timestamp is used, a human-readable timestamp will be printed
2225 before the event.
2226 get-user-sshkeys
2228 Syntax:
2229 get-user-sshkeys domain user
2231 Print SSH authorized keys for given user in the guest domain. Please
2233 note, that an entry in the file has internal structure as defined by
2234 sshd(8) and virsh/libvirt does handle keys as opaque strings, i.e. does
2235 not interpret them.
2236 guest-agent-timeout
2238 Syntax:
2239 guest-agent-timeout domain [--timeout value]
2241 Set how long to wait for a response from guest agent commands. By de‐
2243 fault, agent commands block forever waiting for a response. value must
2244 be a positive value (wait for given amount of seconds) or one of the
2245 following values:
2246 • -2 - block forever waiting for a result (used when --timeout is omit‐
2248 ted),
2249 • -1 - reset timeout to the default value (currently defined as 5 sec‐
2251 onds in libvirt daemon),
2252 • 0 - do not wait at all,
2254 guestinfo
2256 Syntax:
2257 guestinfo domain [--user] [--os] [--timezone] [--hostname] [--filesystem]
2259 [--disk]
2260 Print information about the guest from the point of view of the guest
2262 agent. Note that this command requires a guest agent to be configured
2263 and running in the domain's guest OS.
2264 When run without any arguments, this command prints all information
2266 types that are supported by the guest agent. You can limit the types of
2267 information that are returned by specifying one or more flags. If a
2268 requested information type is not supported, the processes will provide
2269 an exit code of 1. Available information types flags are --user, --os,
2270 --timezone, --hostname, --filesystem and --disk.
2271 Note that depending on the hypervisor type and the version of the guest
2273 agent running within the domain, not all of the following information
2274 may be returned.
2275 When selecting the --user information type, the following fields may be
2277 returned:
2278 • user.count - the number of active users on this domain
2280 • user.<num>.name - username of user <num>
2282 • user.<num>.domain - domain of the user <num> (may only be present on
2284 certain guets types)
2285 • user.<num>.login-time - the login time of user <num> in milliseconds
2287 since the epoch
2288 --os returns:
2290 • os.id - a string identifying the operating system
2292 • os.name - the name of the operating system
2294 • os.pretty-name - a pretty name for the operating system
2296 • os.version - the version of the operating system
2298 • os.version-id - the version id of the operating system
2300 • os.kernel-release - the release of the operating system kernel
2302 • os.kernel-version - the version of the operating system kernel
2304 • os.machine - the machine hardware name
2306 • os.variant - a specific variant or edition of the operating system
2308 • os.variant-id - the id for a specific variant or edition of the oper‐
2310 ating system
2311 --timezone returns:
2313 • timezone.name - the name of the timezone
2315 • timezone.offset - the offset to UTC in seconds
2317 --hostname returns:
2319 • hostname - the hostname of the domain
2321 --filesystem returns:
2323 • fs.count - the number of filesystems defined on this domain
2325 • fs.<num>.mountpoint - the path to the mount point for filesystem
2327 <num>
2328 • fs.<num>.name - device name in the guest (e.g. sda1) for filesystem
2330 <num>
2331 • fs.<num>.fstype - the type of filesystem <num>
2333 • fs.<num>.total-bytes - the total size of filesystem <num>
2335 • fs.<num>.used-bytes - the number of bytes used in filesystem <num>
2337 • fs.<num>.disk.count - the number of disks targeted by filesystem
2339 <num>
2340 • fs.<num>.disk.<num>.alias - the device alias of disk <num> (e.g. sda)
2342 • fs.<num>.disk.<num>.serial - the serial number of disk <num>
2344 • fs.<num>.disk.<num>.device - the device node of disk <num>
2346 --disk returns:
2348 • disk.count - the number of disks defined on this domain
2350 • disk.<num>.name - device node (Linux) or device UNC (Windows)
2352 • disk.<num>.partition - whether this is a partition or disk
2354 • disk.<num>.dependency.count - the number of device dependencies
2356 • disk.<num>.dependency.<num>.name - a dependency name
2358 • disk.<num>.alias - the device alias of the disk (e.g. sda)
2360 • disk.<num>.guest_alias - optional alias assigned to the disk
2362 guestvcpus
2364 Syntax:
2365 guestvcpus domain [[--enable] | [--disable]] [cpulist]
2367 Query or change state of vCPUs from guest's point of view using the
2369 guest agent. When invoked without cpulist the guest is queried for
2370 available guest vCPUs, their state and possibility to be offlined.
2371 If cpulist is provided then one of --enable or --disable must be pro‐
2373 vided too. The desired operation is then executed on the domain.
2374 See vcpupin for information on cpulist.
2376 iothreadadd
2378 Syntax:
2379 iothreadadd domain iothread_id [[--config] [--live] | [--current]]
2381 Add a new IOThread to the domain using the specified iothread_id. If
2383 the iothread_id already exists, the command will fail. The iothread_id
2384 must be greater than zero.
2385 If --live is specified, affect a running guest. If the guest is not
2387 running an error is returned. If --config is specified, affect the
2388 next start of a persistent guest. If --current is specified, it is
2389 equivalent to either --live or --config, depending on the current state
2390 of the guest.
2391 iothreaddel
2393 Syntax:
2394 iothreaddel domain iothread_id [[--config] [--live] | [--current]]
2396 Delete an IOThread from the domain using the specified iothread_id. If
2398 an IOThread is currently assigned to a disk resource such as via the
2399 attach-disk command, then the attempt to remove the IOThread will fail.
2400 If the iothread_id does not exist an error will occur.
2401 If --live is specified, affect a running guest. If the guest is not
2403 running an error is returned. If --config is specified, affect the
2404 next start of a persistent guest. If --current is specified, it is
2405 equivalent to either --live or --config, depending on the current state
2406 of the guest.
2407 iothreadinfo
2409 Syntax:
2410 iothreadinfo domain [[--live] [--config] | [--current]]
2412 Display basic domain IOThreads information including the IOThread ID
2414 and the CPU Affinity for each IOThread.
2415 If --live is specified, get the IOThreads data from the running guest.
2417 If the guest is not running, an error is returned. If --config is
2418 specified, get the IOThreads data from the next start of a persistent
2419 guest. If --current is specified or --live and --config are not speci‐
2420 fied, then get the IOThread data based on the current guest state,
2421 which can either be live or offline.
2422 iothreadpin
2424 Syntax:
2425 iothreadpin domain iothread cpulist [[--live] [--config] | [--current]]
2427 Change the pinning of a domain IOThread to host physical CPUs. In order
2429 to retrieve a list of all IOThreads, use iothreadinfo. To pin an io‐
2430 thread specify the cpulist desired for the IOThread ID as listed in the
2431 iothreadinfo output.
2432 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
2434 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
2435 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
2436 clusive. If you want to reset iothreadpin setting, that is, to pin an
2437 iothread to all physical cpus, simply specify 'r' as a cpulist.
2438 If --live is specified, affect a running guest. If the guest is not
2440 running, an error is returned. If --config is specified, affect the
2441 next start of a persistent guest. If --current is specified, it is
2442 equivalent to either --live or --config, depending on the current state
2443 of the guest. Both --live and --config flags may be given if cpulist
2444 is present, but --current is exclusive. If no flag is specified, be‐
2445 havior is different depending on hypervisor.
2446 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
2448 cal to "9-14,0-7,15" but not identical to "^8,0-15".
2449 iothreadset
2451 Syntax:
2452 iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor]
2454 [--poll-shrink divisor]]
2455 [[--config] [--live] | [--current]]
2456 Modifies an existing iothread of the domain using the specified io‐
2458 thread_id. The --poll-max-ns provides the maximum polling interval to
2459 be allowed for an IOThread in ns. If a 0 (zero) is provided, then
2460 polling for the IOThread is disabled. The --poll-grow is the factor by
2461 which the current polling time will be adjusted in order to reach the
2462 maximum polling time. If a 0 (zero) is provided, then the default fac‐
2463 tor will be used. The --poll-shrink is the quotient by which the cur‐
2464 rent polling time will be reduced in order to get below the maximum
2465 polling interval. If a 0 (zero) is provided, then the default quotient
2466 will be used. The polling values are purely dynamic for a running
2467 guest. Saving, destroying, stopping, etc. the guest will result in the
2468 polling values returning to hypervisor defaults at the next start, re‐
2469 store, etc.
2470 If --live is specified, affect a running guest. If the guest is not
2472 running an error is returned. If --current is specified or --live is
2473 not specified, then handle as if --live was specified. (Where "cur‐
2474 rent" here means whatever the present guest state is: live or offline.)
2475 managedsave
2477 Syntax:
2478 managedsave domain [--bypass-cache] [{--running | --paused}] [--verbose]
2480 Save and destroy (stop) a running domain, so it can be restarted from
2482 the same state at a later time. When the virsh start command is next
2483 run for the domain, it will automatically be started from this saved
2484 state. If --bypass-cache is specified, the save will avoid the file
2485 system cache, although this may slow down the operation.
2486 The progress may be monitored using domjobinfo virsh command and can‐
2488 celed with domjobabort command (sent by another virsh instance). An‐
2489 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2490 process running managedsave command. --verbose displays the progress of
2491 save.
2492 Normally, starting a managed save will decide between running or paused
2494 based on the state the domain was in when the save was done; passing
2495 either the --running or --paused flag will allow overriding which state
2496 the start should use.
2497 The dominfo command can be used to query whether a domain currently has
2499 any managed save image.
2500 managedsave-define
2502 Syntax:
2503 managedsave-define domain xml [{--running | --paused}]
2505 Update the domain XML that will be used when domain is later started.
2507 The xml argument must be a file name containing the alternative XML,
2508 with changes only in the host-specific portions of the domain XML. For
2509 example, it can be used to change disk file paths.
2510 The managed save image records whether the domain should be started to
2512 a running or paused state. Normally, this command does not alter the
2513 recorded state; passing either the --running or --paused flag will al‐
2514 low overriding which state the start should use.
2515 managedsave-dumpxml
2517 Syntax:
2518 managedsave-dumpxml domain [--security-info]
2520 Extract the domain XML that was in effect at the time the saved state
2522 file file was created with the managedsave command. Using --secu‐
2523 rity-info will also include security sensitive information.
2524 managedsave-edit
2526 Syntax:
2527 managedsave-edit domain [{--running | --paused}]
2529 Edit the XML configuration associated with a saved state file of a do‐
2531 main was created by the managedsave command.
2532 The managed save image records whether the domain should be started to
2534 a running or paused state. Normally, this command does not alter the
2535 recorded state; passing either the --running or --paused flag will al‐
2536 low overriding which state the restore should use.
2537 This is equivalent to:
2539 virsh managedsave-dumpxml domain-name > state-file.xml
2541 vi state-file.xml (or make changes with your other text editor)
2542 virsh managedsave-define domain-name state-file-xml
2543 except that it does some error checking.
2545 The editor used can be supplied by the $VISUAL or $EDITOR environment
2547 variables, and defaults to vi.
2548 managedsave-remove
2550 Syntax:
2551 managedsave-remove domain
2553 Remove the managedsave state file for a domain, if it exists. This en‐
2555 sures the domain will do a full boot the next time it is started.
2556 maxvcpus
2558 Syntax:
2559 maxvcpus [type]
2561 Provide the maximum number of virtual CPUs supported for a guest VM on
2563 this connection. If provided, the type parameter must be a valid type
2564 attribute for the <domain> element of XML.
2565 memtune
2567 Syntax:
2568 memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-limit size]
2570 [--min-guarantee size] [[--config] [--live] | [--current]]
2571 Allows you to display or set the domain memory parameters. Without
2573 flags, the current settings are displayed; with a flag, the appropriate
2574 limit is adjusted if supported by the hypervisor. LXC and QEMU/KVM
2575 support --hard-limit, --soft-limit, and --swap-hard-limit. --min-guar‐
2576 antee is supported only by ESX hypervisor. Each of these limits are
2577 scaled integers (see NOTES above), with a default of kibibytes (blocks
2578 of 1024 bytes) if no suffix is present. Libvirt rounds up to the near‐
2579 est kibibyte. Some hypervisors require a larger granularity than KiB,
2580 and requests that are not an even multiple will be rounded up. For ex‐
2581 ample, vSphere/ESX rounds the parameter up to mebibytes (1024
2582 kibibytes).
2583 If --live is specified, affect a running guest. If --config is speci‐
2585 fied, affect the next start of a persistent guest. If --current is
2586 specified, it is equivalent to either --live or --config, depending on
2587 the current state of the guest. Both --live and --config flags may be
2588 given, but --current is exclusive. If no flag is specified, behavior is
2589 different depending on hypervisor.
2590 For QEMU/KVM, the parameters are applied to the QEMU process as a
2592 whole. Thus, when counting them, one needs to add up guest RAM, guest
2593 video RAM, and some memory overhead of QEMU itself. The last piece is
2594 hard to determine so one needs guess and try.
2595 For LXC, the displayed hard_limit value is the current memory setting
2597 from the XML or the results from a virsh setmem command.
2598 • --hard-limit
2600 The maximum memory the guest can use.
2602 • --soft-limit
2604 The memory limit to enforce during memory contention.
2606 • --swap-hard-limit
2608 The maximum memory plus swap the guest can use. This has to be more
2610 than hard-limit value provided.
2611 • --min-guarantee
2613 The guaranteed minimum memory allocation for the guest.
2615 Specifying -1 as a value for these limits is interpreted as unlimited.
2617 metadata
2619 Syntax:
2620 metadata domain [[--live] [--config] | [--current]]
2622 [--edit] [uri] [key] [set] [--remove]
2623 Show or modify custom XML metadata of a domain. The metadata is a user
2625 defined XML that allows storing arbitrary XML data in the domain defi‐
2626 nition. Multiple separate custom metadata pieces can be stored in the
2627 domain XML. The pieces are identified by a private XML namespace pro‐
2628 vided via the uri argument. (See also desc that works with textual
2629 metadata of a domain.)
2630 Flags --live or --config select whether this command works on live or
2632 persistent definitions of the domain. If both --live and --config are
2633 specified, the --config option takes precedence on getting the current
2634 description and both live configuration and config are updated while
2635 setting the description. --current is exclusive and implied if none of
2636 these was specified.
2637 Flag --remove specifies that the metadata element specified by the uri
2639 argument should be removed rather than updated.
2640 Flag --edit specifies that an editor with the metadata identified by
2642 the uri argument should be opened and the contents saved back after‐
2643 wards. Otherwise the new contents can be provided via the set argu‐
2644 ment.
2645 When setting metadata via --edit or set the key argument must be speci‐
2647 fied and is used to prefix the custom elements to bind them to the pri‐
2648 vate namespace.
2649 If neither of --edit and set are specified the XML metadata correspond‐
2651 ing to the uri namespace is displayed instead of being modified.
2652 migrate
2654 Syntax:
2655 migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]]
2657 [--persistent] [--undefinesource] [--suspend] [--copy-storage-all]
2658 [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose]
2659 [--rdma-pin-all] [--abort-on-error] [--postcopy] [--postcopy-after-precopy]
2660 domain desturi [migrateuri] [graphicsuri] [listen-address] [dname]
2661 [--timeout seconds [--timeout-suspend | --timeout-postcopy]]
2662 [--xml file] [--migrate-disks disk-list] [--disks-port port]
2663 [--compressed] [--comp-methods method-list]
2664 [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads]
2665 [--comp-xbzrle-cache] [--auto-converge] [auto-converge-initial]
2666 [auto-converge-increment] [--persistent-xml file] [--tls]
2667 [--postcopy-bandwidth bandwidth]
2668 [--parallel [--parallel-connections connections]]
2669 [--bandwidth bandwidth] [--tls-destination hostname]
2670 [--disks-uri URI]
2671 Migrate domain to another host. Add --live for live migration; <--p2p>
2673 for peer-2-peer migration; --direct for direct migration; or --tun‐
2674 nelled for tunnelled migration. --offline migrates domain definition
2675 without starting the domain on destination and without stopping it on
2676 source host. Offline migration may be used with inactive domains and
2677 it must be used with --persistent option. --persistent leaves the do‐
2678 main persistent on destination host, --undefinesource undefines the do‐
2679 main on the source host, and --suspend leaves the domain paused on the
2680 destination host. --copy-storage-all indicates migration with
2681 non-shared storage with full disk copy, --copy-storage-inc indicates
2682 migration with non-shared storage with incremental copy (same base im‐
2683 age shared between source and destination). In both cases the disk im‐
2684 ages have to exist on destination host, the --copy-storage-... options
2685 only tell libvirt to transfer data from the images on source host to
2686 the images found at the same place on the destination host. By default
2687 only non-shared non-readonly images are transferred. Use --mi‐
2688 grate-disks to explicitly specify a list of disk targets to transfer
2689 via the comma separated disk-list argument. --change-protection en‐
2690 forces that no incompatible configuration changes will be made to the
2691 domain while the migration is underway; this flag is implicitly enabled
2692 when supported by the hypervisor, but can be explicitly used to reject
2693 the migration if the hypervisor lacks change protection support.
2694 --verbose displays the progress of migration. --abort-on-error cancels
2695 the migration if a soft error (for example I/O error) happens during
2696 the migration. --postcopy enables post-copy logic in migration, but
2697 does not actually start post-copy, i.e., migration is started in
2698 pre-copy mode. Once migration is running, the user may switch to
2699 post-copy using the migrate-postcopy command sent from another virsh
2700 instance or use --postcopy-after-precopy along with --postcopy to let
2701 libvirt automatically switch to post-copy after the first pass of
2702 pre-copy is finished. The maximum bandwidth consumed during the
2703 post-copy phase may be limited using --postcopy-bandwidth. The maximum
2704 bandwidth consumed during the pre-copy phase may be limited using
2705 --bandwidth.
2706 --auto-converge forces convergence during live migration. The initial
2708 guest CPU throttling rate can be set with auto-converge-initial. If the
2709 initial throttling rate is not enough to ensure convergence, the rate
2710 is periodically increased by auto-converge-increment.
2711 --rdma-pin-all can be used with RDMA migration (i.e., when migrateuri
2713 starts with rdma://) to tell the hypervisor to pin all domain's memory
2714 at once before migration starts rather than letting it pin memory pages
2715 as needed. For QEMU/KVM this requires hard_limit memory tuning element
2716 (in the domain XML) to be used and set to the maximum memory configured
2717 for the domain plus any memory consumed by the QEMU process itself. Be‐
2718 ware of setting the memory limit too high (and thus allowing the domain
2719 to lock most of the host's memory). Doing so may be dangerous to both
2720 the domain and the host itself since the host's kernel may run out of
2721 memory.
2722 Note: Individual hypervisors usually do not support all possible types
2724 of migration. For example, QEMU does not support direct migration.
2725 In some cases libvirt may refuse to migrate the domain because doing so
2727 may lead to potential problems such as data corruption, and thus the
2728 migration is considered unsafe. For QEMU domain, this may happen if the
2729 domain uses disks without explicitly setting cache mode to "none". Mi‐
2730 grating such domains is unsafe unless the disk images are stored on co‐
2731 herent clustered filesystem, such as GFS2 or GPFS. If you are sure the
2732 migration is safe or you just do not care, use --unsafe to force the
2733 migration.
2734 dname is used for renaming the domain to new name during migration,
2736 which also usually can be omitted. Likewise, --xml file is usually
2737 omitted, but can be used to supply an alternative XML file for use on
2738 the destination to supply a larger set of changes to any host-specific
2739 portions of the domain XML, such as accounting for naming differences
2740 between source and destination in accessing underlying storage. If
2741 --persistent is enabled, --persistent-xml file can be used to supply an
2742 alternative XML file which will be used as the persistent guest defini‐
2743 tion on the destination host.
2744 --timeout seconds tells virsh to run a specified action when live mi‐
2746 gration exceeds that many seconds. It can only be used with --live.
2747 If --timeout-suspend is specified, the domain will be suspended after
2748 the timeout and the migration will complete offline; this is the de‐
2749 fault if no --timeout-\`` option is specified on the command line.
2750 When *--timeout-postcopy is used, virsh will switch migration from
2751 pre-copy to post-copy upon timeout; migration has to be started with
2752 --postcopy option for this to work.
2753 --compressed activates compression, the compression method is chosen
2755 with --comp-methods. Supported methods are "mt" and "xbzrle" and can be
2756 used in any combination. When no methods are specified, a hypervisor
2757 default methods will be used. QEMU defaults to "xbzrle". Compression
2758 methods can be tuned further. --comp-mt-level sets compression level.
2759 Values are in range from 0 to 9, where 1 is maximum speed and 9 is max‐
2760 imum compression. --comp-mt-threads and --comp-mt-dthreads set the num‐
2761 ber of compress threads on source and the number of decompress threads
2762 on target respectively. --comp-xbzrle-cache sets size of page cache in
2763 bytes.
2764 Providing --tls causes the migration to use the host configured TLS
2766 setup (see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in or‐
2767 der to perform the migration of the domain. Usage requires proper TLS
2768 setup for both source and target. Normally the TLS certificate from the
2769 destination host must match the host's name for TLS verification to
2770 succeed. When the certificate does not match the destination hostname
2771 and the expected certificate's hostname is known, --tls-destination can
2772 be used to pass the expected hostname when starting the migration.
2773 --parallel option will cause migration data to be sent over multiple
2775 parallel connections. The number of such connections can be set using
2776 --parallel-connections. Parallel connections may help with saturating
2777 the network link between the source and the target and thus speeding up
2778 the migration.
2779 Running migration can be canceled by interrupting virsh (usually using
2781 Ctrl-C) or by domjobabort command sent from another virsh instance.
2782 The desturi and migrateuri parameters can be used to control which des‐
2784 tination the migration uses. desturi is important for managed migra‐
2785 tion, but unused for direct migration; migrateuri is required for di‐
2786 rect migration, but can usually be automatically determined for managed
2787 migration.
2788 Note: The desturi parameter for normal migration and peer2peer migra‐
2790 tion has different semantics:
2791 • normal migration: the desturi is an address of the target host as
2793 seen from the client machine.
2794 • peer2peer migration: the desturi is an address of the target host as
2796 seen from the source machine.
2797 In a special circumstance where you require a complete control of the
2799 connection and/or libvirt does not have network access to the remote
2800 side you can use a UNIX transport in the URI and specify a socket path
2801 in the query, for example with the qemu driver you could use this:
2802 qemu+unix:///system?socket=/path/to/socket
2804 When migrateuri is not specified, libvirt will automatically determine
2806 the hypervisor specific URI. Some hypervisors, including QEMU, have an
2807 optional "migration_host" configuration parameter (useful when the host
2808 has multiple network interfaces). If this is unspecified, libvirt de‐
2809 termines a name by looking up the target host's configured hostname.
2810 There are a few scenarios where specifying migrateuri may help:
2812 • The configured hostname is incorrect, or DNS is broken. If a host
2814 has a hostname which will not resolve to match one of its public IP
2815 addresses, then libvirt will generate an incorrect URI. In this case
2816 migrateuri should be explicitly specified, using an IP address, or a
2817 correct hostname.
2818 • The host has multiple network interfaces. If a host has multiple
2820 network interfaces, it might be desirable for the migration data
2821 stream to be sent over a specific interface for either security or
2822 performance reasons. In this case migrateuri should be explicitly
2823 specified, using an IP address associated with the network to be
2824 used.
2825 • The firewall restricts what ports are available. When libvirt gener‐
2827 ates a migration URI, it will pick a port number using hypervisor
2828 specific rules. Some hypervisors only require a single port to be
2829 open in the firewalls, while others require a whole range of port
2830 numbers. In the latter case migrateuri might be specified to choose
2831 a specific port number outside the default range in order to comply
2832 with local firewall policies.
2833 • The desturi uses UNIX transport method. In this advanced case lib‐
2835 virt should not guess a migrateuri and it should be specified using
2836 UNIX socket path URI:
2837 unix:///path/to/socket
2839 See https://libvirt.org/migration.html#uris for more details on migra‐
2841 tion URIs.
2842 Optional graphicsuri overrides connection parameters used for automati‐
2844 cally reconnecting a graphical clients at the end of migration. If
2845 omitted, libvirt will compute the parameters based on target host IP
2846 address. In case the client does not have a direct access to the net‐
2847 work virtualization hosts are connected to and needs to connect through
2848 a proxy, graphicsuri may be used to specify the address the client
2849 should connect to. The URI is formed as follows:
2850 protocol://hostname[:port]/[?parameters]
2852 where protocol is either "spice" or "vnc" and parameters is a list of
2854 protocol specific parameters separated by '&'. Currently recognized pa‐
2855 rameters are "tlsPort" and "tlsSubject". For example,
2856 spice://target.host.com:1234/?tlsPort=4567
2858 Optional listen-address sets the listen address that hypervisor on the
2860 destination side should bind to for incoming migration. Both IPv4 and
2861 IPv6 addresses are accepted as well as hostnames (the resolving is done
2862 on destination). Some hypervisors do not support specifying the listen
2863 address and will return an error if this parameter is used. This param‐
2864 eter cannot be used if desturi uses UNIX transport method.
2865 Optional disks-port sets the port that hypervisor on destination side
2867 should bind to for incoming disks traffic. Currently it is supported
2868 only by QEMU.
2869 Optional disks-uri can also be specified (mutually exclusive with
2871 disks-port) to specify what the remote hypervisor should bind/connect
2872 to when migrating disks. This can be tcp://address:port to specify a
2873 listen address (which overrides --migrate-uri and --listen-address for
2874 the disk migration) and a port or unix:///path/to/socket in case you
2875 need the disk migration to happen over a UNIX socket with that speci‐
2876 fied path. In this case you need to make sure the same socket path is
2877 accessible to both source and destination hypervisors and connecting to
2878 the socket on the source (after hypervisor creates it on the destina‐
2879 tion) will actually connect to the destination. If you are using
2880 SELinux (at least on the source host) you need to make sure the socket
2881 on the source is accessible to libvirtd/QEMU for connection. Libvirt
2882 cannot change the context of the existing socket because it is differ‐
2883 ent from the file representation of the socket and the context is cho‐
2884 sen by its creator (usually by using setsockcreatecon{,_raw}() func‐
2885 tions).
2886 migrate-compcache
2888 Syntax:
2889 migrate-compcache domain [--size bytes]
2891 Sets and/or gets size of the cache (in bytes) used for compressing re‐
2893 peatedly transferred memory pages during live migration. When called
2894 without size, the command just prints current size of the compression
2895 cache. When size is specified, the hypervisor is asked to change com‐
2896 pression cache to size bytes and then the current size is printed (the
2897 result may differ from the requested size due to rounding done by the
2898 hypervisor). The size option is supposed to be used while the domain is
2899 being live-migrated as a reaction to migration progress and increasing
2900 number of compression cache misses obtained from domjobinfo.
2901 migrate-getmaxdowntime
2903 Syntax:
2904 migrate-getmaxdowntime domain
2906 Get the maximum tolerable downtime for a domain which is being live-mi‐
2908 grated to another host. This is the number of milliseconds the guest
2909 is allowed to be down at the end of live migration.
2910 migrate-getspeed
2912 Syntax:
2913 migrate-getspeed domain [--postcopy]
2915 Get the maximum migration bandwidth (in MiB/s) for a domain. If the
2917 --postcopy option is specified, the command will get the maximum band‐
2918 width allowed during a post-copy migration phase.
2919 migrate-postcopy
2921 Syntax:
2922 migrate-postcopy domain
2924 Switch the current migration from pre-copy to post-copy. This is only
2926 supported for a migration started with --postcopy option.
2927 migrate-setmaxdowntime
2929 Syntax:
2930 migrate-setmaxdowntime domain downtime
2932 Set maximum tolerable downtime for a domain which is being live-mi‐
2934 grated to another host. The downtime is a number of milliseconds the
2935 guest is allowed to be down at the end of live migration.
2936 migrate-setspeed
2938 Syntax:
2939 migrate-setspeed domain bandwidth [--postcopy]
2941 Set the maximum migration bandwidth (in MiB/s) for a domain which is
2943 being migrated to another host. bandwidth is interpreted as an unsigned
2944 long long value. Specifying a negative value results in an essentially
2945 unlimited value being provided to the hypervisor. The hypervisor can
2946 choose whether to reject the value or convert it to the maximum value
2947 allowed. If the --postcopy option is specified, the command will set
2948 the maximum bandwidth allowed during a post-copy migration phase.
2949 numatune
2951 Syntax:
2952 numatune domain [--mode mode] [--nodeset nodeset]
2954 [[--config] [--live] | [--current]]
2955 Set or get a domain's numa parameters, corresponding to the <numatune>
2957 element of domain XML. Without flags, the current settings are dis‐
2958 played.
2959 mode can be one of `strict', `interleave' and `preferred' or any valid
2961 number from the virDomainNumatuneMemMode enum in case the daemon sup‐
2962 ports it. For a running domain, the mode can't be changed, and the
2963 nodeset can be changed only if the domain was started with a mode of
2964 `strict'.
2965 nodeset is a list of numa nodes used by the host for running the do‐
2967 main. Its syntax is a comma separated list, with '-' for ranges and
2968 '^' for excluding a node.
2969 If --live is specified, set scheduler information of a running guest.
2971 If --config is specified, affect the next start of a persistent guest.
2972 If --current is specified, it is equivalent to either --live or --con‐
2973 fig, depending on the current state of the guest.
2974 For running guests in Linux hosts, the changes made in the domain's
2976 numa parameters does not imply that the guest memory will be moved to a
2977 different nodeset immediately. The memory migration depends on the
2978 guest activity, and the memory of an idle guest will remain in its pre‐
2979 vious nodeset for longer. The presence of VFIO devices will also lock
2980 parts of the guest memory in the same nodeset used to start the guest,
2981 regardless of nodeset changes.
2982 perf
2984 Syntax:
2985 perf domain [--enable eventSpec] [--disable eventSpec]
2987 [[--config] [--live] | [--current]]
2988 Get the current perf events setting or enable/disable specific perf
2990 events for a guest domain.
2991 Perf is a performance analyzing tool in Linux, and it can instrument
2993 CPU performance counters, tracepoints, kprobes, and uprobes (dynamic
2994 tracing). Perf supports a list of measurable events, and can measure
2995 events coming from different sources. For instance, some event are pure
2996 kernel counters, in this case they are called software events, includ‐
2997 ing context-switches, minor-faults, etc.. Now dozens of events from
2998 different sources can be supported by perf.
2999 Currently only QEMU/KVM supports this command. The --enable and --dis‐
3001 able option combined with eventSpec can be used to enable or disable
3002 specific performance event. eventSpec is a string list of one or more
3003 events separated by commas. Valid event names are as follows:
3004 Valid perf event names
3006 • cmt - A PQos (Platform Qos) feature to monitor the usage of cache by
3008 applications running on the platform.
3009 • mbmt - Provides a way to monitor the total system memory bandwidth
3011 between one level of cache and another.
3012 • mbml - Provides a way to limit the amount of data (bytes/s) send
3014 through the memory controller on the socket.
3015 • cache_misses - Provides the count of cache misses by applications
3017 running on the platform.
3018 • cache_references - Provides the count of cache hits by applications
3020 running on th e platform.
3021 • instructions - Provides the count of instructions executed by appli‐
3023 cations running on the platform.
3024 • cpu_cycles - Provides the count of cpu cycles (total/elapsed). May be
3026 used with instructions in order to get a cycles per instruction.
3027 • branch_instructions - Provides the count of branch instructions exe‐
3029 cuted by applications running on the platform.
3030 • branch_misses - Provides the count of branch misses executed by ap‐
3032 plications running on the platform.
3033 • bus_cycles - Provides the count of bus cycles executed by applica‐
3035 tions running on the platform.
3036 • stalled_cycles_frontend - Provides the count of stalled cpu cycles in
3038 the frontend of the instruction processor pipeline by applications
3039 running on the platform.
3040 • stalled_cycles_backend - Provides the count of stalled cpu cycles in
3042 the backend of the instruction processor pipeline by applications
3043 running on the platform.
3044 • ref_cpu_cycles - Provides the count of total cpu cycles not affected
3046 by CPU frequency scaling by applications running on the platform.
3047 • cpu_clock - Provides the cpu clock time consumed by applications run‐
3049 ning on the platform.
3050 • task_clock - Provides the task clock time consumed by applications
3052 running on the platform.
3053 • page_faults - Provides the count of page faults by applications run‐
3055 ning on the platform.
3056 • context_switches - Provides the count of context switches by applica‐
3058 tions running on the platform.
3059 • cpu_migrations - Provides the count cpu migrations by applications
3061 running on the platform.
3062 • page_faults_min - Provides the count minor page faults by applica‐
3064 tions running on the platform.
3065 • page_faults_maj - Provides the count major page faults by applica‐
3067 tions running on the platform.
3068 • alignment_faults - Provides the count alignment faults by applica‐
3070 tions running on the platform.
3071 • emulation_faults - Provides the count emulation faults by applica‐
3073 tions running on the platform.
3074 Note: The statistics can be retrieved using the domstats command using
3076 the --perf flag.
3077 If --live is specified, affect a running guest. If --config is speci‐
3079 fied, affect the next start of a persistent guest. If --current is
3080 specified, it is equivalent to either --live or --config, depending on
3081 the current state of the guest. Both --live and --config flags may be
3082 given, but --current is exclusive. If no flag is specified, behavior is
3083 different depending on hypervisor.
3084 reboot
3086 Syntax:
3087 reboot domain [--mode MODE-LIST]
3089 Reboot a domain. This acts just as if the domain had the reboot com‐
3091 mand run from the console. The command returns as soon as it has exe‐
3092 cuted the reboot action, which may be significantly before the domain
3093 actually reboots.
3094 The exact behavior of a domain when it reboots is set by the on_reboot
3096 parameter in the domain's XML definition.
3097 By default the hypervisor will try to pick a suitable shutdown method.
3099 To specify an alternative method, the --mode parameter can specify a
3100 comma separated list which includes acpi, agent, initctl, signal and
3101 paravirt. The order in which drivers will try each mode is undefined,
3102 and not related to the order specified to virsh. For strict control
3103 over ordering, use a single mode at a time and repeat the command.
3104 reset
3106 Syntax:
3107 reset domain
3109 Reset a domain immediately without any guest shutdown. reset emulates
3111 the power reset button on a machine, where all guest hardware sees the
3112 RST line set and reinitializes internal state.
3113 Note: Reset without any guest OS shutdown risks data loss.
3115 restore
3117 Syntax:
3118 restore state-file [--bypass-cache] [--xml file]
3120 [{--running | --paused}]
3121 Restores a domain from a virsh save state file. See save for more info.
3123 If --bypass-cache is specified, the restore will avoid the file system
3125 cache, although this may slow down the operation.
3126 --xml file is usually omitted, but can be used to supply an alternative
3128 XML file for use on the restored guest with changes only in the
3129 host-specific portions of the domain XML. For example, it can be used
3130 to account for file naming differences in underlying storage due to
3131 disk snapshots taken after the guest was saved.
3132 Normally, restoring a saved image will use the state recorded in the
3134 save image to decide between running or paused; passing either the
3135 --running or --paused flag will allow overriding which state the domain
3136 should be started in.
3137 Note: To avoid corrupting file system contents within the domain, you
3139 should not reuse the saved state file for a second restore unless you
3140 have also reverted all storage volumes back to the same contents as
3141 when the state file was created.
3142 resume
3144 Syntax:
3145 resume domain
3147 Moves a domain out of the suspended state. This will allow a previ‐
3149 ously suspended domain to now be eligible for scheduling by the under‐
3150 lying hypervisor.
3151 save
3153 Syntax:
3154 save domain state-file [--bypass-cache] [--xml file]
3156 [{--running | --paused}] [--verbose]
3157 Saves a running domain (RAM, but not disk state) to a state file so
3159 that it can be restored later. Once saved, the domain will no longer
3160 be running on the system, thus the memory allocated for the domain will
3161 be free for other domains to use. virsh restore restores from this
3162 state file. If --bypass-cache is specified, the save will avoid the
3163 file system cache, although this may slow down the operation.
3164 The progress may be monitored using domjobinfo virsh command and can‐
3166 celed with domjobabort command (sent by another virsh instance). An‐
3167 other option is to send SIGINT (usually with Ctrl-C) to the virsh
3168 process running save command. --verbose displays the progress of save.
3169 This is roughly equivalent to doing a hibernate on a running computer,
3171 with all the same limitations. Open network connections may be severed
3172 upon restore, as TCP timeouts may have expired.
3173 --xml file is usually omitted, but can be used to supply an alternative
3175 XML file for use on the restored guest with changes only in the
3176 host-specific portions of the domain XML. For example, it can be used
3177 to account for file naming differences that are planned to be made via
3178 disk snapshots of underlying storage after the guest is saved.
3179 Normally, restoring a saved image will decide between running or paused
3181 based on the state the domain was in when the save was done; passing
3182 either the --running or --paused flag will allow overriding which state
3183 the restore should use.
3184 Domain saved state files assume that disk images will be unchanged be‐
3186 tween the creation and restore point. For a more complete system re‐
3187 store point, where the disk state is saved alongside the memory state,
3188 see the snapshot family of commands.
3189 save-image-define
3191 Syntax:
3192 save-image-define file xml [{--running | --paused}]
3194 Update the domain XML that will be used when file is later used in the
3196 restore command. The xml argument must be a file name containing the
3197 alternative XML, with changes only in the host-specific portions of the
3198 domain XML. For example, it can be used to account for file naming
3199 differences resulting from creating disk snapshots of underlying stor‐
3200 age after the guest was saved.
3201 The save image records whether the domain should be restored to a run‐
3203 ning or paused state. Normally, this command does not alter the
3204 recorded state; passing either the --running or --paused flag will al‐
3205 low overriding which state the restore should use.
3206 save-image-dumpxml
3208 Syntax:
3209 save-image-dumpxml file [--security-info]
3211 Extract the domain XML that was in effect at the time the saved state
3213 file file was created with the save command. Using --security-info
3214 will also include security sensitive information.
3215 save-image-edit
3217 Syntax:
3218 save-image-edit file [{--running | --paused}]
3220 Edit the XML configuration associated with a saved state file file cre‐
3222 ated by the save command.
3223 The save image records whether the domain should be restored to a run‐
3225 ning or paused state. Normally, this command does not alter the
3226 recorded state; passing either the --running or --paused flag will al‐
3227 low overriding which state the restore should use.
3228 This is equivalent to:
3230 virsh save-image-dumpxml state-file > state-file.xml
3232 vi state-file.xml (or make changes with your other text editor)
3233 virsh save-image-define state-file state-file-xml
3234 except that it does some error checking.
3236 The editor used can be supplied by the $VISUAL or $EDITOR environment
3238 variables, and defaults to vi.
3239 schedinfo
3241 Syntax:
3242 schedinfo domain [[--config] [--live] | [--current]] [[--set] parameter=value]...
3244 schedinfo [--weight number] [--cap number] domain
3245 Allows you to show (and set) the domain scheduler parameters. The pa‐
3247 rameters available for each hypervisor are:
3248 LXC (posix scheduler) : cpu_shares, vcpu_period, vcpu_quota
3250 QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota, emula‐
3252 tor_period, emulator_quota, global_period, global_quota, iothread_pe‐
3253 riod, iothread_quota
3254 Xen (credit scheduler): weight, cap
3256 ESX (allocation scheduler): reservation, limit, shares
3258 If --live is specified, set scheduler information of a running guest.
3260 If --config is specified, affect the next start of a persistent guest.
3261 If --current is specified, it is equivalent to either --live or --con‐
3262 fig, depending on the current state of the guest.
3263 Note: The cpu_shares parameter has a valid value range of 0-262144;
3265 Negative values are wrapped to positive, and larger values are capped
3266 at the maximum. Therefore, -1 is a useful shorthand for 262144. On the
3267 Linux kernel, the values 0 and 1 are automatically converted to a mini‐
3268 mal value of 2.
3269 Note: The weight and cap parameters are defined only for the XEN_CREDIT
3271 scheduler.
3272 Note: The vcpu_period, emulator_period, and iothread_period parameters
3274 have a valid value range of 1000-1000000 or 0, and the vcpu_quota, emu‐
3275 lator_quota, and iothread_quota parameters have a valid value range of
3276 1000-18446744073709551 or less than 0. The value 0 for either parameter
3277 is the same as not specifying that parameter.
3278 screenshot
3280 Syntax:
3281 screenshot domain [imagefilepath] [--screen screenID]
3283 Takes a screenshot of a current domain console and stores it into a
3285 file. Optionally, if the hypervisor supports more displays for a do‐
3286 main, screenID allows specifying which screen will be captured. It is
3287 the sequential number of screen. In case of multiple graphics cards,
3288 heads are enumerated before devices, e.g. having two graphics cards,
3289 both with four heads, screen ID 5 addresses the second head on the sec‐
3290 ond card.
3291 send-key
3293 Syntax:
3294 send-key domain [--codeset codeset] [--holdtime holdtime] keycode...
3296 Parse the keycode sequence as keystrokes to send to domain. Each key‐
3298 code can either be a numeric value or a symbolic name from the corre‐
3299 sponding codeset. If --holdtime is given, each keystroke will be held
3300 for that many milliseconds. The default codeset is linux, but use of
3301 the --codeset option allows other codesets to be chosen.
3302 If multiple keycodes are specified, they are all sent simultaneously to
3304 the guest, and they may be received in random order. If you need dis‐
3305 tinct keypresses, you must use multiple send-key invocations.
3306 • linux
3308 The numeric values are those defined by the Linux generic input event
3310 subsystem. The symbolic names match the corresponding Linux key con‐
3311 stant macro names.
3312 See virkeycode-linux(7) and virkeyname-linux(7)
3314 • xt
3316 The numeric values are those defined by the original XT keyboard con‐
3318 troller. No symbolic names are provided
3319 See virkeycode-xt(7)
3321 • atset1
3323 The numeric values are those defined by the AT keyboard controller,
3325 set 1 (aka XT compatible set). Extended keycoes from atset1 may dif‐
3326 fer from extended keycodes in the xt codeset. No symbolic names are
3327 provided
3328 See virkeycode-atset1(7)
3330 • atset2
3332 The numeric values are those defined by the AT keyboard controller,
3334 set 2. No symbolic names are provided
3335 See virkeycode-atset2(7)
3337 • atset3
3339 The numeric values are those defined by the AT keyboard controller,
3341 set 3 (aka PS/2 compatible set). No symbolic names are provided
3342 See virkeycode-atset3(7)
3344 • os_x
3346 The numeric values are those defined by the macOS keyboard input sub‐
3348 system. The symbolic names match the corresponding macOS key constant
3349 macro names
3350 See virkeycode-osx(7) and virkeyname-osx(7)
3352 • xt_kbd
3354 The numeric values are those defined by the Linux KBD device. These
3356 are a variant on the original XT codeset, but often with different
3357 encoding for extended keycodes. No symbolic names are provided.
3358 See virkeycode-xtkbd(7)
3360 • win32
3362 The numeric values are those defined by the Win32 keyboard input sub‐
3364 system. The symbolic names match the corresponding Win32 key constant
3365 macro names
3366 See virkeycode-win32(7) and virkeyname-win32(7)
3368 • usb
3370 The numeric values are those defined by the USB HID specification for
3372 keyboard input. No symbolic names are provided
3373 See virkeycode-usb(7)
3375 • qnum
3377 The numeric values are those defined by the QNUM extension for send‐
3379 ing raw keycodes. These are a variant on the XT codeset, but extended
3380 keycodes have the low bit of the second byte set, instead of the high
3381 bit of the first byte. No symbolic names are provided.
3382 See virkeycode-qnum(7)
3384 Examples:
3386 # send three strokes 'k', 'e', 'y', using xt codeset. these
3388 # are all pressed simultaneously and may be received by the guest
3389 # in random order
3390 virsh send-key dom --codeset xt 37 18 21
3391 # send one stroke 'right-ctrl+C'
3393 virsh send-key dom KEY_RIGHTCTRL KEY_C
3394 # send a tab, held for 1 second
3396 virsh send-key --holdtime 1000 0xf
3397 send-process-signal
3399 Syntax:
3400 send-process-signal domain-id pid signame
3402 Send a signal signame to the process identified by pid running in the
3404 virtual domain domain-id. The pid is a process ID in the virtual domain
3405 namespace.
3406 The signame argument may be either an integer signal constant number,
3408 or one of the symbolic names:
3409 "nop", "hup", "int", "quit", "ill",
3411 "trap", "abrt", "bus", "fpe", "kill",
3412 "usr1", "segv", "usr2", "pipe", "alrm",
3413 "term", "stkflt", "chld", "cont", "stop",
3414 "tstp", "ttin", "ttou", "urg", "xcpu",
3415 "xfsz", "vtalrm", "prof", "winch", "poll",
3416 "pwr", "sys", "rt0", "rt1", "rt2", "rt3",
3417 "rt4", "rt5", "rt6", "rt7", "rt8", "rt9",
3418 "rt10", "rt11", "rt12", "rt13", "rt14", "rt15",
3419 "rt16", "rt17", "rt18", "rt19", "rt20", "rt21",
3420 "rt22", "rt23", "rt24", "rt25", "rt26", "rt27",
3421 "rt28", "rt29", "rt30", "rt31", "rt32"
3422 The symbol name may optionally be prefixed with sig or sig_ and may be
3424 in uppercase or lowercase.
3425 Examples:
3427 virsh send-process-signal myguest 1 15
3429 virsh send-process-signal myguest 1 term
3430 virsh send-process-signal myguest 1 sigterm
3431 virsh send-process-signal myguest 1 SIG_HUP
3432 set-lifecycle-action
3434 Syntax:
3435 set-lifecycle-action domain type action
3437 [[--config] [--live] | [--current]]
3438 Set the lifecycle action for specified lifecycle type. The valid types
3440 are "poweroff", "reboot" and "crash", and for each of them valid action
3441 is one of "destroy", "restart", "rename-restart", "preserve". For type
3442 "crash", additional actions "coredump-destroy" and "coredump-restart"
3443 are supported.
3444 set-user-password
3446 Syntax:
3447 set-user-password domain user password [--encrypted]
3449 Set the password for the user account in the guest domain.
3451 If --encrypted is specified, the password is assumed to be already en‐
3453 crypted by the method required by the guest OS.
3454 For QEMU/KVM, this requires the guest agent to be configured and run‐
3456 ning.
3457 set-user-sshkeys
3459 Syntax:
3460 set-user-sshkeys domain user [--file FILE] [{--reset | --remove}]
3462 Append keys read from FILE into user's SSH authorized keys file in the
3464 guest domain. In the FILE keys must be on separate lines and each line
3465 must follow authorized keys format as defined by sshd(8).
3466 If --reset is specified, then the guest authorized keys file content is
3468 removed before appending new keys. As a special case, if --reset is
3469 provided and no FILE was provided then no new keys are added and the
3470 authorized keys file is cleared out.
3471 If --remove is specified, then instead of adding any new keys then keys
3473 read from FILE are removed from the authorized keys file. It is not
3474 considered an error if the key does not exist in the file.
3475 setmaxmem
3477 Syntax:
3478 setmaxmem domain size [[--config] [--live] | [--current]]
3480 Change the maximum memory allocation limit for a guest domain. If
3482 --live is specified, affect a running guest. If --config is specified,
3483 affect the next start of a persistent guest. If --current is speci‐
3484 fied, it is equivalent to either --live or --config, depending on the
3485 current state of the guest. Both --live and --config flags may be
3486 given, but --current is exclusive. If no flag is specified, behavior is
3487 different depending on hypervisor.
3488 Some hypervisors such as QEMU/KVM don't support live changes (espe‐
3490 cially increasing) of the maximum memory limit. Even persistent con‐
3491 figuration changes might not be performed with some hypervisors/config‐
3492 uration (e.g. on NUMA enabled domains on QEMU). For complex configura‐
3493 tion changes use command edit instead).
3494 size is a scaled integer (see NOTES above); it defaults to kibibytes
3496 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3497 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3498 rounds up to the nearest kibibyte. Some hypervisors require a larger
3499 granularity than KiB, and requests that are not an even multiple will
3500 be rounded up. For example, vSphere/ESX rounds the parameter up to
3501 mebibytes (1024 kibibytes).
3502 setmem
3504 Syntax:
3505 setmem domain size [[--config] [--live] | [--current]]
3507 Change the memory allocation for a guest domain. If --live is speci‐
3509 fied, perform a memory balloon of a running guest. If --config is
3510 specified, affect the next start of a persistent guest. If --current
3511 is specified, it is equivalent to either --live or --config, depending
3512 on the current state of the guest. Both --live and --config flags may
3513 be given, but --current is exclusive. If no flag is specified, behavior
3514 is different depending on hypervisor.
3515 size is a scaled integer (see NOTES above); it defaults to kibibytes
3517 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3518 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3519 rounds up to the nearest kibibyte. Some hypervisors require a larger
3520 granularity than KiB, and requests that are not an even multiple will
3521 be rounded up. For example, vSphere/ESX rounds the parameter up to
3522 mebibytes (1024 kibibytes).
3523 For Xen, you can only adjust the memory of a running domain if the do‐
3525 main is paravirtualized or running the PV balloon driver.
3526 For LXC, the value being set is the cgroups value for limit_in_bytes or
3528 the maximum amount of user memory (including file cache). When viewing
3529 memory inside the container, this is the /proc/meminfo "MemTotal"
3530 value. When viewing the value from the host, use the virsh memtune com‐
3531 mand. In order to view the current memory in use and the maximum value
3532 allowed to set memory, use the virsh dominfo command.
3533 setvcpus
3535 Syntax:
3536 setvcpus domain count [--maximum] [[--config] [--live] | [--current]] [--guest] [--hotpluggable]
3538 Change the number of virtual CPUs active in a guest domain. By de‐
3540 fault, this command works on active guest domains. To change the set‐
3541 tings for an inactive guest domain, use the --config flag.
3542 The count value may be limited by host, hypervisor, or a limit coming
3544 from the original description of the guest domain. For Xen, you can
3545 only adjust the virtual CPUs of a running domain if the domain is par‐
3546 avirtualized.
3547 If the --config flag is specified, the change is made to the stored XML
3549 configuration for the guest domain, and will only take effect when the
3550 guest domain is next started.
3551 If --live is specified, the guest domain must be active, and the change
3553 takes place immediately. Both the --config and --live flags may be
3554 specified together if supported by the hypervisor. If this command is
3555 run before the guest has finished booting, the guest may fail to
3556 process the change.
3557 If --current is specified, it is equivalent to either --live or --con‐
3559 fig, depending on the current state of the guest.
3560 When no flags are given, the --live flag is assumed and the guest do‐
3562 main must be active. In this situation it is up to the hypervisor
3563 whether the --config flag is also assumed, and therefore whether the
3564 XML configuration is adjusted to make the change persistent.
3565 If --guest is specified, then the count of cpus is modified in the
3567 guest instead of the hypervisor. This flag is usable only for live do‐
3568 mains and may require guest agent to be configured in the guest.
3569 To allow adding vcpus to persistent definitions that can be later ho‐
3571 tunplugged after the domain is booted it is necessary to specify the
3572 --hotpluggable flag. Vcpus added to live domains supporting vcpu unplug
3573 are automatically marked as hotpluggable.
3574 The --maximum flag controls the maximum number of virtual cpus that can
3576 be hot-plugged the next time the domain is booted. As such, it must
3577 only be used with the --config flag, and not with the --live or the
3578 --current flag. Note that it may not be possible to change the maximum
3579 vcpu count if the processor topology is specified for the guest.
3580 setvcpu
3582 Syntax:
3583 setvcpu domain vcpulist [--enable] | [--disable]
3585 [[--live] [--config] | [--current]]
3586 Change state of individual vCPUs using hot(un)plug mechanism.
3588 See vcpupin for information on format of vcpulist. Hypervisor drivers
3590 may require that vcpulist contains exactly vCPUs belonging to one hot‐
3591 pluggable entity. This is usually just a single vCPU but certain archi‐
3592 tectures such as ppc64 require a full core to be specified at once.
3593 Note that hypervisors may refuse to disable certain vcpus such as vcpu
3595 0 or others.
3596 If --live is specified, affect a running domain. If --config is speci‐
3598 fied, affect the next startup of a persistent guest. If --current is
3599 specified, it is equivalent to either --live or --config, depending on
3600 the current state of the guest. This is the default. Both --live and
3601 --config flags may be given, but --current is exclusive.
3602 shutdown
3604 Syntax:
3605 shutdown domain [--mode MODE-LIST]
3607 Gracefully shuts down a domain. This coordinates with the domain OS to
3609 perform graceful shutdown, so there is no guarantee that it will suc‐
3610 ceed, and may take a variable length of time depending on what services
3611 must be shutdown in the domain.
3612 The exact behavior of a domain when it shuts down is set by the
3614 on_poweroff parameter in the domain's XML definition.
3615 If domain is transient, then the metadata of any snapshots and check‐
3617 points will be lost once the guest stops running, but the underlying
3618 contents still exist, and a new domain with the same name and UUID can
3619 restore the snapshot metadata with snapshot-create, and the checkpoint
3620 metadata with checkpoint-create.
3621 By default the hypervisor will try to pick a suitable shutdown method.
3623 To specify an alternative method, the --mode parameter can specify a
3624 comma separated list which includes acpi, agent, initctl, signal and
3625 paravirt. The order in which drivers will try each mode is undefined,
3626 and not related to the order specified to virsh. For strict control
3627 over ordering, use a single mode at a time and repeat the command.
3628 start
3630 Syntax:
3631 start domain-name-or-uuid [--console] [--paused]
3633 [--autodestroy] [--bypass-cache] [--force-boot]
3634 [--pass-fds N,M,...]
3635 Start a (previously defined) inactive domain, either from the last man‐
3637 agedsave state, or via a fresh boot if no managedsave state is present.
3638 The domain will be paused if the --paused option is used and supported
3639 by the driver; otherwise it will be running. If --console is re‐
3640 quested, attach to the console after creation. If --autodestroy is re‐
3641 quested, then the guest will be automatically destroyed when virsh
3642 closes its connection to libvirt, or otherwise exits. If --by‐
3643 pass-cache is specified, and managedsave state exists, the restore will
3644 avoid the file system cache, although this may slow down the operation.
3645 If --force-boot is specified, then any managedsave state is discarded
3646 and a fresh boot occurs.
3647 If --pass-fds is specified, the argument is a comma separated list of
3649 open file descriptors which should be pass on into the guest. The file
3650 descriptors will be re-numbered in the guest, starting from 3. This is
3651 only supported with container based virtualization.
3652 suspend
3654 Syntax:
3655 suspend domain
3657 Suspend a running domain. It is kept in memory but won't be scheduled
3659 anymore.
3660 ttyconsole
3662 Syntax:
3663 ttyconsole domain
3665 Output the device used for the TTY console of the domain. If the infor‐
3667 mation is not available the processes will provide an exit code of 1.
3668 undefine
3670 Syntax:
3671 undefine domain [--managed-save] [--snapshots-metadata]
3673 [--checkpoints-metadata] [--nvram] [--keep-nvram]
3674 [ {--storage volumes | --remove-all-storage
3675 [--delete-storage-volume-snapshots]} --wipe-storage]
3676 Undefine a domain. If the domain is running, this converts it to a
3678 transient domain, without stopping it. If the domain is inactive, the
3679 domain configuration is removed.
3680 The --managed-save flag guarantees that any managed save image (see the
3682 managedsave command) is also cleaned up. Without the flag, attempts to
3683 undefine a domain with a managed save image will fail.
3684 The --snapshots-metadata flag guarantees that any snapshots (see the
3686 snapshot-list command) are also cleaned up when undefining an inactive
3687 domain. Without the flag, attempts to undefine an inactive domain with
3688 snapshot metadata will fail. If the domain is active, this flag is ig‐
3689 nored.
3690 The --checkpoints-metadata flag guarantees that any checkpoints (see
3692 the checkpoint-list command) are also cleaned up when undefining an in‐
3693 active domain. Without the flag, attempts to undefine an inactive do‐
3694 main with checkpoint metadata will fail. If the domain is active, this
3695 flag is ignored.
3696 --nvram and --keep-nvram specify accordingly to delete or keep nvram
3698 (/domain/os/nvram/) file. If the domain has an nvram file and the flags
3699 are omitted, the undefine will fail.
3700 The --storage flag takes a parameter volumes, which is a comma sepa‐
3702 rated list of volume target names or source paths of storage volumes to
3703 be removed along with the undefined domain. Volumes can be undefined
3704 and thus removed only on inactive domains. Volume deletion is only at‐
3705 tempted after the domain is undefined; if not all of the requested vol‐
3706 umes could be deleted, the error message indicates what still remains
3707 behind. If a volume path is not found in the domain definition, it's
3708 treated as if the volume was successfully deleted. Only volumes managed
3709 by libvirt in storage pools can be removed this way. (See domblklist
3710 for list of target names associated to a domain). Example: --storage
3711 vda,/path/to/storage.img
3712 The --remove-all-storage flag specifies that all of the domain's stor‐
3714 age volumes should be deleted.
3715 The --delete-storage-volume-snapshots (previously --delete-snapshots)
3717 flag specifies that any snapshots associated with the storage volume
3718 should be deleted as well. Requires the --remove-all-storage flag to be
3719 provided. Not all storage drivers support this option, presently only
3720 rbd. Using this when also removing volumes handled by a storage driver
3721 which does not support the flag will result in failure.
3722 The flag --wipe-storage specifies that the storage volumes should be
3724 wiped before removal.
3725 NOTE: For an inactive domain, the domain name or UUID must be used as
3727 the domain.
3728 vcpucount
3730 Syntax:
3731 vcpucount domain [{--maximum | --active}
3733 {--config | --live | --current}] [--guest]
3734 Print information about the virtual cpu counts of the given domain. If
3736 no flags are specified, all possible counts are listed in a table; oth‐
3737 erwise, the output is limited to just the numeric value requested. For
3738 historical reasons, the table lists the label "current" on the rows
3739 that can be queried in isolation via the --active flag, rather than re‐
3740 lating to the --current flag.
3741 --maximum requests information on the maximum cap of vcpus that a do‐
3743 main can add via setvcpus, while --active shows the current usage;
3744 these two flags cannot both be specified. --config requires a persis‐
3745 tent guest and requests information regarding the next time the domain
3746 will be booted, --live requires a running domain and lists current val‐
3747 ues, and --current queries according to the current state of the domain
3748 (corresponding to --live if running, or --config if inactive); these
3749 three flags are mutually exclusive.
3750 If --guest is specified, then the count of cpus is reported from the
3752 perspective of the guest. This flag is usable only for live domains and
3753 may require guest agent to be configured in the guest.
3754 vcpuinfo
3756 Syntax:
3757 vcpuinfo domain [--pretty]
3759 Returns basic information about the domain virtual CPUs, like the num‐
3761 ber of vCPUs, the running time, the affinity to physical processors.
3762 With --pretty, cpu affinities are shown as ranges.
3764 Example:
3766 $ virsh vcpuinfo fedora
3768 VCPU: 0
3769 CPU: 0
3770 State: running
3771 CPU time: 7,0s
3772 CPU Affinity: yyyy
3773 VCPU: 1
3775 CPU: 1
3776 State: running
3777 CPU time: 0,7s
3778 CPU Affinity: yyyy
3779 STATES
3781 The State field displays the current operating state of a virtual CPU
3783 • offline
3785 The virtual CPU is offline and not usable by the domain. This state
3787 is not supported by all hypervisors.
3788 • running
3790 The virtual CPU is available to the domain and is operating.
3792 • blocked
3794 The virtual CPU is available to the domain but is waiting for a re‐
3796 source. This state is not supported by all hypervisors, in which
3797 case running may be reported instead.
3798 • no state
3800 The virtual CPU state could not be determined. This could happen if
3802 the hypervisor is newer than virsh.
3803 • N/A
3805 There's no information about the virtual CPU state available. This
3807 can be the case if the domain is not running or the hypervisor does
3808 not report the virtual CPU state.
3809 vcpupin
3811 Syntax:
3812 vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]]
3814 Query or change the pinning of domain VCPUs to host physical CPUs. To
3816 pin a single vcpu, specify cpulist; otherwise, you can query one vcpu
3817 or omit vcpu to list all at once.
3818 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
3820 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
3821 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
3822 clusive. For pinning the vcpu to all physical cpus specify 'r' as a
3823 cpulist. If --live is specified, affect a running guest. If --config
3824 is specified, affect the next start of a persistent guest. If --cur‐
3825 rent is specified, it is equivalent to either --live or --config, de‐
3826 pending on the current state of the guest. Both --live and --config
3827 flags may be given if cpulist is present, but --current is exclusive.
3828 If no flag is specified, behavior is different depending on hypervisor.
3829 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
3831 cal to "9-14,0-7,15" but not identical to "^8,0-15".
3832 vncdisplay
3834 Syntax:
3835 vncdisplay domain
3837 Output the IP address and port number for the VNC display. If the in‐
3839 formation is not available the processes will provide an exit code of
3840 1.
3841
3843 The following commands manipulate devices associated to domains. The
3844 domain can be specified as a short integer, a name or a full UUID. To
3845 better understand the values allowed as options for the command reading
3846 the documentation at https://libvirt.org/formatdomain.html on the for‐
3847 mat of the device sections to get the most accurate set of accepted
3848 values.
3849 attach-device
3851 Syntax:
3852 attach-device domain FILE [[[--live] [--config] | [--current]] | [--persistent]]
3854 Attach a device to the domain, using a device definition in an XML file
3856 using a device definition element such as <disk> or <interface> as the
3857 top-level element. See the documentation at
3858 https://libvirt.org/formatdomain.html#elementsDevices to learn about
3859 libvirt XML format for a device. If --config is specified the command
3860 alters the persistent guest configuration with the device attach taking
3861 effect the next time libvirt starts the domain. For cdrom and floppy
3862 devices, this command only replaces the media within an existing de‐
3863 vice; consider using update-device for this usage. For passthrough
3864 host devices, see also nodedev-detach, needed if the PCI device does
3865 not use managed mode.
3866 If --live is specified, affect a running domain. If --config is speci‐
3868 fied, affect the next startup of a persistent guest. If --current is
3869 specified, it is equivalent to either --live or --config, depending on
3870 the current state of the guest. Both --live and --config flags may be
3871 given, but --current is exclusive. When no flag is specified legacy API
3872 is used whose behavior depends on the hypervisor driver.
3873 For compatibility purposes, --persistent behaves like --config for an
3875 offline domain, and like --live --config for a running domain.
3876 Note: using of partial device definition XML files may lead to unex‐
3878 pected results as some fields may be autogenerated and thus match de‐
3879 vices other than expected.
3880 attach-disk
3882 Syntax:
3883 attach-disk domain source target [[[--live] [--config] |
3885 [--current]] | [--persistent]] [--targetbus bus]
3886 [--driver driver] [--subdriver subdriver] [--iothread iothread]
3887 [--cache cache] [--io io] [--type type] [--alias alias]
3888 [--mode mode] [--sourcetype sourcetype]
3889 [--source-protocol protocol] [--source-host-name hostname:port]
3890 [--source-host-transport transport] [--source-host-socket socket]
3891 [--serial serial] [--wwn wwn] [--rawio] [--address address]
3892 [--multifunction] [--print-xml]
3893 Attach a new disk device to the domain. source is path for the files
3895 and devices unless --source-protocol is specified, in which case source
3896 is the name of a network disk. target controls the bus or device under
3897 which the disk is exposed to the guest OS. It indicates the "logical"
3898 device name; the optional targetbus attribute specifies the type of
3899 disk device to emulate; possible values are driver specific, with typi‐
3900 cal values being ide, scsi, virtio, xen, usb, sata, or sd, if omitted,
3901 the bus type is inferred from the style of the device name (e.g. a de‐
3902 vice named 'sda' will typically be exported using a SCSI bus). driver
3903 can be file, tap or phy for the Xen hypervisor depending on the kind of
3904 access; or qemu for the QEMU emulator. Further details to the driver
3905 can be passed using subdriver. For Xen subdriver can be aio, while for
3906 QEMU subdriver should match the format of the disk source, such as raw
3907 or qcow2. Hypervisor default will be used if subdriver is not speci‐
3908 fied. However, the default may not be correct, esp. for QEMU as for
3909 security reasons it is configured not to detect disk formats. type can
3910 indicate lun, cdrom or floppy as alternative to the disk default, al‐
3911 though this use only replaces the media within the existing virtual
3912 cdrom or floppy device; consider using update-device for this usage in‐
3913 stead. alias can set user supplied alias. mode can specify the two
3914 specific mode readonly or shareable. sourcetype can indicate the type
3915 of source (block|file|network) cache can be one of "default", "none",
3916 "writethrough", "writeback", "directsync" or "unsafe". io controls
3917 specific policies on I/O; QEMU guests support "threads", "native" and
3918 "io_uring". iothread is the number within the range of domain IO‐
3919 Threads to which this disk may be attached (QEMU only). serial is the
3920 serial of disk device. wwn is the wwn of disk device. rawio indicates
3921 the disk needs rawio capability. address is the address of disk device
3922 in the form of pci:domain.bus.slot.function, scsi:controller.bus.unit,
3923 ide:controller.bus.unit, usb:bus.port, sata:controller.bus.unit or
3924 ccw:cssid.ssid.devno. Virtio-ccw devices must have their cssid set to
3925 0xfe. multifunction indicates specified pci address is a multifunction
3926 pci device address.
3927 There is also support for using a network disk. As specified, the user
3929 can provide a --source-protocol in which case the source parameter will
3930 be interpreted as the source name. --source-protocol must be provided
3931 if the user intends to provide a network disk or host information.
3932 Host information can be provided using the tags --source-host-name,
3933 --source-host-transport, and --source-host-socket, which respectively
3934 denote the name of the host, the host's transport method, and the
3935 socket that the host uses. --source-host-socket and --source-host-name
3936 cannot both be provided, and the user must provide a
3937 --source-host-transport if they want to provide a --source-host-socket.
3938 The --source-host-name parameter supports host:port syntax if the user
3939 wants to provide a port as well.
3940 If --print-xml is specified, then the XML of the disk that would be at‐
3942 tached is printed instead.
3943 If --live is specified, affect a running domain. If --config is speci‐
3945 fied, affect the next startup of a persistent guest. If --current is
3946 specified, it is equivalent to either --live or --config, depending on
3947 the current state of the guest. Both --live and --config flags may be
3948 given, but --current is exclusive. When no flag is specified legacy API
3949 is used whose behavior depends on the hypervisor driver.
3950 For compatibility purposes, --persistent behaves like --config for an
3952 offline domain, and like --live --config for a running domain. Like‐
3953 wise, --shareable is an alias for --mode shareable.
3954 attach-interface
3956 Syntax:
3957 attach-interface domain type source [[[--live]
3959 [--config] | [--current]] | [--persistent]]
3960 [--target target] [--mac mac] [--script script] [--model model]
3961 [--inbound average,peak,burst,floor] [--outbound average,peak,burst]
3962 [--alias alias] [--managed] [--print-xml]
3963 Attach a new network interface to the domain.
3965 type can be one of the:
3967 network to indicate connection via a libvirt virtual network,
3969 bridge to indicate connection via a bridge device on the host,
3971 direct to indicate connection directly to one of the host's network in‐
3973 terfaces or bridges,
3974 hostdev to indicate connection using a passthrough of PCI device on the
3976 host.
3977 source indicates the source of the connection. The source depends on
3979 the type of the interface:
3980 network name of the virtual network,
3982 bridge the name of the bridge device,
3984 direct the name of the host's interface or bridge,
3986 hostdev the PCI address of the host's interface formatted as do‐
3988 main:bus:slot.function.
3989 --target is used to specify the tap/macvtap device to be used to con‐
3991 nect the domain to the source. Names starting with 'vnet' are consid‐
3992 ered as auto-generated and are blanked out/regenerated each time the
3993 interface is attached.
3994 --mac specifies the MAC address of the network interface; if a MAC ad‐
3996 dress is not given, a new address will be automatically generated (and
3997 stored in the persistent configuration if "--config" is given on the
3998 command line).
3999 --script is used to specify a path to a custom script to be called
4001 while attaching to a bridge - this will be called instead of the de‐
4002 fault script not in addition to it. This is valid only for interfaces
4003 of bridge type and only for Xen domains.
4004 --model specifies the network device model to be presented to the do‐
4006 main.
4007 alias can set user supplied alias.
4009 --inbound and --outbound control the bandwidth of the interface. At
4011 least one from the average, floor pair must be specified. The other
4012 two peak and burst are optional, so "average,peak", "average,,burst",
4013 "average,,,floor", "average" and ",,,floor" are also legal. Values for
4014 average, floor and peak are expressed in kilobytes per second, while
4015 burst is expressed in kilobytes in a single burst at peak speed as de‐
4016 scribed in the Network XML documentation at
4017 https://libvirt.org/formatnetwork.html#elementQoS.
4018 --managed is usable only for hostdev type and tells libvirt that the
4020 interface should be managed, which means detached and reattached
4021 from/to the host by libvirt.
4022 If --print-xml is specified, then the XML of the interface that would
4024 be attached is printed instead.
4025 If --live is specified, affect a running domain. If --config is speci‐
4027 fied, affect the next startup of a persistent guest. If --current is
4028 specified, affect the current domain state, which can either be live or
4029 offline. Both --live and --config flags may be given, but --current is
4030 exclusive. When no flag is specified legacy API is used whose behavior
4031 depends on the hypervisor driver.
4032 For compatibility purposes, --persistent behaves like --config for an
4034 offline domain, and like --live --config for a running domain.
4035 Note: the optional target value is the name of a device to be created
4037 as the back-end on the node. If not provided a device named "vnetN" or
4038 "vifN" will be created automatically.
4039 detach-device
4041 Syntax:
4042 detach-device domain FILE [[[--live] [--config] |
4044 [--current]] | [--persistent]]
4045 Detach a device from the domain, takes the same kind of XML descrip‐
4047 tions as command attach-device. For passthrough host devices, see also
4048 nodedev-reattach, needed if the device does not use managed mode.
4049 Note: The supplied XML description of the device should be as specific
4051 as its definition in the domain XML. The set of attributes used to
4052 match the device are internal to the drivers. Using a partial defini‐
4053 tion, or attempting to detach a device that is not present in the do‐
4054 main XML, but shares some specific attributes with one that is present,
4055 may lead to unexpected results.
4056 Quirk: Device unplug is asynchronous in most cases and requires guest
4058 cooperation. This means that it's up to the discretion of the guest to
4059 disallow or delay the unplug arbitrarily. As the libvirt API used in
4060 this command was designed as synchronous it returns success after some
4061 timeout even if the device was not unplugged yet to allow further in‐
4062 teractions with the domain e.g. if the guest is unresponsive. Callers
4063 which need to make sure that the device was unplugged can use libvirt
4064 events (see virsh event) to be notified when the device is removed.
4065 Note that the event may arrive before the command returns.
4066 If --live is specified, affect a running domain. If --config is speci‐
4068 fied, affect the next startup of a persistent guest. If --current is
4069 specified, it is equivalent to either --live or --config, depending on
4070 the current state of the guest. Both --live and --config flags may be
4071 given, but --current is exclusive. When no flag is specified legacy API
4072 is used whose behavior depends on the hypervisor driver.
4073 For compatibility purposes, --persistent behaves like --config for an
4075 offline domain, and like --live --config for a running domain.
4076 Note that older versions of virsh used --config as an alias for --per‐
4078 sistent.
4079 detach-device-alias
4081 Syntax:
4082 detach-device-alias domain alias [[[--live] [--config] | [--current]]]]
4084 Detach a device with given alias from the domain. This command returns
4086 successfully after the unplug request was sent to the hypervisor. The
4087 actual removal of the device is notified asynchronously via libvirt
4088 events (see virsh event).
4089 If --live is specified, affect a running domain. If --config is speci‐
4091 fied, affect the next startup of a persistent guest. If --current is
4092 specified, it is equivalent to either --live or --config, depending on
4093 the current state of the guest. Both --live and --config flags may be
4094 given, but --current is exclusive.
4095 detach-disk
4097 Syntax:
4098 detach-disk domain target [[[--live] [--config] |
4100 [--current]] | [--persistent]] [--print-xml]
4101 Detach a disk device from a domain. The target is the device as seen
4103 from the domain.
4104 If --live is specified, affect a running domain. If --config is speci‐
4106 fied, affect the next startup of a persistent guest. If --current is
4107 specified, it is equivalent to either --live or --config, depending on
4108 the current state of the guest. Both --live and --config flags may be
4109 given, but --current is exclusive. When no flag is specified legacy API
4110 is used whose behavior depends on the hypervisor driver.
4111 For compatibility purposes, --persistent behaves like --config for an
4113 offline domain, and like --live --config for a running domain.
4114 Note that older versions of virsh used --config as an alias for --per‐
4116 sistent.
4117 If --print-xml is specified, then the XML which would be used to detach
4119 the disk is printed instead.
4120 Please see documentation for detach-device for known quirks.
4122 detach-interface
4124 Syntax:
4125 detach-interface domain type [--mac mac]
4127 [[[--live] [--config] | [--current]] | [--persistent]]
4128 Detach a network interface from a domain. type can be either network
4130 to indicate a physical network device or bridge to indicate a bridge to
4131 a device. It is recommended to use the mac option to distinguish be‐
4132 tween the interfaces if more than one are present on the domain.
4133 If --live is specified, affect a running domain. If --config is speci‐
4135 fied, affect the next startup of a persistent guest. If --current is
4136 specified, it is equivalent to either --live or --config, depending on
4137 the current state of the guest. Both --live and --config flags may be
4138 given, but --current is exclusive. When no flag is specified legacy API
4139 is used whose behavior depends on the hypervisor driver.
4140 For compatibility purposes, --persistent behaves like --config for an
4142 offline domain, and like --live --config for a running domain.
4143 Note that older versions of virsh used --config as an alias for --per‐
4145 sistent.
4146 Please see documentation for detach-device for known quirks.
4148 update-device
4150 Syntax:
4151 update-device domain file [--force] [[[--live]
4153 [--config] | [--current]] | [--persistent]]
4154 Update the characteristics of a device associated with domain, based on
4156 the device definition in an XML file. The --force option can be used
4157 to force device update, e.g., to eject a CD-ROM even if it is
4158 locked/mounted in the domain. See the documentation at
4159 https://libvirt.org/formatdomain.html#elementsDevices to learn about
4160 libvirt XML format for a device.
4161 If --live is specified, affect a running domain. If --config is speci‐
4163 fied, affect the next startup of a persistent guest. If --current is
4164 specified, it is equivalent to either --live or --config, depending on
4165 the current state of the guest. Both --live and --config flags may be
4166 given, but --current is exclusive. Not specifying any flag is the same
4167 as specifying --current.
4168 For compatibility purposes, --persistent behaves like --config for an
4170 offline domain, and like --live --config for a running domain.
4171 Note that older versions of virsh used --config as an alias for --per‐
4173 sistent.
4174 Note: using of partial device definition XML files may lead to unex‐
4176 pected results as some fields may be autogenerated and thus match de‐
4177 vices other than expected.
4178 change-media
4180 Syntax:
4181 change-media domain path [--eject] [--insert]
4183 [--update] [source] [--force] [[--live] [--config] |
4184 [--current]] [--print-xml] [--block]
4185 Change media of CDROM or floppy drive. path can be the fully-qualified
4187 path or the unique target name (<target dev='hdc'>) of the disk device.
4188 source specifies the path of the media to be inserted or updated. The
4189 --block flag allows setting the backing type in case a block device is
4190 used as media for the CDROM or floppy drive instead of a file.
4191 --eject indicates the media will be ejected. --insert indicates the
4193 media will be inserted. source must be specified. If the device has
4194 source (e.g. <source file='media'>), and source is not specified, --up‐
4195 date is equal to --eject. If the device has no source, and source is
4196 specified, --update is equal to --insert. If the device has source, and
4197 source is specified, --update behaves like combination of --eject and
4198 --insert. If none of --eject, --insert, and --update is specified,
4199 --update is used by default. The --force option can be used to force
4200 media changing. If --live is specified, alter live configuration of
4201 running guest. If --config is specified, alter persistent configura‐
4202 tion, effect observed on next startup of the guest. --current can be
4203 either or both of live and config, depends on the hypervisor's imple‐
4204 mentation. Both --live and --config flags may be given, but --current
4205 is exclusive. If no flag is specified, behavior is different depending
4206 on hypervisor. If --print-xml is specified, the XML that would be used
4207 to change media is printed instead of changing the media.
4208
4210 The following commands manipulate host devices that are intended to be
4211 passed through to guest domains via <hostdev> elements in a domain's
4212 <devices> section. A node device key is generally specified by the bus
4213 name followed by its address, using underscores between all components,
4214 such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
4215 The nodedev-list gives the full list of host devices that are known to
4216 libvirt, although this includes devices that cannot be assigned to a
4217 guest (for example, attempting to detach the PCI device that controls
4218 the host's hard disk controller where the guest's disk images live
4219 could cause the host system to lock up or reboot).
4220 For more information on node device definition see:
4222 https://libvirt.org/formatnode.html.
4223 Passthrough devices cannot be simultaneously used by the host and its
4225 guest domains, nor by multiple active guests at once. If the <hostdev>
4226 description of a PCI device includes the attribute managed='yes', and
4227 the hypervisor driver supports it, then the device is in managed mode,
4228 and attempts to use that passthrough device in an active guest will au‐
4229 tomatically behave as if nodedev-detach (guest start, device hot-plug)
4230 and nodedev-reattach (guest stop, device hot-unplug) were called at the
4231 right points. If a PCI device is not marked as managed, then it must
4232 manually be detached before guests can use it, and manually reattached
4233 to be returned to the host. Also, if a device is manually detached,
4234 then the host does not regain control of the device without a matching
4235 reattach, even if the guests use the device in managed mode.
4236 nodedev-create
4238 Syntax:
4239 nodedev-create FILE
4241 Create a device on the host node that can then be assigned to virtual
4243 machines. Normally, libvirt is able to automatically determine which
4244 host nodes are available for use, but this allows registration of host
4245 hardware that libvirt did not automatically detect. file contains xml
4246 for a top-level <device> description of a node device.
4247 nodedev-destroy
4249 Syntax:
4250 nodedev-destroy device
4252 Destroy (stop) a device on the host. device can be either device name
4254 or wwn pair in "wwnn,wwpn" format (only works for vHBA currently).
4255 Note that this makes libvirt quit managing a host device, and may even
4256 make that device unusable by the rest of the physical host until a re‐
4257 boot.
4258 nodedev-detach
4260 Syntax:
4261 nodedev-detach nodedev [--driver backend_driver]
4263 Detach nodedev from the host, so that it can safely be used by guests
4265 via <hostdev> passthrough. This is reversed with nodedev-reattach, and
4266 is done automatically for managed devices.
4267 Different backend drivers expect the device to be bound to different
4269 dummy devices. For example, QEMU's "kvm" backend driver (the default)
4270 expects the device to be bound to pci-stub, but its "vfio" backend
4271 driver expects the device to be bound to vfio-pci. The --driver parame‐
4272 ter can be used to specify the desired backend driver.
4273 nodedev-dumpxml
4275 Syntax:
4276 nodedev-dumpxml device
4278 Dump a <device> XML representation for the given node device, including
4280 such information as the device name, which bus owns the device, the
4281 vendor and product id, and any capabilities of the device usable by
4282 libvirt (such as whether device reset is supported). device can be ei‐
4283 ther device name or wwn pair in "wwnn,wwpn" format (only works for
4284 HBA).
4285 nodedev-list
4287 Syntax:
4288 nodedev-list cap --tree
4290 List all of the devices available on the node that are known by lib‐
4292 virt. cap is used to filter the list by capability types, the types
4293 must be separated by comma, e.g. --cap pci,scsi. Valid capability types
4294 include 'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host',
4295 'scsi_target', 'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic',
4296 'drm', 'mdev', 'mdev_types', 'ccw', 'css', 'ap_card', 'ap_queue',
4297 'ap_matrix'. If --tree is used, the output is formatted in a tree rep‐
4298 resenting parents of each node. cap and --tree are mutually exclusive.
4299 nodedev-reattach
4301 Syntax:
4302 nodedev-reattach nodedev
4304 Declare that nodedev is no longer in use by any guests, and that the
4306 host can resume normal use of the device. This is done automatically
4307 for PCI devices in managed mode and USB devices, but must be done ex‐
4308 plicitly to match any explicit nodedev-detach.
4309 nodedev-reset
4311 Syntax:
4312 nodedev-reset nodedev
4314 Trigger a device reset for nodedev, useful prior to transferring a node
4316 device between guest passthrough or the host. Libvirt will often do
4317 this action implicitly when required, but this command allows an ex‐
4318 plicit reset when needed.
4319 nodedev-event
4321 Syntax:
4322 nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list}
4324 Wait for a class of node device events to occur, and print appropriate
4326 details of events as they happen. The events can optionally be fil‐
4327 tered by nodedev. Using --list as the only argument will provide a
4328 list of possible event values known by this client, although the con‐
4329 nection might not allow registering for all these events.
4330 By default, this command is one-shot, and returns success once an event
4332 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4333 If --timeout is specified, the command gives up waiting for events af‐
4334 ter seconds have elapsed. With --loop, the command prints all events
4335 until a timeout or interrupt key.
4336 When --timestamp is used, a human-readable timestamp will be printed
4338 before the event.
4339
4341 The following commands manipulate networks. Libvirt has the capability
4342 to define virtual networks which can then be used by domains and linked
4343 to actual network devices. For more detailed information about this
4344 feature see the documentation at https://libvirt.org/formatnetwork.html
4345 . Many of the commands for virtual networks are similar to the ones
4346 used for domains, but the way to name a virtual network is either by
4347 its name or UUID.
4348 net-autostart
4350 Syntax:
4351 net-autostart network [--disable]
4353 Configure a virtual network to be automatically started at boot. The
4355 --disable option disable autostarting.
4356 net-create
4358 Syntax:
4359 net-create file
4361 Create a transient (temporary) virtual network from an XML file and in‐
4363 stantiate (start) the network. See the documentation at
4364 https://libvirt.org/formatnetwork.html to get a description of the XML
4365 network format used by libvirt.
4366 net-define
4368 Syntax:
4369 net-define file
4371 Define an inactive persistent virtual network or modify an existing
4373 persistent one from the XML file.
4374 net-destroy
4376 Syntax:
4377 net-destroy network
4379 Destroy (stop) a given transient or persistent virtual network speci‐
4381 fied by its name or UUID. This takes effect immediately.
4382 net-dumpxml
4384 Syntax:
4385 net-dumpxml network [--inactive]
4387 Output the virtual network information as an XML dump to stdout. If
4389 --inactive is specified, then physical functions are not expanded into
4390 their associated virtual functions.
4391 net-edit
4393 Syntax:
4394 net-edit network
4396 Edit the XML configuration file for a network.
4398 This is equivalent to:
4400 virsh net-dumpxml --inactive network > network.xml
4402 vi network.xml (or make changes with your other text editor)
4403 virsh net-define network.xml
4404 except that it does some error checking.
4406 The editor used can be supplied by the $VISUAL or $EDITOR environment
4408 variables, and defaults to vi.
4409 net-event
4411 Syntax:
4412 net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list}
4414 Wait for a class of network events to occur, and print appropriate de‐
4416 tails of events as they happen. The events can optionally be filtered
4417 by network. Using --list as the only argument will provide a list of
4418 possible event values known by this client, although the connection
4419 might not allow registering for all these events.
4420 By default, this command is one-shot, and returns success once an event
4422 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4423 If --timeout is specified, the command gives up waiting for events af‐
4424 ter seconds have elapsed. With --loop, the command prints all events
4425 until a timeout or interrupt key.
4426 When --timestamp is used, a human-readable timestamp will be printed
4428 before the event.
4429 net-info
4431 Syntax:
4432 net-info network
4434 Returns basic information about the network object.
4436 net-list
4438 Syntax:
4439 net-list [--inactive | --all]
4441 { [--table] | --name | --uuid }
4442 [--persistent] [<--transient>]
4443 [--autostart] [<--no-autostart>]
4444 Returns the list of active networks, if --all is specified this will
4446 also include defined but inactive networks, if --inactive is specified
4447 only the inactive ones will be listed. You may also want to filter the
4448 returned networks by --persistent to list the persistent ones, --tran‐
4449 sient to list the transient ones, --autostart to list the ones with au‐
4450 tostart enabled, and --no-autostart to list the ones with autostart
4451 disabled.
4452 If --name is specified, network names are printed instead of the table
4454 formatted one per line. If --uuid is specified network's UUID's are
4455 printed instead of names. Flag --table specifies that the legacy ta‐
4456 ble-formatted output should be used. This is the default. All of these
4457 are mutually exclusive.
4458 NOTE: When talking to older servers, this command is forced to use a
4460 series of API calls with an inherent race, where a pool might not be
4461 listed or might appear more than once if it changed state between calls
4462 while the list was being collected. Newer servers do not have this
4463 problem.
4464 net-name
4466 Syntax:
4467 net-name network-UUID
4469 Convert a network UUID to network name.
4471 net-start
4473 Syntax:
4474 net-start network
4476 Start a (previously defined) inactive network.
4478 net-undefine
4480 Syntax:
4481 net-undefine network
4483 Undefine the configuration for a persistent network. If the network is
4485 active, make it transient.
4486 net-uuid
4488 Syntax:
4489 net-uuid network-name
4491 Convert a network name to network UUID.
4493 net-update
4495 Syntax:
4496 net-update network command section xml
4498 [--parent-index index] [[--live] [--config] | [--current]]
4499 Update the given section of an existing network definition, with the
4501 changes optionally taking effect immediately, without needing to de‐
4502 stroy and re-start the network.
4503 command is one of "add-first", "add-last", "add" (a synonym for
4505 add-last), "delete", or "modify".
4506 section is one of "bridge", "domain", "ip", "ip-dhcp-host",
4508 "ip-dhcp-range", "forward", "forward-interface", "forward-pf", "port‐
4509 group", "dns-host", "dns-txt", or "dns-srv", each section being named
4510 by a concatenation of the xml element hierarchy leading to the element
4511 being changed. For example, "ip-dhcp-host" will change a <host> element
4512 that is contained inside a <dhcp> element inside an <ip> element of the
4513 network.
4514 xml is either the text of a complete xml element of the type being
4516 changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the
4517 name of a file that contains a complete xml element. Disambiguation is
4518 done by looking at the first character of the provided text - if the
4519 first character is "<", it is xml text, if the first character is not
4520 "<", it is the name of a file that contains the xml text to be used.
4521 The --parent-index option is used to specify which of several parent
4523 elements the requested element is in (0-based). For example, a dhcp
4524 <host> element could be in any one of multiple <ip> elements in the
4525 network; if a parent-index isn't provided, the "most appropriate" <ip>
4526 element will be selected (usually the only one that already has a
4527 <dhcp> element), but if --parent-index is given, that particular in‐
4528 stance of <ip> will get the modification.
4529 If --live is specified, affect a running network. If --config is spec‐
4531 ified, affect the next startup of a persistent network. If --current
4532 is specified, it is equivalent to either --live or --config, depending
4533 on the current state of the guest. Both --live and --config flags may
4534 be given, but --current is exclusive. Not specifying any flag is the
4535 same as specifying --current.
4536 net-dhcp-leases
4538 Syntax:
4539 net-dhcp-leases network [mac]
4541 Get a list of dhcp leases for all network interfaces connected to the
4543 given virtual network or limited output just for one interface if mac
4544 is specified.
4545
4547 The following commands manipulate network ports. Libvirt virtual net‐
4548 works have ports created when a virtual machine has a virtual network
4549 interface added. In general there should be no need to use any of the
4550 commands here, since the hypervisor drivers run these commands are the
4551 right point in a virtual machine's lifecycle. They can be useful for
4552 debugging problems and / or recovering from bugs / stale state.
4553 net-port-list
4555 Syntax:
4556 net-port-list { [--table] | --uuid } network
4558 List all network ports recorded against the network.
4560 If --uuid is specified network ports' UUID's are printed instead of a
4562 table. Flag --table specifies that the legacy table-formatted output
4563 should be used. This is the default. All of these are mutually exclu‐
4564 sive.
4565 net-port-create
4567 Syntax:
4568 net-port-create network file
4570 Allocate a new network port reserving resources based on the port de‐
4572 scription.
4573 net-port-dumpxml
4575 Syntax:
4576 net-port-dumpxml network port
4578 Output the network port information as an XML dump to stdout.
4580 net-port-delete
4582 Syntax:
4583 net-port-delete network port
4585 Delete record of the network port and release its resources
4587
4589 The following commands manipulate host interfaces. Often, these host
4590 interfaces can then be used by name within domain <interface> elements
4591 (such as a system-created bridge interface), but there is no require‐
4592 ment that host interfaces be tied to any particular guest configuration
4593 XML at all.
4594 Many of the commands for host interfaces are similar to the ones used
4596 for domains, and the way to name an interface is either by its name or
4597 its MAC address. However, using a MAC address for an iface argument
4598 only works when that address is unique (if an interface and a bridge
4599 share the same MAC address, which is often the case, then using that
4600 MAC address results in an error due to ambiguity, and you must resort
4601 to a name instead).
4602 iface-bridge
4604 Syntax:
4605 iface-bridge interface bridge [--no-stp] [delay] [--no-start]
4607 Create a bridge device named bridge, and attach the existing network
4609 device interface to the new bridge. The new bridge defaults to start‐
4610 ing immediately, with STP enabled and a delay of 0; these settings can
4611 be altered with --no-stp, --no-start, and an integer number of seconds
4612 for delay. All IP address configuration of interface will be moved to
4613 the new bridge device.
4614 See also iface-unbridge for undoing this operation.
4616 iface-define
4618 Syntax:
4619 iface-define file
4621 Define an inactive persistent physical host interface or modify an ex‐
4623 isting persistent one from the XML file.
4624 iface-destroy
4626 Syntax:
4627 iface-destroy interface
4629 Destroy (stop) a given host interface, such as by running "if-down" to
4631 disable that interface from active use. This takes effect immediately.
4632 iface-dumpxml
4634 Syntax:
4635 iface-dumpxml interface [--inactive]
4637 Output the host interface information as an XML dump to stdout. If
4639 --inactive is specified, then the output reflects the persistent state
4640 of the interface that will be used the next time it is started.
4641 iface-edit
4643 Syntax:
4644 iface-edit interface
4646 Edit the XML configuration file for a host interface.
4648 This is equivalent to:
4650 virsh iface-dumpxml iface > iface.xml
4652 vi iface.xml (or make changes with your other text editor)
4653 virsh iface-define iface.xml
4654 except that it does some error checking.
4656 The editor used can be supplied by the $VISUAL or $EDITOR environment
4658 variables, and defaults to vi.
4659 iface-list
4661 Syntax:
4662 iface-list [--inactive | --all]
4664 Returns the list of active host interfaces. If --all is specified this
4666 will also include defined but inactive interfaces. If --inactive is
4667 specified only the inactive ones will be listed.
4668 iface-name
4670 Syntax:
4671 iface-name interface
4673 Convert a host interface MAC to interface name, if the MAC address is
4675 unique among the host's interfaces.
4676 interface specifies the interface MAC address.
4678 iface-mac
4680 Syntax:
4681 iface-mac interface
4683 Convert a host interface name to MAC address.
4685 interface specifies the interface name.
4687 iface-start
4689 Syntax:
4690 iface-start interface
4692 Start a (previously defined) host interface, such as by running
4694 "if-up".
4695 iface-unbridge
4697 Syntax:
4698 iface-unbridge bridge [--no-start]
4700 Tear down a bridge device named bridge, releasing its underlying inter‐
4702 face back to normal usage, and moving all IP address configuration from
4703 the bridge device to the underlying device. The underlying interface
4704 is restarted unless --no-start is present; this flag is present for
4705 symmetry, but generally not recommended.
4706 See also iface-bridge for creating a bridge.
4708 iface-undefine
4710 Syntax:
4711 iface-undefine interface
4713 Undefine the configuration for an inactive host interface.
4715 iface-begin
4717 Syntax:
4718 iface-begin
4720 Create a snapshot of current host interface settings, which can later
4722 be committed (iface-commit) or restored (iface-rollback). If a snap‐
4723 shot already exists, then this command will fail until the previous
4724 snapshot has been committed or restored. Undefined behavior results if
4725 any external changes are made to host interfaces outside of the libvirt
4726 API between the beginning of a snapshot and its eventual commit or
4727 rollback.
4728 iface-commit
4730 Syntax:
4731 iface-commit
4733 Declare all changes since the last iface-begin as working, and delete
4735 the rollback point. If no interface snapshot has already been started,
4736 then this command will fail.
4737 iface-rollback
4739 Syntax:
4740 iface-rollback
4742 Revert all host interface settings back to the state recorded in the
4744 last iface-begin. If no interface snapshot has already been started,
4745 then this command will fail. Rebooting the host also serves as an im‐
4746 plicit rollback point.
4747
4749 The following commands manipulate storage pools. Libvirt has the capa‐
4750 bility to manage various storage solutions, including files, raw parti‐
4751 tions, and domain-specific formats, used to provide the storage volumes
4752 visible as devices within virtual machines. For more detailed informa‐
4753 tion about this feature, see the documentation at
4754 https://libvirt.org/formatstorage.html . Many of the commands for pools
4755 are similar to the ones used for domains.
4756 find-storage-pool-sources
4758 Syntax:
4759 find-storage-pool-sources type [srcSpec]
4761 Returns XML describing all possible available storage pool sources that
4763 could be used to create or define a storage pool of a given type. If
4764 srcSpec is provided, it is a file that contains XML to further restrict
4765 the query for pools.
4766 Not all storage pools support discovery in this manner. Furthermore,
4768 for those that do support discovery, only specific XML elements are re‐
4769 quired in order to return valid data, while other elements and even at‐
4770 tributes of some elements are ignored since they are not necessary to
4771 find the pool based on the search criteria. The following lists the
4772 supported type options and the expected minimal XML elements used to
4773 perform the search.
4774 For a "netfs" or "gluster" pool, the minimal expected XML required is
4776 the <host> element with a "name" attribute describing the IP address or
4777 hostname to be used to find the pool. The "port" attribute will be ig‐
4778 nored as will any other provided XML elements in srcSpec.
4779 For a "logical" pool, the contents of the srcSpec file are ignored, al‐
4781 though if provided the file must at least exist.
4782 For an "iscsi" or "iscsi-direct" pool, the minimal expect XML required
4784 is the <host> element with a "name" attribute describing the IP address
4785 or hostname to be used to find the pool (the iSCSI server address). Op‐
4786 tionally, the "port" attribute may be provided, although it will de‐
4787 fault to 3260. Optionally, an <initiator> XML element with a "name" at‐
4788 tribute may be provided to further restrict the iSCSI target search to
4789 a specific initiator for multi-iqn iSCSI storage pools.
4790 find-pool-sources-as
4792 Syntax:
4793 find-storage-pool-sources-as type [host] [port] [initiator]
4795 Rather than providing srcSpec XML file for find-storage-pool-sources
4797 use this command option in order to have virsh generate the query XML
4798 file using the optional arguments. The command will return the same
4799 output XML as find-storage-pool-sources.
4800 Use host to describe a specific host to use for networked storage, such
4802 as netfs, gluster, and iscsi type pools.
4803 Use port to further restrict which networked port to utilize for the
4805 connection if required by the specific storage backend, such as iscsi.
4806 Use initiator to further restrict the iscsi type pool searches to spe‐
4808 cific target initiators.
4809 pool-autostart
4811 Syntax:
4812 pool-autostart pool-or-uuid [--disable]
4814 Configure whether pool should automatically start at boot.
4816 pool-build
4818 Syntax:
4819 pool-build pool-or-uuid [--overwrite] [--no-overwrite]
4821 Build a given pool.
4823 Options --overwrite and --no-overwrite can only be used for pool-build
4825 a filesystem, disk, or logical pool.
4826 For a file system pool if neither flag is specified, then pool-build
4828 just makes the target path directory and no attempt to run mkfs on the
4829 target volume device. If --no-overwrite is specified, it probes to de‐
4830 termine if a filesystem already exists on the target device, returning
4831 an error if one exists or using mkfs to format the target device if
4832 not. If --overwrite is specified, mkfs is always executed and any ex‐
4833 isting data on the target device is overwritten unconditionally.
4834 For a disk pool, if neither of them is specified or --no-overwrite is
4836 specified, pool-build will check the target volume device for existing
4837 filesystems or partitions before attempting to write a new label on the
4838 target volume device. If the target volume device already has a label,
4839 the command will fail. If --overwrite is specified, then no check will
4840 be made on the target volume device prior to writing a new label. Writ‐
4841 ing of the label uses the pool source format type or "dos" if not spec‐
4842 ified.
4843 For a logical pool, if neither of them is specified or --no-overwrite
4845 is specified, pool-build will check the target volume devices for ex‐
4846 isting filesystems or partitions before attempting to initialize and
4847 format each device for usage by the logical pool. If any target volume
4848 device already has a label, the command will fail. If --overwrite is
4849 specified, then no check will be made on the target volume devices
4850 prior to initializing and formatting each device. Once all the target
4851 volume devices are properly formatted via pvcreate, the volume group
4852 will be created using all the devices.
4853 pool-create
4855 Syntax:
4856 pool-create file [--build] [[--overwrite] | [--no-overwrite]]
4858 Create and start a pool object from the XML file.
4860 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
4862 creation in order to remove the need for a follow-up command to build
4863 the pool. The --overwrite and --no-overwrite flags follow the same
4864 rules as pool-build. If just --build is provided, then pool-build is
4865 called with no flags.
4866 pool-create-as
4868 Syntax:
4869 pool-create-as name type
4871 [--source-host hostname] [--source-path path] [--source-dev path]
4872 [--source-name name] [--target path] [--source-format format]
4873 [--source-initiator initiator-iqn]
4874 [--auth-type authtype --auth-username username
4875 [--secret-usage usage | --secret-uuid uuid]]
4876 [--source-protocol-ver ver]
4877 [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn]
4878 [--adapter-parent parent |
4879 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
4880 --adapter-parent-fabric-wwn parent_fabric_wwn]]
4881 [--build] [[--overwrite] | [--no-overwrite]] [--print-xml]
4882 Create and start a pool object name from the raw parameters. If
4884 --print-xml is specified, then print the XML of the pool object without
4885 creating the pool. Otherwise, the pool has the specified type. When
4886 using pool-create-as for a pool of type "disk", the existing partitions
4887 found on the --source-dev path will be used to populate the disk pool.
4888 Therefore, it is suggested to use pool-define-as and pool-build with
4889 the --overwrite in order to properly initialize the disk pool.
4890 [--source-host hostname] provides the source hostname for pools backed
4892 by storage from a remote server (pool types netfs, iscsi, rbd, sheep‐
4893 dog, gluster).
4894 [--source-path path] provides the source directory path for pools
4896 backed by directories (pool type dir).
4897 [--source-dev path] provides the source path for pools backed by physi‐
4899 cal devices (pool types fs, logical, disk, iscsi, zfs).
4900 [--source-name name] provides the source name for pools backed by stor‐
4902 age from a named element (pool types logical, rbd, sheepdog, gluster).
4903 [--target path] is the path for the mapping of the storage pool into
4905 the host file system.
4906 [--source-format format] provides information about the format of the
4908 pool (pool types fs, netfs, disk, logical).
4909 [--source-initiator initiator-iqn] provides the initiator iqn for iscsi
4911 connection of the pool (pool type iscsi-direct).
4912 [--auth-type authtype --auth-username username [--secret-usage usage |
4914 --secret-uuid uuid]] provides the elements required to generate authen‐
4915 tication credentials for the storage pool. The authtype is either chap
4916 for iscsi type pools or ceph for rbd type pools. Either the secret us‐
4917 age or uuid value may be provided, but not both.
4918 [--source-protocol-ver ver] provides the NFS protocol version number
4920 used to contact the server's NFS service via nfs mount option
4921 'nfsvers=n'. It is expect the ver value is an unsigned integer.
4922 [--adapter-name name] defines the scsi_hostN adapter name to be used
4924 for the scsi_host adapter type pool.
4925 [--adapter-wwnn wwnn --adapter-wwpn wwpn [--adapter-parent parent |
4927 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
4928 --adapter-parent-fabric-wwn parent_fabric_wwn]] defines the wwnn and
4929 wwpn to be used for the fc_host adapter type pool. Optionally provide
4930 the parent scsi_hostN node device to be used for the vHBA either by
4931 parent name, parent_wwnn and parent_wwpn, or parent_fabric_wwn. The
4932 parent name could change between reboots if the hardware environment
4933 changes, so providing the parent_wwnn and parent_wwpn ensure usage of
4934 the same physical HBA even if the scsi_hostN node device changes. Usage
4935 of the parent_fabric_wwn allows a bit more flexibility to choose an HBA
4936 on the same storage fabric in order to define the pool.
4937 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
4939 creation in order to remove the need for a follow-up command to build
4940 the pool. The --overwrite and --no-overwrite flags follow the same
4941 rules as pool-build. If just --build is provided, then pool-build is
4942 called with no flags.
4943 For a "logical" pool only [--name] needs to be provided. The
4945 [--source-name] if provided must match the Volume Group name. If not
4946 provided, one will be generated using the [--name]. If provided the
4947 [--target] is ignored and a target source is generated using the
4948 [--source-name] (or as generated from the [--name]).
4949 pool-define
4951 Syntax:
4952 pool-define file
4954 Define an inactive persistent storage pool or modify an existing per‐
4956 sistent one from the XML file.
4957 pool-define-as
4959 Syntax:
4960 pool-define-as name type
4962 [--source-host hostname] [--source-path path] [--source-dev path]
4963 [*--source-name name*] [*--target path*] [*--source-format format*]
4964 [--source-initiator initiator-iqn]
4965 [*--auth-type authtype* *--auth-username username*
4966 [*--secret-usage usage* | *--secret-uuid uuid*]]
4967 [*--source-protocol-ver ver*]
4968 [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*]
4969 [*--adapter-parent parent*]] [*--print-xml*]
4970 Create, but do not start, a pool object name from the raw parameters.
4972 If --print-xml is specified, then print the XML of the pool object
4973 without defining the pool. Otherwise, the pool has the specified type.
4974 Use the same arguments as pool-create-as, except for the --build,
4976 --overwrite, and --no-overwrite options.
4977 pool-destroy
4979 Syntax:
4980 pool-destroy pool-or-uuid
4982 Destroy (stop) a given pool object. Libvirt will no longer manage the
4984 storage described by the pool object, but the raw data contained in the
4985 pool is not changed, and can be later recovered with pool-create.
4986 pool-delete
4988 Syntax:
4989 pool-delete pool-or-uuid
4991 Destroy the resources used by a given pool object. This operation is
4993 non-recoverable. The pool object will still exist after this command,
4994 ready for the creation of new storage volumes.
4995 pool-dumpxml
4997 Syntax:
4998 pool-dumpxml [--inactive] pool-or-uuid
5000 Returns the XML information about the pool object. --inactive tells
5002 virsh to dump pool configuration that will be used on next start of the
5003 pool as opposed to the current pool configuration.
5004 pool-edit
5006 Syntax:
5007 pool-edit pool-or-uuid
5009 Edit the XML configuration file for a storage pool.
5011 This is equivalent to:
5013 virsh pool-dumpxml pool > pool.xml
5015 vi pool.xml (or make changes with your other text editor)
5016 virsh pool-define pool.xml
5017 except that it does some error checking.
5019 The editor used can be supplied by the $VISUAL or $EDITOR environment
5021 variables, and defaults to vi.
5022 pool-info
5024 Syntax:
5025 pool-info [--bytes] pool-or-uuid
5027 Returns basic information about the pool object. If --bytes is speci‐
5029 fied the sizes of basic info are not converted to human friendly units.
5030 pool-list
5032 Syntax:
5033 pool-list [--inactive] [--all]
5035 [--persistent] [--transient]
5036 [--autostart] [--no-autostart]
5037 [[--details] [--uuid]
5038 [--name] [<type>]
5039 List pool objects known to libvirt. By default, only active pools are
5041 listed; --inactive lists just the inactive pools, and --all lists all
5042 pools.
5043 In addition, there are several sets of filtering flags. --persistent is
5045 to list the persistent pools, --transient is to list the transient
5046 pools. --autostart lists the autostarting pools, --no-autostart lists
5047 the pools with autostarting disabled. If --uuid is specified only
5048 pool's UUIDs are printed. If --name is specified only pool's names are
5049 printed. If both --name and --uuid are specified, pool's UUID and names
5050 are printed side by side without any header. Option --details is mutu‐
5051 ally exclusive with options --uuid and --name.
5052 You may also want to list pools with specified types using type, the
5054 pool types must be separated by comma, e.g. --type dir,disk. The valid
5055 pool types include 'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi',
5056 'scsi', 'mpath', 'rbd', 'sheepdog', 'gluster', 'zfs', 'vstorage' and
5057 'iscsi-direct'.
5058 The --details option instructs virsh to additionally display pool per‐
5060 sistence and capacity related information where available.
5061 NOTE: When talking to older servers, this command is forced to use a
5063 series of API calls with an inherent race, where a pool might not be
5064 listed or might appear more than once if it changed state between calls
5065 while the list was being collected. Newer servers do not have this
5066 problem.
5067 pool-name
5069 Syntax:
5070 pool-name uuid
5072 Convert the uuid to a pool name.
5074 pool-refresh
5076 Syntax:
5077 pool-refresh pool-or-uuid
5079 Refresh the list of volumes contained in pool.
5081 pool-start
5083 Syntax:
5084 pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]
5086 Start the storage pool, which is previously defined but inactive.
5088 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build prior
5090 to pool-start to ensure the pool environment is in an expected state
5091 rather than needing to run the build command prior to startup. The
5092 --overwrite and --no-overwrite flags follow the same rules as
5093 pool-build. If just --build is provided, then pool-build is called with
5094 no flags.
5095 Note: A storage pool that relies on remote resources such as an "iscsi"
5097 or a (v)HBA backed "scsi" pool may need to be refreshed multiple times
5098 in order to have all the volumes detected (see pool-refresh). This is
5099 because the corresponding volume devices may not be present in the
5100 host's filesystem during the initial pool startup or the current re‐
5101 fresh attempt. The number of refresh retries is dependent upon the net‐
5102 work connection and the time the host takes to export the corresponding
5103 devices.
5104 pool-undefine
5106 Syntax:
5107 pool-undefine pool-or-uuid
5109 Undefine the configuration for an inactive pool.
5111 pool-uuid
5113 Syntax:
5114 pool-uuid pool
5116 Returns the UUID of the named pool.
5118 pool-event
5120 Syntax:
5121 pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list}
5123 Wait for a class of storage pool events to occur, and print appropriate
5125 details of events as they happen. The events can optionally be fil‐
5126 tered by pool. Using --list as the only argument will provide a list
5127 of possible event values known by this client, although the connection
5128 might not allow registering for all these events.
5129 By default, this command is one-shot, and returns success once an event
5131 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
5132 If --timeout is specified, the command gives up waiting for events af‐
5133 ter seconds have elapsed. With --loop, the command prints all events
5134 until a timeout or interrupt key.
5135 When --timestamp is used, a human-readable timestamp will be printed
5137 before the event.
5138
5140 vol-create
5141 Syntax:
5142 vol-create pool-or-uuid FILE [--prealloc-metadata]
5144 Create a volume from an XML <file>.
5146 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5148 ume in.
5149 FILE is the XML <file> with the volume definition. An easy way to cre‐
5151 ate the XML <file> is to use the vol-dumpxml command to obtain the def‐
5152 inition of a pre-existing volume.
5153 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5155 don't support full allocation). This option creates a sparse image file
5156 with metadata, resulting in higher performance compared to images with
5157 no preallocation and only slightly higher initial disk space usage.
5158 Example:
5160 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
5162 vi newvolume.xml (or make changes with your other text editor)
5163 virsh vol-create differentstoragepool newvolume.xml
5164 vol-create-from
5166 Syntax:
5167 vol-create-from pool-or-uuid FILE vol-name-or-key-or-path
5169 [--inputpool pool-or-uuid] [--prealloc-metadata] [--reflink]
5170 Create a volume, using another volume as input.
5172 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5174 ume in.
5175 FILE is the XML <file> with the volume definition.
5177 vol-name-or-key-or-path is the name or key or path of the source vol‐
5179 ume.
5180 --inputpool pool-or-uuid is the name or uuid of the storage pool the
5182 source volume is in.
5183 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5185 don't support full allocation). This option creates a sparse image file
5186 with metadata, resulting in higher performance compared to images with
5187 no preallocation and only slightly higher initial disk space usage.
5188 When --reflink is specified, perform a COW lightweight copy, where the
5190 data blocks are copied only when modified. If this is not possible,
5191 the copy fails.
5192 vol-create-as
5194 Syntax:
5195 vol-create-as pool-or-uuid name capacity [--allocation size] [--format string]
5197 [--backing-vol vol-name-or-key-or-path]
5198 [--backing-vol-format string] [--prealloc-metadata] [--print-xml]
5199 Create a volume from a set of arguments unless --print-xml is speci‐
5201 fied, in which case just the XML of the volume object is printed out
5202 without any actual object creation.
5203 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5205 ume in.
5206 name is the name of the new volume. For a disk pool, this must match
5208 the partition name as determined from the pool's source device path and
5209 the next available partition. For example, a source device path of
5210 /dev/sdb and there are no partitions on the disk, then the name must be
5211 sdb1 with the next name being sdb2 and so on.
5212 capacity is the size of the volume to be created, as a scaled integer
5214 (see NOTES above), defaulting to bytes if there is no suffix.
5215 --allocation size is the initial size to be allocated in the volume,
5217 also as a scaled integer defaulting to bytes.
5218 --format string is used in file based storage pools to specify the vol‐
5220 ume file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use ex‐
5221 tended for disk storage pools in order to create an extended partition
5222 (other values are validity checked but not preserved when libvirtd is
5223 restarted or the pool is refreshed).
5224 --backing-vol vol-name-or-key-or-path is the source backing volume to
5226 be used if taking a snapshot of an existing volume.
5227 --backing-vol-format string is the format of the snapshot backing vol‐
5229 ume; raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, how‐
5230 ever, meant for file based storage pools.
5231 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5233 don't support full allocation). This option creates a sparse image file
5234 with metadata, resulting in higher performance compared to images with
5235 no preallocation and only slightly higher initial disk space usage.
5236 vol-clone
5238 Syntax:
5239 vol-clone vol-name-or-key-or-path name
5241 [--pool pool-or-uuid] [--prealloc-metadata] [--reflink]
5242 Clone an existing volume within the parent pool. Less powerful, but
5244 easier to type, version of vol-create-from.
5245 vol-name-or-key-or-path is the name or key or path of the source vol‐
5247 ume.
5248 name is the name of the new volume.
5250 --pool pool-or-uuid is the name or UUID of the storage pool that con‐
5252 tains the source volume and will contain the new volume. If the source
5253 volume name is provided instead of the key or path, then providing the
5254 pool is necessary to find the volume to be cloned; otherwise, the first
5255 volume found by the key or path will be used.
5256 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5258 don't support full allocation). This option creates a sparse image file
5259 with metadata, resulting in higher performance compared to images with
5260 no preallocation and only slightly higher initial disk space usage.
5261 When --reflink is specified, perform a COW lightweight copy, where the
5263 data blocks are copied only when modified. If this is not possible,
5264 the copy fails.
5265 vol-delete
5267 Syntax:
5268 vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots]
5270 Delete a given volume.
5272 vol-name-or-key-or-path is the volume name or key or path of the volume
5274 to delete.
5275 [--pool pool-or-uuid] is the name or UUID of the storage pool the vol‐
5277 ume is in. If the volume name is provided instead of the key or path,
5278 then providing the pool is necessary to find the volume to be deleted;
5279 otherwise, the first volume found by the key or path will be used.
5280 The --delete-snapshots flag specifies that any snapshots associated
5282 with the storage volume should be deleted as well. Not all storage
5283 drivers support this option, presently only rbd.
5284 vol-upload
5286 Syntax:
5287 vol-upload vol-name-or-key-or-path local-file
5289 [--pool pool-or-uuid] [--offset bytes]
5290 [--length bytes] [--sparse]
5291 Upload the contents of local-file to a storage volume.
5293 vol-name-or-key-or-path is the name or key or path of the volume where
5295 the local-file will be uploaded.
5296 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5298 is in. If the volume name is provided instead of the key or path, then
5299 providing the pool is necessary to find the volume to be uploaded into;
5300 otherwise, the first volume found by the key or path will be used.
5301 --offset is the position in the storage volume at which to start writ‐
5303 ing the data. The value must be 0 or larger.
5304 --length is an upper bound of the amount of data to be uploaded. A
5306 negative value is interpreted as an unsigned long long value to essen‐
5307 tially include everything from the offset to the end of the volume.
5308 If --sparse is specified, this command will preserve volume sparseness.
5310 An error will occur if the local-file is greater than the specified
5312 length.
5313 See the description for the libvirt virStorageVolUpload API for details
5315 regarding possible target volume and pool changes as a result of the
5316 pool refresh when the upload is attempted.
5317 vol-download
5319 Syntax:
5320 vol-download vol-name-or-key-or-path local-file
5322 [--pool pool-or-uuid] [--offset bytes] [--length bytes]
5323 [--sparse]
5324 Download the contents of a storage volume to local-file.
5326 vol-name-or-key-or-path is the name or key or path of the volume to
5328 download into local-file.
5329 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5331 is in. If the volume name is provided instead of the key or path, then
5332 providing the pool is necessary to find the volume to be uploaded into;
5333 otherwise, the first volume found by the key or path will be used.
5334 --offset is the position in the storage volume at which to start read‐
5336 ing the data. The value must be 0 or larger.
5337 --length is an upper bound of the amount of data to be downloaded. A
5339 negative value is interpreted as an unsigned long long value to essen‐
5340 tially include everything from the offset to the end of the volume.
5341 If --sparse is specified, this command will preserve volume sparseness.
5343 vol-wipe
5345 Syntax:
5346 vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm]
5348 Wipe a volume, ensure data previously on the volume is not accessible
5350 to future reads.
5351 vol-name-or-key-or-path is the name or key or path of the volume to
5353 wipe. It is possible to choose different wiping algorithms instead of
5354 re-writing volume with zeroes.
5355 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5357 is in. If the volume name is provided instead of the key or path, then
5358 providing the pool is necessary to find the volume to be wiped; other‐
5359 wise, the first volume found by the key or path will be used.
5360 Use the --algorithm switch choosing from the list of the following al‐
5362 gorithms in order to define which algorithm to use for the wipe.
5363 Supported algorithms
5365 • zero - 1-pass all zeroes
5367 • nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for sani‐
5369 tizing removable and non-removable hard disks: random x2, 0x00, ver‐
5370 ify.
5371 • dod - 4-pass DoD 5220.22-M section 8-306 procedure for sani‐
5373 tizing removable and non-removable rigid disks: random, 0x00, 0xff,
5374 verify.
5375 • bsi - 9-pass method recommended by the German Center of Secu‐
5377 rity in Information Technologies (https://www.bsi.bund.de): 0xff,
5378 0xfe, 0xfd, 0xfb, 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
5379 • gutmann - The canonical 35-pass sequence described in Gutmann's
5381 paper.
5382 • schneier - 7-pass method described by Bruce Schneier in "Applied
5384 Cryptography" (1996): 0x00, 0xff, random x5.
5385 • pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7.
5387 • pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
5389 • random - 1-pass pattern: random.
5391 • trim - 1-pass trimming the volume using TRIM or DISCARD
5393 Note: The scrub binary will be used to handle the 'nnsa', 'dod', 'bsi',
5395 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33' algorithms. The
5396 availability of the algorithms may be limited by the version of the
5397 scrub binary installed on the host. The 'zero' algorithm will write ze‐
5398 roes to the entire volume. For some volumes, such as sparse or rbd vol‐
5399 umes, this may result in completely filling the volume with zeroes mak‐
5400 ing it appear to be completely full. As an alternative, the 'trim' al‐
5401 gorithm does not overwrite all the data in a volume, rather it expects
5402 the storage driver to be able to discard all bytes in a volume. It is
5403 up to the storage driver to handle how the discarding occurs. Not all
5404 storage drivers or volume types can support 'trim'.
5405 vol-dumpxml
5407 Syntax:
5408 vol-dumpxml vol-name-or-key-or-path [--pool pool-or-uuid]
5410 Output the volume information as an XML dump to stdout.
5412 vol-name-or-key-or-path is the name or key or path of the volume to
5414 output the XML.
5415 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5417 is in. If the volume name is provided instead of the key or path, then
5418 providing the pool is necessary to find the volume to be uploaded into;
5419 otherwise, the first volume found by the key or path will be used.
5420 vol-info
5422 Syntax:
5423 vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical]
5425 Returns basic information about the given storage volume.
5427 vol-name-or-key-or-path is the name or key or path of the volume to re‐
5429 turn information for.
5430 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5432 is in. If the volume name is provided instead of the key or path, then
5433 providing the pool is necessary to find the volume to be uploaded into;
5434 otherwise, the first volume found by the key or path will be used.
5435 If --bytes is specified the sizes are not converted to human friendly
5437 units.
5438 If --physical is specified, then the host physical size is returned and
5440 displayed instead of the allocation value. The physical value for some
5441 file types, such as qcow2 may have a different (larger) physical value
5442 than is shown for allocation. Additionally sparse files will have dif‐
5443 ferent physical and allocation values.
5444 vol-list
5446 Syntax:
5447 vol-list [--pool pool-or-uuid] [--details]
5449 Return the list of volumes in the given storage pool.
5451 --pool pool-or-uuid is the name or UUID of the storage pool.
5453 The --details option instructs virsh to additionally display volume
5455 type and capacity related information where available.
5456 vol-pool
5458 Syntax:
5459 vol-pool vol-key-or-path [--uuid]
5461 Return the pool name or UUID for a given volume. By default, the pool
5463 name is returned.
5464 vol-key-or-path is the key or path of the volume to return the pool in‐
5466 formation.
5467 If the --uuid option is given, the pool UUID is returned instead.
5469 vol-path
5471 Syntax:
5472 vol-path vol-name-or-key [--pool pool-or-uuid]
5474 Return the path for a given volume.
5476 vol-name-or-key is the name or key of the volume to return the path.
5478 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5480 is in. If the volume name is provided instead of the key, then provid‐
5481 ing the pool is necessary to find the volume to be uploaded into; oth‐
5482 erwise, the first volume found by the key will be used.
5483 vol-name
5485 Syntax:
5486 vol-name vol-key-or-path
5488 Return the name for a given volume.
5490 vol-key-or-path is the key or path of the volume to return the name.
5492 vol-key
5494 Syntax:
5495 vol-key vol-name-or-path [--pool pool-or-uuid]
5497 Return the volume key for a given volume.
5499 vol-name-or-path is the name or path of the volume to return the volume
5501 key.
5502 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5504 is in. If the volume name is provided instead of the path, then provid‐
5505 ing the pool is necessary to find the volume to be uploaded into; oth‐
5506 erwise, the first volume found by the path will be used.
5507 vol-resize
5509 Syntax:
5510 vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink]
5512 Resize the capacity of the given volume, in bytes.
5514 vol-name-or-key-or-path is the name or key or path of the volume to re‐
5516 size.
5517 capacity is a scaled integer (see NOTES above) for the volume, which
5519 defaults to bytes if there is no suffix.
5520 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5522 is in. If the volume name is provided instead of the key or path, then
5523 providing the pool is necessary to find the volume to be uploaded into;
5524 otherwise, the first volume found by the key or path will be used.
5525 The new capacity might be sparse unless --allocate is specified.
5527 Normally, capacity is the new size, but if --delta is present, then it
5529 is added to the existing size.
5530 Attempts to shrink the volume will fail unless --shrink is present.
5532 The capacity cannot be negative unless --shrink is provided, but a neg‐
5533 ative sign is not necessary.
5534 This command is only safe for storage volumes not in use by an active
5536 guest; see also blockresize for live resizing.
5537
5539 The following commands manipulate "secrets" (e.g. passwords,
5540 passphrases and encryption keys). Libvirt can store secrets indepen‐
5541 dently from their use, and other objects (e.g. volumes or domains) can
5542 refer to the secrets for encryption or possibly other uses. Secrets
5543 are identified using a UUID. See https://libvirt.org/formatsecret.html
5544 for documentation of the XML format used to represent properties of se‐
5545 crets.
5546 secret-define
5548 Syntax:
5549 secret-define file
5551 Create a secret with the properties specified in file, with no associ‐
5553 ated secret value. If file does not specify a UUID, choose one auto‐
5554 matically. If file specifies a UUID of an existing secret, replace its
5555 properties by properties defined in file, without affecting the secret
5556 value.
5557 secret-dumpxml
5559 Syntax:
5560 secret-dumpxml secret
5562 Output properties of secret (specified by its UUID) as an XML dump to
5564 stdout.
5565 secret-event
5567 Syntax:
5568 secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list}
5570 Wait for a class of secret events to occur, and print appropriate de‐
5572 tails of events as they happen. The events can optionally be filtered
5573 by secret. Using --list as the only argument will provide a list of
5574 possible event values known by this client, although the connection
5575 might not allow registering for all these events.
5576 By default, this command is one-shot, and returns success once an event
5578 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
5579 If --timeout is specified, the command gives up waiting for events af‐
5580 ter seconds have elapsed. With --loop, the command prints all events
5581 until a timeout or interrupt key.
5582 When --timestamp is used, a human-readable timestamp will be printed
5584 before the event.
5585 secret-set-value
5587 Syntax:
5588 secret-set-value secret (--file filename [--plain] | --interactive | base64)
5590 Set the value associated with secret (specified by its UUID) to the
5592 value Base64-encoded value base64 or Base-64-encoded contents of file
5593 named filename. Using the --plain flag is together with --file allows
5594 one to use the file contents directly as the secret value.
5595 If --interactive flag is used the secret value is read as a password
5597 from the terminal.
5598 Note that --file, --interactive and base64 options are mutually exclu‐
5600 sive.
5601 Passing secrets via the base64 option on command line is INSECURE and
5603 deprecated. Use the --file option instead.
5604 secret-get-value
5606 Syntax:
5607 secret-get-value [--plain] secret
5609 Output the value associated with secret (specified by its UUID) to std‐
5611 out, encoded using Base64.
5612 If the --plain flag is used the value is not base64 encoded, but rather
5614 printed raw. Note that unless virsh is started in quiet mode (virsh -q)
5615 it prints a newline at the end of the command. This newline is not part
5616 of the secret.
5617 secret-undefine
5619 Syntax:
5620 secret-undefine secret
5622 Delete a secret (specified by its UUID), including the associated
5624 value, if any.
5625 secret-list
5627 Syntax:
5628 secret-list [--ephemeral] [--no-ephemeral]
5630 [--private] [--no-private]
5631 Returns the list of secrets. You may also want to filter the returned
5633 secrets by --ephemeral to list the ephemeral ones, --no-ephemeral to
5634 list the non-ephemeral ones, --private to list the private ones, and
5635 --no-private to list the non-private ones.
5636
5638 The following commands manipulate domain snapshots. Snapshots take the
5639 disk, memory, and device state of a domain at a point-of-time, and save
5640 it for future use. They have many uses, from saving a "clean" copy of
5641 an OS image to saving a domain's state before a potentially destructive
5642 operation. Snapshots are identified with a unique name. See
5643 https://libvirt.org/formatsnapshot.html for documentation of the XML
5644 format used to represent properties of snapshots.
5645 snapshot-create
5647 Syntax:
5648 snapshot-create domain [xmlfile] {[--redefine [--current]] |
5650 [--no-metadata] [--halt] [--disk-only] [--reuse-external]
5651 [--quiesce] [--atomic] [--live]} [--validate]
5652 Create a snapshot for domain domain with the properties specified in
5654 xmlfile. Optionally, the --validate option can be passed to validate
5655 the format of the input XML file against an internal RNG schema (iden‐
5656 tical to using the virt-xml-validate(1) tool). Normally, the only prop‐
5657 erties settable for a domain snapshot are the <name> and <description>
5658 elements, as well as <disks> if --disk-only is given; the rest of the
5659 fields are ignored, and automatically filled in by libvirt. If xmlfile
5660 is completely omitted, then libvirt will choose a value for all fields.
5661 The new snapshot will become current, as listed by snapshot-current.
5662 If --halt is specified, the domain will be left in an inactive state
5664 after the snapshot is created.
5665 If --disk-only is specified, the snapshot will only include disk con‐
5667 tent rather than the usual full system snapshot with vm state. Disk
5668 snapshots are captured faster than full system snapshots, but reverting
5669 to a disk snapshot may require fsck or journal replays, since it is
5670 like the disk state at the point when the power cord is abruptly
5671 pulled; and mixing --halt and --disk-only loses any data that was not
5672 flushed to disk at the time.
5673 If --redefine is specified, then all XML elements produced by snap‐
5675 shot-dumpxml are valid; this can be used to migrate snapshot hierarchy
5676 from one machine to another, to recreate hierarchy for the case of a
5677 transient domain that goes away and is later recreated with the same
5678 name and UUID, or to make slight alterations in the snapshot metadata
5679 (such as host-specific aspects of the domain XML embedded in the snap‐
5680 shot). When this flag is supplied, the xmlfile argument is mandatory,
5681 and the domain's current snapshot will not be altered unless the --cur‐
5682 rent flag is also given.
5683 If --no-metadata is specified, then the snapshot data is created, but
5685 any metadata is immediately discarded (that is, libvirt does not treat
5686 the snapshot as current, and cannot revert to the snapshot unless --re‐
5687 define is later used to teach libvirt about the metadata again).
5688 If --reuse-external is specified, and the snapshot XML requests an ex‐
5690 ternal snapshot with a destination of an existing file, then the desti‐
5691 nation must exist and be pre-created with correct format and metadata.
5692 The file is then reused; otherwise, a snapshot is refused to avoid los‐
5693 ing contents of the existing files.
5694 If --quiesce is specified, libvirt will try to use guest agent to
5696 freeze and unfreeze domain's mounted file systems. However, if domain
5697 has no guest agent, snapshot creation will fail. Currently, this re‐
5698 quires --disk-only to be passed as well.
5699 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
5701 ther succeeds, or fails with no changes; not all hypervisors support
5702 this. If this flag is not specified, then some hypervisors may fail
5703 after partially performing the action, and dumpxml must be used to see
5704 whether any partial changes occurred.
5705 If --live is specified, libvirt takes the snapshot while the guest is
5707 running. Both disk snapshot and domain memory snapshot are taken. This
5708 increases the size of the memory image of the external snapshot. This
5709 is currently supported only for full system external snapshots.
5710 Existence of snapshot metadata will prevent attempts to undefine a per‐
5712 sistent guest. However, for transient domains, snapshot metadata is
5713 silently lost when the domain quits running (whether by command such as
5714 destroy or by internal guest action).
5715 For now, it is not possible to create snapshots in a domain that has
5717 checkpoints, although this restriction will be lifted in a future re‐
5718 lease.
5719 snapshot-create-as
5721 Syntax:
5722 snapshot-create-as domain {[--print-xml] [--no-metadata]
5724 [--halt] [--reuse-external]} [name]
5725 [description] [--disk-only [--quiesce]] [--atomic]
5726 [[--live] [--memspec memspec]] [--diskspec] diskspec]...
5727 Create a snapshot for domain domain with the given <name> and <descrip‐
5729 tion>; if either value is omitted, libvirt will choose a value. If
5730 --print-xml is specified, then XML appropriate for snapshot-create is
5731 output, rather than actually creating a snapshot. Otherwise, if --halt
5732 is specified, the domain will be left in an inactive state after the
5733 snapshot is created, and if --disk-only is specified, the snapshot will
5734 not include vm state.
5735 The --memspec option can be used to control whether a full system snap‐
5737 shot is internal or external. The --memspec flag is mandatory, fol‐
5738 lowed by a memspec of the form [file=]name[,snapshot=type], where type
5739 can be no, internal, or external. To include a literal comma in
5740 file=name, escape it with a second comma. --memspec cannot be used to‐
5741 gether with --disk-only.
5742 The --diskspec option can be used to control how --disk-only and exter‐
5744 nal full system snapshots create external files. This option can occur
5745 multiple times, according to the number of <disk> elements in the do‐
5746 main xml. Each <diskspec> is in the form disk[,snap‐
5747 shot=type][,driver=type][,stype=type][,file=name]. A diskspec must be
5748 provided for disks backed by block devices as libvirt doesn't auto-gen‐
5749 erate file names for those. The optional stype parameter allows one to
5750 control the type of the source file. Supported values are 'file' (de‐
5751 fault) and 'block'. To exclude a disk from an external snapshot use
5752 --diskspec disk,snapshot=no.
5753 To include a literal comma in disk or in file=name, escape it with a
5755 second comma. A literal --diskspec must precede each diskspec unless
5756 all three of domain, name, and description are also present. For exam‐
5757 ple, a diskspec of "vda,snapshot=external,file=/path/to,,new" results
5758 in the following XML:
5759 <disk name='vda' snapshot='external'>
5761 <source file='/path/to,new'/>
5762 </disk>
5763 If --reuse-external is specified, and the domain XML or diskspec option
5765 requests an external snapshot with a destination of an existing file,
5766 then the destination must exist and be pre-created with correct format
5767 and metadata. The file is then reused; otherwise, a snapshot is refused
5768 to avoid losing contents of the existing files.
5769 If --quiesce is specified, libvirt will try to use guest agent to
5771 freeze and unfreeze domain's mounted file systems. However, if domain
5772 has no guest agent, snapshot creation will fail. Currently, this re‐
5773 quires --disk-only to be passed as well.
5774 If --no-metadata is specified, then the snapshot data is created, but
5776 any metadata is immediately discarded (that is, libvirt does not treat
5777 the snapshot as current, and cannot revert to the snapshot unless snap‐
5778 shot-create is later used to teach libvirt about the metadata again).
5779 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
5781 ther succeeds, or fails with no changes; not all hypervisors support
5782 this. If this flag is not specified, then some hypervisors may fail
5783 after partially performing the action, and dumpxml must be used to see
5784 whether any partial changes occurred.
5785 If --live is specified, libvirt takes the snapshot while the guest is
5787 running. This increases the size of the memory image of the external
5788 snapshot. This is currently supported only for external full system
5789 snapshots.
5790 For now, it is not possible to create snapshots in a domain that has
5792 checkpoints, although this restriction will be lifted in a future re‐
5793 lease.
5794 snapshot-current
5796 Syntax:
5797 snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
5799 Without snapshotname, this will output the snapshot XML for the do‐
5801 main's current snapshot (if any). If --name is specified, just the
5802 current snapshot name instead of the full xml. Otherwise, using --se‐
5803 curity-info will also include security sensitive information in the
5804 XML.
5805 With snapshotname, this is a request to make the existing named snap‐
5807 shot become the current snapshot, without reverting the domain.
5808 snapshot-edit
5810 Syntax:
5811 snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]}
5813 Edit the XML configuration file for snapshotname of a domain. If both
5815 snapshotname and --current are specified, also force the edited snap‐
5816 shot to become the current snapshot. If snapshotname is omitted, then
5817 --current must be supplied, to edit the current snapshot.
5818 This is equivalent to:
5820 virsh snapshot-dumpxml dom name > snapshot.xml
5822 vi snapshot.xml (or make changes with your other text editor)
5823 virsh snapshot-create dom snapshot.xml --redefine [--current]
5824 except that it does some error checking.
5826 The editor used can be supplied by the $VISUAL or $EDITOR environment
5828 variables, and defaults to vi.
5829 If --rename is specified, then the edits can change the snapshot name.
5831 If --clone is specified, then changing the snapshot name will create a
5832 clone of the snapshot metadata. If neither is specified, then the ed‐
5833 its must not change the snapshot name. Note that changing a snapshot
5834 name must be done with care, since the contents of some snapshots, such
5835 as internal snapshots within a single qcow2 file, are accessible only
5836 from the original name.
5837 snapshot-info
5839 Syntax:
5840 snapshot-info domain {snapshot | --current}
5842 Output basic information about a named <snapshot>, or the current snap‐
5844 shot with --current.
5845 snapshot-list
5847 Syntax:
5848 snapshot-list domain [--metadata] [--no-metadata]
5850 [{--parent | --roots | [{--tree | --name}]}] [--topological]
5851 [{[--from] snapshot | --current} [--descendants]]
5852 [--leaves] [--no-leaves] [--inactive] [--active]
5853 [--disk-only] [--internal] [--external]
5854 List all of the available snapshots for the given domain, defaulting to
5856 show columns for the snapshot name, creation time, and domain state.
5857 Normally, table form output is sorted by snapshot name; using --topo‐
5859 logical instead sorts so that no child is listed before its ancestors
5860 (although there may be more than one possible ordering with this prop‐
5861 erty).
5862 If --parent is specified, add a column to the output table giving the
5864 name of the parent of each snapshot. If --roots is specified, the list
5865 will be filtered to just snapshots that have no parents. If --tree is
5866 specified, the output will be in a tree format, listing just snapshot
5867 names. These three options are mutually exclusive. If --name is speci‐
5868 fied only the snapshot name is printed. This option is mutually exclu‐
5869 sive with --tree.
5870 If --from is provided, filter the list to snapshots which are children
5872 of the given snapshot; or if --current is provided, start at the cur‐
5873 rent snapshot. When used in isolation or with --parent, the list is
5874 limited to direct children unless --descendants is also present. When
5875 used with --tree, the use of --descendants is implied. This option is
5876 not compatible with --roots. Note that the starting point of --from or
5877 --current is not included in the list unless the --tree option is also
5878 present.
5879 If --leaves is specified, the list will be filtered to just snapshots
5881 that have no children. Likewise, if --no-leaves is specified, the list
5882 will be filtered to just snapshots with children. (Note that omitting
5883 both options does no filtering, while providing both options will ei‐
5884 ther produce the same list or error out depending on whether the server
5885 recognizes the flags). Filtering options are not compatible with
5886 --tree.
5887 If --metadata is specified, the list will be filtered to just snapshots
5889 that involve libvirt metadata, and thus would prevent undefine of a
5890 persistent guest, or be lost on destroy of a transient domain. Like‐
5891 wise, if --no-metadata is specified, the list will be filtered to just
5892 snapshots that exist without the need for libvirt metadata.
5893 If --inactive is specified, the list will be filtered to snapshots that
5895 were taken when the domain was shut off. If --active is specified, the
5896 list will be filtered to snapshots that were taken when the domain was
5897 running, and where the snapshot includes the memory state to revert to
5898 that running state. If --disk-only is specified, the list will be fil‐
5899 tered to snapshots that were taken when the domain was running, but
5900 where the snapshot includes only disk state.
5901 If --internal is specified, the list will be filtered to snapshots that
5903 use internal storage of existing disk images. If --external is speci‐
5904 fied, the list will be filtered to snapshots that use external files
5905 for disk images or memory state.
5906 snapshot-dumpxml
5908 Syntax:
5909 snapshot-dumpxml domain snapshot [--security-info]
5911 Output the snapshot XML for the domain's snapshot named snapshot. Us‐
5913 ing --security-info will also include security sensitive information.
5914 Use snapshot-current to easily access the XML of the current snapshot.
5915 snapshot-parent
5917 Syntax:
5918 snapshot-parent domain {snapshot | --current}
5920 Output the name of the parent snapshot, if any, for the given snapshot,
5922 or for the current snapshot with --current.
5923 snapshot-revert
5925 Syntax:
5926 snapshot-revert domain {snapshot | --current} [{--running | --paused}] [--force]
5928 Revert the given domain to the snapshot specified by snapshot, or to
5930 the current snapshot with --current. Be aware that this is a destruc‐
5931 tive action; any changes in the domain since the last snapshot was
5932 taken will be lost. Also note that the state of the domain after snap‐
5933 shot-revert is complete will be the state of the domain at the time the
5934 original snapshot was taken.
5935 Normally, reverting to a snapshot leaves the domain in the state it was
5937 at the time the snapshot was created, except that a disk snapshot with
5938 no vm state leaves the domain in an inactive state. Passing either the
5939 --running or --paused flag will perform additional state changes (such
5940 as booting an inactive domain, or pausing a running domain). Since
5941 transient domains cannot be inactive, it is required to use one of
5942 these flags when reverting to a disk snapshot of a transient domain.
5943 There are a number of cases where a snapshot revert involves extra
5945 risk, which requires the use of --force to proceed:
5946 • One is the case of a snapshot that lacks full domain information
5948 for reverting configuration (such as snapshots created prior to
5949 libvirt 0.9.5); since libvirt cannot prove that the current con‐
5950 figuration matches what was in use at the time of the snapshot,
5951 supplying --force assures libvirt that the snapshot is compatible
5952 with the current configuration (and if it is not, the domain will
5953 likely fail to run).
5954 • Another is the case of reverting from a running domain to an ac‐
5956 tive state where a new hypervisor has to be created rather than
5957 reusing the existing hypervisor, because it implies drawbacks such
5958 as breaking any existing VNC or Spice connections; this condition
5959 happens with an active snapshot that uses a provably incompatible
5960 configuration, as well as with an inactive snapshot that is com‐
5961 bined with the --start or --pause flag.
5962 • Also, libvirt will refuse to restore snapshots of inactive QEMU
5964 domains while there is managed saved state. This is because those
5965 snapshots do not contain memory state and will therefore not re‐
5966 place the existing memory state. This ends up switching a disk un‐
5967 derneath a running system and will likely cause extensive filesys‐
5968 tem corruption or crashes due to swap content mismatches when run.
5969 snapshot-delete
5971 Syntax:
5972 snapshot-delete domain {snapshot | --current}
5974 [--metadata] [{--children | --children-only}]
5975 Delete the snapshot for the domain named snapshot, or the current snap‐
5977 shot with --current. If this snapshot has child snapshots, changes
5978 from this snapshot will be merged into the children. If --children is
5979 passed, then delete this snapshot and any children of this snapshot.
5980 If --children-only is passed, then delete any children of this snap‐
5981 shot, but leave this snapshot intact. These two flags are mutually ex‐
5982 clusive.
5983 If --metadata is specified, then only delete the snapshot metadata
5985 maintained by libvirt, while leaving the snapshot contents intact for
5986 access by external tools; otherwise deleting a snapshot also removes
5987 the data contents from that point in time.
5988
5990 The following commands manipulate domain checkpoints. Checkpoints
5991 serve as a point in time to identify which portions of a guest's disks
5992 have changed after that time, making it possible to perform incremental
5993 and differential backups. Checkpoints are identified with a unique
5994 name. See https://libvirt.org/formatcheckpoint.html for documentation
5995 of the XML format used to represent properties of checkpoints.
5996 checkpoint-create
5998 Syntax:
5999 checkpoint-create domain [xmlfile] { --redefine [--redefine-validate] | [--quiesce]}
6001 Create a checkpoint for domain domain with the properties specified in
6003 xmlfile describing a <domaincheckpoint> top-level element. The format
6004 of the input XML file will be validated against an internal RNG schema
6005 (identical to using the virt-xml-validate(1) tool). If xmlfile is com‐
6006 pletely omitted, then libvirt will create a checkpoint with a name
6007 based on the current time.
6008 If --redefine is specified, then all XML elements produced by check‐
6010 point-dumpxml are valid; this can be used to migrate checkpoint hierar‐
6011 chy from one machine to another, to recreate hierarchy for the case of
6012 a transient domain that goes away and is later recreated with the same
6013 name and UUID, or to make slight alterations in the checkpoint metadata
6014 (such as host-specific aspects of the domain XML embedded in the check‐
6015 point). When this flag is supplied, the xmlfile argument is mandatory.
6016 If --redefine-validate is specified along with --redefine the hypervi‐
6018 sor performs validation of metadata associated with the checkpoint
6019 stored in places besides the checkpoint XML. Note that some hypervisors
6020 may require that the domain is running to perform validation.
6021 If --quiesce is specified, libvirt will try to use guest agent to
6023 freeze and unfreeze domain's mounted file systems. However, if domain
6024 has no guest agent, checkpoint creation will fail.
6025 Existence of checkpoint metadata will prevent attempts to undefine a
6027 persistent guest. However, for transient domains, checkpoint metadata
6028 is silently lost when the domain quits running (whether by command such
6029 as destroy or by internal guest action).
6030 For now, it is not possible to create checkpoints in a domain that has
6032 snapshots, although this restriction will be lifted in a future re‐
6033 lease.
6034 checkpoint-create-as
6036 Syntax:
6037 checkpoint-create-as domain [--print-xml] [name]
6039 [description] [--quiesce] [--diskspec] diskspec]...
6040 Create a checkpoint for domain domain with the given <name> and <de‐
6042 scription>; if either value is omitted, libvirt will choose a value.
6043 If --print-xml is specified, then XML appropriate for checkpoint-create
6044 is output, rather than actually creating a checkpoint.
6045 The --diskspec option can be used to control which guest disks partici‐
6047 pate in the checkpoint. This option can occur multiple times, according
6048 to the number of <disk> elements in the domain xml. Each <diskspec> is
6049 in the form disk[,checkpoint=type][,bitmap=name]. A literal --diskspec
6050 must precede each diskspec unless all three of domain, name, and de‐
6051 scription are also present. For example, a diskspec of "vda,check‐
6052 point=bitmap,bitmap=map1" results in the following XML:
6053 <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
6055 If --quiesce is specified, libvirt will try to use guest agent to
6057 freeze and unfreeze domain's mounted file systems. However, if domain
6058 has no guest agent, checkpoint creation will fail.
6059 For now, it is not possible to create checkpoints in a domain that has
6061 snapshots, although this restriction will be lifted in a future re‐
6062 lease.
6063 checkpoint-edit
6065 Syntax:
6066 checkpoint-edit domain checkpointname
6068 Edit the XML configuration file for checkpointname of a domain.
6070 This is equivalent to:
6072 virsh checkpoint-dumpxml dom name > checkpoint.xml
6074 vi checkpoint.xml (or make changes with your other text editor)
6075 virsh checkpoint-create dom checkpoint.xml --redefine
6076 except that it does some error checking, including that the edits
6078 should not attempt to change the checkpoint name.
6079 The editor used can be supplied by the $VISUAL or $EDITOR environment
6081 variables, and defaults to vi.
6082 checkpoint-info
6084 Syntax:
6085 checkpoint-info domain checkpoint
6087 Output basic information about a named <checkpoint>.
6089 checkpoint-list
6091 Syntax:
6092 checkpoint-list domain [{--parent | --roots |
6094 [{--tree | --name}]}] [--topological]
6095 [[--from] checkpoint | [--descendants]]
6096 [--leaves] [--no-leaves]
6097 List all of the available checkpoints for the given domain, defaulting
6099 to show columns for the checkpoint name and creation time.
6100 Normally, table form output is sorted by checkpoint name; using --topo‐
6102 logical instead sorts so that no child is listed before its ancestors
6103 (although there may be more than one possible ordering with this prop‐
6104 erty).
6105 If --parent is specified, add a column to the output table giving the
6107 name of the parent of each checkpoint. If --roots is specified, the
6108 list will be filtered to just checkpoints that have no parents. If
6109 --tree is specified, the output will be in a tree format, listing just
6110 checkpoint names. These three options are mutually exclusive. If
6111 --name is specified only the checkpoint name is printed. This option is
6112 mutually exclusive with --tree.
6113 If --from is provided, filter the list to checkpoints which are chil‐
6115 dren of the given checkpoint. When used in isolation or with --parent,
6116 the list is limited to direct children unless --descendants is also
6117 present. When used with --tree, the use of --descendants is implied.
6118 This option is not compatible with --roots. Note that the starting
6119 point of --from is not included in the list unless the --tree option is
6120 also present.
6121 If --leaves is specified, the list will be filtered to just checkpoints
6123 that have no children. Likewise, if --no-leaves is specified, the list
6124 will be filtered to just checkpoints with children. (Note that omit‐
6125 ting both options does no filtering, while providing both options will
6126 either produce the same list or error out depending on whether the
6127 server recognizes the flags). Filtering options are not compatible
6128 with --tree.
6129 checkpoint-dumpxml
6131 Syntax:
6132 checkpoint-dumpxml domain checkpoint [--security-info] [--no-domain] [--size]
6134 Output the checkpoint XML for the domain's checkpoint named checkpoint.
6136 Using --security-info will also include security sensitive information.
6137 Using --size will add XML indicating the current size in bytes of guest
6139 data that has changed since the checkpoint was created (although remem‐
6140 ber that guest activity between a size check and actually creating a
6141 backup can result in the backup needing slightly more space). Note that
6142 some hypervisors may require that domain is running when --size is
6143 used.
6144 Using --no-domain will omit the <domain> element from the output for a
6146 more compact view.
6147 checkpoint-parent
6149 Syntax:
6150 checkpoint-parent domain checkpoint
6152 Output the name of the parent checkpoint, if any, for the given check‐
6154 point.
6155 checkpoint-delete
6157 Syntax:
6158 checkpoint-delete domain checkpoint
6160 [--metadata] [{--children | --children-only}]
6161 Delete the checkpoint for the domain named checkpoint. The record of
6163 which portions of the disk changed since the checkpoint are merged into
6164 the parent checkpoint (if any). If --children is passed, then delete
6165 this checkpoint and any children of this checkpoint. If --chil‐
6166 dren-only is passed, then delete any children of this checkpoint, but
6167 leave this checkpoint intact. These two flags are mutually exclusive.
6168 If --metadata is specified, then only delete the checkpoint metadata
6170 maintained by libvirt, while leaving the checkpoint contents intact for
6171 access by external tools; otherwise deleting a checkpoint also removes
6172 the ability to perform an incremental backup from that point in time.
6173
6175 The following commands manipulate network filters. Network filters al‐
6176 low filtering of the network traffic coming from and going to virtual
6177 machines. Individual network traffic filters are written in XML and
6178 may contain references to other network filters, describe traffic fil‐
6179 tering rules, or contain both. Network filters are referenced by vir‐
6180 tual machines from within their interface description. A network filter
6181 may be referenced by multiple virtual machines' interfaces.
6182 nwfilter-define
6184 Syntax:
6185 nwfilter-define xmlfile
6187 Make a new network filter known to libvirt. If a network filter with
6189 the same name already exists, it will be replaced with the new XML.
6190 Any running virtual machine referencing this network filter will have
6191 its network traffic rules adapted. If for any reason the network traf‐
6192 fic filtering rules cannot be instantiated by any of the running vir‐
6193 tual machines, then the new XML will be rejected.
6194 nwfilter-undefine
6196 Syntax:
6197 nwfilter-undefine nwfilter-name
6199 Delete a network filter. The deletion will fail if any running virtual
6201 machine is currently using this network filter.
6202 nwfilter-list
6204 Syntax:
6205 nwfilter-list
6207 List all of the available network filters.
6209 nwfilter-dumpxml
6211 Syntax:
6212 nwfilter-dumpxml nwfilter-name
6214 Output the network filter XML.
6216 nwfilter-edit
6218 Syntax:
6219 nwfilter-edit nwfilter-name
6221 Edit the XML of a network filter.
6223 This is equivalent to:
6225 virsh nwfilter-dumpxml myfilter > myfilter.xml
6227 vi myfilter.xml (or make changes with your other text editor)
6228 virsh nwfilter-define myfilter.xml
6229 except that it does some error checking. The new network filter may be
6231 rejected due to the same reason as mentioned in nwfilter-define.
6232 The editor used can be supplied by the $VISUAL or $EDITOR environment
6234 variables, and defaults to vi.
6235
6237 The following commands manipulate network filter bindings. Network fil‐
6238 ter bindings track the association between a network port and a network
6239 filter. Generally the bindings are managed automatically by the hyper‐
6240 visor drivers when adding/removing NICs on a guest.
6241 If an admin is creating/deleting TAP devices for non-guest usage, how‐
6243 ever, the network filter binding commands provide a way to make use of
6244 the network filters directly.
6245 nwfilter-binding-create
6247 Syntax:
6248 nwfilter-binding-create xmlfile
6250 Associate a network port with a network filter. The network filter
6252 backend will immediately attempt to instantiate the filter rules on the
6253 port. This command may be used to associate a filter with a currently
6254 running guest that does not have a filter defined for a specific net‐
6255 work port. Since the bindings are generally automatically managed by
6256 the hypervisor, using this command to define a filter for a network
6257 port and then starting the guest afterwards may prevent the guest from
6258 starting if it attempts to use the network port and finds a filter al‐
6259 ready defined.
6260 nwfilter-binding-delete
6262 Syntax:
6263 nwfilter-binding-delete port-name
6265 Disassociate a network port from a network filter. The network filter
6267 backend will immediately tear down the filter rules that exist on the
6268 port. This command may be used to remove the network port binding for a
6269 filter currently in use for the guest while the guest is running with‐
6270 out needing to restart the guest. Restoring the network port binding
6271 filter for the running guest would be accomplished by using nwfil‐
6272 ter-binding-create.
6273 nwfilter-binding-list
6275 Syntax:
6276 nwfilter-binding-list
6278 List all of the network ports which have filters associated with them.
6280 nwfilter-binding-dumpxml
6282 Syntax:
6283 nwfilter-binding-dumpxml port-name
6285 Output the network filter binding XML for the network device called
6287 port-name.
6288
6290 NOTE: Use of the following commands is strongly discouraged. They can
6291 cause libvirt to become confused and do the wrong thing on subsequent
6292 operations. Once you have used these commands, please do not report
6293 problems to the libvirt developers; the reports will be ignored. If
6294 you find that these commands are the only way to accomplish something,
6295 then it is better to request that the feature be added as a first-class
6296 citizen in the regular libvirt library.
6297 qemu-attach
6299 Syntax:
6300 qemu-attach pid
6302 Attach an externally launched QEMU process to the libvirt QEMU driver.
6304 The QEMU process must have been created with a monitor connection using
6305 the UNIX driver. Ideally the process will also have had the '-name' ar‐
6306 gument specified.
6307 $ qemu-kvm -cdrom ~/demo.iso \
6309 -monitor unix:/tmp/demo,server,nowait \
6310 -name foo \
6311 -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea &
6312 $ QEMUPID=$!
6313 $ virsh qemu-attach $QEMUPID
6314 Not all functions of libvirt are expected to work reliably after at‐
6316 taching to an externally launched QEMU process. There may be issues
6317 with the guest ABI changing upon migration and device hotplug or hotun‐
6318 plug may not work. The attached environment should be considered pri‐
6319 marily read-only.
6320 qemu-monitor-command
6322 Syntax:
6323 qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] } command...
6325 Send an arbitrary monitor command command to domain domain through the
6327 QEMU monitor. The results of the command will be printed on stdout.
6328 If more than one argument is provided for command, they are concate‐
6330 nated with a space in between before passing the single command to the
6331 monitor.
6332 Note that libvirt uses the QMP to talk to qemu so command must be valid
6334 JSON in QMP format to work properly.
6335 If --pretty is given the QMP reply is pretty-printed.
6337 If --return-value is given the 'return' key of the QMP response object
6339 is extracted rather than passing through the full reply from QEMU.
6340 If --hmp is passed, the command is considered to be a human monitor
6342 command and libvirt will automatically convert it into QMP and convert
6343 the result back.
6344 qemu-agent-command
6346 Syntax:
6347 qemu-agent-command domain [--timeout seconds | --async | --block] command...
6349 Send an arbitrary guest agent command command to domain domain through
6351 QEMU agent. --timeout, --async and --block options are exclusive.
6352 --timeout requires timeout seconds seconds and it must be positive.
6353 When --aysnc is given, the command waits for timeout whether success or
6354 failed. And when --block is given, the command waits forever with
6355 blocking timeout.
6356 qemu-monitor-event
6358 Syntax:
6359 qemu-monitor-event [domain] [--event event-name]
6361 [--loop] [--timeout seconds] [--pretty] [--regex] [--no-case]
6362 [--timestamp]
6363 Wait for arbitrary QEMU monitor events to occur, and print out the de‐
6365 tails of events as they happen. The events can optionally be filtered
6366 by domain or event-name. The 'query-events' QMP command can be used
6367 via qemu-monitor-command to learn what events are supported. If
6368 --regex is used, event-name is a basic regular expression instead of a
6369 literal string. If --no-case is used, event-name will match case-in‐
6370 sensitively.
6371 By default, this command is one-shot, and returns success once an event
6373 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
6374 If --timeout is specified, the command gives up waiting for events af‐
6375 ter seconds have elapsed. With --loop, the command prints all events
6376 until a timeout or interrupt key. If --pretty is specified, any JSON
6377 event details are pretty-printed for better legibility.
6378 When --timestamp is used, a human-readable timestamp will be printed
6380 before the event, and the timing information provided by QEMU will be
6381 omitted.
6382 lxc-enter-namespace
6384 Syntax:
6385 lxc-enter-namespace domain [--noseclabel] --
6387 /path/to/binary [arg1, [arg2, ...]]
6388 Enter the namespace of domain and execute the command /path/to/binary
6390 passing the requested args. The binary path is relative to the con‐
6391 tainer root filesystem, not the host root filesystem. The binary will
6392 inherit the environment variables / console visible to virsh. The com‐
6393 mand will be run with the same sVirt context and cgroups placement as
6394 processes within the container. This command only works when connected
6395 to the LXC hypervisor driver. This command succeeds only if
6396 /path/to/binary has 0 exit status.
6397 By default the new process will run with the security label of the new
6399 parent container. Use the --noseclabel option to instead have the
6400 process keep the same security label as virsh.
6401
6403 The following environment variables can be set to alter the behaviour
6404 of virsh
6405 • VIRSH_DEBUG=<0 to 4>
6407 Turn on verbose debugging of virsh commands. Valid levels are
6409 • VIRSH_DEBUG=0
6411 DEBUG - Messages at ALL levels get logged
6413 • VIRSH_DEBUG=1
6415 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
6417 • VIRSH_DEBUG=2
6419 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
6421 • VIRSH_DEBUG=3
6423 WARNING - Logs messages at levels WARNING and ERROR
6425 • VIRSH_DEBUG=4
6427 ERROR - Messages at only ERROR level gets logged.
6429 • VIRSH_LOG_FILE=``LOGFILE``
6431 The file to log virsh debug messages.
6433 • VIRSH_DEFAULT_CONNECT_URI
6435 The hypervisor to connect to by default. Set this to a URI, in the
6437 same format as accepted by the connect option. This environment vari‐
6438 able is deprecated in favour of the global LIBVIRT_DEFAULT_URI vari‐
6439 able which serves the same purpose.
6440 • LIBVIRT_DEFAULT_URI
6442 The hypervisor to connect to by default. Set this to a URI, in the
6444 same format as accepted by the connect option. This overrides the de‐
6445 fault URI set in any client config file and prevents libvirt from
6446 probing for drivers.
6447 • VISUAL
6449 The editor to use by the edit and related options.
6451 • EDITOR
6453 The editor to use by the edit and related options, if VISUAL is not
6455 set.
6456 • VIRSH_HISTSIZE
6458 The number of commands to remember in the command history. The de‐
6460 fault value is 500.
6461 • LIBVIRT_DEBUG=LEVEL
6463 Turn on verbose debugging of all libvirt API calls. Valid levels are
6465 • LIBVIRT_DEBUG=1
6467 Messages at level DEBUG or above
6469 • LIBVIRT_DEBUG=2
6471 Messages at level INFO or above
6473 • LIBVIRT_DEBUG=3
6475 Messages at level WARNING or above
6477 • LIBVIRT_DEBUG=4
6479 Messages at level ERROR
6481 For further information about debugging options consult
6483 https://libvirt.org/logging.html
6484
6486 Please report all bugs you discover. This should be done via either:
6487 1. the mailing list
6489 https://libvirt.org/contact.html
6491 2. the bug tracker
6493 https://libvirt.org/bugs.html
6495 Alternatively, you may report bugs to your software distributor / ven‐
6497 dor.
6498
6500 Please refer to the AUTHORS file distributed with libvirt.
6501
6503 Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in
6504 the libvirt AUTHORS file.
6505
6507 virsh is distributed under the terms of the GNU LGPL v2+. This is free
6508 software; see the source for copying conditions. There is NO warranty;
6509 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
6510
6512 virt-install(1), virt-xml-validate(1), virt-top(1), virt-df(1),
6513 https://libvirt.org/
6514 VIRSH(1)