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
15 domains. The program can be used to create, pause, and shutdown
16 domains. It can also be used to list current domains. Libvirt is a C
17 toolkit to interact with the virtualization capabilities of recent
18 versions of Linux (and other OSes). It is free software available under
19 the GNU Lesser General Public License. Virtualization of the Linux
20 Operating System means the ability to run multiple instances of
21 Operating Systems concurrently on a single hardware system where the
22 basic resources are driven by a Linux instance. The library aims at
23 providing a long term stable C API. It currently supports Xen, QEMU,
24 KVM, LXC, OpenVZ, VirtualBox 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
31 numeric 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
36 numeric names to domains, however, doing so will result in a domain
37 that can only be identified by domain id. In other words, if a numeric
38 value is supplied it will be interpreted as a domain id, not as a name.
39 Any command starting with # is treated as a comment and silently
40 ignored, 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
44 COMMAND_STRING which is a single shell argument consisting of multiple
45 COMMAND actions and their arguments joined with whitespace and
46 separated by semicolons or newlines between commands, where unquoted
47 backslash-newline pairs are elided. Within COMMAND_STRING, virsh
48 understands the same single, double, and backslash escapes as the
49 shell, although you must add another layer of shell escaping in
50 creating the single shell argument, and any word starting with unquoted
51 # begins a comment that ends at newline. If no command is given in the
52 command line, virsh will then start a minimal interpreter waiting for
53 your commands, 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
59 of the default connection.
60 -d, --debug LEVEL
62 Enable debug messages at integer LEVEL and above. LEVEL can range
63 from 0 to 4 (default). See the documentation of VIRSH_DEBUG
64 environment variable below for the description of each LEVEL.
65 -e, --escape string
67 Set alternative escape sequence for console command. By default,
68 telnet's ^] is used. Allowed characters when using hat notation
69 are: alphabetic character, @, [, ], \, ^, _.
70 -h, --help
72 Ignore all other arguments, and behave as if the help command were
73 given instead.
74 -k, --keepalive-interval INTERVAL
76 Set an INTERVAL (in seconds) for sending keepalive messages to
77 check whether connection to the server is still alive. Setting the
78 interval to 0 disables client keepalive mechanism.
79 -K, --keepalive-count COUNT
81 Set a number of times keepalive message can be sent without getting
82 an answer from the server without marking the connection dead.
83 There is no effect to this setting in case the INTERVAL is set to
84 0.
85 -l, --log FILE
87 Output logging details to FILE.
88 -q, --quiet
90 Avoid extra informational messages.
91 -r, --readonly
93 Make the initial connection read-only, as if by the --readonly
94 option of the connect command.
95 -t, --timing
97 Output elapsed time information for each command.
98 -v, --version[=short]
100 Ignore all other arguments, and prints the version of the libvirt
101 library virsh is coming from
102 -V, --version=long
104 Ignore all other arguments, and prints the version of the libvirt
105 library virsh is coming from and which options and driver are
106 compiled in.
107
109 Most virsh operations rely upon the libvirt library being able to
110 connect to an already running libvirtd service. This can usually be
111 done using the command service libvirtd start.
112 Most virsh commands require root privileges to run due to the
114 communications channels used to talk to the hypervisor. Running as non
115 root will return an error.
116 Most virsh commands act synchronously, except maybe shutdown, setvcpus
118 and setmem. In those cases the fact that the virsh program returned,
119 may not mean the action is complete and you must poll periodically to
120 detect that the guest completed the operation.
121 virsh strives for backward compatibility. Although the help command
123 only lists the preferred usage of a command, if an older version of
124 virsh supported an alternate spelling of a command or option (such as
125 --tunnelled instead of --tunneled), then scripts using that older
126 spelling will continue to work.
127 Several virsh commands take an optionally scaled integer; if no scale
129 is provided, then the default is listed in the command (for historical
130 reasons, some commands default to bytes, while other commands default
131 to kibibytes). The following case-insensitive suffixes can be used to
132 select a specific scale:
133 b, byte byte 1
134 KB kilobyte 1,000
135 k, KiB kibibyte 1,024
136 MB megabyte 1,000,000
137 M, MiB mebibyte 1,048,576
138 GB gigabyte 1,000,000,000
139 G, GiB gibibyte 1,073,741,824
140 TB terabyte 1,000,000,000,000
141 T, TiB tebibyte 1,099,511,627,776
142 PB petabyte 1,000,000,000,000,000
143 P, PiB pebibyte 1,125,899,906,842,624
144 EB exabyte 1,000,000,000,000,000,000
145 E, EiB exbibyte 1,152,921,504,606,846,976
146
148 The following commands are generic i.e. not specific to a domain.
149 help [command-or-group]
151 This lists each of the virsh commands. When used without options,
152 all commands are listed, one per line, grouped into related
153 categories, displaying the keyword for each group.
154 To display only commands for a specific group, give the keyword for
156 that group as an option. For example:
157 virsh # help host
159 Host and Hypervisor (help keyword 'host'):
161 capabilities capabilities
162 cpu-models show the CPU models for an architecture
163 connect (re)connect to hypervisor
164 freecell NUMA free memory
165 hostname print the hypervisor hostname
166 qemu-attach Attach to existing QEMU process
167 qemu-monitor-command QEMU Monitor Command
168 qemu-agent-command QEMU Guest Agent Command
169 sysinfo print the hypervisor sysinfo
170 uri print the hypervisor canonical URI
171 To display detailed information for a specific command, give its
173 name as the option instead. For example:
174 virsh # help list
176 NAME
177 list - list domains
178 SYNOPSIS
180 list [--inactive] [--all]
181 DESCRIPTION
183 Returns list of domains.
184 OPTIONS
186 --inactive list inactive domains
187 --all list inactive & active domains
188 quit, exit
190 quit this interactive terminal
191 version [--daemon]
193 Will print out the major version info about what this built from.
194 If --daemon is specified then the version of the libvirt daemon is
195 included in the output.
196 Example
198 $ virsh version
200 Compiled against library: libvirt 1.2.3
201 Using library: libvirt 1.2.3
202 Using API: QEMU 1.2.3
203 Running hypervisor: QEMU 2.0.50
204 $ virsh version --daemon
206 Compiled against library: libvirt 1.2.3
207 Using library: libvirt 1.2.3
208 Using API: QEMU 1.2.3
209 Running hypervisor: QEMU 2.0.50
210 Running against daemon: 1.2.6
211 cd [directory]
213 Will change current directory to directory. The default directory
214 for the cd command is the home directory or, if there is no HOME
215 variable in the environment, the root directory.
216 This command is only available in interactive mode.
218 pwd Will print the current directory.
220 connect [URI] [--readonly]
222 (Re)-Connect to the hypervisor. When the shell is first started,
223 this is automatically run with the URI parameter requested by the
224 "-c" option on the command line. The URI parameter specifies how to
225 connect to the hypervisor. The documentation page at
226 <https://libvirt.org/uri.html> list the values supported, but the
227 most common are:
228 xen:///system
230 this is used to connect to the local Xen hypervisor
231 qemu:///system
233 connect locally as root to the daemon supervising QEMU and KVM
234 domains
235 qemu:///session
237 connect locally as a normal user to his own set of QEMU and KVM
238 domains
239 lxc:///system
241 connect to a local linux container
242 To find the currently used URI, check the uri command documented
244 below.
245 For remote access see the documentation page at
247 <https://libvirt.org/uri.html> on how to make URIs. The --readonly
248 option allows for read-only connection
249 uri Prints the hypervisor canonical URI, can be useful in shell mode.
251 hostname
253 Print the hypervisor hostname.
254 sysinfo
256 Print the XML representation of the hypervisor sysinfo, if
257 available.
258 nodeinfo
260 Returns basic information about the node, like number and type of
261 CPU, and size of the physical memory. The output corresponds to
262 virNodeInfo structure. Specifically, the "CPU socket(s)" field
263 means number of CPU sockets per NUMA cell. The information libvirt
264 displays is dependent upon what each architecture may provide.
265 nodecpumap [--pretty]
267 Displays the node's total number of CPUs, the number of online CPUs
268 and the list of online CPUs.
269 With --pretty the online CPUs are printed as a range instead of a
271 list.
272 nodecpustats [cpu] [--percent]
274 Returns cpu stats of the node. If cpu is specified, this will
275 print the specified cpu statistics only. If --percent is
276 specified, this will print the percentage of each kind of cpu
277 statistics during 1 second.
278 nodememstats [cell]
280 Returns memory stats of the node. If cell is specified, this will
281 print the specified cell statistics only.
282 nodesuspend [target] [duration]
284 Puts the node (host machine) into a system-wide sleep state and
285 schedule the node's Real-Time-Clock interrupt to resume the node
286 after the time duration specified by duration is out. target
287 specifies the state to which the host will be suspended to, it can
288 be "mem" (suspend to RAM), "disk" (suspend to disk), or "hybrid"
289 (suspend to both RAM and disk). duration specifies the time
290 duration in seconds for which the host has to be suspended, it
291 should be at least 60 seconds.
292 node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs] [shm-merge-
294 across-nodes]
295 Allows you to display or set the node memory parameters. shm-
296 pages-to-scan can be used to set the number of pages to scan before
297 the shared memory service goes to sleep; shm-sleep-millisecs can be
298 used to set the number of millisecs the shared memory service
299 should sleep before next scan; shm-merge-across-nodes specifies if
300 pages from different numa nodes can be merged. When set to 0, only
301 pages which physically reside in the memory area of same NUMA node
302 can be merged. When set to 1, pages from all nodes can be merged.
303 Default to 1.
304 Note: Currently the "shared memory service" only means KSM (Kernel
306 Samepage Merging).
307 capabilities
309 Print an XML document describing the capabilities of the hypervisor
310 we are currently connected to. This includes a section on the host
311 capabilities in terms of CPU and features, and a set of description
312 for each kind of guest which can be virtualized. For a more
313 complete description see:
314 <https://libvirt.org/formatcaps.html> The XML also show the NUMA
315 topology information if available.
316 domcapabilities [virttype] [emulatorbin] [arch] [machine]
318 Print an XML document describing the domain capabilities for the
319 hypervisor we are connected to using information either sourced
320 from an existing domain or taken from the virsh capabilities
321 output. This may be useful if you intend to create a new domain and
322 are curious if for instance it could make use of VFIO by creating a
323 domain for the hypervisor with a specific emulator and
324 architecture.
325 Each hypervisor will have different requirements regarding which
327 options are required and which are optional. A hypervisor can
328 support providing a default value for any of the options.
329 The virttype option specifies the virtualization type used. The
331 value to be used is either from the 'type' attribute of the
332 <domain/> top level element from the domain XML or the 'type'
333 attribute found within each <guest/> element from the virsh
334 capabilities output. The emulatorbin option specifies the path to
335 the emulator. The value to be used is either the <emulator> element
336 in the domain XML or the virsh capabilities output. The arch option
337 specifies the architecture to be used for the domain. The value to
338 be used is either the "arch" attribute from the domain's XML <os/>
339 element and <type/> subelement or the "name" attribute of an
340 <arch/> element from the virsh capabililites output. The machine
341 specifies the machine type for the emulator. The value to be used
342 is either the "machine" attribute from the domain's XML <os/>
343 element and <type/> subelement or one from a list of machines from
344 the virsh capabilities output for a specific architecture and
345 domain type.
346 For the qemu hypervisor, a virttype of either 'qemu' or 'kvm' must
348 be supplied along with either the emulatorbin or arch in order to
349 generate output for the default machine. Supplying a machine value
350 will generate output for the specific machine.
351 pool-capabilities Print an XML document describing the storage pool
353 capabilities for the connected storage driver. This may be useful if
354 you intend to create a new storage pool and need to know the available
355 pool types and supported storage pool source and target volume formats
356 as well as the required source elements to create the pool.
357 inject-nmi domain
358 Inject NMI to the guest.
359 list [--inactive | --all] [--managed-save] [--title] { [--table] |
361 --name | --uuid } [--persistent] [--transient] [--with-managed-save]
362 [--without-managed-save] [--autostart] [--no-autostart]
363 [--with-snapshot] [--without-snapshot] [--with-checkpoint]
364 [--without-checkpoint] [--state-running] [--state-paused]
365 [--state-shutoff] [--state-other]
366 Prints information about existing domains. If no options are
367 specified it prints out information about running domains.
368 An example format for the list is as follows:
370 virsh list
372 Id Name State
373 ----------------------------------------------------
374 0 Domain-0 running
375 2 fedora paused
376 Name is the name of the domain. ID the domain numeric id. State
378 is the run state (see below).
379 STATES
381 The State field lists what state each domain is currently in. A
383 domain can be in one of the following possible states:
384 running
386 The domain is currently running on a CPU
387 idle
389 The domain is idle, and not running or runnable. This can be
390 caused because the domain is waiting on IO (a traditional wait
391 state) or has gone to sleep because there was nothing else for
392 it to do.
393 paused
395 The domain has been paused, usually occurring through the
396 administrator running virsh suspend. When in a paused state
397 the domain will still consume allocated resources like memory,
398 but will not be eligible for scheduling by the hypervisor.
399 in shutdown
401 The domain is in the process of shutting down, i.e. the guest
402 operating system has been notified and should be in the process
403 of stopping its operations gracefully.
404 shut off
406 The domain is not running. Usually this indicates the domain
407 has been shut down completely, or has not been started.
408 crashed
410 The domain has crashed, which is always a violent ending.
411 Usually this state can only occur if the domain has been
412 configured not to restart on crash.
413 pmsuspended
415 The domain has been suspended by guest power management, e.g.
416 entered into s3 state.
417 Normally only active domains are listed. To list inactive domains
419 specify --inactive or --all to list both active and inactive
420 domains.
421 To further filter the list of domains you may specify one or more
423 of filtering flags supported by the list command. These flags are
424 grouped by function. Specifying one or more flags from a group
425 enables the filter group. Note that some combinations of flags may
426 yield no results. Supported filtering flags and groups:
427 Persistence
429 Flag --persistent is used to include persistent domains in the
430 returned list. To include transient domains specify
431 --transient.
432 Existence of managed save image
434 To list domains having a managed save image specify flag
435 --with-managed-save. For domains that don't have a managed save
436 image specify --without-managed-save.
437 Domain state
439 The following filter flags select a domain by its state:
440 --state-running for running domains, --state-paused for paused
441 domains, --state-shutoff for turned off domains and
442 --state-other for all other states as a fallback.
443 Autostarting domains
445 To list autostarting domains use the flag --autostart. To list
446 domains with this feature disabled use --no-autostart.
447 Snapshot existence
449 Domains that have snapshot images can be listed using flag
450 --with-snapshot, domains without a snapshot --without-snapshot.
451 Checkpoint existence
453 Domains that have checkpoints can be listed using flag
454 --with-checkpoint, domains without a checkpoint
455 --without-checkpoint.
456 When talking to older servers, this command is forced to use a
458 series of API calls with an inherent race, where a domain might not
459 be listed or might appear more than once if it changed state
460 between calls while the list was being collected. Newer servers do
461 not have this problem.
462 If --managed-save is specified, then domains that have managed save
464 state (only possible if they are in the shut off state, so you need
465 to specify --inactive or --all to actually list them) will instead
466 show as saved in the listing. This flag is usable only with the
467 default --table output. Note that this flag does not filter the
468 list of domains.
469 If --name is specified, domain names are printed instead of the
471 table formatted one per line. If --uuid is specified domain's
472 UUID's are printed instead of names. Flag --table specifies that
473 the legacy table-formatted output should be used. This is the
474 default.
475 If both --name and --uuid are specified, domain UUID's and names
477 are printed side by side without any header. Flag --table specifies
478 that the legacy table-formatted output should be used. This is the
479 default if neither --name nor --uuid are specified. Option --table
480 is mutually exclusive with options --uuid and --name.
481 If --title is specified, then the short domain description (title)
483 is printed in an extra column. This flag is usable only with the
484 default --table output.
485 Example:
487 virsh list --title
489 Id Name State Title
490 -------------------------------------------
491 0 Domain-0 running Mailserver 1
492 2 fedora paused
493 freecell [{ [--cellno] cellno | --all }]
495 Prints the available amount of memory on the machine or within a
496 NUMA cell. The freecell command can provide one of three different
497 displays of available memory on the machine depending on the
498 options specified. With no options, it displays the total free
499 memory on the machine. With the --all option, it displays the free
500 memory in each cell and the total free memory on the machine.
501 Finally, with a numeric argument or with --cellno plus a cell
502 number it will display the free memory for the specified cell only.
503 freepages [{ [--cellno] cellno [--pagesize] pagesize | --all }]
505 Prints the available amount of pages within a NUMA cell. cellno
506 refers to the NUMA cell you're interested in. pagesize is a scaled
507 integer (see NOTES above). Alternatively, if --all is used, info
508 on each possible combination of NUMA cell and page size is printed
509 out.
510 allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno]
512 cellno] [--add] [--all]
513 Change the size of pages pool of pagesize on the host. If --add is
514 specified, then pagecount pages are added into the pool. However,
515 if --add wasn't specified, then the pagecount is taken as the new
516 absolute size of the pool (this may be used to free some pages and
517 size the pool down). The cellno modifier can be used to narrow the
518 modification down to a single host NUMA cell. On the other end of
519 spectrum lies --all which executes the modification on all NUMA
520 cells.
521 cpu-baseline FILE [--features] [--migratable]
523 Compute baseline CPU which will be supported by all host CPUs given
524 in <file>. (See hypervisor-cpu-baseline command to get a CPU which
525 can be provided by a specific hypervisor.) The list of host CPUs is
526 built by extracting all <cpu> elements from the <file>. Thus, the
527 <file> can contain either a set of <cpu> elements separated by new
528 lines or even a set of complete <capabilities> elements printed by
529 capabilities command. If --features is specified, then the
530 resulting XML description will explicitly include all features that
531 make up the CPU, without this option features that are part of the
532 CPU model will not be listed in the XML description. If
533 --migratable is specified, features that block migration will not
534 be included in the resulting CPU.
535 cpu-compare FILE [--error]
537 Compare CPU definition from XML <file> with host CPU. (See
538 hypervisor-cpu-compare command for comparing the CPU definition
539 with the CPU which a specific hypervisor is able to provide on the
540 host.) The XML <file> may contain either host or guest CPU
541 definition. The host CPU definition is the <cpu> element and its
542 contents as printed by capabilities command. The guest CPU
543 definition is the <cpu> element and its contents from domain XML
544 definition or the CPU definition created from the host CPU model
545 found in domain capabilities XML (printed by domcapabilities
546 command). In addition to the <cpu> element itself, this command
547 accepts full domain XML, capabilities XML, or domain capabilities
548 XML containing the CPU definition. For more information on guest
549 CPU definition see:
550 <https://libvirt.org/formatdomain.html#elementsCPU>. If --error is
551 specified, the command will return an error when the given CPU is
552 incompatible with host CPU and a message providing more details
553 about the incompatibility will be printed out.
554 cpu-models arch
556 Print the list of CPU models known by libvirt for the specified
557 architecture. Whether a specific hypervisor is able to create a
558 domain which uses any of the printed CPU models is a separate
559 question which can be answered by looking at the domain
560 capabilities XML returned by domcapabilities command. Moreover,
561 for some architectures libvirt does not know any CPU models and the
562 usable CPU models are only limited by the hypervisor. This command
563 will print that all CPU models are accepted for these architectures
564 and the actual list of supported CPU models can be checked in the
565 domain capabilities XML.
566 echo [--shell] [--xml] [err...] [arg...]
568 Echo back each arg, separated by space. If --shell is specified,
569 then the output will be single-quoted where needed, so that it is
570 suitable for reuse in a shell context. If --xml is specified, then
571 the output will be escaped for use in XML. If --err is specified,
572 prefix "error: " and output to stderr instead of stdout.
573 hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine]
575 [--error]
576 Compare CPU definition from XML <file> with the CPU the hypervisor
577 is able to provide on the host. (This is different from cpu-compare
578 which compares the CPU definition with the host CPU without
579 considering any specific hypervisor and its abilities.)
580 The XML FILE may contain either a host or guest CPU definition. The
582 host CPU definition is the <cpu> element and its contents as
583 printed by the capabilities command. The guest CPU definition is
584 the <cpu> element and its contents from the domain XML definition
585 or the CPU definition created from the host CPU model found in the
586 domain capabilities XML (printed by the domcapabilities command).
587 In addition to the <cpu> element itself, this command accepts full
588 domain XML, capabilities XML, or domain capabilities XML containing
589 the CPU definition. For more information on guest CPU definition
590 see: <https://libvirt.org/formatdomain.html#elementsCPU>.
591 The virttype option specifies the virtualization type (usable in
593 the 'type' attribute of the <domain> top level element from the
594 domain XML). emulator specifies the path to the emulator, arch
595 specifies the CPU architecture, and machine specifies the machine
596 type. If --error is specified, the command will return an error
597 when the given CPU is incompatible with the host CPU and a message
598 providing more details about the incompatibility will be printed
599 out.
600 hypervisor-cpu-baseline FILE [virttype] [emulator] [arch] [machine]
602 [--features] [--migratable]
603 Compute a baseline CPU which will be compatible with all CPUs
604 defined in an XML file and with the CPU the hypervisor is able to
605 provide on the host. (This is different from cpu-baseline which
606 does not consider any hypervisor abilities when computing the
607 baseline CPU.)
608 The XML FILE may contain either host or guest CPU definitions
610 describing the host CPU model. The host CPU definition is the <cpu>
611 element and its contents as printed by capabilities command. The
612 guest CPU definition may be created from the host CPU model found
613 in domain capabilities XML (printed by domcapabilities command). In
614 addition to the <cpu> elements, this command accepts full
615 capabilities XMLs, or domain capabilities XMLs containing the CPU
616 definitions. For best results, use only the CPU definitions from
617 domain capabilities.
618 When FILE contains only a single CPU definition, the command will
620 print the same CPU with restrictions imposed by the capabilities of
621 the hypervisor. Specifically, running th virsh hypervisor-cpu-
622 baseline command with no additional options on the result of virsh
623 domcapabilities will transform the host CPU model from domain
624 capabilities XML to a form directly usable in domain XML.
625 The virttype option specifies the virtualization type (usable in
627 the 'type' attribute of the <domain> top level element from the
628 domain XML). emulator specifies the path to the emulator, arch
629 specifies the CPU architecture, and machine specifies the machine
630 type. If --features is specified, then the resulting XML
631 description will explicitly include all features that make up the
632 CPU, without this option features that are part of the CPU model
633 will not be listed in the XML description. If --migratable is
634 specified, features that block migration will not be included in
635 the resulting CPU.
636
638 The following commands manipulate domains directly, as stated
639 previously most commands take domain as the first parameter. The domain
640 can be specified as a short integer, a name or a full UUID.
641 autostart [--disable] domain
643 Configure a domain to be automatically started at boot.
644 The option --disable disables autostarting.
646 console domain [devname] [--safe] [--force]
648 Connect the virtual serial console for the guest. The optional
649 devname parameter refers to the device alias of an alternate
650 console, serial or parallel device configured for the guest. If
651 omitted, the primary console will be opened.
652 If the flag --safe is specified, the connection is only attempted
654 if the driver supports safe console handling. This flag specifies
655 that the server has to ensure exclusive access to console devices.
656 Optionally the --force flag may be specified, requesting to
657 disconnect any existing sessions, such as in a case of a broken
658 connection.
659 create FILE [--console] [--paused] [--autodestroy] [--pass-fds N,M,...]
661 [--validate]
662 Create a domain from an XML <file>. Optionally, --validate option
663 can be passed to validate the format of the input XML file against
664 an internal RNG schema (identical to using virt-xml-validate(1)
665 tool). Domains created using this command are going to be either
666 transient (temporary ones that will vanish once destroyed) or
667 existing persistent domains that will run with one-time use
668 configuration, leaving the persistent XML untouched (this can come
669 handy during an automated testing of various configurations all
670 based on the original XML). See the Example section for usage
671 demonstration.
672 The domain will be paused if the --paused option is used and
674 supported by the driver; otherwise it will be running. If --console
675 is requested, attach to the console after creation. If
676 --autodestroy is requested, then the guest will be automatically
677 destroyed when virsh closes its connection to libvirt, or otherwise
678 exits.
679 If --pass-fds is specified, the argument is a comma separated list
681 of open file descriptors which should be pass on into the guest.
682 The file descriptors will be re-numbered in the guest, starting
683 from 3. This is only supported with container based virtualization.
684 Example
686 1) prepare a template from an existing domain (skip directly to 3a if writing
688 one from scratch)
689 # virsh dumpxml <domain> > domain.xml
691 2) edit the template using an editor of your choice and:
693 a) DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or
694 b) DON'T CHANGE! either <name> or <uuid>
695 # $EDITOR domain.xml
697 3) create a domain from domain.xml, depending on whether following 2a or 2b
699 respectively:
700 a) the domain is going to be transient
701 b) an existing persistent domain will run with a modified one-time
702 configuration
703 # virsh create domain.xml
705 define FILE [--validate]
707 Define a domain from an XML <file>. Optionally, the format of the
708 input XML file can be validated against an internal RNG schema with
709 --validate (identical to using virt-xml-validate(1) tool). The
710 domain definition is registered but not started. If domain is
711 already running, the changes will take effect on the next boot.
712 desc domain [[--live] [--config] | [--current]] [--title] [--edit]
714 [--new-desc New description or title message]
715 Show or modify description and title of a domain. These values are
716 user fields that allow storing arbitrary textual data to allow easy
717 identification of domains. Title should be short, although it's not
718 enforced. (See also metadata that works with XML based domain
719 metadata.)
720 Flags --live or --config select whether this command works on live
722 or persistent definitions of the domain. If both --live and
723 --config are specified, the --config option takes precedence on
724 getting the current description and both live configuration and
725 config are updated while setting the description. --current is
726 exclusive and implied if none of these was specified.
727 Flag --edit specifies that an editor with the contents of current
729 description or title should be opened and the contents saved back
730 afterwards.
731 Flag --title selects operation on the title field instead of
733 description.
734 If neither of --edit and --new-desc are specified the note or
736 description is displayed instead of being modified.
737 destroy domain [--graceful]
739 Immediately terminate the domain domain. This doesn't give the
740 domain OS any chance to react, and it's the equivalent of ripping
741 the power cord out on a physical machine. In most cases you will
742 want to use the shutdown command instead. However, this does not
743 delete any storage volumes used by the guest, and if the domain is
744 persistent, it can be restarted later.
745 If domain is transient, then the metadata of any snapshots will be
747 lost once the guest stops running, but the snapshot contents still
748 exist, and a new domain with the same name and UUID can restore the
749 snapshot metadata with snapshot-create. Similarly, the metadata of
750 any checkpoints will be lost, but can be restored with checkpoint-
751 create.
752 If --graceful is specified, don't resort to extreme measures (e.g.
754 SIGKILL) when the guest doesn't stop after a reasonable timeout;
755 return an error instead.
756 domblkstat domain [block-device] [--human]
758 Get device block stats for a running domain. A block-device
759 corresponds to a unique target name (<target dev='name'/>) or
760 source file (<source file='name'/>) for one of the disk devices
761 attached to domain (see also domblklist for listing these names).
762 On a lxc or qemu domain, omitting the block-device yields device
763 block stats summarily for the entire domain.
764 Use --human for a more human readable output.
766 Availability of these fields depends on hypervisor. Unsupported
768 fields are missing from the output. Other fields may appear if
769 communicating with a newer version of libvirtd.
770 Explanation of fields (fields appear in the following order):
772 rd_req - count of read operations
773 rd_bytes - count of read bytes
774 wr_req - count of write operations
775 wr_bytes - count of written bytes
776 errs - error count
777 flush_operations - count of flush operations
778 rd_total_times - total time read operations took (ns)
779 wr_total_times - total time write operations took (ns)
780 flush_total_times - total time flush operations took (ns)
781 <-- other fields provided by hypervisor -->
782 domifaddr domain [interface] [--full] [--source lease|agent|arp]
784 Get a list of interfaces of a running domain along with their IP
785 and MAC addresses, or limited output just for one interface if
786 interface is specified. Note that interface can be driver
787 dependent, it can be the name within guest OS or the name you would
788 see in domain XML. Moreover, the whole command may require a guest
789 agent to be configured for the queried domain under some
790 hypervisors, notably QEMU.
791 If --full is specified, the interface name and MAC address is
793 always displayed when the interface has multiple IP addresses or
794 aliases; otherwise, only the interface name and MAC address is
795 displayed for the first name and MAC address with "-" for the
796 others using the same name and MAC address.
797 The --source argument specifies what data source to use for the
799 addresses, currently 'lease' to read DHCP leases, 'agent' to query
800 the guest OS via an agent, or 'arp' to get IP from host's arp
801 tables. If unspecified, 'lease' is the default.
802 domifstat domain interface-device
804 Get network interface stats for a running domain. The network
805 interface stats are only available for interfaces that have a
806 physical source interface. This does not include, for example, a
807 'user' interface type since it is a virtual LAN with NAT to the
808 outside world. interface-device can be the interface target by name
809 or MAC address.
810 domif-setlink domain interface-device state [--config]
812 Modify link state of the domain's virtual interface. Possible
813 values for state are "up" and "down". If --config is specified,
814 only the persistent configuration of the domain is modified, for
815 compatibility purposes, --persistent is alias of --config.
816 interface-device can be the interface's target name or the MAC
817 address.
818 domif-getlink domain interface-device [--config]
820 Query link state of the domain's virtual interface. If --config is
821 specified, query the persistent configuration, for compatibility
822 purposes, --persistent is alias of --config.
823 interface-device can be the interface's target name or the MAC
825 address.
826 domiftune domain interface-device [[--config] [--live] | [--current]]
828 [--inbound average,peak,burst,floor] [--outbound average,peak,burst]
829 Set or query the domain's network interface's bandwidth parameters.
830 interface-device can be the interface's target name (<target
831 dev='name'/>), or the MAC address.
832 If no --inbound or --outbound is specified, this command will query
834 and show the bandwidth settings. Otherwise, it will set the inbound
835 or outbound bandwidth. average,peak,burst,floor is the same as in
836 command attach-interface. Values for average, peak and floor are
837 expressed in kilobytes per second, while burst is expressed in
838 kilobytes in a single burst at peak speed as described in the
839 Network XML documentation at
840 <https://libvirt.org/formatnetwork.html#elementQoS>.
841 To clear inbound or outbound settings, use --inbound or --outbound
843 respectfully with average value of zero.
844 If --live is specified, affect a running guest. If --config is
846 specified, affect the next boot of a persistent guest. If
847 --current is specified, affect the current guest state. Both
848 --live and --config flags may be given, but --current is exclusive.
849 If no flag is specified, behavior is different depending on
850 hypervisor.
851 dommemstat domain [--period seconds] [[--config] [--live] |
853 [--current]]
854 Get memory stats for a running domain.
855 Availability of these fields depends on hypervisor. Unsupported
857 fields are missing from the output. Other fields may appear if
858 communicating with a newer version of libvirtd.
859 Explanation of fields:
861 swap_in - The amount of data read from swap space (in
862 KiB)
863 swap_out - The amount of memory written out to swap
864 space (in KiB)
865 major_fault - The number of page faults where disk IO was
866 required
867 minor_fault - The number of other page faults
868 unused - The amount of memory left unused by the
869 system (in KiB)
870 available - The amount of usable memory as seen by the
871 domain (in KiB)
872 actual - Current balloon value (in KiB)
873 rss - Resident Set Size of the running domain's
874 process (in KiB)
875 usable - The amount of memory which can be reclaimed
876 by balloon without causing host swapping (in KiB)
877 last-update - Timestamp of the last update of statistics
878 (in seconds)
879 disk_caches - The amount of memory that can be reclaimed
880 without additional I/O, typically disk caches (in KiB)
881 hugetlb_pgalloc - The number of successful huge page
882 allocations initiated from within the domain
883 hugetlb_pgfail - The number of failed huge page allocations
884 initiated from within the domain
885 For QEMU/KVM with a memory balloon, setting the optional --period
887 to a value larger than 0 in seconds will allow the balloon driver
888 to return additional statistics which will be displayed by
889 subsequent dommemstat commands. Setting the --period to 0 will stop
890 the balloon driver collection, but does not clear the statistics in
891 the balloon driver. Requires at least QEMU/KVM 1.5 to be running on
892 the host.
893 The --live, --config, and --current flags are only valid when using
895 the --period option in order to set the collection period for the
896 balloon driver. If --live is specified, only the running guest
897 collection period is affected. If --config is specified, affect the
898 next boot of a persistent guest. If --current is specified, affect
899 the current guest state.
900 Both --live and --config flags may be given, but --current is
902 exclusive. If no flag is specified, behavior is different depending
903 on the guest state.
904 domblkerror domain
906 Show errors on block devices. This command usually comes handy
907 when domstate command says that a domain was paused due to I/O
908 error. The domblkerror command lists all block devices in error
909 state and the error seen on each of them.
910 domblkinfo domain [block-device --all] [--human]
912 Get block device size info for a domain. A block-device
913 corresponds to a unique target name (<target dev='name'/>) or
914 source file (<source file='name'/>) for one of the disk devices
915 attached to domain (see also domblklist for listing these names).
916 If --human is set, the output will have a human readable output.
917 If --all is set, the output will be a table showing all block
918 devices size info associated with domain. The --all option takes
919 precedence of the others.
920 domblklist domain [--inactive] [--details]
922 Print a table showing the brief information of all block devices
923 associated with domain. If --inactive is specified, query the block
924 devices that will be used on the next boot, rather than those
925 currently in use by a running domain. If --details is specified,
926 disk type and device value will also be printed. Other contexts
927 that require a block device name (such as domblkinfo or snapshot-
928 create for disk snapshots) will accept either target or unique
929 source names printed by this command.
930 domstats [--raw] [--enforce] [--backing] [--nowait] [--state]
932 [--cpu-total] [--balloon] [--vcpu] [--interface] [--block] [--perf]
933 [--iothread] [[--list-active] [--list-inactive] [--list-persistent]
934 [--list-transient] [--list-running] [--list-paused] [--list-shutoff]
935 [--list-other]] | [domain ...]
936 Get statistics for multiple or all domains. Without any argument
937 this command prints all available statistics for all domains.
938 The list of domains to gather stats for can be either limited by
940 listing the domains as a space separated list, or by specifying one
941 of the filtering flags --list-*. (The approaches can't be
942 combined.)
943 By default some of the returned fields may be converted to more
945 human friendly values by a set of pretty-printers. To suppress this
946 behavior use the --raw flag.
947 The individual statistics groups are selectable via specific flags.
949 By default all supported statistics groups are returned. Supported
950 statistics groups flags are: --state, --cpu-total, --balloon,
951 --vcpu, --interface, --block, --perf, --iothread.
952 Note that - depending on the hypervisor type and version or the
954 domain state - not all of the following statistics may be returned.
955 When selecting the --state group the following fields are returned:
957 "state.state" - state of the VM, returned as number from
959 virDomainState enum
960 "state.reason" - reason for entering given state, returned
961 as int from virDomain*Reason enum corresponding
962 to given state
963 --cpu-total returns:
965 "cpu.time" - total cpu time spent for this domain in nanoseconds
967 "cpu.user" - user cpu time spent in nanoseconds
968 "cpu.system" - system cpu time spent in nanoseconds
969 "cpu.cache.monitor.count" - the number of cache monitors for this
970 domain
971 "cpu.cache.monitor.<num>.name" - the name of cache monitor <num>
972 "cpu.cache.monitor.<num>.vcpus" - vcpu list of cache monitor <num>
973 "cpu.cache.monitor.<num>.bank.count" - the number of cache banks
974 in cache monitor <num>
975 "cpu.cache.monitor.<num>.bank.<index>.id" - host allocated cache id
976 for bank <index> in
977 cache monitor <num>
978 "cpu.cache.monitor.<num>.bank.<index>.bytes" - the number of bytes
979 of last level cache
980 that the domain is
981 using on cache bank
982 <index>
983 --balloon returns:
985 "balloon.current" - the memory in KiB currently used
987 "balloon.maximum" - the maximum memory in KiB allowed
988 "balloon.swap_in" - the amount of data read from swap space (in KiB)
989 "balloon.swap_out" - the amount of memory written out to swap
990 space (in KiB)
991 "balloon.major_fault" - the number of page faults then disk IO
992 was required
993 "balloon.minor_fault" - the number of other page faults
994 "balloon.unused" - the amount of memory left unused by the
995 system (in KiB)
996 "balloon.available" - the amount of usable memory as seen by
997 the domain (in KiB)
998 "balloon.rss" - Resident Set Size of running domain's process
999 (in KiB)
1000 "balloon.usable" - the amount of memory which can be reclaimed by
1001 balloon without causing host swapping (in KiB)
1002 "balloon.last-update" - timestamp of the last update of statistics
1003 (in seconds)
1004 "balloon.disk_caches " - the amount of memory that can be reclaimed
1005 without additional I/O, typically disk
1006 caches (in KiB)
1007 --vcpu returns:
1009 "vcpu.current" - current number of online virtual CPUs
1011 "vcpu.maximum" - maximum number of online virtual CPUs
1012 "vcpu.<num>.state" - state of the virtual CPU <num>, as
1013 number from virVcpuState enum
1014 "vcpu.<num>.time" - virtual cpu time spent by virtual
1015 CPU <num> (in microseconds)
1016 "vcpu.<num>.wait" - virtual cpu time spent by virtual
1017 CPU <num> waiting on I/O (in microseconds)
1018 "vcpu.<num>.halted" - virtual CPU <num> is halted: yes or
1019 no (may indicate the processor is idle
1020 or even disabled, depending on the
1021 architecture)
1022 --interface returns:
1024 "net.count" - number of network interfaces on this domain
1026 "net.<num>.name" - name of the interface <num>
1027 "net.<num>.rx.bytes" - number of bytes received
1028 "net.<num>.rx.pkts" - number of packets received
1029 "net.<num>.rx.errs" - number of receive errors
1030 "net.<num>.rx.drop" - number of receive packets dropped
1031 "net.<num>.tx.bytes" - number of bytes transmitted
1032 "net.<num>.tx.pkts" - number of packets transmitted
1033 "net.<num>.tx.errs" - number of transmission errors
1034 "net.<num>.tx.drop" - number of transmit packets dropped
1035 --perf returns the statistics of all enabled perf events:
1037 "perf.cmt" - the cache usage in Byte currently used
1039 "perf.mbmt" - total system bandwidth from one level of cache
1040 "perf.mbml" - bandwidth of memory traffic for a memory controller
1041 "perf.cpu_cycles" - the count of cpu cycles (total/elapsed)
1042 "perf.instructions" - the count of instructions
1043 "perf.cache_references" - the count of cache hits
1044 "perf.cache_misses" - the count of caches misses
1045 "perf.branch_instructions" - the count of branch instructions
1046 "perf.branch_misses" - the count of branch misses
1047 "perf.bus_cycles" - the count of bus cycles
1048 "perf.stalled_cycles_frontend" - the count of stalled frontend
1049 cpu cycles
1050 "perf.stalled_cycles_backend" - the count of stalled backend
1051 cpu cycles
1052 "perf.ref_cpu_cycles" - the count of ref cpu cycles
1053 "perf.cpu_clock" - the count of cpu clock time
1054 "perf.task_clock" - the count of task clock time
1055 "perf.page_faults" - the count of page faults
1056 "perf.context_switches" - the count of context switches
1057 "perf.cpu_migrations" - the count of cpu migrations
1058 "perf.page_faults_min" - the count of minor page faults
1059 "perf.page_faults_maj" - the count of major page faults
1060 "perf.alignment_faults" - the count of alignment faults
1061 "perf.emulation_faults" - the count of emulation faults
1062 See the perf command for more details about each event.
1064 --block returns information about disks associated with each
1066 domain. Using the --backing flag extends this information to cover
1067 all resources in the backing chain, rather than the default of
1068 limiting information to the active layer for each guest disk.
1069 Information listed includes:
1070 "block.count" - number of block devices being listed
1072 "block.<num>.name" - name of the target of the block
1073 device <num> (the same name for
1074 multiple entries if I<--backing>
1075 is present)
1076 "block.<num>.backingIndex" - when I<--backing> is present,
1077 matches up with the <backingStore>
1078 index listed in domain XML for
1079 backing files
1080 "block.<num>.path" - file source of block device <num>, if
1081 it is a local file or block device
1082 "block.<num>.rd.reqs" - number of read requests
1083 "block.<num>.rd.bytes" - number of read bytes
1084 "block.<num>.rd.times" - total time (ns) spent on reads
1085 "block.<num>.wr.reqs" - number of write requests
1086 "block.<num>.wr.bytes" - number of written bytes
1087 "block.<num>.wr.times" - total time (ns) spent on writes
1088 "block.<num>.fl.reqs" - total flush requests
1089 "block.<num>.fl.times" - total time (ns) spent on cache flushing
1090 "block.<num>.errors" - Xen only: the 'oo_req' value
1091 "block.<num>.allocation" - offset of highest written sector in bytes
1092 "block.<num>.capacity" - logical size of source file in bytes
1093 "block.<num>.physical" - physical size of source file in bytes
1094 "block.<num>.threshold" - threshold (in bytes) for delivering the
1095 VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event
1096 See domblkthreshold.
1097 --iothread returns information about IOThreads on the running guest
1099 if supported by the hypervisor.
1100 The "poll-max-ns" for each thread is the maximum nanoseconds to
1102 allow each polling interval to occur. A polling interval is a
1103 period of time allowed for a thread to process data before being
1104 the guest gives up its CPU quantum back to the host. A value set
1105 too small will not allow the IOThread to run long enough on a CPU
1106 to process data. A value set too high will consume too much CPU
1107 time per IOThread failing to allow other threads running on the CPU
1108 to get time. The polling interval is not available for statistical
1109 purposes.
1110 "iothread.<id>.poll-max-ns" - maximum polling time in nanoseconds used
1112 by the <id> IOThread. A value of 0 (zero)
1113 indicates polling is disabled.
1114 "iothread.<id>.poll-grow" - polling time grow value. A value of 0 (zero)
1115 indicates growth is managed by the hypervisor.
1116 "iothread.<id>.poll-shrink" - polling time shrink value. A value of
1117 0 (zero) indicates shrink is managed by
1118 the hypervisor.
1119 Selecting a specific statistics groups doesn't guarantee that the
1121 daemon supports the selected group of stats. Flag --enforce forces
1122 the command to fail if the daemon doesn't support the selected
1123 group.
1124 When collecting stats libvirtd may wait for some time if there's
1126 already another job running on given domain for it to finish. This
1127 may cause unnecessary delay in delivering stats. Using --nowait
1128 suppresses this behaviour. On the other hand some statistics might
1129 be missing for such domain.
1130 domiflist domain [--inactive]
1132 Print a table showing the brief information of all virtual
1133 interfaces associated with domain. If --inactive is specified,
1134 query the virtual interfaces that will be used on the next boot,
1135 rather than those currently in use by a running domain. Other
1136 contexts that require a MAC address of virtual interface (such as
1137 detach-interface or domif-setlink) will accept the MAC address
1138 printed by this command.
1139 blockcommit domain path [bandwidth] [--bytes] [base] [--shallow] [top]
1141 [--delete] [--keep-relative] [--wait [--async] [--verbose]] [--timeout
1142 seconds] [--active] [{--pivot | --keep-overlay}]
1143 Reduce the length of a backing image chain, by committing changes
1144 at the top of the chain (snapshot or delta files) into backing
1145 images. By default, this command attempts to flatten the entire
1146 chain. If base and/or top are specified as files within the
1147 backing chain, then the operation is constrained to committing just
1148 that portion of the chain; --shallow can be used instead of base to
1149 specify the immediate backing file of the resulting top image to be
1150 committed. The files being committed are rendered invalid,
1151 possibly as soon as the operation starts; using the --delete flag
1152 will attempt to remove these invalidated files at the successful
1153 completion of the commit operation. When the --keep-relative flag
1154 is used, the backing file paths will be kept relative.
1155 When top is omitted or specified as the active image, it is also
1157 possible to specify --active to trigger a two-phase active commit.
1158 In the first phase, top is copied into base and the job can only be
1159 canceled, with top still containing data not yet in base. In the
1160 second phase, top and base remain identical until a call to
1161 blockjob with the --abort flag (keeping top as the active image
1162 that tracks changes from that point in time) or the --pivot flag
1163 (making base the new active image and invalidating top).
1164 By default, this command returns as soon as possible, and data for
1166 the entire disk is committed in the background; the progress of the
1167 operation can be checked with blockjob. However, if --wait is
1168 specified, then this command will block until the operation
1169 completes (or for --active, enters the second phase), or until the
1170 operation is canceled because the optional timeout in seconds
1171 elapses or SIGINT is sent (usually with "Ctrl-C"). Using --verbose
1172 along with --wait will produce periodic status updates. If job
1173 cancellation is triggered, --async will return control to the user
1174 as fast as possible, otherwise the command may continue to block a
1175 little while longer until the job is done cleaning up. Using
1176 --pivot is shorthand for combining --active --wait with an
1177 automatic blockjob --pivot; and using --keep-overlay is shorthand
1178 for combining --active --wait with an automatic blockjob --abort.
1179 path specifies fully-qualified path of the disk; it corresponds to
1181 a unique target name (<target dev='name'/>) or source file (<source
1182 file='name'/>) for one of the disk devices attached to domain (see
1183 also domblklist for listing these names). bandwidth specifies
1184 copying bandwidth limit in MiB/s, although for qemu, it may be non-
1185 zero only for an online domain. For further information on the
1186 bandwidth argument see the corresponding section for the blockjob
1187 command.
1188 blockcopy domain path { dest [format] [--blockdev] | --xml file }
1190 [--shallow] [--reuse-external] [bandwidth] [--wait [--async]
1191 [--verbose]] [{--pivot | --finish}] [--timeout seconds] [granularity]
1192 [buf-size] [--bytes] [--transient-job]
1193 Copy a disk backing image chain to a destination. Either dest as
1194 the destination file name, or --xml with the name of an XML file
1195 containing a top-level <disk> element describing the destination,
1196 must be present. Additionally, if dest is given, format should be
1197 specified to declare the format of the destination (if format is
1198 omitted, then libvirt will reuse the format of the source, or with
1199 --reuse-external will be forced to probe the destination format,
1200 which could be a potential security hole). The command supports
1201 --raw as a boolean flag synonym for --format=raw. When using dest,
1202 the destination is treated as a regular file unless --blockdev is
1203 used to signal that it is a block device. By default, this command
1204 flattens the entire chain; but if --shallow is specified, the copy
1205 shares the backing chain.
1206 If --reuse-external is specified, then the destination must exist
1208 and have sufficient space to hold the copy. If --shallow is used in
1209 conjunction with --reuse-external then the pre-created image must
1210 have guest visible contents identical to guest visible contents of
1211 the backing file of the original image. This may be used to modify
1212 the backing file names on the destination.
1213 By default, the copy job runs in the background, and consists of
1215 two phases. Initially, the job must copy all data from the source,
1216 and during this phase, the job can only be canceled to revert back
1217 to the source disk, with no guarantees about the destination.
1218 After this phase completes, both the source and the destination
1219 remain mirrored until a call to blockjob with the --abort and
1220 --pivot flags pivots over to the copy, or a call without --pivot
1221 leaves the destination as a faithful copy of that point in time.
1222 However, if --wait is specified, then this command will block until
1223 the mirroring phase begins, or cancel the operation if the optional
1224 timeout in seconds elapses or SIGINT is sent (usually with
1225 "Ctrl-C"). Using --verbose along with --wait will produce periodic
1226 status updates. Using --pivot (similar to blockjob --pivot) or
1227 --finish (similar to blockjob --abort) implies --wait, and will
1228 additionally end the job cleanly rather than leaving things in the
1229 mirroring phase. If job cancellation is triggered by timeout or by
1230 --finish, --async will return control to the user as fast as
1231 possible, otherwise the command may continue to block a little
1232 while longer until the job has actually cancelled.
1233 path specifies fully-qualified path of the disk. bandwidth
1235 specifies copying bandwidth limit in MiB/s. Specifying a negative
1236 value is interpreted as an unsigned long long value that might be
1237 essentially unlimited, but more likely would overflow; it is safer
1238 to use 0 for that purpose. For further information on the bandwidth
1239 argument see the corresponding section for the blockjob command.
1240 Specifying granularity allows fine-tuning of the granularity that
1241 will be copied when a dirty region is detected; larger values
1242 trigger less I/O overhead but may end up copying more data overall
1243 (the default value is usually correct); hypervisors may restrict
1244 this to be a power of two or fall within a certain range.
1245 Specifying buf-size will control how much data can be
1246 simultaneously in-flight during the copy; larger values use more
1247 memory but may allow faster completion (the default value is
1248 usually correct).
1249 --transient-job allows specifying that the user does not require
1251 the job to be recovered if the VM crashes or is turned off before
1252 the job completes. This flag removes the restriction of copy jobs
1253 to transient domains if that restriction is applied by the
1254 hypervisor.
1255 blockpull domain path [bandwidth] [--bytes] [base] [--wait [--verbose]
1257 [--timeout seconds] [--async]] [--keep-relative]
1258 Populate a disk from its backing image chain. By default, this
1259 command flattens the entire chain; but if base is specified,
1260 containing the name of one of the backing files in the chain, then
1261 that file becomes the new backing file and only the intermediate
1262 portion of the chain is pulled. Once all requested data from the
1263 backing image chain has been pulled, the disk no longer depends on
1264 that portion of the backing chain.
1265 By default, this command returns as soon as possible, and data for
1267 the entire disk is pulled in the background; the progress of the
1268 operation can be checked with blockjob. However, if --wait is
1269 specified, then this command will block until the operation
1270 completes, or cancel the operation if the optional timeout in
1271 seconds elapses or SIGINT is sent (usually with "Ctrl-C"). Using
1272 --verbose along with --wait will produce periodic status updates.
1273 If job cancellation is triggered, --async will return control to
1274 the user as fast as possible, otherwise the command may continue to
1275 block a little while longer until the job is done cleaning up.
1276 Using the --keep-relative flag will keep the backing chain names
1278 relative.
1279 path specifies fully-qualified path of the disk; it corresponds to
1281 a unique target name (<target dev='name'/>) or source file (<source
1282 file='name'/>) for one of the disk devices attached to domain (see
1283 also domblklist for listing these names). bandwidth specifies
1284 copying bandwidth limit in MiB/s. For further information on the
1285 bandwidth argument see the corresponding section for the blockjob
1286 command.
1287 blkdeviotune domain device [[--config] [--live] | [--current]] [[total-
1289 bytes-sec] | [read-bytes-sec] [write-bytes-sec]] [[total-iops-sec] |
1290 [read-iops-sec] [write-iops-sec]] [[total-bytes-sec-max] | [read-bytes-
1291 sec-max] [write-bytes-sec-max]] [[total-iops-sec-max] | [read-iops-sec-
1292 max] [write-iops-sec-max]] [[total-bytes-sec-max-length] | [read-bytes-
1293 sec-max-length] [write-bytes-sec-max-length]] [[total-iops-sec-max-
1294 length] | [read-iops-sec-max-length] [write-iops-sec-max-length]]
1295 [size-iops-sec] [group-name]
1296 Set or query the block disk io parameters for a block device of
1297 domain. device specifies a unique target name (<target
1298 dev='name'/>) or source file (<source file='name'/>) for one of the
1299 disk devices attached to domain (see also domblklist for listing
1300 these names).
1301 If no limit is specified, it will query current I/O limits setting.
1303 Otherwise, alter the limits with these flags: --total-bytes-sec
1304 specifies total throughput limit as a scaled integer, the default
1305 being bytes per second if no suffix is specified. --read-bytes-sec
1306 specifies read throughput limit as a scaled integer, the default
1307 being bytes per second if no suffix is specified.
1308 --write-bytes-sec specifies write throughput limit as a scaled
1309 integer, the default being bytes per second if no suffix is
1310 specified. --total-iops-sec specifies total I/O operations limit
1311 per second. --read-iops-sec specifies read I/O operations limit
1312 per second. --write-iops-sec specifies write I/O operations limit
1313 per second. --total-bytes-sec-max specifies maximum total
1314 throughput limit as a scaled integer, the default being bytes per
1315 second if no suffix is specified --read-bytes-sec-max specifies
1316 maximum read throughput limit as a scaled integer, the default
1317 being bytes per second if no suffix is specified.
1318 --write-bytes-sec-max specifies maximum write throughput limit as a
1319 scaled integer, the default being bytes per second if no suffix is
1320 specified. --total-iops-sec-max specifies maximum total I/O
1321 operations limit per second. --read-iops-sec-max specifies maximum
1322 read I/O operations limit per second. --write-iops-sec-max
1323 specifies maximum write I/O operations limit per second.
1324 --total-bytes-sec-max-length specifies duration in seconds to allow
1325 maximum total throughput limit. --read-bytes-sec-max-length
1326 specifies duration in seconds to allow maximum read throughput
1327 limit. --write-bytes-sec-max-length specifies duration in seconds
1328 to allow maximum write throughput limit.
1329 --total-iops-sec-max-length specifies duration in seconds to allow
1330 maximum total I/O operations limit. --read-iops-sec-max-length
1331 specifies duration in seconds to allow maximum read I/O operations
1332 limit. --write-iops-sec-max-length specifies duration in seconds
1333 to allow maximum write I/O operations limit. --size-iops-sec
1334 specifies size I/O operations limit per second. --group-name
1335 specifies group name to share I/O quota between multiple drives.
1336 For a qemu domain, if no name is provided, then the default is to
1337 have a single group for each device.
1338 Older versions of virsh only accepted these options with underscore
1340 instead of dash, as in --total_bytes_sec.
1341 Bytes and iops values are independent, but setting only one value
1343 (such as --read-bytes-sec) resets the other two in that category to
1344 unlimited. An explicit 0 also clears any limit. A non-zero value
1345 for a given total cannot be mixed with non-zero values for read or
1346 write.
1347 It is up to the hypervisor to determine how to handle the length
1349 values. For the qemu hypervisor, if an I/O limit value or maximum
1350 value is set, then the default value of 1 second will be displayed.
1351 Supplying a 0 will reset the value back to the default.
1352 If --live is specified, affect a running guest. If --config is
1354 specified, affect the next boot of a persistent guest. If
1355 --current is specified, affect the current guest state. When
1356 setting the disk io parameters both --live and --config flags may
1357 be given, but --current is exclusive. For querying only one of
1358 --live, --config or --current can be specified. If no flag is
1359 specified, behavior is different depending on hypervisor.
1360 blockjob domain path { [--abort] [--async] [--pivot] | [--info] [--raw]
1362 [--bytes] | [bandwidth] }
1363 Manage active block operations. There are three mutually-exclusive
1364 modes: --info, bandwidth, and --abort. --async and --pivot imply
1365 abort mode; --raw implies info mode; and if no mode was given,
1366 --info mode is assumed.
1367 path specifies fully-qualified path of the disk; it corresponds to
1369 a unique target name (<target dev='name'/>) or source file (<source
1370 file='name'/>) for one of the disk devices attached to domain (see
1371 also domblklist for listing these names).
1372 In --abort mode, the active job on the specified disk will be
1374 aborted. If --async is also specified, this command will return
1375 immediately, rather than waiting for the cancellation to complete.
1376 If --pivot is specified, this requests that an active copy or
1377 active commit job be pivoted over to the new image.
1378 In --info mode, the active job information on the specified disk
1380 will be printed. By default, the output is a single human-readable
1381 summary line; this format may change in future versions. Adding
1382 --raw lists each field of the struct, in a stable format. If the
1383 --bytes flag is set, then the command errors out if the server
1384 could not supply bytes/s resolution; when omitting the flag, raw
1385 output is listed in MiB/s and human-readable output automatically
1386 selects the best resolution supported by the server.
1387 bandwidth can be used to set bandwidth limit for the active job in
1389 MiB/s. If --bytes is specified then the bandwidth value is
1390 interpreted in bytes/s. Specifying a negative value is interpreted
1391 as an unsigned long value or essentially unlimited. The hypervisor
1392 can choose whether to reject the value or convert it to the maximum
1393 value allowed. Optionally a scaled positive number may be used as
1394 bandwidth (see NOTES above). Using --bytes with a scaled value
1395 permits a finer granularity to be selected. A scaled value used
1396 without --bytes will be rounded down to MiB/s. Note that the
1397 --bytes may be unsupported by the hypervisor.
1398 domblkthreshold domain dev threshold
1400 Set the threshold value for delivering the block-threshold event.
1401 dev specifies the disk device target or backing chain element of
1402 given device using the 'target[1]' syntax. threshold is a scaled
1403 value of the offset. If the block device should write beyond that
1404 offset the event will be delivered.
1405 blockresize domain path size
1407 Resize a block device of domain while the domain is running, path
1408 specifies the absolute path of the block device; it corresponds to
1409 a unique target name (<target dev='name'/>) or source file (<source
1410 file='name'/>) for one of the disk devices attached to domain (see
1411 also domblklist for listing these names).
1412 size is a scaled integer (see NOTES above) which defaults to KiB
1414 (blocks of 1024 bytes) if there is no suffix. You must use a
1415 suffix of "B" to get bytes (note that for historical reasons, this
1416 differs from vol-resize which defaults to bytes without a suffix).
1417 domdisplay domain [--include-password] [[--type] type] [--all]
1419 Output a URI which can be used to connect to the graphical display
1420 of the domain via VNC, SPICE or RDP. The particular graphical
1421 display type can be selected using the type parameter (e.g. "vnc",
1422 "spice", "rdp"). If --include-password is specified, the SPICE
1423 channel password will be included in the URI. If --all is
1424 specified, then all show all possible graphical displays, for a VM
1425 could have more than one graphical displays.
1426 domfsinfo domain
1428 Show a list of mounted filesystems within the running domain. The
1429 list contains mountpoints, names of a mounted device in the guest,
1430 filesystem types, and unique target names used in the domain XML
1431 (<target dev='name'/>).
1432 Note that this command requires a guest agent configured and
1434 running in the domain's guest OS.
1435 domfsfreeze domain [[--mountpoint] mountpoint...]
1437 Freeze mounted filesystems within a running domain to prepare for
1438 consistent snapshots.
1439 The --mountpoint option takes a parameter mountpoint, which is a
1441 mount point path of the filesystem to be frozen. This option can
1442 occur multiple times. If this is not specified, every mounted
1443 filesystem is frozen.
1444 Note: snapshot-create command has a --quiesce option to freeze and
1446 thaw the filesystems automatically to keep snapshots consistent.
1447 domfsfreeze command is only needed when a user wants to utilize the
1448 native snapshot features of storage devices not supported by
1449 libvirt.
1450 domfsthaw domain [[--mountpoint] mountpoint...]
1452 Thaw mounted filesystems within a running domain, which have been
1453 frozen by domfsfreeze command.
1454 The --mountpoint option takes a parameter mountpoint, which is a
1456 mount point path of the filesystem to be thawed. This option can
1457 occur multiple times. If this is not specified, every mounted
1458 filesystem is thawed.
1459 domfstrim domain [--minimum bytes] [--mountpoint mountPoint]
1461 Issue a fstrim command on all mounted filesystems within a running
1462 domain. It discards blocks which are not in use by the filesystem.
1463 If --minimum bytes is specified, it tells guest kernel length of
1464 contiguous free range. Smaller than this may be ignored (this is a
1465 hint and the guest may not respect it). By increasing this value,
1466 the fstrim operation will complete more quickly for filesystems
1467 with badly fragmented free space, although not all blocks will be
1468 discarded. The default value is zero, meaning "discard every free
1469 block". Moreover, if a user wants to trim only one mount point, it
1470 can be specified via optional --mountpoint parameter.
1471 domhostname domain
1473 Returns the hostname of a domain, if the hypervisor makes it
1474 available.
1475 dominfo domain
1477 Returns basic information about the domain.
1478 domuuid domain-name-or-id
1480 Convert a domain name or id to domain UUID
1481 domid domain-name-or-uuid
1483 Convert a domain name (or UUID) to a domain id
1484 domjobabort domain
1486 Abort the currently running domain job.
1487 domjobinfo domain [--completed]
1489 Returns information about jobs running on a domain. --completed
1490 tells virsh to return information about a recently finished job.
1491 Statistics of a completed job are automatically destroyed once read
1492 or when libvirtd is restarted. Note that time information returned
1493 for completed migrations may be completely irrelevant unless both
1494 source and destination hosts have synchronized time (i.e., NTP
1495 daemon is running on both of them).
1496 domname domain-id-or-uuid
1498 Convert a domain Id (or UUID) to domain name
1499 domrename domain new-name
1501 Rename a domain. This command changes current domain name to the
1502 new name specified in the second argument.
1503 Note: Domain must be inactive and without snapshots or checkpoints.
1505 domstate domain [--reason]
1507 Returns state about a domain. --reason tells virsh to also print
1508 reason for the state.
1509 domcontrol domain
1511 Returns state of an interface to VMM used to control a domain. For
1512 states other than "ok" or "error" the command also prints number of
1513 seconds elapsed since the control interface entered its current
1514 state.
1515 domtime domain { [--now] [--pretty] [--sync] [--time time] }
1517 Gets or sets the domain's system time. When run without any
1518 arguments (but domain), the current domain's system time is printed
1519 out. The --pretty modifier can be used to print the time in more
1520 human readable form.
1521 When --time time is specified, the domain's time is not gotten but
1523 set instead. The --now modifier acts like if it was an alias for
1524 --time $now, which means it sets the time that is currently on the
1525 host virsh is running at. In both cases (setting and getting), time
1526 is in seconds relative to Epoch of 1970-01-01 in UTC. The --sync
1527 modifies the set behavior a bit: The time passed is ignored, but
1528 the time to set is read from domain's RTC instead. Please note,
1529 that some hypervisors may require a guest agent to be configured in
1530 order to get or set the guest time.
1531 domxml-from-native format config
1533 Convert the file config in the native guest configuration format
1534 named by format to a domain XML format. For QEMU/KVM hypervisor,
1535 the format argument must be qemu-argv. For Xen hypervisor, the
1536 format argument may be xen-xm, xen-xl, or xen-sxpr. For LXC
1537 hypervisor, the format argument must be lxc-tools. For VMware/ESX
1538 hypervisor, the format argument must be vmware-vmx. For the Bhyve
1539 hypervisor, the format argument must be bhyve-argv.
1540 domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-
1542 uuid }
1543 Convert the file xml into domain XML format or convert an existing
1544 --domain to the native guest configuration format named by format.
1545 The xml and --domain arguments are mutually exclusive. For the
1546 types of format argument, refer to domxml-from-native.
1547 dump domain corefilepath [--bypass-cache] { [--live] | [--crash] |
1549 [--reset] } [--verbose] [--memory-only] [--format string]
1550 Dumps the core of a domain to a file for analysis. If --live is
1551 specified, the domain continues to run until the core dump is
1552 complete, rather than pausing up front. If --crash is specified,
1553 the domain is halted with a crashed status, rather than merely left
1554 in a paused state. If --reset is specified, the domain is reset
1555 after successful dump. Note, these three switches are mutually
1556 exclusive. If --bypass-cache is specified, the save will avoid the
1557 file system cache, although this may slow down the operation. If
1558 --memory-only is specified, the file is elf file, and will only
1559 include domain's memory and cpu common register value. It is very
1560 useful if the domain uses host devices directly. --format string
1561 is used to specify the format of 'memory-only' dump, and string can
1562 be one of them: elf, kdump-zlib(kdump-compressed format with zlib-
1563 compressed), kdump-lzo(kdump-compressed format with lzo-
1564 compressed), kdump-snappy(kdump-compressed format with snappy-
1565 compressed).
1566 The progress may be monitored using domjobinfo virsh command and
1568 canceled with domjobabort command (sent by another virsh instance).
1569 Another option is to send SIGINT (usually with "Ctrl-C") to the
1570 virsh process running dump command. --verbose displays the progress
1571 of dump.
1572 NOTE: Some hypervisors may require the user to manually ensure
1574 proper permissions on file and path specified by argument
1575 corefilepath.
1576 NOTE: Crash dump in a old kvmdump format is being obsolete and
1578 cannot be loaded and processed by crash utility since its version
1579 6.1.0. A --memory-only option is required in order to produce valid
1580 ELF file which can be later processed by the crash utility.
1581 dumpxml domain [--inactive] [--security-info] [--update-cpu]
1583 [--migratable]
1584 Output the domain information as an XML dump to stdout, this format
1585 can be used by the create command. Additional options affecting the
1586 XML dump may be used. --inactive tells virsh to dump domain
1587 configuration that will be used on next start of the domain as
1588 opposed to the current domain configuration. Using --security-info
1589 will also include security sensitive information in the XML dump.
1590 --update-cpu updates domain CPU requirements according to host CPU.
1591 With --migratable one can request an XML that is suitable for
1592 migrations, i.e., compatible with older libvirt releases and
1593 possibly amended with internal run-time options. This option may
1594 automatically enable other options (--update-cpu, --security-info,
1595 ...) as necessary.
1596 edit domain
1598 Edit the XML configuration file for a domain, which will affect the
1599 next boot of the guest.
1600 This is equivalent to:
1602 virsh dumpxml --inactive --security-info domain > domain.xml
1604 vi domain.xml (or make changes with your other text editor)
1605 virsh define domain.xml
1606 except that it does some error checking.
1608 The editor used can be supplied by the $VISUAL or $EDITOR
1610 environment variables, and defaults to "vi".
1611 event {[domain] { event | --all } [--loop] [--timeout seconds]
1613 [--timestamp] | --list}
1614 Wait for a class of domain events to occur, and print appropriate
1615 details of events as they happen. The events can optionally be
1616 filtered by domain. Using --list as the only argument will provide
1617 a list of possible event values known by this client, although the
1618 connection might not allow registering for all these events. It is
1619 also possible to use --all instead of event to register for all
1620 possible event types at once.
1621 By default, this command is one-shot, and returns success once an
1623 event occurs; you can send SIGINT (usually via "Ctrl-C") to quit
1624 immediately. If --timeout is specified, the command gives up
1625 waiting for events after seconds have elapsed. With --loop, the
1626 command prints all events until a timeout or interrupt key.
1627 When --timestamp is used, a human-readable timestamp will be
1629 printed before the event.
1630 iothreadinfo domain [[--live] [--config] | [--current]]
1632 Display basic domain IOThreads information including the IOThread
1633 ID and the CPU Affinity for each IOThread.
1634 If --live is specified, get the IOThreads data from the running
1636 guest. If the guest is not running, an error is returned. If
1637 --config is specified, get the IOThreads data from the next boot of
1638 a persistent guest. If --current is specified or --live and
1639 --config are not specified, then get the IOThread data based on the
1640 current guest state.
1641 iothreadpin domain iothread cpulist [[--live] [--config] | [--current]]
1643 Change the pinning of a domain IOThread to host physical CPUs. In
1644 order to retrieve a list of all IOThreads, use iothreadinfo. To pin
1645 an iothread specify the cpulist desired for the IOThread ID as
1646 listed in the iothreadinfo output.
1647 cpulist is a list of physical CPU numbers. Its syntax is a comma
1649 separated list and a special markup using '-' and '^' (ex. '0-4',
1650 '0-3,^2') can also be allowed. The '-' denotes the range and the
1651 '^' denotes exclusive. If you want to reset iothreadpin setting,
1652 that is, to pin an iothread to all physical cpus, simply specify
1653 'r' as a cpulist.
1654 If --live is specified, affect a running guest. If the guest is not
1656 running, an error is returned. If --config is specified, affect
1657 the next boot of a persistent guest. If --current is specified or
1658 --live and --config are not specified, affect the current guest
1659 state. Both --live and --config flags may be given if cpulist is
1660 present, but --current is exclusive. If no flag is specified,
1661 behavior is different depending on hypervisor.
1662 Note: The expression is sequentially evaluated, so "0-15,^8" is
1664 identical to "9-14,0-7,15" but not identical to "^8,0-15".
1665 iothreadadd domain iothread_id [[--config] [--live] | [--current]]
1667 Add a new IOThread to the domain using the specified iothread_id.
1668 If the iothread_id already exists, the command will fail. The
1669 iothread_id must be greater than zero.
1670 If --live is specified, affect a running guest. If the guest is not
1672 running an error is returned. If --config is specified, affect the
1673 next boot of a persistent guest. If --current is specified or
1674 --live and --config are not specified, affect the current guest
1675 state.
1676 iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor]
1678 [--poll-shrink divisor]] [[--config] [--live] | [--current]]
1679 Modifies an existing iothread of the domain using the specified
1680 iothread_id. The --poll-max-ns provides the maximum polling
1681 interval to be allowed for an IOThread in ns. If a 0 (zero) is
1682 provided, then polling for the IOThread is disabled. The
1683 --poll-grow is the factor by which the current polling time will be
1684 adjusted in order to reach the maximum polling time. If a 0 (zero)
1685 is provided, then the default factor will be used. The
1686 --poll-shrink is the quotient by which the current polling time
1687 will be reduced in order to get below the maximum polling interval.
1688 If a 0 (zero) is provided, then the default quotient will be used.
1689 The polling values are purely dynamic for a running guest. Saving,
1690 destroying, stopping, etc. the guest will result in the polling
1691 values returning to hypervisor defaults at the next start, restore,
1692 etc.
1693 If --live is specified, affect a running guest. If the guest is not
1695 running an error is returned. If --current is specified or --live
1696 is not specified, then handle as if --live was specified.
1697 iothreaddel domain iothread_id [[--config] [--live] | [--current]]
1699 Delete an IOThread from the domain using the specified iothread_id.
1700 If an IOThread is currently assigned to a disk resource such as via
1701 the attach-disk command, then the attempt to remove the IOThread
1702 will fail. If the iothread_id does not exist an error will occur.
1703 If --live is specified, affect a running guest. If the guest is not
1705 running an error is returned. If --config is specified, affect the
1706 next boot of a persistent guest. If --current is specified or
1707 --live and --config are not specified, affect the current guest
1708 state.
1709 managedsave domain [--bypass-cache] [{--running | --paused}]
1711 [--verbose]
1712 Save and destroy (stop) a running domain, so it can be restarted
1713 from the same state at a later time. When the virsh start command
1714 is next run for the domain, it will automatically be started from
1715 this saved state. If --bypass-cache is specified, the save will
1716 avoid the file system cache, although this may slow down the
1717 operation.
1718 The progress may be monitored using domjobinfo virsh command and
1720 canceled with domjobabort command (sent by another virsh instance).
1721 Another option is to send SIGINT (usually with "Ctrl-C") to the
1722 virsh process running managedsave command. --verbose displays the
1723 progress of save.
1724 Normally, starting a managed save will decide between running or
1726 paused based on the state the domain was in when the save was done;
1727 passing either the --running or --paused flag will allow overriding
1728 which state the start should use.
1729 The dominfo command can be used to query whether a domain currently
1731 has any managed save image.
1732 managedsave-remove domain
1734 Remove the managedsave state file for a domain, if it exists. This
1735 ensures the domain will do a full boot the next time it is started.
1736 managedsave-define domain xml [{--running | --paused}]
1738 Update the domain XML that will be used when domain is later
1739 started. The xml argument must be a file name containing the
1740 alternative XML, with changes only in the host-specific portions of
1741 the domain XML. For example, it can be used to change disk file
1742 paths.
1743 The managed save image records whether the domain should be started
1745 to a running or paused state. Normally, this command does not
1746 alter the recorded state; passing either the --running or --paused
1747 flag will allow overriding which state the start should use.
1748 managedsave-dumpxml domain [--security-info]
1750 Extract the domain XML that was in effect at the time the saved
1751 state file file was created with the managedsave command. Using
1752 --security-info will also include security sensitive information.
1753 managedsave-edit domain [{--running | --paused}]
1755 Edit the XML configuration associated with a saved state file of a
1756 domain was created by the managedsave command.
1757 The managed save image records whether the domain should be started
1759 to a running or paused state. Normally, this command does not
1760 alter the recorded state; passing either the --running or --paused
1761 flag will allow overriding which state the restore should use.
1762 This is equivalent to:
1764 virsh managedsave-dumpxml domain-name > state-file.xml
1766 vi state-file.xml (or make changes with your other text editor)
1767 virsh managedsave-define domain-name state-file-xml
1768 except that it does some error checking.
1770 The editor used can be supplied by the $VISUAL or $EDITOR
1772 environment variables, and defaults to "vi".
1773 maxvcpus [type]
1775 Provide the maximum number of virtual CPUs supported for a guest VM
1776 on this connection. If provided, the type parameter must be a
1777 valid type attribute for the <domain> element of XML.
1778 cpu-stats domain [--total] [start] [count]
1780 Provide cpu statistics information of a domain. The domain should
1781 be running. Default it shows stats for all CPUs, and a total. Use
1782 --total for only the total stats, start for only the per-cpu stats
1783 of the CPUs from start, count for only count CPUs' stats.
1784 metadata domain [[--live] [--config] | [--current]] [--edit] [uri]
1786 [key] [set] [--remove]
1787 Show or modify custom XML metadata of a domain. The metadata is a
1788 user defined XML that allows storing arbitrary XML data in the
1789 domain definition. Multiple separate custom metadata pieces can be
1790 stored in the domain XML. The pieces are identified by a private
1791 XML namespace provided via the uri argument. (See also desc that
1792 works with textual metadata of a domain.)
1793 Flags --live or --config select whether this command works on live
1795 or persistent definitions of the domain. If both --live and
1796 --config are specified, the --config option takes precedence on
1797 getting the current description and both live configuration and
1798 config are updated while setting the description. --current is
1799 exclusive and implied if none of these was specified.
1800 Flag --remove specifies that the metadata element specified by the
1802 uri argument should be removed rather than updated.
1803 Flag --edit specifies that an editor with the metadata identified
1805 by the uri argument should be opened and the contents saved back
1806 afterwards. Otherwise the new contents can be provided via the set
1807 argument.
1808 When setting metadata via --edit or set the key argument must be
1810 specified and is used to prefix the custom elements to bind them to
1811 the private namespace.
1812 If neither of --edit and set are specified the XML metadata
1814 corresponding to the uri namespace is displayed instead of being
1815 modified.
1816 migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]]
1818 [--persistent] [--undefinesource] [--suspend] [--copy-storage-all]
1819 [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose]
1820 [--rdma-pin-all] [--abort-on-error] [--postcopy]
1821 [--postcopy-after-precopy] domain desturi [migrateuri] [graphicsuri]
1822 [listen-address] [dname] [--timeout seconds [--timeout-suspend |
1823 --timeout-postcopy]] [--xml file] [--migrate-disks disk-list]
1824 [--disks-port port] [--compressed] [--comp-methods method-list]
1825 [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads]
1826 [--comp-xbzrle-cache] [--auto-converge] [auto-converge-initial] [auto-
1827 converge-increment] [--persistent-xml file] [--tls]
1828 [--postcopy-bandwidth bandwidth] [--parallel [--parallel-connections
1829 connections]]
1830 Migrate domain to another host. Add --live for live migration;
1831 <--p2p> for peer-2-peer migration; --direct for direct migration;
1832 or --tunnelled for tunnelled migration. --offline migrates domain
1833 definition without starting the domain on destination and without
1834 stopping it on source host. Offline migration may be used with
1835 inactive domains and it must be used with --persistent option.
1836 --persistent leaves the domain persistent on destination host,
1837 --undefinesource undefines the domain on the source host, and
1838 --suspend leaves the domain paused on the destination host.
1839 --copy-storage-all indicates migration with non-shared storage with
1840 full disk copy, --copy-storage-inc indicates migration with non-
1841 shared storage with incremental copy (same base image shared
1842 between source and destination). In both cases the disk images
1843 have to exist on destination host, the --copy-storage-... options
1844 only tell libvirt to transfer data from the images on source host
1845 to the images found at the same place on the destination host. By
1846 default only non-shared non-readonly images are transferred. Use
1847 --migrate-disks to explicitly specify a list of disk targets to
1848 transfer via the comma separated disk-list argument.
1849 --change-protection enforces that no incompatible configuration
1850 changes will be made to the domain while the migration is underway;
1851 this flag is implicitly enabled when supported by the hypervisor,
1852 but can be explicitly used to reject the migration if the
1853 hypervisor lacks change protection support. --verbose displays the
1854 progress of migration. --abort-on-error cancels the migration if a
1855 soft error (for example I/O error) happens during the migration.
1856 --postcopy enables post-copy logic in migration, but does not
1857 actually start post-copy, i.e., migration is started in pre-copy
1858 mode. Once migration is running, the user may switch to post-copy
1859 using the migrate-postcopy command sent from another virsh instance
1860 or use --postcopy-after-precopy along with --postcopy to let
1861 libvirt automatically switch to post-copy after the first pass of
1862 pre-copy is finished. The maximum bandwidth consumed during the
1863 post-copy phase may be limited using --postcopy-bandwidth.
1864 --auto-converge forces convergence during live migration. The
1866 initial guest CPU throttling rate can be set with auto-converge-
1867 initial. If the initial throttling rate is not enough to ensure
1868 convergence, the rate is periodically increased by auto-converge-
1869 increment.
1870 --rdma-pin-all can be used with RDMA migration (i.e., when
1872 migrateuri starts with rdma://) to tell the hypervisor to pin all
1873 domain's memory at once before migration starts rather than letting
1874 it pin memory pages as needed. For QEMU/KVM this requires
1875 hard_limit memory tuning element (in the domain XML) to be used and
1876 set to the maximum memory configured for the domain plus any memory
1877 consumed by the QEMU process itself. Beware of setting the memory
1878 limit too high (and thus allowing the domain to lock most of the
1879 host's memory). Doing so may be dangerous to both the domain and
1880 the host itself since the host's kernel may run out of memory.
1881 Note: Individual hypervisors usually do not support all possible
1883 types of migration. For example, QEMU does not support direct
1884 migration.
1885 In some cases libvirt may refuse to migrate the domain because
1887 doing so may lead to potential problems such as data corruption,
1888 and thus the migration is considered unsafe. For QEMU domain, this
1889 may happen if the domain uses disks without explicitly setting
1890 cache mode to "none". Migrating such domains is unsafe unless the
1891 disk images are stored on coherent clustered filesystem, such as
1892 GFS2 or GPFS. If you are sure the migration is safe or you just do
1893 not care, use --unsafe to force the migration.
1894 dname is used for renaming the domain to new name during migration,
1896 which also usually can be omitted. Likewise, --xml file is usually
1897 omitted, but can be used to supply an alternative XML file for use
1898 on the destination to supply a larger set of changes to any host-
1899 specific portions of the domain XML, such as accounting for naming
1900 differences between source and destination in accessing underlying
1901 storage. If --persistent is enabled, --persistent-xml file can be
1902 used to supply an alternative XML file which will be used as the
1903 persistent domain definition on the destination host.
1904 --timeout seconds tells virsh to run a specified action when live
1906 migration exceeds that many seconds. It can only be used with
1907 --live. If --timeout-suspend is specified, the domain will be
1908 suspended after the timeout and the migration will complete
1909 offline; this is the default if no --timeout-* option is specified
1910 on the command line. When --timeout-postcopy is used, virsh will
1911 switch migration from pre-copy to post-copy upon timeout; migration
1912 has to be started with --postcopy option for this to work.
1913 --compressed activates compression, the compression method is
1915 chosen with --comp-methods. Supported methods are "mt" and "xbzrle"
1916 and can be used in any combination. When no methods are specified,
1917 a hypervisor default methods will be used. QEMU defaults to
1918 "xbzrle". Compression methods can be tuned further. --comp-mt-level
1919 sets compression level. Values are in range from 0 to 9, where 1
1920 is maximum speed and 9 is maximum compression. --comp-mt-threads
1921 and --comp-mt-dthreads set the number of compress threads on source
1922 and the number of decompress threads on target respectively.
1923 --comp-xbzrle-cache sets size of page cache in bytes.
1924 Providing --tls causes the migration to use the host configured TLS
1926 setup (see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in
1927 order to perform the migration of the domain. Usage requires proper
1928 TLS setup for both source and target.
1929 --parallel option will cause migration data to be sent over
1931 multiple parallel connections. The number of such connections can
1932 be set using --parallel-connections. Parallel connections may help
1933 with saturating the network link between the source and the target
1934 and thus speeding up the migration.
1935 Running migration can be canceled by interrupting virsh (usually
1937 using "Ctrl-C") or by domjobabort command sent from another virsh
1938 instance.
1939 The desturi and migrateuri parameters can be used to control which
1941 destination the migration uses. desturi is important for managed
1942 migration, but unused for direct migration; migrateuri is required
1943 for direct migration, but can usually be automatically determined
1944 for managed migration.
1945 Note: The desturi parameter for normal migration and peer2peer
1947 migration has different semantics:
1948 · normal migration: the desturi is an address of the target host
1950 as seen from the client machine.
1951 · peer2peer migration: the desturi is an address of the target
1953 host as seen from the source machine.
1954 When migrateuri is not specified, libvirt will automatically
1956 determine the hypervisor specific URI. Some hypervisors, including
1957 QEMU, have an optional "migration_host" configuration parameter
1958 (useful when the host has multiple network interfaces). If this is
1959 unspecified, libvirt determines a name by looking up the target
1960 host's configured hostname.
1961 There are a few scenarios where specifying migrateuri may help:
1963 · The configured hostname is incorrect, or DNS is broken. If a
1965 host has a hostname which will not resolve to match one of its
1966 public IP addresses, then libvirt will generate an incorrect
1967 URI. In this case migrateuri should be explicitly specified,
1968 using an IP address, or a correct hostname.
1969 · The host has multiple network interfaces. If a host has
1971 multiple network interfaces, it might be desirable for the
1972 migration data stream to be sent over a specific interface for
1973 either security or performance reasons. In this case
1974 migrateuri should be explicitly specified, using an IP address
1975 associated with the network to be used.
1976 · The firewall restricts what ports are available. When libvirt
1978 generates a migration URI, it will pick a port number using
1979 hypervisor specific rules. Some hypervisors only require a
1980 single port to be open in the firewalls, while others require a
1981 whole range of port numbers. In the latter case migrateuri
1982 might be specified to choose a specific port number outside the
1983 default range in order to comply with local firewall policies.
1984 See <https://libvirt.org/migration.html#uris> for more details on
1986 migration URIs.
1987 Optional graphicsuri overrides connection parameters used for
1989 automatically reconnecting a graphical clients at the end of
1990 migration. If omitted, libvirt will compute the parameters based on
1991 target host IP address. In case the client does not have a direct
1992 access to the network virtualization hosts are connected to and
1993 needs to connect through a proxy, graphicsuri may be used to
1994 specify the address the client should connect to. The URI is formed
1995 as follows:
1996 protocol://hostname[:port]/[?parameters]
1998 where protocol is either "spice" or "vnc" and parameters is a list
2000 of protocol specific parameters separated by '&'. Currently
2001 recognized parameters are "tlsPort" and "tlsSubject". For example,
2002 spice://target.host.com:1234/?tlsPort=4567
2004 Optional listen-address sets the listen address that hypervisor on
2006 the destination side should bind to for incoming migration. Both
2007 IPv4 and IPv6 addresses are accepted as well as hostnames (the
2008 resolving is done on destination). Some hypervisors do not support
2009 this feature and will return an error if this parameter is used.
2010 Optional disks-port sets the port that hypervisor on destination
2012 side should bind to for incoming disks traffic. Currently it is
2013 supported only by qemu.
2014 migrate-setmaxdowntime domain downtime
2016 Set maximum tolerable downtime for a domain which is being live-
2017 migrated to another host. The downtime is a number of milliseconds
2018 the guest is allowed to be down at the end of live migration.
2019 migrate-getmaxdowntime domain
2021 Get the maximum tolerable downtime for a domain which is being
2022 live-migrated to another host. This is the number of milliseconds
2023 the guest is allowed to be down at the end of live migration.
2024 migrate-compcache domain [--size bytes]
2026 Sets and/or gets size of the cache (in bytes) used for compressing
2027 repeatedly transferred memory pages during live migration. When
2028 called without size, the command just prints current size of the
2029 compression cache. When size is specified, the hypervisor is asked
2030 to change compression cache to size bytes and then the current size
2031 is printed (the result may differ from the requested size due to
2032 rounding done by the hypervisor). The size option is supposed to be
2033 used while the domain is being live-migrated as a reaction to
2034 migration progress and increasing number of compression cache
2035 misses obtained from domjobinfo.
2036 migrate-setspeed domain bandwidth [--postcopy]
2038 Set the maximum migration bandwidth (in MiB/s) for a domain which
2039 is being migrated to another host. bandwidth is interpreted as an
2040 unsigned long long value. Specifying a negative value results in an
2041 essentially unlimited value being provided to the hypervisor. The
2042 hypervisor can choose whether to reject the value or convert it to
2043 the maximum value allowed. If the --postcopy option is specified,
2044 the command will set the maximum bandwidth allowed during a post-
2045 copy migration phase.
2046 migrate-getspeed domain [--postcopy]
2048 Get the maximum migration bandwidth (in MiB/s) for a domain. If the
2049 --postcopy option is specified, the command will get the maximum
2050 bandwidth allowed during a post-copy migration phase.
2051 migrate-postcopy domain
2053 Switch the current migration from pre-copy to post-copy. This is
2054 only supported for a migration started with --postcopy option.
2055 numatune domain [--mode mode] [--nodeset nodeset] [[--config] [--live]
2057 | [--current]]
2058 Set or get a domain's numa parameters, corresponding to the
2059 <numatune> element of domain XML. Without flags, the current
2060 settings are displayed.
2061 mode can be one of `strict', `interleave' and `preferred' or any
2063 valid number from the virDomainNumatuneMemMode enum in case the
2064 daemon supports it. For a running domain, the mode can't be
2065 changed, and the nodeset can be changed only if the domain was
2066 started with a mode of `strict'.
2067 nodeset is a list of numa nodes used by the host for running the
2069 domain. Its syntax is a comma separated list, with '-' for ranges
2070 and '^' for excluding a node.
2071 If --live is specified, set scheduler information of a running
2073 guest. If --config is specified, affect the next boot of a
2074 persistent guest. If --current is specified, affect the current
2075 guest state.
2076 reboot domain [--mode MODE-LIST]
2078 Reboot a domain. This acts just as if the domain had the reboot
2079 command run from the console. The command returns as soon as it
2080 has executed the reboot action, which may be significantly before
2081 the domain actually reboots.
2082 The exact behavior of a domain when it reboots is set by the
2084 on_reboot parameter in the domain's XML definition.
2085 By default the hypervisor will try to pick a suitable shutdown
2087 method. To specify an alternative method, the --mode parameter can
2088 specify a comma separated list which includes "acpi", "agent",
2089 "initctl", "signal" and "paravirt". The order in which drivers will
2090 try each mode is undefined, and not related to the order specified
2091 to virsh. For strict control over ordering, use a single mode at a
2092 time and repeat the command.
2093 reset domain
2095 Reset a domain immediately without any guest shutdown. reset
2096 emulates the power reset button on a machine, where all guest
2097 hardware sees the RST line set and reinitializes internal state.
2098 Note: Reset without any guest OS shutdown risks data loss.
2100 restore state-file [--bypass-cache] [--xml file] [{--running |
2102 --paused}]
2103 Restores a domain from a virsh save state file. See save for more
2104 info.
2105 If --bypass-cache is specified, the restore will avoid the file
2107 system cache, although this may slow down the operation.
2108 --xml file is usually omitted, but can be used to supply an
2110 alternative XML file for use on the restored guest with changes
2111 only in the host-specific portions of the domain XML. For example,
2112 it can be used to account for file naming differences in underlying
2113 storage due to disk snapshots taken after the guest was saved.
2114 Normally, restoring a saved image will use the state recorded in
2116 the save image to decide between running or paused; passing either
2117 the --running or --paused flag will allow overriding which state
2118 the domain should be started in.
2119 Note: To avoid corrupting file system contents within the domain,
2121 you should not reuse the saved state file for a second restore
2122 unless you have also reverted all storage volumes back to the same
2123 contents as when the state file was created.
2124 save domain state-file [--bypass-cache] [--xml file] [{--running |
2126 --paused}] [--verbose]
2127 Saves a running domain (RAM, but not disk state) to a state file so
2128 that it can be restored later. Once saved, the domain will no
2129 longer be running on the system, thus the memory allocated for the
2130 domain will be free for other domains to use. virsh restore
2131 restores from this state file. If --bypass-cache is specified, the
2132 save will avoid the file system cache, although this may slow down
2133 the operation.
2134 The progress may be monitored using domjobinfo virsh command and
2136 canceled with domjobabort command (sent by another virsh instance).
2137 Another option is to send SIGINT (usually with "Ctrl-C") to the
2138 virsh process running save command. --verbose displays the progress
2139 of save.
2140 This is roughly equivalent to doing a hibernate on a running
2142 computer, with all the same limitations. Open network connections
2143 may be severed upon restore, as TCP timeouts may have expired.
2144 --xml file is usually omitted, but can be used to supply an
2146 alternative XML file for use on the restored guest with changes
2147 only in the host-specific portions of the domain XML. For example,
2148 it can be used to account for file naming differences that are
2149 planned to be made via disk snapshots of underlying storage after
2150 the guest is saved.
2151 Normally, restoring a saved image will decide between running or
2153 paused based on the state the domain was in when the save was done;
2154 passing either the --running or --paused flag will allow overriding
2155 which state the restore should use.
2156 Domain saved state files assume that disk images will be unchanged
2158 between the creation and restore point. For a more complete system
2159 restore point, where the disk state is saved alongside the memory
2160 state, see the snapshot family of commands.
2161 save-image-define file xml [{--running | --paused}]
2163 Update the domain XML that will be used when file is later used in
2164 the restore command. The xml argument must be a file name
2165 containing the alternative XML, with changes only in the host-
2166 specific portions of the domain XML. For example, it can be used
2167 to account for file naming differences resulting from creating disk
2168 snapshots of underlying storage after the guest was saved.
2169 The save image records whether the domain should be restored to a
2171 running or paused state. Normally, this command does not alter the
2172 recorded state; passing either the --running or --paused flag will
2173 allow overriding which state the restore should use.
2174 save-image-dumpxml file [--security-info]
2176 Extract the domain XML that was in effect at the time the saved
2177 state file file was created with the save command. Using
2178 --security-info will also include security sensitive information.
2179 save-image-edit file [{--running | --paused}]
2181 Edit the XML configuration associated with a saved state file file
2182 created by the save command.
2183 The save image records whether the domain should be restored to a
2185 running or paused state. Normally, this command does not alter the
2186 recorded state; passing either the --running or --paused flag will
2187 allow overriding which state the restore should use.
2188 This is equivalent to:
2190 virsh save-image-dumpxml state-file > state-file.xml
2192 vi state-file.xml (or make changes with your other text editor)
2193 virsh save-image-define state-file state-file-xml
2194 except that it does some error checking.
2196 The editor used can be supplied by the $VISUAL or $EDITOR
2198 environment variables, and defaults to "vi".
2199 schedinfo domain [[--config] [--live] | [--current]] [[--set]
2201 parameter=value]...
2202 schedinfo [--weight number] [--cap number] domain
2203 Allows you to show (and set) the domain scheduler parameters. The
2204 parameters available for each hypervisor are:
2205 LXC (posix scheduler) : cpu_shares, vcpu_period, vcpu_quota
2207 QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota,
2209 emulator_period, emulator_quota, iothread_quota, iothread_period
2210 Xen (credit scheduler): weight, cap
2212 ESX (allocation scheduler): reservation, limit, shares
2214 If --live is specified, set scheduler information of a running
2216 guest. If --config is specified, affect the next boot of a
2217 persistent guest. If --current is specified, affect the current
2218 guest state.
2219 Note: The cpu_shares parameter has a valid value range of 0-262144;
2221 Negative values are wrapped to positive, and larger values are
2222 capped at the maximum. Therefore, -1 is a useful shorthand for
2223 262144. On the Linux kernel, the values 0 and 1 are automatically
2224 converted to a minimal value of 2.
2225 Note: The weight and cap parameters are defined only for the
2227 XEN_CREDIT scheduler.
2228 Note: The vcpu_period, emulator_period, and iothread_period
2230 parameters have a valid value range of 1000-1000000 or 0, and the
2231 vcpu_quota, emulator_quota, and iothread_quota parameters have a
2232 valid value range of 1000-18446744073709551 or less than 0. The
2233 value 0 for either parameter is the same as not specifying that
2234 parameter.
2235 screenshot domain [imagefilepath] [--screen screenID]
2237 Takes a screenshot of a current domain console and stores it into a
2238 file. Optionally, if the hypervisor supports more displays for a
2239 domain, screenID allows specifying which screen will be captured.
2240 It is the sequential number of screen. In case of multiple graphics
2241 cards, heads are enumerated before devices, e.g. having two
2242 graphics cards, both with four heads, screen ID 5 addresses the
2243 second head on the second card.
2244 send-key domain [--codeset codeset] [--holdtime holdtime] keycode...
2246 Parse the keycode sequence as keystrokes to send to domain. Each
2247 keycode can either be a numeric value or a symbolic name from the
2248 corresponding codeset. If --holdtime is given, each keystroke will
2249 be held for that many milliseconds. The default codeset is linux,
2250 but use of the --codeset option allows other codesets to be chosen.
2251 If multiple keycodes are specified, they are all sent
2253 simultaneously to the guest, and they may be received in random
2254 order. If you need distinct keypresses, you must use multiple send-
2255 key invocations.
2256 linux
2258 The numeric values are those defined by the Linux generic input
2259 event subsystem. The symbolic names match the corresponding
2260 Linux key constant macro names.
2261 See virkeycode-linux(7) and virkeyname-linux(7)
2263 xt The numeric values are those defined by the original XT
2265 keyboard controller. No symbolic names are provided
2266 See virkeycode-xt(7)
2268 atset1
2270 The numeric values are those defined by the AT keyboard
2271 controller, set 1 (aka XT compatible set). Extended keycoes
2272 from atset1 may differ from extended keycodes in the xt
2273 codeset. No symbolic names are provided
2274 See virkeycode-atset1(7)
2276 atset2
2278 The numeric values are those defined by the AT keyboard
2279 controller, set 2. No symbolic names are provided
2280 See virkeycode-atset2(7)
2282 atset3
2284 The numeric values are those defined by the AT keyboard
2285 controller, set 3 (aka PS/2 compatible set). No symbolic names
2286 are provided
2287 See virkeycode-atset3(7)
2289 os_x
2291 The numeric values are those defined by the macOS keyboard
2292 input subsystem. The symbolic names match the corresponding
2293 macOS key constant macro names
2294 See virkeycode-osx(7) and virkeyname-osx(7)
2296 xt_kbd
2298 The numeric values are those defined by the Linux KBD device.
2299 These are a variant on the original XT codeset, but often with
2300 different encoding for extended keycodes. No symbolic names are
2301 provided.
2302 See virkeycode-xtkbd(7)
2304 win32
2306 The numeric values are those defined by the Win32 keyboard
2307 input subsystem. The symbolic names match the corresponding
2308 Win32 key constant macro names
2309 See virkeycode-win32(7) and virkeyname-win32(7)
2311 usb The numeric values are those defined by the USB HID
2313 specification for keyboard input. No symbolic names are
2314 provided
2315 See virkeycode-usb(7)
2317 qnum
2319 The numeric values are those defined by the QNUM extension for
2320 sending raw keycodes. These are a variant on the XT codeset,
2321 but extended keycodes have the low bit of the second byte set,
2322 instead of the high bit of the first byte. No symbolic names
2323 are provided.
2324 See virkeycode-qnum(7)
2326 Examples
2328 # send three strokes 'k', 'e', 'y', using xt codeset. these
2329 # are all pressed simultaneously and may be received by the guest
2330 # in random order
2331 virsh send-key dom --codeset xt 37 18 21
2332 # send one stroke 'right-ctrl+C'
2334 virsh send-key dom KEY_RIGHTCTRL KEY_C
2335 # send a tab, held for 1 second
2337 virsh send-key --holdtime 1000 0xf
2338 send-process-signal domain-id pid signame
2340 Send a signal signame to the process identified by pid running in
2341 the virtual domain domain-id. The pid is a process ID in the
2342 virtual domain namespace.
2343 The signame argument may be either an integer signal constant
2345 number, or one of the symbolic names:
2346 "nop", "hup", "int", "quit", "ill",
2348 "trap", "abrt", "bus", "fpe", "kill",
2349 "usr1", "segv", "usr2", "pipe", "alrm",
2350 "term", "stkflt", "chld", "cont", "stop",
2351 "tstp", "ttin", "ttou", "urg", "xcpu",
2352 "xfsz", "vtalrm", "prof", "winch", "poll",
2353 "pwr", "sys", "rt0", "rt1", "rt2", "rt3",
2354 "rt4", "rt5", "rt6", "rt7", "rt8", "rt9",
2355 "rt10", "rt11", "rt12", "rt13", "rt14", "rt15",
2356 "rt16", "rt17", "rt18", "rt19", "rt20", "rt21",
2357 "rt22", "rt23", "rt24", "rt25", "rt26", "rt27",
2358 "rt28", "rt29", "rt30", "rt31", "rt32"
2359 The symbol name may optionally be prefixed with 'sig' or 'sig_' and
2361 may be in uppercase or lowercase.
2362 Examples
2364 virsh send-process-signal myguest 1 15
2365 virsh send-process-signal myguest 1 term
2366 virsh send-process-signal myguest 1 sigterm
2367 virsh send-process-signal myguest 1 SIG_HUP
2368 setmem domain size [[--config] [--live] | [--current]]
2370 Change the memory allocation for a guest domain. If --live is
2371 specified, perform a memory balloon of a running guest. If
2372 --config is specified, affect the next boot of a persistent guest.
2373 If --current is specified, affect the current guest state. Both
2374 --live and --config flags may be given, but --current is exclusive.
2375 If no flag is specified, behavior is different depending on
2376 hypervisor.
2377 size is a scaled integer (see NOTES above); it defaults to
2379 kibibytes (blocks of 1024 bytes) unless you provide a suffix (and
2380 the older option name --kilobytes is available as a deprecated
2381 synonym) . Libvirt rounds up to the nearest kibibyte. Some
2382 hypervisors require a larger granularity than KiB, and requests
2383 that are not an even multiple will be rounded up. For example,
2384 vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
2385 For Xen, you can only adjust the memory of a running domain if the
2387 domain is paravirtualized or running the PV balloon driver.
2388 For LXC, the value being set is the cgroups value for
2390 limit_in_bytes or the maximum amount of user memory (including file
2391 cache). When viewing memory inside the container, this is the
2392 /proc/meminfo "MemTotal" value. When viewing the value from the
2393 host, use the virsh memtune command. In order to view the current
2394 memory in use and the maximum value allowed to set memory, use the
2395 virsh dominfo command.
2396 set-lifecycle-action domain type action [[--config] [--live] |
2398 [--current]]
2399 Set the lifecycle action for specified lifecycle type. The valid
2400 types are "poweroff", "reboot" and "crash", and for each of them
2401 valid action is one of "destroy", "restart", "rename-restart",
2402 "preserve". For type "crash", additional actions "coredump-
2403 destroy" and "coredump-restart" are supported.
2404 set-user-password domain user password [--encrypted]
2406 Set the password for the user account in the guest domain.
2407 If --encrypted is specified, the password is assumed to be already
2409 encrypted by the method required by the guest OS.
2410 For QEMU/KVM, this requires the guest agent to be configured and
2412 running.
2413 setmaxmem domain size [[--config] [--live] | [--current]]
2415 Change the maximum memory allocation limit for a guest domain. If
2416 --live is specified, affect a running guest. If --config is
2417 specified, affect the next boot of a persistent guest. If
2418 --current is specified, affect the current guest state. Both
2419 --live and --config flags may be given, but --current is exclusive.
2420 If no flag is specified, behavior is different depending on
2421 hypervisor.
2422 Some hypervisors such as QEMU/KVM don't support live changes
2424 (especially increasing) of the maximum memory limit. Even
2425 persistent configuration changes might not be performed with some
2426 hypervisors/configuration (e.g. on NUMA enabled domains on QEMU).
2427 For complex configuration changes use command edit instead).
2428 size is a scaled integer (see NOTES above); it defaults to
2430 kibibytes (blocks of 1024 bytes) unless you provide a suffix (and
2431 the older option name --kilobytes is available as a deprecated
2432 synonym) . Libvirt rounds up to the nearest kibibyte. Some
2433 hypervisors require a larger granularity than KiB, and requests
2434 that are not an even multiple will be rounded up. For example,
2435 vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
2436 memtune domain [--hard-limit size] [--soft-limit size]
2438 [--swap-hard-limit size] [--min-guarantee size] [[--config] [--live] |
2439 [--current]]
2440 Allows you to display or set the domain memory parameters. Without
2441 flags, the current settings are displayed; with a flag, the
2442 appropriate limit is adjusted if supported by the hypervisor. LXC
2443 and QEMU/KVM support --hard-limit, --soft-limit, and
2444 --swap-hard-limit. --min-guarantee is supported only by ESX
2445 hypervisor. Each of these limits are scaled integers (see NOTES
2446 above), with a default of kibibytes (blocks of 1024 bytes) if no
2447 suffix is present. Libvirt rounds up to the nearest kibibyte. Some
2448 hypervisors require a larger granularity than KiB, and requests
2449 that are not an even multiple will be rounded up. For example,
2450 vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
2451 If --live is specified, affect a running guest. If --config is
2453 specified, affect the next boot of a persistent guest. If
2454 --current is specified, affect the current guest state. Both
2455 --live and --config flags may be given, but --current is exclusive.
2456 If no flag is specified, behavior is different depending on
2457 hypervisor.
2458 For QEMU/KVM, the parameters are applied to the QEMU process as a
2460 whole. Thus, when counting them, one needs to add up guest RAM,
2461 guest video RAM, and some memory overhead of QEMU itself. The last
2462 piece is hard to determine so one needs guess and try.
2463 For LXC, the displayed hard_limit value is the current memory
2465 setting from the XML or the results from a virsh setmem command.
2466 --hard-limit
2468 The maximum memory the guest can use.
2469 --soft-limit
2471 The memory limit to enforce during memory contention.
2472 --swap-hard-limit
2474 The maximum memory plus swap the guest can use. This has to be
2475 more than hard-limit value provided.
2476 --min-guarantee
2478 The guaranteed minimum memory allocation for the guest.
2479 Specifying -1 as a value for these limits is interpreted as
2481 unlimited.
2482 perf domain [--enable eventSpec] [--disable eventSpec] [[--config]
2484 [--live] | [--current]]
2485 Get the current perf events setting or enable/disable specific perf
2486 events for a guest domain.
2487 Perf is a performance analyzing tool in Linux, and it can
2489 instrument CPU performance counters, tracepoints, kprobes, and
2490 uprobes (dynamic tracing). Perf supports a list of measurable
2491 events, and can measure events coming from different sources. For
2492 instance, some event are pure kernel counters, in this case they
2493 are called software events, including context-switches, minor-
2494 faults, etc.. Now dozens of events from different sources can be
2495 supported by perf.
2496 Currently only QEMU/KVM supports this command. The --enable and
2498 --disable option combined with eventSpec can be used to enable or
2499 disable specific performance event. eventSpec is a string list of
2500 one or more events separated by commas. Valid event names are as
2501 follows:
2502 Valid perf event names
2504 cmt - A PQos (Platform Qos) feature to monitor the
2505 usage of cache by applications running on the
2506 platform.
2507 mbmt - Provides a way to monitor the total system
2508 memory bandwidth between one level of cache
2509 and another.
2510 mbml - Provides a way to limit the amount of data
2511 (bytes/s) send through the memory controller
2512 on the socket.
2513 cache_misses - Provides the count of cache misses by
2514 applications running on the platform.
2515 cache_references - Provides the count of cache hits by
2516 applications running on th e platform.
2517 instructions - Provides the count of instructions executed
2518 by applications running on the platform.
2519 cpu_cycles - Provides the count of cpu cycles
2520 (total/elapsed). May be used with
2521 instructions in order to get a cycles
2522 per instruction.
2523 branch_instructions - Provides the count of branch instructions
2524 executed by applications running on the
2525 platform.
2526 branch_misses - Provides the count of branch misses executed
2527 by applications running on the platform.
2528 bus_cycles - Provides the count of bus cycles executed
2529 by applications running on the platform.
2530 stalled_cycles_frontend - Provides the count of stalled cpu
2531 cycles in the frontend of the
2532 instruction processor pipeline by
2533 applications running on the platform.
2534 stalled_cycles_backend - Provides the count of stalled cpu
2535 cycles in the backend of the
2536 instruction processor pipeline by
2537 applications running on the platform.
2538 ref_cpu_cycles - Provides the count of total cpu cycles
2539 not affected by CPU frequency scaling by
2540 applications running on the platform.
2541 cpu_clock - Provides the cpu clock time consumed by
2542 applications running on the platform.
2543 task_clock - Provides the task clock time consumed by
2544 applications running on the platform.
2545 page_faults - Provides the count of page faults by
2546 applications running on the platform.
2547 context_switches - Provides the count of context switches
2548 by applications running on the platform.
2549 cpu_migrations - Provides the count cpu migrations by
2550 applications running on the platform.
2551 page_faults_min - Provides the count minor page faults
2552 by applications running on the platform.
2553 page_faults_maj - Provides the count major page faults
2554 by applications running on the platform.
2555 alignment_faults - Provides the count alignment faults
2556 by applications running on the platform.
2557 emulation_faults - Provides the count emulation faults
2558 by applications running on the platform.
2559 Note: The statistics can be retrieved using the domstats command
2561 using the --perf flag.
2562 If --live is specified, affect a running guest. If --config is
2564 specified, affect the next boot of a persistent guest. If
2565 --current is specified, affect the current guest state. Both
2566 --live and --config flags may be given, but --current is exclusive.
2567 If no flag is specified, behavior is different depending on
2568 hypervisor.
2569 blkiotune domain [--weight weight] [--device-weights device-weights]
2571 [--device-read-iops-sec device-read-iops-sec] [--device-write-iops-sec
2572 device-write-iops-sec] [--device-read-bytes-sec device-read-bytes-sec]
2573 [--device-write-bytes-sec device-write-bytes-sec] [[--config] [--live]
2574 | [--current]]
2575 Display or set the blkio parameters. QEMU/KVM supports --weight.
2576 --weight is in range [100, 1000]. After kernel 2.6.39, the value
2577 could be in the range [10, 1000].
2578 device-weights is a single string listing one or more device/weight
2580 pairs, in the format of
2581 /path/to/device,weight,/path/to/device,weight. Each weight is in
2582 the range [100, 1000], [10, 1000] after kernel 2.6.39, or the value
2583 0 to remove that device from per-device listings. Only the devices
2584 listed in the string are modified; any existing per-device weights
2585 for other devices remain unchanged.
2586 device-read-iops-sec is a single string listing one or more
2588 device/read_iops_sec pairs, int the format of
2589 /path/to/device,read_iops_sec,/path/to/device,read_iops_sec. Each
2590 read_iops_sec is a number which type is unsigned int, value 0 to
2591 remove that device from per-device listing. Only the devices
2592 listed in the string are modified; any existing per-device
2593 read_iops_sec for other devices remain unchanged.
2594 device-write-iops-sec is a single string listing one or more
2596 device/write_iops_sec pairs, int the format of
2597 /path/to/device,write_iops_sec,/path/to/device,write_iops_sec.
2598 Each write_iops_sec is a number which type is unsigned int, value 0
2599 to remove that device from per-device listing. Only the devices
2600 listed in the string are modified; any existing per-device
2601 write_iops_sec for other devices remain unchanged.
2602 device-read-bytes-sec is a single string listing one or more
2604 device/read_bytes_sec pairs, int the format of
2605 /path/to/device,read_bytes_sec,/path/to/device,read_bytes_sec.
2606 Each read_bytes_sec is a number which type is unsigned long long,
2607 value 0 to remove that device from per-device listing. Only the
2608 devices listed in the string are modified; any existing per-device
2609 read_bytes_sec for other devices remain unchanged.
2610 device-write-bytes-sec is a single string listing one or more
2612 device/write_bytes_sec pairs, int the format of
2613 /path/to/device,write_bytes_sec,/path/to/device,write_bytes_sec.
2614 Each write_bytes_sec is a number which type is unsigned long long,
2615 value 0 to remove that device from per-device listing. Only the
2616 devices listed in the string are modified; any existing per-device
2617 write_bytes_sec for other devices remain unchanged.
2618 If --live is specified, affect a running guest. If --config is
2620 specified, affect the next boot of a persistent guest. If
2621 --current is specified, affect the current guest state. Both
2622 --live and --config flags may be given, but --current is exclusive.
2623 If no flag is specified, behavior is different depending on
2624 hypervisor.
2625 setvcpus domain count [--maximum] [[--config] [--live] | [--current]]
2627 [--guest] [--hotpluggable]
2628 Change the number of virtual CPUs active in a guest domain. By
2629 default, this command works on active guest domains. To change the
2630 settings for an inactive guest domain, use the --config flag.
2631 The count value may be limited by host, hypervisor, or a limit
2633 coming from the original description of the guest domain. For Xen,
2634 you can only adjust the virtual CPUs of a running domain if the
2635 domain is paravirtualized.
2636 If the --config flag is specified, the change is made to the stored
2638 XML configuration for the guest domain, and will only take effect
2639 when the guest domain is next started.
2640 If --live is specified, the guest domain must be active, and the
2642 change takes place immediately. Both the --config and --live flags
2643 may be specified together if supported by the hypervisor. If this
2644 command is run before the guest has finished booting, the guest may
2645 fail to process the change.
2646 If --current is specified, affect the current guest state.
2648 When no flags are given, the --live flag is assumed and the guest
2650 domain must be active. In this situation it is up to the
2651 hypervisor whether the --config flag is also assumed, and therefore
2652 whether the XML configuration is adjusted to make the change
2653 persistent.
2654 If --guest is specified, then the count of cpus is modified in the
2656 guest instead of the hypervisor. This flag is usable only for live
2657 domains and may require guest agent to be configured in the guest.
2658 To allow adding vcpus to persistent definitions that can be later
2660 hotunplugged after the domain is booted it is necessary to specify
2661 the --hotpluggable flag. Vcpus added to live domains supporting
2662 vcpu unplug are automatically marked as hotpluggable.
2663 The --maximum flag controls the maximum number of virtual cpus that
2665 can be hot-plugged the next time the domain is booted. As such, it
2666 must only be used with the --config flag, and not with the --live
2667 or the --current flag. Note that it may not be possible to change
2668 the maximum vcpu count if the processor topology is specified for
2669 the guest.
2670 setvcpu domain vcpulist [--enable] | [--disable] [[--live] [--config] |
2672 [--current]]
2673 Change state of individual vCPUs using hot(un)plug mechanism.
2674 See vcpupin for information on format of vcpulist. Hypervisor
2676 drivers may require that vcpulist contains exactly vCPUs belonging
2677 to one hotpluggable entity. This is usually just a single vCPU but
2678 certain architectures such as ppc64 require a full core to be
2679 specified at once.
2680 Note that hypervisors may refuse to disable certain vcpus such as
2682 vcpu 0 or others.
2683 If --live is specified, affect a running domain. If --config is
2685 specified, affect the next startup of a persistent domain. If
2686 --current is specified, affect the current domain state. This is
2687 the default. Both --live and --config flags may be given, but
2688 --current is exclusive.
2689 shutdown domain [--mode MODE-LIST]
2691 Gracefully shuts down a domain. This coordinates with the domain
2692 OS to perform graceful shutdown, so there is no guarantee that it
2693 will succeed, and may take a variable length of time depending on
2694 what services must be shutdown in the domain.
2695 The exact behavior of a domain when it shuts down is set by the
2697 on_poweroff parameter in the domain's XML definition.
2698 If domain is transient, then the metadata of any snapshots and
2700 checkpoints will be lost once the guest stops running, but the
2701 underlying contents still exist, and a new domain with the same
2702 name and UUID can restore the snapshot metadata with snapshot-
2703 create, and the checkpoint metadata with checkpoint-create.
2704 By default the hypervisor will try to pick a suitable shutdown
2706 method. To specify an alternative method, the --mode parameter can
2707 specify a comma separated list which includes "acpi", "agent",
2708 "initctl", "signal" and "paravirt". The order in which drivers will
2709 try each mode is undefined, and not related to the order specified
2710 to virsh. For strict control over ordering, use a single mode at a
2711 time and repeat the command.
2712 start domain-name-or-uuid [--console] [--paused] [--autodestroy]
2714 [--bypass-cache] [--force-boot] [--pass-fds N,M,...]
2715 Start a (previously defined) inactive domain, either from the last
2716 managedsave state, or via a fresh boot if no managedsave state is
2717 present. The domain will be paused if the --paused option is used
2718 and supported by the driver; otherwise it will be running. If
2719 --console is requested, attach to the console after creation. If
2720 --autodestroy is requested, then the guest will be automatically
2721 destroyed when virsh closes its connection to libvirt, or otherwise
2722 exits. If --bypass-cache is specified, and managedsave state
2723 exists, the restore will avoid the file system cache, although this
2724 may slow down the operation. If --force-boot is specified, then
2725 any managedsave state is discarded and a fresh boot occurs.
2726 If --pass-fds is specified, the argument is a comma separated list
2728 of open file descriptors which should be pass on into the guest.
2729 The file descriptors will be re-numbered in the guest, starting
2730 from 3. This is only supported with container based virtualization.
2731 suspend domain
2733 Suspend a running domain. It is kept in memory but won't be
2734 scheduled anymore.
2735 resume domain
2737 Moves a domain out of the suspended state. This will allow a
2738 previously suspended domain to now be eligible for scheduling by
2739 the underlying hypervisor.
2740 dompmsuspend domain target [--duration]
2742 Suspend a running domain into one of these states (possible target
2743 values):
2744 mem equivalent of S3 ACPI state
2745 disk equivalent of S4 ACPI state
2746 hybrid RAM is saved to disk but not powered off
2747 The --duration argument specifies number of seconds before the
2749 domain is woken up after it was suspended (see also dompmwakeup).
2750 Default is 0 for unlimited suspend time. (This feature isn't
2751 currently supported by any hypervisor driver and 0 should be
2752 used.).
2753 Note that this command requires a guest agent configured and
2755 running in the domain's guest OS.
2756 Beware that at least for QEMU, the domain's process will be
2758 terminated when target disk is used and a new process will be
2759 launched when libvirt is asked to wake up the domain. As a result
2760 of this, any runtime changes, such as device hotplug or memory
2761 settings, are lost unless such changes were made with --config
2762 flag.
2763 dompmwakeup domain
2765 Wakeup a domain from pmsuspended state (either suspended by
2766 dompmsuspend or from the guest itself). Injects a wakeup into the
2767 guest that is in pmsuspended state, rather than waiting for the
2768 previously requested duration (if any) to elapse. This operation
2769 doesn't not necessarily fail if the domain is running.
2770 ttyconsole domain
2772 Output the device used for the TTY console of the domain. If the
2773 information is not available the processes will provide an exit
2774 code of 1.
2775 undefine domain [--managed-save] [--snapshots-metadata]
2777 [--checkpoints-metadata] [--nvram] [--keep-nvram] [ {--storage volumes
2778 | --remove-all-storage [--delete-storage-volume-snapshots]}
2779 --wipe-storage]
2780 Undefine a domain. If the domain is running, this converts it to a
2781 transient domain, without stopping it. If the domain is inactive,
2782 the domain configuration is removed.
2783 The --managed-save flag guarantees that any managed save image (see
2785 the managedsave command) is also cleaned up. Without the flag,
2786 attempts to undefine a domain with a managed save image will fail.
2787 The --snapshots-metadata flag guarantees that any snapshots (see
2789 the snapshot-list command) are also cleaned up when undefining an
2790 inactive domain. Without the flag, attempts to undefine an
2791 inactive domain with snapshot metadata will fail. If the domain is
2792 active, this flag is ignored.
2793 The --checkpoints-metadata flag guarantees that any checkpoints
2795 (see the checkpoint-list command) are also cleaned up when
2796 undefining an inactive domain. Without the flag, attempts to
2797 undefine an inactive domain with checkpoint metadata will fail. If
2798 the domain is active, this flag is ignored.
2799 --nvram and --keep-nvram specify accordingly to delete or keep
2801 nvram (/domain/os/nvram/) file. If the domain has an nvram file and
2802 the flags are omitted, the undefine will fail.
2803 The --storage flag takes a parameter volumes, which is a comma
2805 separated list of volume target names or source paths of storage
2806 volumes to be removed along with the undefined domain. Volumes can
2807 be undefined and thus removed only on inactive domains. Volume
2808 deletion is only attempted after the domain is undefined; if not
2809 all of the requested volumes could be deleted, the error message
2810 indicates what still remains behind. If a volume path is not found
2811 in the domain definition, it's treated as if the volume was
2812 successfully deleted. Only volumes managed by libvirt in storage
2813 pools can be removed this way. (See domblklist for list of target
2814 names associated to a domain). Example: --storage
2815 vda,/path/to/storage.img
2816 The --remove-all-storage flag specifies that all of the domain's
2818 storage volumes should be deleted.
2819 The --delete-storage-volume-snapshots (previously
2821 --delete-snapshots) flag specifies that any snapshots associated
2822 with the storage volume should be deleted as well. Requires the
2823 --remove-all-storage flag to be provided. Not all storage drivers
2824 support this option, presently only rbd. Using this when also
2825 removing volumes handled by a storage driver which does not support
2826 the flag will result in failure.
2827 The flag --wipe-storage specifies that the storage volumes should
2829 be wiped before removal.
2830 NOTE: For an inactive domain, the domain name or UUID must be used
2832 as the domain.
2833 vcpucount domain [{--maximum | --active} {--config | --live |
2835 --current}] [--guest]
2836 Print information about the virtual cpu counts of the given domain.
2837 If no flags are specified, all possible counts are listed in a
2838 table; otherwise, the output is limited to just the numeric value
2839 requested. For historical reasons, the table lists the label
2840 "current" on the rows that can be queried in isolation via the
2841 --active flag, rather than relating to the --current flag.
2842 --maximum requests information on the maximum cap of vcpus that a
2844 domain can add via setvcpus, while --active shows the current
2845 usage; these two flags cannot both be specified. --config requires
2846 a persistent domain and requests information regarding the next
2847 time the domain will be booted, --live requires a running domain
2848 and lists current values, and --current queries according to the
2849 current state of the domain (corresponding to --live if running, or
2850 --config if inactive); these three flags are mutually exclusive.
2851 If --guest is specified, then the count of cpus is reported from
2853 the perspective of the guest. This flag is usable only for live
2854 domains and may require guest agent to be configured in the guest.
2855 vcpuinfo domain [--pretty]
2857 Returns basic information about the domain virtual CPUs, like the
2858 number of vCPUs, the running time, the affinity to physical
2859 processors.
2860 With --pretty, cpu affinities are shown as ranges.
2862 An example output is
2864 $ virsh vcpuinfo fedora
2866 VCPU: 0
2867 CPU: 0
2868 State: running
2869 CPU time: 7,0s
2870 CPU Affinity: yyyy
2871 VCPU: 1
2873 CPU: 1
2874 State: running
2875 CPU time: 0,7s
2876 CPU Affinity: yyyy
2877 STATES
2879 The State field displays the current operating state of a virtual
2881 CPU
2882 offline
2884 The virtual CPU is offline and not usable by the domain. This
2885 state is not supported by all hypervisors.
2886 running
2888 The virtual CPU is available to the domain and is operating.
2889 blocked
2891 The virtual CPU is available to the domain but is waiting for a
2892 resource. This state is not supported by all hypervisors, in
2893 which case running may be reported instead.
2894 no state
2896 The virtual CPU state could not be determined. This could
2897 happen if the hypervisor is newer than virsh.
2898 N/A There's no information about the virtual CPU state available.
2900 This can be the case if the domain is not running or the
2901 hypervisor does not report the virtual CPU state.
2902 vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]]
2904 Query or change the pinning of domain VCPUs to host physical CPUs.
2905 To pin a single vcpu, specify cpulist; otherwise, you can query one
2906 vcpu or omit vcpu to list all at once.
2907 cpulist is a list of physical CPU numbers. Its syntax is a comma
2909 separated list and a special markup using '-' and '^' (ex. '0-4',
2910 '0-3,^2') can also be allowed. The '-' denotes the range and the
2911 '^' denotes exclusive. For pinning the vcpu to all physical cpus
2912 specify 'r' as a cpulist. If --live is specified, affect a running
2913 guest. If --config is specified, affect the next boot of a
2914 persistent guest. If --current is specified, affect the current
2915 guest state. Both --live and --config flags may be given if
2916 cpulist is present, but --current is exclusive. If no flag is
2917 specified, behavior is different depending on hypervisor.
2918 Note: The expression is sequentially evaluated, so "0-15,^8" is
2920 identical to "9-14,0-7,15" but not identical to "^8,0-15".
2921 emulatorpin domain [cpulist] [[--live] [--config] | [--current]]
2923 Query or change the pinning of domain's emulator threads to host
2924 physical CPUs.
2925 See vcpupin for cpulist.
2927 If --live is specified, affect a running guest. If --config is
2929 specified, affect the next boot of a persistent guest. If
2930 --current is specified, affect the current guest state. Both
2931 --live and --config flags may be given if cpulist is present, but
2932 --current is exclusive. If no flag is specified, behavior is
2933 different depending on hypervisor.
2934 guestvcpus domain [[--enable] | [--disable]] [cpulist]
2936 Query or change state of vCPUs from guest's point of view using the
2937 guest agent. When invoked without cpulist the guest is queried for
2938 available guest vCPUs, their state and possibility to be offlined.
2939 If cpulist is provided then one of --enable or --disable must be
2941 provided too. The desired operation is then executed on the domain.
2942 See vcpupin for information on cpulist.
2944 vncdisplay domain
2946 Output the IP address and port number for the VNC display. If the
2947 information is not available the processes will provide an exit
2948 code of 1.
2949
2951 The following commands manipulate devices associated to domains. The
2952 domain can be specified as a short integer, a name or a full UUID. To
2953 better understand the values allowed as options for the command reading
2954 the documentation at <https://libvirt.org/formatdomain.html> on the
2955 format of the device sections to get the most accurate set of accepted
2956 values.
2957 attach-device domain FILE [[[--live] [--config] | [--current]] |
2959 [--persistent]]
2960 Attach a device to the domain, using a device definition in an XML
2961 file using a device definition element such as <disk> or
2962 <interface> as the top-level element. See the documentation at
2963 <https://libvirt.org/formatdomain.html#elementsDevices> to learn
2964 about libvirt XML format for a device. If --config is specified
2965 the command alters the persistent domain configuration with the
2966 device attach taking effect the next time libvirt starts the
2967 domain. For cdrom and floppy devices, this command only replaces
2968 the media within an existing device; consider using update-device
2969 for this usage. For passthrough host devices, see also nodedev-
2970 detach, needed if the PCI device does not use managed mode.
2971 If --live is specified, affect a running domain. If --config is
2973 specified, affect the next startup of a persistent domain. If
2974 --current is specified, affect the current domain state. Both
2975 --live and --config flags may be given, but --current is exclusive.
2976 When no flag is specified legacy API is used whose behavior depends
2977 on the hypervisor driver.
2978 For compatibility purposes, --persistent behaves like --config for
2980 an offline domain, and like --live --config for a running domain.
2981 Note: using of partial device definition XML files may lead to
2983 unexpected results as some fields may be autogenerated and thus
2984 match devices other than expected.
2985 attach-disk domain source target [[[--live] [--config] | [--current]] |
2987 [--persistent]] [--targetbus bus] [--driver driver] [--subdriver
2988 subdriver] [--iothread iothread] [--cache cache] [--io io] [--type
2989 type] [--alias alias] [--mode mode] [--sourcetype sourcetype] [--serial
2990 serial] [--wwn wwn] [--rawio] [--address address] [--multifunction]
2991 [--print-xml]
2992 Attach a new disk device to the domain. source is path for the
2993 files and devices. target controls the bus or device under which
2994 the disk is exposed to the guest OS. It indicates the "logical"
2995 device name; the optional targetbus attribute specifies the type of
2996 disk device to emulate; possible values are driver specific, with
2997 typical values being ide, scsi, virtio, xen, usb, sata, or sd, if
2998 omitted, the bus type is inferred from the style of the device name
2999 (e.g. a device named 'sda' will typically be exported using a SCSI
3000 bus). driver can be file, tap or phy for the Xen hypervisor
3001 depending on the kind of access; or qemu for the QEMU emulator.
3002 Further details to the driver can be passed using subdriver. For
3003 Xen subdriver can be aio, while for QEMU subdriver should match the
3004 format of the disk source, such as raw or qcow2. Hypervisor
3005 default will be used if subdriver is not specified. However, the
3006 default may not be correct, esp. for QEMU as for security reasons
3007 it is configured not to detect disk formats. type can indicate
3008 lun, cdrom or floppy as alternative to the disk default, although
3009 this use only replaces the media within the existing virtual cdrom
3010 or floppy device; consider using update-device for this usage
3011 instead. alias can set user supplied alias. mode can specify the
3012 two specific mode readonly or shareable. sourcetype can indicate
3013 the type of source (block|file) cache can be one of "default",
3014 "none", "writethrough", "writeback", "directsync" or "unsafe". io
3015 controls specific policies on I/O; QEMU guests support "threads"
3016 and "native". iothread is the number within the range of domain
3017 IOThreads to which this disk may be attached (QEMU only). serial
3018 is the serial of disk device. wwn is the wwn of disk device. rawio
3019 indicates the disk needs rawio capability. address is the address
3020 of disk device in the form of pci:domain.bus.slot.function,
3021 scsi:controller.bus.unit, ide:controller.bus.unit, usb:bus.port,
3022 sata:controller.bus.unit or ccw:cssid.ssid.devno. Virtio-ccw
3023 devices must have their cssid set to 0xfe. multifunction indicates
3024 specified pci address is a multifunction pci device address.
3025 If --print-xml is specified, then the XML of the disk that would be
3027 attached is printed instead.
3028 If --live is specified, affect a running domain. If --config is
3030 specified, affect the next startup of a persistent domain. If
3031 --current is specified, affect the current domain state. Both
3032 --live and --config flags may be given, but --current is exclusive.
3033 When no flag is specified legacy API is used whose behavior depends
3034 on the hypervisor driver.
3035 For compatibility purposes, --persistent behaves like --config for
3037 an offline domain, and like --live --config for a running domain.
3038 Likewise, --shareable is an alias for --mode shareable.
3039 attach-interface domain type source [[[--live] [--config] |
3041 [--current]] | [--persistent]] [--target target] [--mac mac] [--script
3042 script] [--model model] [--inbound average,peak,burst,floor]
3043 [--outbound average,peak,burst] [--alias alias] [--managed]
3044 [--print-xml]
3045 Attach a new network interface to the domain.
3046 type can be one of the:
3048 network to indicate connection via a libvirt virtual network,
3050 bridge to indicate connection via a bridge device on the host,
3052 direct to indicate connection directly to one of the host's
3054 network interfaces or bridges,
3055 hostdev to indicate connection using a passthrough of PCI
3057 device on the host.
3058 source indicates the source of the connection. The source depends
3060 on the type of the interface:
3061 network name of the virtual network,
3063 bridge the name of the bridge device,
3065 direct the name of the host's interface or bridge,
3067 hostdev the PCI address of the host's interface formatted as
3069 domain:bus:slot.function.
3070 --target is used to specify the tap/macvtap device to be used to
3072 connect the domain to the source. Names starting with 'vnet' are
3073 considered as auto-generated and are blanked out/regenerated each
3074 time the interface is attached.
3075 --mac specifies the MAC address of the network interface; if a MAC
3077 address is not given, a new address will be automatically generated
3078 (and stored in the persistent configuration if "--config" is given
3079 on the command line).
3080 --script is used to specify a path to a custom script to be called
3082 while attaching to a bridge - this will be called instead of the
3083 default script not in addition to it. This is valid only for
3084 interfaces of bridge type and only for Xen domains.
3085 --model specifies the network device model to be presented to the
3087 domain.
3088 alias can set user supplied alias.
3090 --inbound and --outbound control the bandwidth of the interface.
3092 At least one from the average, floor pair must be specified. The
3093 other two peak and burst are optional, so "average,peak",
3094 "average,,burst", "average,,,floor", "average" and ",,,floor" are
3095 also legal. Values for average, floor and peak are expressed in
3096 kilobytes per second, while burst is expressed in kilobytes in a
3097 single burst at peak speed as described in the Network XML
3098 documentation at
3099 <https://libvirt.org/formatnetwork.html#elementQoS>.
3100 --managed is usable only for hostdev type and tells libvirt that
3102 the interface should be managed, which means detached and
3103 reattached from/to the host by libvirt.
3104 If --print-xml is specified, then the XML of the interface that
3106 would be attached is printed instead.
3107 If --live is specified, affect a running domain. If --config is
3109 specified, affect the next startup of a persistent domain. If
3110 --current is specified, affect the current domain state. Both
3111 --live and --config flags may be given, but --current is exclusive.
3112 When no flag is specified legacy API is used whose behavior depends
3113 on the hypervisor driver.
3114 For compatibility purposes, --persistent behaves like --config for
3116 an offline domain, and like --live --config for a running domain.
3117 Note: the optional target value is the name of a device to be
3119 created as the back-end on the node. If not provided a device
3120 named "vnetN" or "vifN" will be created automatically.
3121 detach-device domain FILE [[[--live] [--config] | [--current]] |
3123 [--persistent]]
3124 Detach a device from the domain, takes the same kind of XML
3125 descriptions as command attach-device. For passthrough host
3126 devices, see also nodedev-reattach, needed if the device does not
3127 use managed mode.
3128 Note: The supplied XML description of the device should be as
3130 specific as its definition in the domain XML. The set of attributes
3131 used to match the device are internal to the drivers. Using a
3132 partial definition, or attempting to detach a device that is not
3133 present in the domain XML, but shares some specific attributes with
3134 one that is present, may lead to unexpected results.
3135 Quirk: Device unplug is asynchronous in most cases and requires
3137 guest cooperation. This means that it's up to the discretion of the
3138 guest to disallow or delay the unplug arbitrarily. As the libvirt
3139 API used in this command was designed as synchronous it returns
3140 success after some timeout even if the device was not unplugged yet
3141 to allow further interactions with the domain e.g. if the guest is
3142 unresponsive. Callers which need to make sure that the device was
3143 unplugged can use libvirt events (see virsh event) to be notified
3144 when the device is removed. Note that the event may arrive before
3145 the command returns.
3146 If --live is specified, affect a running domain. If --config is
3148 specified, affect the next startup of a persistent domain. If
3149 --current is specified, affect the current domain state. Both
3150 --live and --config flags may be given, but --current is exclusive.
3151 When no flag is specified legacy API is used whose behavior depends
3152 on the hypervisor driver.
3153 For compatibility purposes, --persistent behaves like --config for
3155 an offline domain, and like --live --config for a running domain.
3156 Note that older versions of virsh used --config as an alias for
3158 --persistent.
3159 detach-device-alias domain alias [[[--live] [--config] | [--current]]]]
3161 Detach a device with given alias from the domain. This command
3162 returns successfully after the unplug request was sent to the
3163 hypervisor. The actual removal of the device is notified
3164 asynchronously via libvirt events (see virsh event).
3165 If --live is specified, affect a running domain. If --config is
3167 specified, affect the next startup of a persistent domain. If
3168 --current is specified, affect the current domain state. Both
3169 --live and --config flags may be given, but --current is exclusive.
3170 detach-disk domain target [[[--live] [--config] | [--current]] |
3172 [--persistent]] [--print-xml]
3173 Detach a disk device from a domain. The target is the device as
3174 seen from the domain.
3175 If --live is specified, affect a running domain. If --config is
3177 specified, affect the next startup of a persistent domain. If
3178 --current is specified, affect the current domain state. Both
3179 --live and --config flags may be given, but --current is exclusive.
3180 When no flag is specified legacy API is used whose behavior depends
3181 on the hypervisor driver.
3182 For compatibility purposes, --persistent behaves like --config for
3184 an offline domain, and like --live --config for a running domain.
3185 Note that older versions of virsh used --config as an alias for
3187 --persistent.
3188 If --print-xml is specified, then the XML which would be used to
3190 detach the disk is printed instead.
3191 Please see documentation for detach-device for known quirks.
3193 detach-interface domain type [--mac mac] [[[--live] [--config] |
3195 [--current]] | [--persistent]]
3196 Detach a network interface from a domain. type can be either
3197 network to indicate a physical network device or bridge to indicate
3198 a bridge to a device. It is recommended to use the mac option to
3199 distinguish between the interfaces if more than one are present on
3200 the domain.
3201 If --live is specified, affect a running domain. If --config is
3203 specified, affect the next startup of a persistent domain. If
3204 --current is specified, affect the current domain state. Both
3205 --live and --config flags may be given, but --current is exclusive.
3206 When no flag is specified legacy API is used whose behavior depends
3207 on the hypervisor driver.
3208 For compatibility purposes, --persistent behaves like --config for
3210 an offline domain, and like --live --config for a running domain.
3211 Note that older versions of virsh used --config as an alias for
3213 --persistent.
3214 Please see documentation for detach-device for known quirks.
3216 update-device domain file [--force] [[[--live] [--config] |
3218 [--current]] | [--persistent]]
3219 Update the characteristics of a device associated with domain,
3220 based on the device definition in an XML file. The --force option
3221 can be used to force device update, e.g., to eject a CD-ROM even if
3222 it is locked/mounted in the domain. See the documentation at
3223 <https://libvirt.org/formatdomain.html#elementsDevices> to learn
3224 about libvirt XML format for a device.
3225 If --live is specified, affect a running domain. If --config is
3227 specified, affect the next startup of a persistent domain. If
3228 --current is specified, affect the current domain state. Both
3229 --live and --config flags may be given, but --current is exclusive.
3230 Not specifying any flag is the same as specifying --current.
3231 For compatibility purposes, --persistent behaves like --config for
3233 an offline domain, and like --live --config for a running domain.
3234 Note that older versions of virsh used --config as an alias for
3236 --persistent.
3237 Note: using of partial device definition XML files may lead to
3239 unexpected results as some fields may be autogenerated and thus
3240 match devices other than expected.
3241 change-media domain path [--eject] [--insert] [--update] [source]
3243 [--force] [[--live] [--config] | [--current]] [--print-xml] [--block]
3244 Change media of CDROM or floppy drive. path can be the fully-
3245 qualified path or the unique target name (<target dev='hdc'>) of
3246 the disk device. source specifies the path of the media to be
3247 inserted or updated. The --block flag allows setting the backing
3248 type in case a block device is used as media for the CDROM or
3249 floppy drive instead of a file.
3250 --eject indicates the media will be ejected. --insert indicates
3252 the media will be inserted. source must be specified. If the
3253 device has source (e.g. <source file='media'>), and source is not
3254 specified, --update is equal to --eject. If the device has no
3255 source, and source is specified, --update is equal to --insert. If
3256 the device has source, and source is specified, --update behaves
3257 like combination of --eject and --insert. If none of --eject,
3258 --insert, and --update is specified, --update is used by default.
3259 The --force option can be used to force media changing. If --live
3260 is specified, alter live configuration of running guest. If
3261 --config is specified, alter persistent configuration, effect
3262 observed on next boot. --current can be either or both of live and
3263 config, depends on the hypervisor's implementation. Both --live
3264 and --config flags may be given, but --current is exclusive. If no
3265 flag is specified, behavior is different depending on hypervisor.
3266 If --print-xml is specified, the XML that would be used to change
3267 media is printed instead of changing the media.
3268
3270 The following commands manipulate host devices that are intended to be
3271 passed through to guest domains via <hostdev> elements in a domain's
3272 <devices> section. A node device key is generally specified by the bus
3273 name followed by its address, using underscores between all components,
3274 such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
3275 The nodedev-list gives the full list of host devices that are known to
3276 libvirt, although this includes devices that cannot be assigned to a
3277 guest (for example, attempting to detach the PCI device that controls
3278 the host's hard disk controller where the guest's disk images live
3279 could cause the host system to lock up or reboot).
3280 For more information on node device definition see:
3282 <https://libvirt.org/formatnode.html>.
3283 Passthrough devices cannot be simultaneously used by the host and its
3285 guest domains, nor by multiple active guests at once. If the <hostdev>
3286 description of a PCI device includes the attribute managed='yes', and
3287 the hypervisor driver supports it, then the device is in managed mode,
3288 and attempts to use that passthrough device in an active guest will
3289 automatically behave as if nodedev-detach (guest start, device hot-
3290 plug) and nodedev-reattach (guest stop, device hot-unplug) were called
3291 at the right points. If a PCI device is not marked as managed, then it
3292 must manually be detached before guests can use it, and manually
3293 reattached to be returned to the host. Also, if a device is manually
3294 detached, then the host does not regain control of the device without a
3295 matching reattach, even if the guests use the device in managed mode.
3296 nodedev-create FILE
3298 Create a device on the host node that can then be assigned to
3299 virtual machines. Normally, libvirt is able to automatically
3300 determine which host nodes are available for use, but this allows
3301 registration of host hardware that libvirt did not automatically
3302 detect. file contains xml for a top-level <device> description of
3303 a node device.
3304 nodedev-destroy device
3306 Destroy (stop) a device on the host. device can be either device
3307 name or wwn pair in "wwnn,wwpn" format (only works for vHBA
3308 currently). Note that this makes libvirt quit managing a host
3309 device, and may even make that device unusable by the rest of the
3310 physical host until a reboot.
3311 nodedev-detach nodedev [--driver backend_driver]
3313 Detach nodedev from the host, so that it can safely be used by
3314 guests via <hostdev> passthrough. This is reversed with nodedev-
3315 reattach, and is done automatically for managed devices.
3316 Different backend drivers expect the device to be bound to
3318 different dummy devices. For example, QEMU's "kvm" backend driver
3319 (the default) expects the device to be bound to pci-stub, but its
3320 "vfio" backend driver expects the device to be bound to vfio-pci.
3321 The --driver parameter can be used to specify the desired backend
3322 driver.
3323 nodedev-dumpxml device
3325 Dump a <device> XML representation for the given node device,
3326 including such information as the device name, which bus owns the
3327 device, the vendor and product id, and any capabilities of the
3328 device usable by libvirt (such as whether device reset is
3329 supported). device can be either device name or wwn pair in
3330 "wwnn,wwpn" format (only works for HBA).
3331 nodedev-list cap --tree
3333 List all of the devices available on the node that are known by
3334 libvirt. cap is used to filter the list by capability types, the
3335 types must be separated by comma, e.g. --cap pci,scsi. Valid
3336 capability types include 'system', 'pci', 'usb_device', 'usb',
3337 'net', 'scsi_host', 'scsi_target', 'scsi', 'storage', 'fc_host',
3338 'vports', 'scsi_generic', 'drm', 'mdev', 'mdev_types', 'ccw'. If
3339 --tree is used, the output is formatted in a tree representing
3340 parents of each node. cap and --tree are mutually exclusive.
3341 nodedev-reattach nodedev
3343 Declare that nodedev is no longer in use by any guests, and that
3344 the host can resume normal use of the device. This is done
3345 automatically for PCI devices in managed mode and USB devices, but
3346 must be done explicitly to match any explicit nodedev-detach.
3347 nodedev-reset nodedev
3349 Trigger a device reset for nodedev, useful prior to transferring a
3350 node device between guest passthrough or the host. Libvirt will
3351 often do this action implicitly when required, but this command
3352 allows an explicit reset when needed.
3353 nodedev-event {[nodedev] event [--loop] [--timeout seconds]
3355 [--timestamp] | --list}
3356 Wait for a class of node device events to occur, and print
3357 appropriate details of events as they happen. The events can
3358 optionally be filtered by nodedev. Using --list as the only
3359 argument will provide a list of possible event values known by this
3360 client, although the connection might not allow registering for all
3361 these events.
3362 By default, this command is one-shot, and returns success once an
3364 event occurs; you can send SIGINT (usually via "Ctrl-C") to quit
3365 immediately. If --timeout is specified, the command gives up
3366 waiting for events after seconds have elapsed. With --loop, the
3367 command prints all events until a timeout or interrupt key.
3368 When --timestamp is used, a human-readable timestamp will be
3370 printed before the event.
3371
3373 The following commands manipulate networks. Libvirt has the capability
3374 to define virtual networks which can then be used by domains and linked
3375 to actual network devices. For more detailed information about this
3376 feature see the documentation at
3377 <https://libvirt.org/formatnetwork.html> . Many of the commands for
3378 virtual networks are similar to the ones used for domains, but the way
3379 to name a virtual network is either by its name or UUID.
3380 net-autostart network [--disable]
3382 Configure a virtual network to be automatically started at boot.
3383 The --disable option disable autostarting.
3384 net-create file
3386 Create a transient (temporary) virtual network from an XML file and
3387 instantiate (start) the network. See the documentation at
3388 <https://libvirt.org/formatnetwork.html> to get a description of
3389 the XML network format used by libvirt.
3390 net-define file
3392 Define an inactive persistent virtual network or modify an existing
3393 persistent one from the XML file.
3394 net-destroy network
3396 Destroy (stop) a given transient or persistent virtual network
3397 specified by its name or UUID. This takes effect immediately.
3398 net-dumpxml network [--inactive]
3400 Output the virtual network information as an XML dump to stdout.
3401 If --inactive is specified, then physical functions are not
3402 expanded into their associated virtual functions.
3403 net-edit network
3405 Edit the XML configuration file for a network.
3406 This is equivalent to:
3408 virsh net-dumpxml --inactive network > network.xml
3410 vi network.xml (or make changes with your other text editor)
3411 virsh net-define network.xml
3412 except that it does some error checking.
3414 The editor used can be supplied by the $VISUAL or $EDITOR
3416 environment variables, and defaults to "vi".
3417 net-event {[network] event [--loop] [--timeout seconds] [--timestamp] |
3419 --list}
3420 Wait for a class of network events to occur, and print appropriate
3421 details of events as they happen. The events can optionally be
3422 filtered by network. Using --list as the only argument will
3423 provide a list of possible event values known by this client,
3424 although the connection might not allow registering for all these
3425 events.
3426 By default, this command is one-shot, and returns success once an
3428 event occurs; you can send SIGINT (usually via "Ctrl-C") to quit
3429 immediately. If --timeout is specified, the command gives up
3430 waiting for events after seconds have elapsed. With --loop, the
3431 command prints all events until a timeout or interrupt key.
3432 When --timestamp is used, a human-readable timestamp will be
3434 printed before the event.
3435 net-info network
3437 Returns basic information about the network object.
3438 net-list [--inactive | --all] { [--table] | --name | --uuid }
3440 [--persistent] [<--transient>] [--autostart] [<--no-autostart>]
3441 Returns the list of active networks, if --all is specified this
3442 will also include defined but inactive networks, if --inactive is
3443 specified only the inactive ones will be listed. You may also want
3444 to filter the returned networks by --persistent to list the
3445 persistent ones, --transient to list the transient ones,
3446 --autostart to list the ones with autostart enabled, and
3447 --no-autostart to list the ones with autostart disabled.
3448 If --name is specified, network names are printed instead of the
3450 table formatted one per line. If --uuid is specified network's
3451 UUID's are printed instead of names. Flag --table specifies that
3452 the legacy table-formatted output should be used. This is the
3453 default. All of these are mutually exclusive.
3454 NOTE: When talking to older servers, this command is forced to use
3456 a series of API calls with an inherent race, where a pool might not
3457 be listed or might appear more than once if it changed state
3458 between calls while the list was being collected. Newer servers do
3459 not have this problem.
3460 net-name network-UUID
3462 Convert a network UUID to network name.
3463 net-start network
3465 Start a (previously defined) inactive network.
3466 net-undefine network
3468 Undefine the configuration for a persistent network. If the network
3469 is active, make it transient.
3470 net-uuid network-name
3472 Convert a network name to network UUID.
3473 net-update network command section xml [--parent-index index] [[--live]
3475 [--config] | [--current]]
3476 Update the given section of an existing network definition, with
3477 the changes optionally taking effect immediately, without needing
3478 to destroy and re-start the network.
3479 command is one of "add-first", "add-last", "add" (a synonym for
3481 add-last), "delete", or "modify".
3482 section is one of "bridge", "domain", "ip", "ip-dhcp-host", "ip-
3484 dhcp-range", "forward", "forward-interface", "forward-pf",
3485 "portgroup", "dns-host", "dns-txt", or "dns-srv", each section
3486 being named by a concatenation of the xml element hierarchy leading
3487 to the element being changed. For example, "ip-dhcp-host" will
3488 change a <host> element that is contained inside a <dhcp> element
3489 inside an <ip> element of the network.
3490 xml is either the text of a complete xml element of the type being
3492 changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or
3493 the name of a file that contains a complete xml element.
3494 Disambiguation is done by looking at the first character of the
3495 provided text - if the first character is "<", it is xml text, if
3496 the first character is not "<", it is the name of a file that
3497 contains the xml text to be used.
3498 The --parent-index option is used to specify which of several
3500 parent elements the requested element is in (0-based). For example,
3501 a dhcp <host> element could be in any one of multiple <ip> elements
3502 in the network; if a parent-index isn't provided, the "most
3503 appropriate" <ip> element will be selected (usually the only one
3504 that already has a <dhcp> element), but if --parent-index is given,
3505 that particular instance of <ip> will get the modification.
3506 If --live is specified, affect a running network. If --config is
3508 specified, affect the next startup of a persistent network. If
3509 --current is specified, affect the current network state. Both
3510 --live and --config flags may be given, but --current is exclusive.
3511 Not specifying any flag is the same as specifying --current.
3512 net-dhcp-leases network [mac]
3514 Get a list of dhcp leases for all network interfaces connected to
3515 the given virtual network or limited output just for one interface
3516 if mac is specified.
3517
3519 The following commands manipulate host interfaces. Often, these host
3520 interfaces can then be used by name within domain <interface> elements
3521 (such as a system-created bridge interface), but there is no
3522 requirement that host interfaces be tied to any particular guest
3523 configuration XML at all.
3524 Many of the commands for host interfaces are similar to the ones used
3526 for domains, and the way to name an interface is either by its name or
3527 its MAC address. However, using a MAC address for an iface argument
3528 only works when that address is unique (if an interface and a bridge
3529 share the same MAC address, which is often the case, then using that
3530 MAC address results in an error due to ambiguity, and you must resort
3531 to a name instead).
3532 iface-bridge interface bridge [--no-stp] [delay] [--no-start]
3534 Create a bridge device named bridge, and attach the existing
3535 network device interface to the new bridge. The new bridge
3536 defaults to starting immediately, with STP enabled and a delay of
3537 0; these settings can be altered with --no-stp, --no-start, and an
3538 integer number of seconds for delay. All IP address configuration
3539 of interface will be moved to the new bridge device.
3540 See also iface-unbridge for undoing this operation.
3542 iface-define file
3544 Define an inactive persistent physical host interface or modify an
3545 existing persistent one from the XML file.
3546 iface-destroy interface
3548 Destroy (stop) a given host interface, such as by running "if-down"
3549 to disable that interface from active use. This takes effect
3550 immediately.
3551 iface-dumpxml interface [--inactive]
3553 Output the host interface information as an XML dump to stdout. If
3554 --inactive is specified, then the output reflects the persistent
3555 state of the interface that will be used the next time it is
3556 started.
3557 iface-edit interface
3559 Edit the XML configuration file for a host interface.
3560 This is equivalent to:
3562 virsh iface-dumpxml iface > iface.xml
3564 vi iface.xml (or make changes with your other text editor)
3565 virsh iface-define iface.xml
3566 except that it does some error checking.
3568 The editor used can be supplied by the $VISUAL or $EDITOR
3570 environment variables, and defaults to "vi".
3571 iface-list [--inactive | --all]
3573 Returns the list of active host interfaces. If --all is specified
3574 this will also include defined but inactive interfaces. If
3575 --inactive is specified only the inactive ones will be listed.
3576 iface-name interface
3578 Convert a host interface MAC to interface name, if the MAC address
3579 is unique among the host's interfaces.
3580 interface specifies the interface MAC address.
3582 iface-mac interface
3584 Convert a host interface name to MAC address.
3585 interface specifies the interface name.
3587 iface-start interface
3589 Start a (previously defined) host interface, such as by running
3590 "if-up".
3591 iface-unbridge bridge [--no-start]
3593 Tear down a bridge device named bridge, releasing its underlying
3594 interface back to normal usage, and moving all IP address
3595 configuration from the bridge device to the underlying device. The
3596 underlying interface is restarted unless --no-start is present;
3597 this flag is present for symmetry, but generally not recommended.
3598 See also iface-bridge for creating a bridge.
3600 iface-undefine interface
3602 Undefine the configuration for an inactive host interface.
3603 iface-begin
3605 Create a snapshot of current host interface settings, which can
3606 later be committed (iface-commit) or restored (iface-rollback). If
3607 a snapshot already exists, then this command will fail until the
3608 previous snapshot has been committed or restored. Undefined
3609 behavior results if any external changes are made to host
3610 interfaces outside of the libvirt API between the beginning of a
3611 snapshot and its eventual commit or rollback.
3612 iface-commit
3614 Declare all changes since the last iface-begin as working, and
3615 delete the rollback point. If no interface snapshot has already
3616 been started, then this command will fail.
3617 iface-rollback
3619 Revert all host interface settings back to the state recorded in
3620 the last iface-begin. If no interface snapshot has already been
3621 started, then this command will fail. Rebooting the host also
3622 serves as an implicit rollback point.
3623
3625 The following commands manipulate storage pools. Libvirt has the
3626 capability to manage various storage solutions, including files, raw
3627 partitions, and domain-specific formats, used to provide the storage
3628 volumes visible as devices within virtual machines. For more detailed
3629 information about this feature, see the documentation at
3630 <https://libvirt.org/formatstorage.html> . Many of the commands for
3631 pools are similar to the ones used for domains.
3632 find-storage-pool-sources type [srcSpec]
3634 Returns XML describing all possible available storage pool sources
3635 that could be used to create or define a storage pool of a given
3636 type. If srcSpec is provided, it is a file that contains XML to
3637 further restrict the query for pools.
3638 Not all storage pools support discovery in this manner.
3640 Furthermore, for those that do support discovery, only specific XML
3641 elements are required in order to return valid data, while other
3642 elements and even attributes of some elements are ignored since
3643 they are not necessary to find the pool based on the search
3644 criteria. The following lists the supported type options and the
3645 expected minimal XML elements used to perform the search.
3646 For a "netfs" or "gluster" pool, the minimal expected XML required
3648 is the <host> element with a "name" attribute describing the IP
3649 address or hostname to be used to find the pool. The "port"
3650 attribute will be ignored as will any other provided XML elements
3651 in srcSpec.
3652 For a "logical" pool, the contents of the srcSpec file are ignored,
3654 although if provided the file must at least exist.
3655 For an "iscsi" pool, the minimal expect XML required is the <host>
3657 element with a "name" attribute describing the IP address or
3658 hostname to be used to find the pool (the iSCSI server address).
3659 Optionally, the "port" attribute may be provided, although it will
3660 default to 3260. Optionally, an <initiator> XML element with a
3661 "name" attribute may be provided to further restrict the iSCSI
3662 target search to a specific initiator for multi-iqn iSCSI storage
3663 pools.
3664 find-storage-pool-sources-as type [host] [port] [initiator]
3666 Rather than providing srcSpec XML file for find-storage-pool-
3667 sources use this command option in order to have virsh generate the
3668 query XML file using the optional arguments. The command will
3669 return the same output XML as find-storage-pool-sources.
3670 Use host to describe a specific host to use for networked storage,
3672 such as netfs, gluster, and iscsi type pools.
3673 Use port to further restrict which networked port to utilize for
3675 the connection if required by the specific storage backend, such as
3676 iscsi.
3677 Use initiator to further restrict the iscsi type pool searches to
3679 specific target initiators.
3680 pool-autostart pool-or-uuid [--disable]
3682 Configure whether pool should automatically start at boot.
3683 pool-build pool-or-uuid [--overwrite] [--no-overwrite]
3685 Build a given pool.
3686 Options --overwrite and --no-overwrite can only be used for pool-
3688 build a filesystem, disk, or logical pool.
3689 For a file system pool if neither flag is specified, then pool-
3691 build just makes the target path directory and no attempt to run
3692 mkfs on the target volume device. If --no-overwrite is specified,
3693 it probes to determine if a filesystem already exists on the target
3694 device, returning an error if one exists or using mkfs to format
3695 the target device if not. If --overwrite is specified, mkfs is
3696 always executed and any existing data on the target device is
3697 overwritten unconditionally.
3698 For a disk pool, if neither of them is specified or --no-overwrite
3700 is specified, pool-build will check the target volume device for
3701 existing filesystems or partitions before attempting to write a new
3702 label on the target volume device. If the target volume device
3703 already has a label, the command will fail. If --overwrite is
3704 specified, then no check will be made on the target volume device
3705 prior to writing a new label. Writing of the label uses the pool
3706 source format type or "dos" if not specified.
3707 For a logical pool, if neither of them is specified or
3709 --no-overwrite is specified, pool-build will check the target
3710 volume devices for existing filesystems or partitions before
3711 attempting to initialize and format each device for usage by the
3712 logical pool. If any target volume device already has a label, the
3713 command will fail. If --overwrite is specified, then no check will
3714 be made on the target volume devices prior to initializing and
3715 formatting each device. Once all the target volume devices are
3716 properly formatted via pvcreate, the volume group will be created
3717 using all the devices.
3718 pool-create file [--build] [[--overwrite] | [--no-overwrite]]
3720 Create and start a pool object from the XML file.
3721 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build
3723 after creation in order to remove the need for a follow-up command
3724 to build the pool. The --overwrite and --no-overwrite flags follow
3725 the same rules as pool-build. If just --build is provided, then
3726 pool-build is called with no flags.
3727 pool-create-as name type [--source-host hostname] [--source-path path]
3729 [--source-dev path] [--source-name name] [--target path]
3730 [--source-format format] [--auth-type authtype --auth-username username
3731 [--secret-usage usage | --secret-uuid uuid]] [--source-protocol-ver
3732 ver] [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn]
3733 [--adapter-parent parent | --adapter-parent-wwnn parent_wwnn adapter-
3734 parent-wwpn parent_wwpn | --adapter-parent-fabric-wwn
3735 parent_fabric_wwn]] [--build] [[--overwrite] | [--no-overwrite]]
3736 [--print-xml]
3737 Create and start a pool object name from the raw parameters. If
3738 --print-xml is specified, then print the XML of the pool object
3739 without creating the pool. Otherwise, the pool has the specified
3740 type. When using pool-create-as for a pool of type "disk", the
3741 existing partitions found on the --source-dev path will be used to
3742 populate the disk pool. Therefore, it is suggested to use pool-
3743 define-as and pool-build with the --overwrite in order to properly
3744 initialize the disk pool.
3745 [--source-host hostname] provides the source hostname for pools
3747 backed by storage from a remote server (pool types netfs, iscsi,
3748 rbd, sheepdog, gluster).
3749 [--source-path path] provides the source directory path for pools
3751 backed by directories (pool type dir).
3752 [--source-dev path] provides the source path for pools backed by
3754 physical devices (pool types fs, logical, disk, iscsi, zfs).
3755 [--source-name name] provides the source name for pools backed by
3757 storage from a named element (pool types logical, rbd, sheepdog,
3758 gluster).
3759 [--target path] is the path for the mapping of the storage pool
3761 into the host file system.
3762 [--source-format format] provides information about the format of
3764 the pool (pool types fs, netfs, disk, logical).
3765 [--auth-type authtype --auth-username username [--secret-usage
3767 usage | --secret-uuid uuid]] provides the elements required to
3768 generate authentication credentials for the storage pool. The
3769 authtype is either chap for iscsi type pools or ceph for rbd type
3770 pools. Either the secret usage or uuid value may be provided, but
3771 not both.
3772 [--source-protocol-ver ver] provides the NFS protocol version
3774 number used to contact the server's NFS service via nfs mount
3775 option 'nfsvers=n'. It is expect the ver value is an unsigned
3776 integer.
3777 [--adapter-name name] defines the scsi_hostN adapter name to be
3779 used for the scsi_host adapter type pool.
3780 [--adapter-wwnn wwnn --adapter-wwpn wwpn [--adapter-parent parent |
3782 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
3783 --adapter-parent-fabric-wwn parent_fabric_wwn]] defines the wwnn
3784 and wwpn to be used for the fc_host adapter type pool. Optionally
3785 provide the parent scsi_hostN node device to be used for the vHBA
3786 either by parent name, parent_wwnn and parent_wwpn, or
3787 parent_fabric_wwn. The parent name could change between reboots if
3788 the hardware environment changes, so providing the parent_wwnn and
3789 parent_wwpn ensure usage of the same physical HBA even if the
3790 scsi_hostN node device changes. Usage of the parent_fabric_wwn
3791 allows a bit more flexibility to choose an HBA on the same storage
3792 fabric in order to define the pool.
3793 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build
3795 after creation in order to remove the need for a follow-up command
3796 to build the pool. The --overwrite and --no-overwrite flags follow
3797 the same rules as pool-build. If just --build is provided, then
3798 pool-build is called with no flags.
3799 For a "logical" pool only [--name] needs to be provided. The
3801 [--source-name] if provided must match the Volume Group name. If
3802 not provided, one will be generated using the [--name]. If provided
3803 the [--target] is ignored and a target source is generated using
3804 the [--source-name] (or as generated from the [--name]).
3805 pool-define file
3807 Define an inactive persistent storage pool or modify an existing
3808 persistent one from the XML file.
3809 pool-define-as name type [--source-host hostname] [--source-path path]
3811 [--source-dev path] [--source-name name] [--target path]
3812 [--source-format format] [--auth-type authtype --auth-username username
3813 [--secret-usage usage | --secret-uuid uuid]] [--source-protocol-ver
3814 ver] [[--adapter-name name] | [--adapter-wwnn --adapter-wwpn]
3815 [--adapter-parent parent]] [--print-xml]
3816 Create, but do not start, a pool object name from the raw
3817 parameters. If --print-xml is specified, then print the XML of the
3818 pool object without defining the pool. Otherwise, the pool has the
3819 specified type.
3820 Use the same arguments as pool-create-as, except for the --build,
3822 --overwrite, and --no-overwrite options.
3823 pool-destroy pool-or-uuid
3825 Destroy (stop) a given pool object. Libvirt will no longer manage
3826 the storage described by the pool object, but the raw data
3827 contained in the pool is not changed, and can be later recovered
3828 with pool-create.
3829 pool-delete pool-or-uuid
3831 Destroy the resources used by a given pool object. This operation
3832 is non-recoverable. The pool object will still exist after this
3833 command, ready for the creation of new storage volumes.
3834 pool-dumpxml [--inactive] pool-or-uuid
3836 Returns the XML information about the pool object. --inactive
3837 tells virsh to dump pool configuration that will be used on next
3838 start of the pool as opposed to the current pool configuration.
3839 pool-edit pool-or-uuid
3841 Edit the XML configuration file for a storage pool.
3842 This is equivalent to:
3844 virsh pool-dumpxml pool > pool.xml
3846 vi pool.xml (or make changes with your other text editor)
3847 virsh pool-define pool.xml
3848 except that it does some error checking.
3850 The editor used can be supplied by the $VISUAL or $EDITOR
3852 environment variables, and defaults to "vi".
3853 pool-info [--bytes] pool-or-uuid
3855 Returns basic information about the pool object. If --bytes is
3856 specified the sizes of basic info are not converted to human
3857 friendly units.
3858 pool-list [--inactive] [--all] [--persistent] [--transient]
3860 [--autostart] [--no-autostart] [[--details] [--uuid] [--name] [<type>]
3861 List pool objects known to libvirt. By default, only active pools
3862 are listed; --inactive lists just the inactive pools, and --all
3863 lists all pools.
3864 In addition, there are several sets of filtering flags.
3866 --persistent is to list the persistent pools, --transient is to
3867 list the transient pools. --autostart lists the autostarting
3868 pools, --no-autostart lists the pools with autostarting disabled.
3869 If --uuid is specified only pool's UUIDs are printed. If --name is
3870 specified only pool's names are printed. If both --name and --uuid
3871 are specified, pool's UUID and names are printed side by side
3872 without any header. Option --details is mutually exclusive with
3873 options --uuid and --name.
3874 You may also want to list pools with specified types using type,
3876 the pool types must be separated by comma, e.g. --type dir,disk.
3877 The valid pool types include 'dir', 'fs', 'netfs', 'logical',
3878 'disk', 'iscsi', 'scsi', 'mpath', 'rbd', 'sheepdog', 'gluster',
3879 'zfs', 'vstorage' and 'iscsi-direct'.
3880 The --details option instructs virsh to additionally display pool
3882 persistence and capacity related information where available.
3883 NOTE: When talking to older servers, this command is forced to use
3885 a series of API calls with an inherent race, where a pool might not
3886 be listed or might appear more than once if it changed state
3887 between calls while the list was being collected. Newer servers do
3888 not have this problem.
3889 pool-name uuid
3891 Convert the uuid to a pool name.
3892 pool-refresh pool-or-uuid
3894 Refresh the list of volumes contained in pool.
3895 pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]
3897 Start the storage pool, which is previously defined but inactive.
3898 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build
3900 prior to pool-start to ensure the pool environment is in an
3901 expected state rather than needing to run the build command prior
3902 to startup. The --overwrite and --no-overwrite flags follow the
3903 same rules as pool-build. If just --build is provided, then pool-
3904 build is called with no flags.
3905 Note: A storage pool that relies on remote resources such as an
3907 "iscsi" or a (v)HBA backed "scsi" pool may need to be refreshed
3908 multiple times in order to have all the volumes detected (see pool-
3909 refresh). This is because the corresponding volume devices may not
3910 be present in the host's filesystem during the initial pool startup
3911 or the current refresh attempt. The number of refresh retries is
3912 dependent upon the network connection and the time the host takes
3913 to export the corresponding devices.
3914 pool-undefine pool-or-uuid
3916 Undefine the configuration for an inactive pool.
3917 pool-uuid pool
3919 Returns the UUID of the named pool.
3920 pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] |
3922 --list}
3923 Wait for a class of storage pool events to occur, and print
3924 appropriate details of events as they happen. The events can
3925 optionally be filtered by pool. Using --list as the only argument
3926 will provide a list of possible event values known by this client,
3927 although the connection might not allow registering for all these
3928 events.
3929 By default, this command is one-shot, and returns success once an
3931 event occurs; you can send SIGINT (usually via "Ctrl-C") to quit
3932 immediately. If --timeout is specified, the command gives up
3933 waiting for events after seconds have elapsed. With --loop, the
3934 command prints all events until a timeout or interrupt key.
3935 When --timestamp is used, a human-readable timestamp will be
3937 printed before the event.
3938
3940 vol-create pool-or-uuid FILE [--prealloc-metadata]
3941 Create a volume from an XML <file>.
3942 pool-or-uuid is the name or UUID of the storage pool to create the
3944 volume in.
3945 FILE is the XML <file> with the volume definition. An easy way to
3947 create the XML <file> is to use the vol-dumpxml command to obtain
3948 the definition of a pre-existing volume.
3949 [--prealloc-metadata] preallocate metadata (for qcow2 images which
3951 don't support full allocation). This option creates a sparse image
3952 file with metadata, resulting in higher performance compared to
3953 images with no preallocation and only slightly higher initial disk
3954 space usage.
3955 Example
3957 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
3959 vi newvolume.xml (or make changes with your other text editor)
3960 virsh vol-create differentstoragepool newvolume.xml
3961 vol-create-from pool-or-uuid FILE vol-name-or-key-or-path [--inputpool
3963 pool-or-uuid] [--prealloc-metadata] [--reflink]
3964 Create a volume, using another volume as input.
3965 pool-or-uuid is the name or UUID of the storage pool to create the
3967 volume in.
3968 FILE is the XML <file> with the volume definition.
3970 vol-name-or-key-or-path is the name or key or path of the source
3972 volume.
3973 --inputpool pool-or-uuid is the name or uuid of the storage pool
3975 the source volume is in.
3976 [--prealloc-metadata] preallocate metadata (for qcow2 images which
3978 don't support full allocation). This option creates a sparse image
3979 file with metadata, resulting in higher performance compared to
3980 images with no preallocation and only slightly higher initial disk
3981 space usage.
3982 When --reflink is specified, perform a COW lightweight copy, where
3984 the data blocks are copied only when modified. If this is not
3985 possible, the copy fails.
3986 vol-create-as pool-or-uuid name capacity [--allocation size] [--format
3988 string] [--backing-vol vol-name-or-key-or-path] [--backing-vol-format
3989 string] [--prealloc-metadata] [--print-xml]
3990 Create a volume from a set of arguments unless --print-xml is
3991 specified, in which case just the XML of the volume object is
3992 printed out without any actual object creation.
3993 pool-or-uuid is the name or UUID of the storage pool to create the
3995 volume in.
3996 name is the name of the new volume. For a disk pool, this must
3998 match the partition name as determined from the pool's source
3999 device path and the next available partition. For example, a source
4000 device path of /dev/sdb and there are no partitions on the disk,
4001 then the name must be sdb1 with the next name being sdb2 and so on.
4002 capacity is the size of the volume to be created, as a scaled
4004 integer (see NOTES above), defaulting to bytes if there is no
4005 suffix.
4006 --allocation size is the initial size to be allocated in the
4008 volume, also as a scaled integer defaulting to bytes.
4009 --format string is used in file based storage pools to specify the
4011 volume file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use
4012 extended for disk storage pools in order to create an extended
4013 partition (other values are validity checked but not preserved when
4014 libvirtd is restarted or the pool is refreshed).
4015 --backing-vol vol-name-or-key-or-path is the source backing volume
4017 to be used if taking a snapshot of an existing volume.
4018 --backing-vol-format string is the format of the snapshot backing
4020 volume; raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are,
4021 however, meant for file based storage pools.
4022 [--prealloc-metadata] preallocate metadata (for qcow2 images which
4024 don't support full allocation). This option creates a sparse image
4025 file with metadata, resulting in higher performance compared to
4026 images with no preallocation and only slightly higher initial disk
4027 space usage.
4028 vol-clone vol-name-or-key-or-path name [--pool pool-or-uuid]
4030 [--prealloc-metadata] [--reflink]
4031 Clone an existing volume within the parent pool. Less powerful,
4032 but easier to type, version of vol-create-from.
4033 vol-name-or-key-or-path is the name or key or path of the source
4035 volume.
4036 name is the name of the new volume.
4038 --pool pool-or-uuid is the name or UUID of the storage pool that
4040 contains the source volume and will contain the new volume. If the
4041 source volume name is provided instead of the key or path, then
4042 providing the pool is necessary to find the volume to be cloned;
4043 otherwise, the first volume found by the key or path will be used.
4044 [--prealloc-metadata] preallocate metadata (for qcow2 images which
4046 don't support full allocation). This option creates a sparse image
4047 file with metadata, resulting in higher performance compared to
4048 images with no preallocation and only slightly higher initial disk
4049 space usage.
4050 When --reflink is specified, perform a COW lightweight copy, where
4052 the data blocks are copied only when modified. If this is not
4053 possible, the copy fails.
4054 vol-delete vol-name-or-key-or-path [--pool pool-or-uuid]
4056 [--delete-snapshots]
4057 Delete a given volume.
4058 vol-name-or-key-or-path is the volume name or key or path of the
4060 volume to delete.
4061 [--pool pool-or-uuid] is the name or UUID of the storage pool the
4063 volume is in. If the volume name is provided instead of the key or
4064 path, then providing the pool is necessary to find the volume to be
4065 deleted; otherwise, the first volume found by the key or path will
4066 be used.
4067 The --delete-snapshots flag specifies that any snapshots associated
4069 with the storage volume should be deleted as well. Not all storage
4070 drivers support this option, presently only rbd.
4071 vol-upload vol-name-or-key-or-path local-file [--pool pool-or-uuid]
4073 [--offset bytes] [--length bytes] [--sparse]
4074 Upload the contents of local-file to a storage volume.
4075 vol-name-or-key-or-path is the name or key or path of the volume
4077 where the local-file will be uploaded.
4078 --pool pool-or-uuid is the name or UUID of the storage pool the
4080 volume is in. If the volume name is provided instead of the key or
4081 path, then providing the pool is necessary to find the volume to be
4082 uploaded into; otherwise, the first volume found by the key or path
4083 will be used.
4084 --offset is the position in the storage volume at which to start
4086 writing the data. The value must be 0 or larger.
4087 --length is an upper bound of the amount of data to be uploaded. A
4089 negative value is interpreted as an unsigned long long value to
4090 essentially include everything from the offset to the end of the
4091 volume.
4092 If --sparse is specified, this command will preserve volume
4094 sparseness.
4095 An error will occur if the local-file is greater than the specified
4097 length.
4098 See the description for the libvirt virStorageVolUpload API for
4100 details regarding possible target volume and pool changes as a
4101 result of the pool refresh when the upload is attempted.
4102 vol-download vol-name-or-key-or-path local-file [--pool pool-or-uuid]
4104 [--offset bytes] [--length bytes] [--sparse]
4105 Download the contents of a storage volume to local-file.
4106 vol-name-or-key-or-path is the name or key or path of the volume to
4108 download into local-file.
4109 --pool pool-or-uuid is the name or UUID of the storage pool the
4111 volume is in. If the volume name is provided instead of the key or
4112 path, then providing the pool is necessary to find the volume to be
4113 uploaded into; otherwise, the first volume found by the key or path
4114 will be used.
4115 --offset is the position in the storage volume at which to start
4117 reading the data. The value must be 0 or larger.
4118 --length is an upper bound of the amount of data to be downloaded.
4120 A negative value is interpreted as an unsigned long long value to
4121 essentially include everything from the offset to the end of the
4122 volume.
4123 If --sparse is specified, this command will preserve volume
4125 sparseness.
4126 vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm
4128 algorithm]
4129 Wipe a volume, ensure data previously on the volume is not
4130 accessible to future reads.
4131 vol-name-or-key-or-path is the name or key or path of the volume to
4133 wipe. It is possible to choose different wiping algorithms instead
4134 of re-writing volume with zeroes.
4135 --pool pool-or-uuid is the name or UUID of the storage pool the
4137 volume is in. If the volume name is provided instead of the key or
4138 path, then providing the pool is necessary to find the volume to be
4139 wiped; otherwise, the first volume found by the key or path will be
4140 used.
4141 Use the --algorithm switch choosing from the list of the following
4143 algorithms in order to define which algorithm to use for the wipe.
4144 Supported algorithms
4146 zero - 1-pass all zeroes
4147 nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for
4148 sanitizing removable and non-removable hard disks:
4149 random x2, 0x00, verify.
4150 dod - 4-pass DoD 5220.22-M section 8-306 procedure for
4151 sanitizing removable and non-removable rigid
4152 disks: random, 0x00, 0xff, verify.
4153 bsi - 9-pass method recommended by the German Center of
4154 Security in Information Technologies
4155 (http://www.bsi.bund.de): 0xff, 0xfe, 0xfd, 0xfb,
4156 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
4157 gutmann - The canonical 35-pass sequence described in
4158 Gutmann's paper.
4159 schneier - 7-pass method described by Bruce Schneier in
4160 "Applied Cryptography" (1996): 0x00, 0xff,
4161 random x5.
4162 pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7.
4163 pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
4164 random - 1-pass pattern: random.
4165 trim - 1-pass trimming the volume using TRIM or DISCARD
4166 Note: The "scrub" binary will be used to handle the 'nnsa', 'dod',
4168 'bsi', 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33'
4169 algorithms. The availability of the algorithms may be limited by
4170 the version of the "scrub" binary installed on the host. The 'zero'
4171 algorithm will write zeroes to the entire volume. For some volumes,
4172 such as sparse or rbd volumes, this may result in completely
4173 filling the volume with zeroes making it appear to be completely
4174 full. As an alternative, the 'trim' algorithm does not overwrite
4175 all the data in a volume, rather it expects the storage driver to
4176 be able to discard all bytes in a volume. It is up to the storage
4177 driver to handle how the discarding occurs. Not all storage drivers
4178 or volume types can support 'trim'.
4179 vol-dumpxml vol-name-or-key-or-path [--pool pool-or-uuid]
4181 Output the volume information as an XML dump to stdout.
4182 vol-name-or-key-or-path is the name or key or path of the volume to
4184 output the XML.
4185 --pool pool-or-uuid is the name or UUID of the storage pool the
4187 volume is in. If the volume name is provided instead of the key or
4188 path, then providing the pool is necessary to find the volume to be
4189 uploaded into; otherwise, the first volume found by the key or path
4190 will be used.
4191 vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes]
4193 [--physical]
4194 Returns basic information about the given storage volume.
4195 vol-name-or-key-or-path is the name or key or path of the volume to
4197 return information for.
4198 --pool pool-or-uuid is the name or UUID of the storage pool the
4200 volume is in. If the volume name is provided instead of the key or
4201 path, then providing the pool is necessary to find the volume to be
4202 uploaded into; otherwise, the first volume found by the key or path
4203 will be used.
4204 If --bytes is specified the sizes are not converted to human
4206 friendly units.
4207 If --physical is specified, then the host physical size is returned
4209 and displayed instead of the allocation value. The physical value
4210 for some file types, such as qcow2 may have a different (larger)
4211 physical value than is shown for allocation. Additionally sparse
4212 files will have different physical and allocation values.
4213 vol-list [--pool pool-or-uuid] [--details]
4215 Return the list of volumes in the given storage pool.
4216 --pool pool-or-uuid is the name or UUID of the storage pool.
4218 The --details option instructs virsh to additionally display volume
4220 type and capacity related information where available.
4221 vol-pool vol-key-or-path [--uuid]
4223 Return the pool name or UUID for a given volume. By default, the
4224 pool name is returned.
4225 vol-key-or-path is the key or path of the volume to return the pool
4227 information.
4228 If the --uuid option is given, the pool UUID is returned instead.
4230 vol-path vol-name-or-key [--pool pool-or-uuid]
4232 Return the path for a given volume.
4233 vol-name-or-key is the name or key of the volume to return the
4235 path.
4236 --pool pool-or-uuid is the name or UUID of the storage pool the
4238 volume is in. If the volume name is provided instead of the key,
4239 then providing the pool is necessary to find the volume to be
4240 uploaded into; otherwise, the first volume found by the key will be
4241 used.
4242 vol-name vol-key-or-path
4244 Return the name for a given volume.
4245 vol-key-or-path is the key or path of the volume to return the
4247 name.
4248 vol-key vol-name-or-path [--pool pool-or-uuid]
4250 Return the volume key for a given volume.
4251 vol-name-or-path is the name or path of the volume to return the
4253 volume key.
4254 --pool pool-or-uuid is the name or UUID of the storage pool the
4256 volume is in. If the volume name is provided instead of the path,
4257 then providing the pool is necessary to find the volume to be
4258 uploaded into; otherwise, the first volume found by the path will
4259 be used.
4260 vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate]
4262 [--delta] [--shrink]
4263 Resize the capacity of the given volume, in bytes.
4264 vol-name-or-key-or-path is the name or key or path of the volume to
4266 resize.
4267 capacity is a scaled integer (see NOTES above) for the volume,
4269 which defaults to bytes if there is no suffix.
4270 --pool pool-or-uuid is the name or UUID of the storage pool the
4272 volume is in. If the volume name is provided instead of the key or
4273 path, then providing the pool is necessary to find the volume to be
4274 uploaded into; otherwise, the first volume found by the key or path
4275 will be used.
4276 The new capacity might be sparse unless --allocate is specified.
4278 Normally, capacity is the new size, but if --delta is present, then
4280 it is added to the existing size.
4281 Attempts to shrink the volume will fail unless --shrink is present.
4283 The capacity cannot be negative unless --shrink is provided, but a
4284 negative sign is not necessary.
4285 This command is only safe for storage volumes not in use by an
4287 active guest; see also blockresize for live resizing.
4288
4290 The following commands manipulate "secrets" (e.g. passwords,
4291 passphrases and encryption keys). Libvirt can store secrets
4292 independently from their use, and other objects (e.g. volumes or
4293 domains) can refer to the secrets for encryption or possibly other
4294 uses. Secrets are identified using a UUID. See
4295 <https://libvirt.org/formatsecret.html> for documentation of the XML
4296 format used to represent properties of secrets.
4297 secret-define file
4299 Create a secret with the properties specified in file, with no
4300 associated secret value. If file does not specify a UUID, choose
4301 one automatically. If file specifies a UUID of an existing secret,
4302 replace its properties by properties defined in file, without
4303 affecting the secret value.
4304 secret-dumpxml secret
4306 Output properties of secret (specified by its UUID) as an XML dump
4307 to stdout.
4308 secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp]
4310 | --list}
4311 Wait for a class of secret events to occur, and print appropriate
4312 details of events as they happen. The events can optionally be
4313 filtered by secret. Using --list as the only argument will provide
4314 a list of possible event values known by this client, although the
4315 connection might not allow registering for all these events.
4316 By default, this command is one-shot, and returns success once an
4318 event occurs; you can send SIGINT (usually via "Ctrl-C") to quit
4319 immediately. If --timeout is specified, the command gives up
4320 waiting for events after seconds have elapsed. With --loop, the
4321 command prints all events until a timeout or interrupt key.
4322 When --timestamp is used, a human-readable timestamp will be
4324 printed before the event.
4325 secret-set-value secret base64
4327 Set the value associated with secret (specified by its UUID) to the
4328 value Base64-encoded value base64.
4329 secret-get-value secret
4331 Output the value associated with secret (specified by its UUID) to
4332 stdout, encoded using Base64.
4333 secret-undefine secret
4335 Delete a secret (specified by its UUID), including the associated
4336 value, if any.
4337 secret-list [--ephemeral] [--no-ephemeral] [--private] [--no-private]
4339 Returns the list of secrets. You may also want to filter the
4340 returned secrets by --ephemeral to list the ephemeral ones,
4341 --no-ephemeral to list the non-ephemeral ones, --private to list
4342 the private ones, and --no-private to list the non-private ones.
4343
4345 The following commands manipulate domain snapshots. Snapshots take the
4346 disk, memory, and device state of a domain at a point-of-time, and save
4347 it for future use. They have many uses, from saving a "clean" copy of
4348 an OS image to saving a domain's state before a potentially destructive
4349 operation. Snapshots are identified with a unique name. See
4350 <https://libvirt.org/formatsnapshot.html> for documentation of the XML
4351 format used to represent properties of snapshots.
4352 snapshot-create domain [xmlfile] {[--redefine [--current]] |
4354 [--no-metadata] [--halt] [--disk-only] [--reuse-external] [--quiesce]
4355 [--atomic] [--live]} [--validate]
4356 Create a snapshot for domain domain with the properties specified
4357 in xmlfile. Optionally, the --validate option can be passed to
4358 validate the format of the input XML file against an internal RNG
4359 schema (identical to using the virt-xml-validate(1) tool).
4360 Normally, the only properties settable for a domain snapshot are
4361 the <name> and <description> elements, as well as <disks> if
4362 --disk-only is given; the rest of the fields are ignored, and
4363 automatically filled in by libvirt. If xmlfile is completely
4364 omitted, then libvirt will choose a value for all fields. The new
4365 snapshot will become current, as listed by snapshot-current.
4366 If --halt is specified, the domain will be left in an inactive
4368 state after the snapshot is created.
4369 If --disk-only is specified, the snapshot will only include disk
4371 content rather than the usual full system snapshot with vm state.
4372 Disk snapshots are captured faster than full system snapshots, but
4373 reverting to a disk snapshot may require fsck or journal replays,
4374 since it is like the disk state at the point when the power cord is
4375 abruptly pulled; and mixing --halt and --disk-only loses any data
4376 that was not flushed to disk at the time.
4377 If --redefine is specified, then all XML elements produced by
4379 snapshot-dumpxml are valid; this can be used to migrate snapshot
4380 hierarchy from one machine to another, to recreate hierarchy for
4381 the case of a transient domain that goes away and is later
4382 recreated with the same name and UUID, or to make slight
4383 alterations in the snapshot metadata (such as host-specific aspects
4384 of the domain XML embedded in the snapshot). When this flag is
4385 supplied, the xmlfile argument is mandatory, and the domain's
4386 current snapshot will not be altered unless the --current flag is
4387 also given.
4388 If --no-metadata is specified, then the snapshot data is created,
4390 but any metadata is immediately discarded (that is, libvirt does
4391 not treat the snapshot as current, and cannot revert to the
4392 snapshot unless --redefine is later used to teach libvirt about the
4393 metadata again).
4394 If --reuse-external is specified, and the snapshot XML requests an
4396 external snapshot with a destination of an existing file, then the
4397 destination must exist and be pre-created with correct format and
4398 metadata. The file is then reused; otherwise, a snapshot is refused
4399 to avoid losing contents of the existing files.
4400 If --quiesce is specified, libvirt will try to use guest agent to
4402 freeze and unfreeze domain's mounted file systems. However, if
4403 domain has no guest agent, snapshot creation will fail. Currently,
4404 this requires --disk-only to be passed as well.
4405 If --atomic is specified, libvirt will guarantee that the snapshot
4407 either succeeds, or fails with no changes; not all hypervisors
4408 support this. If this flag is not specified, then some hypervisors
4409 may fail after partially performing the action, and dumpxml must be
4410 used to see whether any partial changes occurred.
4411 If --live is specified, libvirt takes the snapshot while the guest
4413 is running. Both disk snapshot and domain memory snapshot are
4414 taken. This increases the size of the memory image of the external
4415 snapshot. This is currently supported only for full system external
4416 snapshots.
4417 Existence of snapshot metadata will prevent attempts to undefine a
4419 persistent domain. However, for transient domains, snapshot
4420 metadata is silently lost when the domain quits running (whether by
4421 command such as destroy or by internal guest action).
4422 For now, it is not possible to create snapshots in a domain that
4424 has checkpoints, although this restriction will be lifted in a
4425 future release.
4426 snapshot-create-as domain {[--print-xml] [--no-metadata] [--halt]
4428 [--reuse-external]} [name] [description] [--disk-only [--quiesce]]
4429 [--atomic] [[--live] [--memspec memspec]] [--diskspec] diskspec]...
4430 Create a snapshot for domain domain with the given <name> and
4431 <description>; if either value is omitted, libvirt will choose a
4432 value. If --print-xml is specified, then XML appropriate for
4433 snapshot-create is output, rather than actually creating a
4434 snapshot. Otherwise, if --halt is specified, the domain will be
4435 left in an inactive state after the snapshot is created, and if
4436 --disk-only is specified, the snapshot will not include vm state.
4437 The --memspec option can be used to control whether a full system
4439 snapshot is internal or external. The --memspec flag is mandatory,
4440 followed by a memspec of the form [file=]name[,snapshot=type],
4441 where type can be no, internal, or external. To include a literal
4442 comma in file=name, escape it with a second comma. --memspec cannot
4443 be used together with --disk-only.
4444 The --diskspec option can be used to control how --disk-only and
4446 external full system snapshots create external files. This option
4447 can occur multiple times, according to the number of <disk>
4448 elements in the domain xml. Each <diskspec> is in the form
4449 disk[,snapshot=type][,driver=type][,stype=type][,file=name]. A
4450 diskspec must be provided for disks backed by block devices as
4451 libvirt doesn't auto-generate file names for those. The optional
4452 stype parameter allows to control the type of the source file.
4453 Supported values are 'file' (default) and 'block'.
4454 To include a literal comma in disk or in file=name, escape it with
4456 a second comma. A literal --diskspec must precede each diskspec
4457 unless all three of domain, name, and description are also present.
4458 For example, a diskspec of
4459 "vda,snapshot=external,file=/path/to,,new" results in the following
4460 XML:
4461 <disk name='vda' snapshot='external'>
4462 <source file='/path/to,new'/>
4463 </disk>
4464 If --reuse-external is specified, and the domain XML or diskspec
4466 option requests an external snapshot with a destination of an
4467 existing file, then the destination must exist and be pre-created
4468 with correct format and metadata. The file is then reused;
4469 otherwise, a snapshot is refused to avoid losing contents of the
4470 existing files.
4471 If --quiesce is specified, libvirt will try to use guest agent to
4473 freeze and unfreeze domain's mounted file systems. However, if
4474 domain has no guest agent, snapshot creation will fail. Currently,
4475 this requires --disk-only to be passed as well.
4476 If --no-metadata is specified, then the snapshot data is created,
4478 but any metadata is immediately discarded (that is, libvirt does
4479 not treat the snapshot as current, and cannot revert to the
4480 snapshot unless snapshot-create is later used to teach libvirt
4481 about the metadata again).
4482 If --atomic is specified, libvirt will guarantee that the snapshot
4484 either succeeds, or fails with no changes; not all hypervisors
4485 support this. If this flag is not specified, then some hypervisors
4486 may fail after partially performing the action, and dumpxml must be
4487 used to see whether any partial changes occurred.
4488 If --live is specified, libvirt takes the snapshot while the guest
4490 is running. This increases the size of the memory image of the
4491 external snapshot. This is currently supported only for external
4492 full system snapshots.
4493 For now, it is not possible to create snapshots in a domain that
4495 has checkpoints, although this restriction will be lifted in a
4496 future release.
4497 snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
4499 Without snapshotname, this will output the snapshot XML for the
4500 domain's current snapshot (if any). If --name is specified, just
4501 the current snapshot name instead of the full xml. Otherwise,
4502 using --security-info will also include security sensitive
4503 information in the XML.
4504 With snapshotname, this is a request to make the existing named
4506 snapshot become the current snapshot, without reverting the domain.
4507 snapshot-edit domain [snapshotname] [--current] {[--rename] |
4509 [--clone]}
4510 Edit the XML configuration file for snapshotname of a domain. If
4511 both snapshotname and --current are specified, also force the
4512 edited snapshot to become the current snapshot. If snapshotname is
4513 omitted, then --current must be supplied, to edit the current
4514 snapshot.
4515 This is equivalent to:
4517 virsh snapshot-dumpxml dom name > snapshot.xml
4519 vi snapshot.xml (or make changes with your other text editor)
4520 virsh snapshot-create dom snapshot.xml --redefine [--current]
4521 except that it does some error checking.
4523 The editor used can be supplied by the $VISUAL or $EDITOR
4525 environment variables, and defaults to "vi".
4526 If --rename is specified, then the edits can change the snapshot
4528 name. If --clone is specified, then changing the snapshot name
4529 will create a clone of the snapshot metadata. If neither is
4530 specified, then the edits must not change the snapshot name. Note
4531 that changing a snapshot name must be done with care, since the
4532 contents of some snapshots, such as internal snapshots within a
4533 single qcow2 file, are accessible only from the original name.
4534 snapshot-info domain {snapshot | --current}
4536 Output basic information about a named <snapshot>, or the current
4537 snapshot with --current.
4538 snapshot-list domain [--metadata] [--no-metadata] [{--parent | --roots
4540 | [{--tree | --name}]}] [--topological] [{[--from] snapshot |
4541 --current} [--descendants]] [--leaves] [--no-leaves] [--inactive]
4542 [--active] [--disk-only] [--internal] [--external]
4543 List all of the available snapshots for the given domain,
4544 defaulting to show columns for the snapshot name, creation time,
4545 and domain state.
4546 Normally, table form output is sorted by snapshot name; using
4548 --topological instead sorts so that no child is listed before its
4549 ancestors (although there may be more than one possible ordering
4550 with this property).
4551 If --parent is specified, add a column to the output table giving
4553 the name of the parent of each snapshot. If --roots is specified,
4554 the list will be filtered to just snapshots that have no parents.
4555 If --tree is specified, the output will be in a tree format,
4556 listing just snapshot names. These three options are mutually
4557 exclusive. If --name is specified only the snapshot name is
4558 printed. This option is mutually exclusive with --tree.
4559 If --from is provided, filter the list to snapshots which are
4561 children of the given snapshot; or if --current is provided, start
4562 at the current snapshot. When used in isolation or with --parent,
4563 the list is limited to direct children unless --descendants is also
4564 present. When used with --tree, the use of --descendants is
4565 implied. This option is not compatible with --roots. Note that
4566 the starting point of --from or --current is not included in the
4567 list unless the --tree option is also present.
4568 If --leaves is specified, the list will be filtered to just
4570 snapshots that have no children. Likewise, if --no-leaves is
4571 specified, the list will be filtered to just snapshots with
4572 children. (Note that omitting both options does no filtering,
4573 while providing both options will either produce the same list or
4574 error out depending on whether the server recognizes the flags).
4575 Filtering options are not compatible with --tree.
4576 If --metadata is specified, the list will be filtered to just
4578 snapshots that involve libvirt metadata, and thus would prevent
4579 undefine of a persistent domain, or be lost on destroy of a
4580 transient domain. Likewise, if --no-metadata is specified, the
4581 list will be filtered to just snapshots that exist without the need
4582 for libvirt metadata.
4583 If --inactive is specified, the list will be filtered to snapshots
4585 that were taken when the domain was shut off. If --active is
4586 specified, the list will be filtered to snapshots that were taken
4587 when the domain was running, and where the snapshot includes the
4588 memory state to revert to that running state. If --disk-only is
4589 specified, the list will be filtered to snapshots that were taken
4590 when the domain was running, but where the snapshot includes only
4591 disk state.
4592 If --internal is specified, the list will be filtered to snapshots
4594 that use internal storage of existing disk images. If --external
4595 is specified, the list will be filtered to snapshots that use
4596 external files for disk images or memory state.
4597 snapshot-dumpxml domain snapshot [--security-info]
4599 Output the snapshot XML for the domain's snapshot named snapshot.
4600 Using --security-info will also include security sensitive
4601 information. Use snapshot-current to easily access the XML of the
4602 current snapshot.
4603 snapshot-parent domain {snapshot | --current}
4605 Output the name of the parent snapshot, if any, for the given
4606 snapshot, or for the current snapshot with --current.
4607 snapshot-revert domain {snapshot | --current} [{--running | --paused}]
4609 [--force]
4610 Revert the given domain to the snapshot specified by snapshot, or
4611 to the current snapshot with --current. Be aware that this is a
4612 destructive action; any changes in the domain since the last
4613 snapshot was taken will be lost. Also note that the state of the
4614 domain after snapshot-revert is complete will be the state of the
4615 domain at the time the original snapshot was taken.
4616 Normally, reverting to a snapshot leaves the domain in the state it
4618 was at the time the snapshot was created, except that a disk
4619 snapshot with no vm state leaves the domain in an inactive state.
4620 Passing either the --running or --paused flag will perform
4621 additional state changes (such as booting an inactive domain, or
4622 pausing a running domain). Since transient domains cannot be
4623 inactive, it is required to use one of these flags when reverting
4624 to a disk snapshot of a transient domain.
4625 There are two cases where a snapshot revert involves extra risk,
4627 which requires the use of --force to proceed. One is the case of a
4628 snapshot that lacks full domain information for reverting
4629 configuration (such as snapshots created prior to libvirt 0.9.5);
4630 since libvirt cannot prove that the current configuration matches
4631 what was in use at the time of the snapshot, supplying --force
4632 assures libvirt that the snapshot is compatible with the current
4633 configuration (and if it is not, the domain will likely fail to
4634 run). The other is the case of reverting from a running domain to
4635 an active state where a new hypervisor has to be created rather
4636 than reusing the existing hypervisor, because it implies drawbacks
4637 such as breaking any existing VNC or Spice connections; this
4638 condition happens with an active snapshot that uses a provably
4639 incompatible configuration, as well as with an inactive snapshot
4640 that is combined with the --start or --pause flag.
4641 snapshot-delete domain {snapshot | --current} [--metadata] [{--children
4643 | --children-only}]
4644 Delete the snapshot for the domain named snapshot, or the current
4645 snapshot with --current. If this snapshot has child snapshots,
4646 changes from this snapshot will be merged into the children. If
4647 --children is passed, then delete this snapshot and any children of
4648 this snapshot. If --children-only is passed, then delete any
4649 children of this snapshot, but leave this snapshot intact. These
4650 two flags are mutually exclusive.
4651 If --metadata is specified, then only delete the snapshot metadata
4653 maintained by libvirt, while leaving the snapshot contents intact
4654 for access by external tools; otherwise deleting a snapshot also
4655 removes the data contents from that point in time.
4656
4658 The following commands manipulate domain checkpoints. Checkpoints
4659 serve as a point in time to identify which portions of a guest's disks
4660 have changed after that time, making it possible to perform incremental
4661 and differential backups. Checkpoints are identified with a unique
4662 name. See <https://libvirt.org/formatcheckpoint.html> for
4663 documentation of the XML format used to represent properties of
4664 checkpoints.
4665 checkpoint-create domain [xmlfile] { --redefine | [--quiesce]}
4667 Create a checkpoint for domain domain with the properties specified
4668 in xmlfile describing a <domaincheckpoint> top-level element. The
4669 format of the input XML file will be validated against an internal
4670 RNG schema (idential to using the virt-xml-validate(1) tool). If
4671 xmlfile is completely omitted, then libvirt will create a
4672 checkpoint with a name based on the current time.
4673 If --redefine is specified, then all XML elements produced by
4675 checkpoint-dumpxml are valid; this can be used to migrate
4676 checkpoint hierarchy from one machine to another, to recreate
4677 hierarchy for the case of a transient domain that goes away and is
4678 later recreated with the same name and UUID, or to make slight
4679 alterations in the checkpoint metadata (such as host-specific
4680 aspects of the domain XML embedded in the checkpoint). When this
4681 flag is supplied, the xmlfile argument is mandatory.
4682 If --quiesce is specified, libvirt will try to use guest agent to
4684 freeze and unfreeze domain's mounted file systems. However, if
4685 domain has no guest agent, checkpoint creation will fail.
4686 Existence of checkpoint metadata will prevent attempts to undefine
4688 a persistent domain. However, for transient domains, checkpoint
4689 metadata is silently lost when the domain quits running (whether by
4690 command such as destroy or by internal guest action).
4691 For now, it is not possible to create checkpoints in a domain that
4693 has snapshots, although this restriction will be lifted in a future
4694 release.
4695 checkpoint-create-as domain [--print-xml] [name] [description]
4697 [--quiesce] [--diskspec] diskspec]...
4698 Create a checkpoint for domain domain with the given <name> and
4699 <description>; if either value is omitted, libvirt will choose a
4700 value. If --print-xml is specified, then XML appropriate for
4701 checkpoint-create is output, rather than actually creating a
4702 checkpoint.
4703 The --diskspec option can be used to control which guest disks
4705 participate in the checkpoint. This option can occur multiple
4706 times, according to the number of <disk> elements in the domain
4707 xml. Each <diskspec> is in the form
4708 disk[,checkpoint=type][,bitmap=name]. A literal --diskspec must
4709 precede each diskspec unless all three of domain, name, and
4710 description are also present. For example, a diskspec of
4711 "vda,checkpoint=bitmap,bitmap=map1" results in the following XML:
4712 <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
4713 If --quiesce is specified, libvirt will try to use guest agent to
4715 freeze and unfreeze domain's mounted file systems. However, if
4716 domain has no guest agent, checkpoint creation will fail.
4717 For now, it is not possible to create checkpoints in a domain that
4719 has snapshots, although this restriction will be lifted in a future
4720 release.
4721 checkpoint-edit domain checkpointname
4723 Edit the XML configuration file for checkpointname of a domain.
4724 This is equivalent to:
4726 virsh checkpoint-dumpxml dom name > checkpoint.xml
4728 vi checkpoint.xml (or make changes with your other text editor)
4729 virsh checkpoint-create dom checkpoint.xml --redefine
4730 except that it does some error checking, including that the edits
4732 should not attempt to change the checkpoint name.
4733 The editor used can be supplied by the $VISUAL or $EDITOR
4735 environment variables, and defaults to "vi".
4736 checkpoint-info domain checkpoint
4738 Output basic information about a named <checkpoint>.
4739 checkpoint-list domain [{--parent | --roots | [{--tree | --name}]}]
4741 [--topological] [[--from] checkpoint | [--descendants]] [--leaves]
4742 [--no-leaves]
4743 List all of the available checkpoints for the given domain,
4744 defaulting to show columns for the checkpoint name and creation
4745 time.
4746 Normally, table form output is sorted by checkpoint name; using
4748 --topological instead sorts so that no child is listed before its
4749 ancestors (although there may be more than one possible ordering
4750 with this property).
4751 If --parent is specified, add a column to the output table giving
4753 the name of the parent of each checkpoint. If --roots is
4754 specified, the list will be filtered to just checkpoints that have
4755 no parents. If --tree is specified, the output will be in a tree
4756 format, listing just checkpoint names. These three options are
4757 mutually exclusive. If --name is specified only the checkpoint name
4758 is printed. This option is mutually exclusive with --tree.
4759 If --from is provided, filter the list to checkpoints which are
4761 children of the given checkpoint. When used in isolation or with
4762 --parent, the list is limited to direct children unless
4763 --descendants is also present. When used with --tree, the use of
4764 --descendants is implied. This option is not compatible with
4765 --roots. Note that the starting point of --from is not included in
4766 the list unless the --tree option is also present.
4767 If --leaves is specified, the list will be filtered to just
4769 checkpoints that have no children. Likewise, if --no-leaves is
4770 specified, the list will be filtered to just checkpoints with
4771 children. (Note that omitting both options does no filtering,
4772 while providing both options will either produce the same list or
4773 error out depending on whether the server recognizes the flags).
4774 Filtering options are not compatible with --tree.
4775 checkpoint-dumpxml domain checkpoint [--security-info] [--no-domain]
4777 [--size]
4778 Output the checkpoint XML for the domain's checkpoint named
4779 checkpoint. Using --security-info will also include security
4780 sensitive information. Using --size will add XML indicating the
4781 current size in bytes of guest data that has changed since the
4782 checkpoint was created (although remember that guest activity
4783 between a size check and actually creating a backup can result in
4784 the backup needing slightly more space). Using --no-domain will
4785 omit the <domain> element from the output for a more compact view.
4786 checkpoint-parent domain checkpoint
4788 Output the name of the parent checkpoint, if any, for the given
4789 checkpoint.
4790 checkpoint-delete domain checkpoint [--metadata] [{--children |
4792 --children-only}]
4793 Delete the checkpoint for the domain named checkpoint. The record
4794 of which portions of the disk changed since the checkpoint are
4795 merged into the parent checkpoint (if any). If --children is
4796 passed, then delete this checkpoint and any children of this
4797 checkpoint. If --children-only is passed, then delete any children
4798 of this checkpoint, but leave this checkpoint intact. These two
4799 flags are mutually exclusive.
4800 If --metadata is specified, then only delete the checkpoint
4802 metadata maintained by libvirt, while leaving the checkpoint
4803 contents intact for access by external tools; otherwise deleting a
4804 checkpoint also removes the ability to perform an incremental
4805 backup from that point in time.
4806
4808 The following commands manipulate network filters. Network filters
4809 allow filtering of the network traffic coming from and going to virtual
4810 machines. Individual network traffic filters are written in XML and
4811 may contain references to other network filters, describe traffic
4812 filtering rules, or contain both. Network filters are referenced by
4813 virtual machines from within their interface description. A network
4814 filter may be referenced by multiple virtual machines' interfaces.
4815 nwfilter-define xmlfile
4817 Make a new network filter known to libvirt. If a network filter
4818 with the same name already exists, it will be replaced with the new
4819 XML. Any running virtual machine referencing this network filter
4820 will have its network traffic rules adapted. If for any reason the
4821 network traffic filtering rules cannot be instantiated by any of
4822 the running virtual machines, then the new XML will be rejected.
4823 nwfilter-undefine nwfilter-name
4825 Delete a network filter. The deletion will fail if any running
4826 virtual machine is currently using this network filter.
4827 nwfilter-list
4829 List all of the available network filters.
4830 nwfilter-dumpxml nwfilter-name
4832 Output the network filter XML.
4833 nwfilter-edit nwfilter-name
4835 Edit the XML of a network filter.
4836 This is equivalent to:
4838 virsh nwfilter-dumpxml myfilter > myfilter.xml
4840 vi myfilter.xml (or make changes with your other text editor)
4841 virsh nwfilter-define myfilter.xml
4842 except that it does some error checking. The new network filter
4844 may be rejected due to the same reason as mentioned in nwfilter-
4845 define.
4846 The editor used can be supplied by the $VISUAL or $EDITOR
4848 environment variables, and defaults to "vi".
4849
4851 The following commands manipulate network filter bindings. Network
4852 filter bindings track the association between a network port and a
4853 network filter. Generally the bindings are managed automatically by the
4854 hypervisor drivers when adding/removing NICs on a guest.
4855 If an admin is creating/deleting TAP devices for non-guest usage,
4857 however, the network filter binding commands provide a way to make use
4858 of the network filters directly.
4859 nwfilter-binding-create xmlfile
4861 Associate a network port with a network filter. The network filter
4862 backend will immediately attempt to instantiate the filter rules on
4863 the port. This command may be used to associate a filter with a
4864 currently running guest that does not have a filter defined for a
4865 specific network port. Since the bindings are generally
4866 automatically managed by the hypervisor, using this command to
4867 define a filter for a network port and then starting the guest
4868 afterwards may prevent the guest from starting if it attempts to
4869 use the network port and finds a filter already defined.
4870 nwfilter-binding-delete port-name
4872 Disassociate a network port from a network filter. The network
4873 filter backend will immediately tear down the filter rules that
4874 exist on the port. This command may be used to remove the network
4875 port binding for a filter currently in use for the guest while the
4876 guest is running without needing to restart the guest. Restoring
4877 the network port binding filter for the running guest would be
4878 accomplished by using nwfilter-binding-create.
4879 nwfilter-binding-list
4881 List all of the network ports which have filters associated with
4882 them.
4883 nwfilter-binding-dumpxml port-name
4885 Output the network filter binding XML for the network device called
4886 "port-name".
4887
4889 NOTE: Use of the following commands is strongly discouraged. They can
4890 cause libvirt to become confused and do the wrong thing on subsequent
4891 operations. Once you have used these commands, please do not report
4892 problems to the libvirt developers; the reports will be ignored. If
4893 you find that these commands are the only way to accomplish something,
4894 then it is better to request that the feature be added as a first-class
4895 citizen in the regular libvirt library.
4896 qemu-attach pid
4898 Attach an externally launched QEMU process to the libvirt QEMU
4899 driver. The QEMU process must have been created with a monitor
4900 connection using the UNIX driver. Ideally the process will also
4901 have had the '-name' argument specified.
4902 $ qemu-kvm -cdrom ~/demo.iso \
4904 -monitor unix:/tmp/demo,server,nowait \
4905 -name foo \
4906 -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea &
4907 $ QEMUPID=$!
4908 $ virsh qemu-attach $QEMUPID
4909 Not all functions of libvirt are expected to work reliably after
4911 attaching to an externally launched QEMU process. There may be
4912 issues with the guest ABI changing upon migration and device
4913 hotplug or hotunplug may not work. The attached environment should
4914 be considered primarily read-only.
4915 qemu-monitor-command domain { [--hmp] | [--pretty] } command...
4917 Send an arbitrary monitor command command to domain domain through
4918 the qemu monitor. The results of the command will be printed on
4919 stdout. If --hmp is passed, the command is considered to be a
4920 human monitor command and libvirt will automatically convert it
4921 into QMP if needed. In that case the result will also be converted
4922 back from QMP. If --pretty is given, and the monitor uses QMP,
4923 then the output will be pretty-printed. If more than one argument
4924 is provided for command, they are concatenated with a space in
4925 between before passing the single command to the monitor.
4926 qemu-agent-command domain [--timeout seconds | --async | --block]
4928 command...
4929 Send an arbitrary guest agent command command to domain domain
4930 through qemu agent. --timeout, --async and --block options are
4931 exclusive. --timeout requires timeout seconds seconds and it must
4932 be positive. When --aysnc is given, the command waits for timeout
4933 whether success or failed. And when --block is given, the command
4934 waits forever with blocking timeout.
4935 qemu-monitor-event [domain] [--event event-name] [--loop] [--timeout
4937 seconds] [--pretty] [--regex] [--no-case] [--timestamp]
4938 Wait for arbitrary QEMU monitor events to occur, and print out the
4939 details of events as they happen. The events can optionally be
4940 filtered by domain or event-name. The 'query-events' QMP command
4941 can be used via qemu-monitor-command to learn what events are
4942 supported. If --regex is used, event-name is a basic regular
4943 expression instead of a literal string. If --no-case is used,
4944 event-name will match case-insensitively.
4945 By default, this command is one-shot, and returns success once an
4947 event occurs; you can send SIGINT (usually via "Ctrl-C") to quit
4948 immediately. If --timeout is specified, the command gives up
4949 waiting for events after seconds have elapsed. With --loop, the
4950 command prints all events until a timeout or interrupt key. If
4951 --pretty is specified, any JSON event details are pretty-printed
4952 for better legibility.
4953 When --timestamp is used, a human-readable timestamp will be
4955 printed before the event, and the timing information provided by
4956 QEMU will be omitted.
4957 lxc-enter-namespace domain [--noseclabel] -- /path/to/binary [arg1,
4959 [arg2, ...]]
4960 Enter the namespace of domain and execute the command
4961 "/path/to/binary" passing the requested args. The binary path is
4962 relative to the container root filesystem, not the host root
4963 filesystem. The binary will inherit the environment variables /
4964 console visible to virsh. The command will be run with the same
4965 sVirt context and cgroups placement as processes within the
4966 container. This command only works when connected to the LXC
4967 hypervisor driver. This command succeeds only if "/path/to/binary"
4968 has 0 exit status.
4969 By default the new process will run with the security label of the
4971 new parent container. Use the --noseclabel option to instead have
4972 the process keep the same security label as "virsh".
4973
4975 The following environment variables can be set to alter the behaviour
4976 of "virsh"
4977 VIRSH_DEBUG=<0 to 4>
4979 Turn on verbose debugging of virsh commands. Valid levels are
4980 · VIRSH_DEBUG=0
4982 DEBUG - Messages at ALL levels get logged
4984 · VIRSH_DEBUG=1
4986 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
4988 · VIRSH_DEBUG=2
4990 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
4992 · VIRSH_DEBUG=3
4994 WARNING - Logs messages at levels WARNING and ERROR
4996 · VIRSH_DEBUG=4
4998 ERROR - Messages at only ERROR level gets logged.
5000 VIRSH_LOG_FILE="LOGFILE"
5002 The file to log virsh debug messages.
5003 VIRSH_DEFAULT_CONNECT_URI
5005 The hypervisor to connect to by default. Set this to a URI, in the
5006 same format as accepted by the connect option. This environment
5007 variable is deprecated in favour of the global LIBVIRT_DEFAULT_URI
5008 variable which serves the same purpose.
5009 LIBVIRT_DEFAULT_URI
5011 The hypervisor to connect to by default. Set this to a URI, in the
5012 same format as accepted by the connect option. This overrides the
5013 default URI set in any client config file and prevents libvirt from
5014 probing for drivers.
5015 VISUAL
5017 The editor to use by the edit and related options.
5018 EDITOR
5020 The editor to use by the edit and related options, if "VISUAL" is
5021 not set.
5022 VIRSH_HISTSIZE
5024 The number of commands to remember in the command history. The
5025 default value is 500.
5026 LIBVIRT_DEBUG=LEVEL
5028 Turn on verbose debugging of all libvirt API calls. Valid levels
5029 are
5030 · LIBVIRT_DEBUG=1
5032 Messages at level DEBUG or above
5034 · LIBVIRT_DEBUG=2
5036 Messages at level INFO or above
5038 · LIBVIRT_DEBUG=3
5040 Messages at level WARNING or above
5042 · LIBVIRT_DEBUG=4
5044 Messages at level ERROR
5046 For further information about debugging options consult
5048 <https://libvirt.org/logging.html>
5049
5051 Report any bugs discovered to the libvirt community via the mailing
5052 list <https://libvirt.org/contact.html> or bug tracker
5053 <https://libvirt.org/bugs.html>. Alternatively report bugs to your
5054 software distributor / vendor.
5055
5057 Please refer to the AUTHORS file distributed with libvirt.
5058 Based on the xm man page by:
5060 Sean Dague <sean at dague dot net>
5061 Daniel Stekloff <dsteklof at us dot ibm dot com>
5062
5064 Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in
5065 the libvirt AUTHORS file.
5066
5068 virsh is distributed under the terms of the GNU LGPL v2+. This is free
5069 software; see the source for copying conditions. There is NO warranty;
5070 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
5071
5073 virt-install(1), virt-xml-validate(1), virt-top(1), virt-df(1),
5074 <https://libvirt.org/>
5075libvirt-5.6.0 2019-07-30 VIRSH(1)