1VIRSH(1) Virtualization Support VIRSH(1)
2
3
4
6 virsh - management user interface
7
9 virsh [OPTION]... [COMMAND_STRING]
10
11 virsh [OPTION]... COMMAND [ARG]...
12
14 The virsh program is the main interface for managing virsh guest do‐
15 mains. The program can be used to create, pause, and shutdown domains.
16 It can also be used to list current domains. Libvirt is a C toolkit to
17 interact with the virtualization capabilities of recent versions of
18 Linux (and other OSes). It is free software available under the GNU
19 Lesser General Public License. Virtualization of the Linux Operating
20 System means the ability to run multiple instances of Operating Systems
21 concurrently on a single hardware system where the basic resources are
22 driven by a Linux instance. The library aims at providing a long term
23 stable C API. It currently supports Xen, QEMU, KVM, LXC, OpenVZ, Vir‐
24 tualBox and VMware ESX.
25
26 The basic structure of most virsh usage is:
27
28 virsh [OPTION]... <command> <domain> [ARG]...
29
30 Where command is one of the commands listed below; domain is the nu‐
31 meric domain id, or the domain name, or the domain UUID; and ARGS are
32 command specific options. There are a few exceptions to this rule in
33 the cases where the command in question acts on all domains, the entire
34 machine, or directly on the xen hypervisor. Those exceptions will be
35 clear for each of those commands. Note: it is permissible to give nu‐
36 meric names to domains, however, doing so will result in a domain that
37 can only be identified by domain id. In other words, if a numeric value
38 is supplied it will be interpreted as a domain id, not as a name. Any
39 command starting with # is treated as a comment and silently ignored,
40 all other unrecognized commands are diagnosed.
41
42 The virsh program can be used either to run one COMMAND by giving the
43 command and its arguments on the shell command line, or a COM‐
44 MAND_STRING which is a single shell argument consisting of multiple
45 COMMAND actions and their arguments joined with whitespace and sepa‐
46 rated by semicolons or newlines between commands, where unquoted back‐
47 slash-newline pairs are elided. Within COMMAND_STRING, virsh under‐
48 stands the same single, double, and backslash escapes as the shell, al‐
49 though you must add another layer of shell escaping in creating the
50 single shell argument, and any word starting with unquoted # begins a
51 comment that ends at newline. If no command is given in the command
52 line, virsh will then start a minimal interpreter waiting for your com‐
53 mands, and the quit command will then exit the program.
54
55 The virsh program understands the following OPTIONS.
56
57 -c, --connect URI
58
59 Connect to the specified URI, as if by the connect command, instead of
60 the default connection.
61
62 -d, --debug LEVEL
63
64 Enable debug messages at integer LEVEL and above. LEVEL can range from
65 0 to 4 (default). See the documentation of VIRSH_DEBUG environment
66 variable below for the description of each LEVEL.
67
68 • -e, --escape string
69
70 Set alternative escape sequence for console command. By default, tel‐
71 net's ^] is used. Allowed characters when using hat notation are: al‐
72 phabetic character, @, [, ], , ^, _.
73
74 • -h, --help
75
76 Ignore all other arguments, and behave as if the help command were
77 given instead.
78
79 • -k, --keepalive-interval INTERVAL
80
81 Set an INTERVAL (in seconds) for sending keepalive messages to check
82 whether connection to the server is still alive. Setting the interval
83 to 0 disables client keepalive mechanism.
84
85 • -K, --keepalive-count COUNT
86
87 Set a number of times keepalive message can be sent without getting an
88 answer from the server without marking the connection dead. There is
89 no effect to this setting in case the INTERVAL is set to 0.
90
91 • -l, --log FILE
92
93 Output logging details to FILE.
94
95 • -q, --quiet
96
97 Avoid extra informational messages.
98
99 • -r, --readonly
100
101 Make the initial connection read-only, as if by the --readonly option
102 of the connect command.
103
104 • -t, --timing
105
106 Output elapsed time information for each command.
107
108 • -v, --version[=short]
109
110 Ignore all other arguments, and prints the version of the libvirt li‐
111 brary virsh is coming from
112
113 • -V, --version=long
114
115 Ignore all other arguments, and prints the version of the libvirt li‐
116 brary virsh is coming from and which options and driver are compiled
117 in.
118
120 Most virsh operations rely upon the libvirt library being able to con‐
121 nect to an already running libvirtd service. This can usually be done
122 using the command service libvirtd start.
123
124 Most virsh commands require root privileges to run due to the communi‐
125 cations channels used to talk to the hypervisor. Running as non root
126 will return an error.
127
128 Most virsh commands act synchronously, except maybe shutdown, setvcpus
129 and setmem. In those cases the fact that the virsh program returned,
130 may not mean the action is complete and you must poll periodically to
131 detect that the guest completed the operation.
132
133 virsh strives for backward compatibility. Although the help command
134 only lists the preferred usage of a command, if an older version of
135 virsh supported an alternate spelling of a command or option (such as
136 --tunnelled instead of --tunneled), then scripts using that older
137 spelling will continue to work.
138
139 Several virsh commands take an optionally scaled integer; if no scale
140 is provided, then the default is listed in the command (for historical
141 reasons, some commands default to bytes, while other commands default
142 to kibibytes). The following case-insensitive suffixes can be used to
143 select a specific scale:
144
145 b, byte byte 1
146 KB kilobyte 1,000
147 k, KiB kibibyte 1,024
148 MB megabyte 1,000,000
149 M, MiB mebibyte 1,048,576
150 GB gigabyte 1,000,000,000
151 G, GiB gibibyte 1,073,741,824
152 TB terabyte 1,000,000,000,000
153 T, TiB tebibyte 1,099,511,627,776
154 PB petabyte 1,000,000,000,000,000
155 P, PiB pebibyte 1,125,899,906,842,624
156 EB exabyte 1,000,000,000,000,000,000
157 E, EiB exbibyte 1,152,921,504,606,846,976
158
160 The following commands are generic i.e. not specific to a domain.
161
162 help
163 Syntax:
164
165 help [command-or-group]
166
167 This lists each of the virsh commands. When used without options, all
168 commands are listed, one per line, grouped into related categories,
169 displaying the keyword for each group.
170
171 To display only commands for a specific group, give the keyword for
172 that group as an option. For example:
173
174 Example 1:
175
176 virsh # help host
177
178 Host and Hypervisor (help keyword 'host'):
179 capabilities capabilities
180 cpu-models show the CPU models for an architecture
181 connect (re)connect to hypervisor
182 freecell NUMA free memory
183 hostname print the hypervisor hostname
184 qemu-attach Attach to existing QEMU process
185 qemu-monitor-command QEMU Monitor Command
186 qemu-agent-command QEMU Guest Agent Command
187 sysinfo print the hypervisor sysinfo
188 uri print the hypervisor canonical URI
189
190 To display detailed information for a specific command, give its name
191 as the option instead. For example:
192
193 Example 2:
194
195 virsh # help list
196 NAME
197 list - list domains
198
199 SYNOPSIS
200 list [--inactive] [--all]
201
202 DESCRIPTION
203 Returns list of domains.
204
205 OPTIONS
206 --inactive list inactive domains
207 --all list inactive & active domains
208
209 quit, exit
210 Syntax:
211
212 quit
213 exit
214
215 quit this interactive terminal
216
217 version
218 Syntax:
219
220 version [--daemon]
221
222 Will print out the major version info about what this built from. If
223 --daemon is specified then the version of the libvirt daemon is in‐
224 cluded in the output.
225
226 Example:
227
228 $ virsh version
229 Compiled against library: libvirt 1.2.3
230 Using library: libvirt 1.2.3
231 Using API: QEMU 1.2.3
232 Running hypervisor: QEMU 2.0.50
233
234 $ virsh version --daemon
235 Compiled against library: libvirt 1.2.3
236 Using library: libvirt 1.2.3
237 Using API: QEMU 1.2.3
238 Running hypervisor: QEMU 2.0.50
239 Running against daemon: 1.2.6
240
241 cd
242 Syntax:
243
244 cd [directory]
245
246 Will change current directory to directory. The default directory for
247 the cd command is the home directory or, if there is no HOME variable
248 in the environment, the root directory.
249
250 This command is only available in interactive mode.
251
252 pwd
253 Syntax:
254
255 pwd
256
257 Will print the current directory.
258
259 connect
260 Syntax:
261
262 connect [URI] [--readonly]
263
264 (Re)-Connect to the hypervisor. When the shell is first started, this
265 is automatically run with the URI parameter requested by the -c option
266 on the command line. The URI parameter specifies how to connect to the
267 hypervisor. The URI docs https://libvirt.org/uri.html list the values
268 supported, but the most common are:
269
270 • xen:///system
271
272 this is used to connect to the local Xen hypervisor
273
274 • qemu:///system
275
276 connect locally as root to the daemon supervising QEMU and KVM do‐
277 mains
278
279 • qemu:///session
280
281 connect locally as a normal user to his own set of QEMU and KVM do‐
282 mains
283
284 • lxc:///system
285
286 connect to a local linux container
287
288 To find the currently used URI, check the uri command documented below.
289
290 For remote access see the URI docs https://libvirt.org/uri.html on how
291 to make URIs. The --readonly option allows for read-only connection
292
293 uri
294 Syntax:
295
296 uri
297
298 Prints the hypervisor canonical URI, can be useful in shell mode.
299
300 hostname
301 Syntax:
302
303 hostname
304
305 Print the hypervisor hostname.
306
307 sysinfo
308 Syntax:
309
310 sysinfo
311
312 Print the XML representation of the hypervisor sysinfo, if available.
313
314 nodeinfo
315 Syntax:
316
317 nodeinfo
318
319 Returns basic information about the node, like number and type of CPU,
320 and size of the physical memory. The output corresponds to virNodeInfo
321 structure. Specifically, the "CPU socket(s)" field means number of CPU
322 sockets per NUMA cell. The information libvirt displays is dependent
323 upon what each architecture may provide.
324
325 nodecpumap
326 Syntax:
327
328 nodecpumap [--pretty]
329
330 Displays the node's total number of CPUs, the number of online CPUs and
331 the list of online CPUs.
332
333 With --pretty the online CPUs are printed as a range instead of a list.
334
335 nodecpustats
336 Syntax:
337
338 nodecpustats [cpu] [--percent]
339
340 Returns cpu stats of the node. If cpu is specified, this will print
341 the specified cpu statistics only. If --percent is specified, this
342 will print the percentage of each kind of cpu statistics during 1 sec‐
343 ond.
344
345 nodememstats
346 Syntax:
347
348 nodememstats [cell]
349
350 Returns memory stats of the node. If cell is specified, this will
351 print the specified cell statistics only.
352
353 nodesuspend
354 Syntax:
355
356 nodesuspend [target] [duration]
357
358 Puts the node (host machine) into a system-wide sleep state and sched‐
359 ule the node's Real-Time-Clock interrupt to resume the node after the
360 time duration specified by duration is out. target specifies the state
361 to which the host will be suspended to, it can be "mem" (suspend to
362 RAM), "disk" (suspend to disk), or "hybrid" (suspend to both RAM and
363 disk). duration specifies the time duration in seconds for which the
364 host has to be suspended, it should be at least 60 seconds.
365
366 node-memory-tune
367 Syntax:
368
369 node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs] [shm-merge-across-nodes]
370
371 Allows you to display or set the node memory parameters.
372 shm-pages-to-scan can be used to set the number of pages to scan before
373 the shared memory service goes to sleep; shm-sleep-millisecs can be
374 used to set the number of millisecs the shared memory service should
375 sleep before next scan; shm-merge-across-nodes specifies if pages from
376 different numa nodes can be merged. When set to 0, only pages which
377 physically reside in the memory area of same NUMA node can be merged.
378 When set to 1, pages from all nodes can be merged. Default to 1.
379
380 Note: Currently the "shared memory service" only means KSM (Kernel
381 Samepage Merging).
382
383 capabilities
384 Syntax:
385
386 capabilities
387
388 Print an XML document describing the capabilities of the hypervisor we
389 are currently connected to. This includes a section on the host capa‐
390 bilities in terms of CPU and features, and a set of description for
391 each kind of guest which can be virtualized. For a more complete de‐
392 scription see:
393
394 https://libvirt.org/formatcaps.html
395
396 The XML also show the NUMA topology information if available.
397
398 domcapabilities
399 Syntax:
400
401 domcapabilities [virttype] [emulatorbin] [arch] [machine]
402
403 Print an XML document describing the domain capabilities for the hyper‐
404 visor we are connected to using information either sourced from an ex‐
405 isting domain or taken from the virsh capabilities output. This may be
406 useful if you intend to create a new domain and are curious if for in‐
407 stance it could make use of VFIO by creating a domain for the hypervi‐
408 sor with a specific emulator and architecture.
409
410 Each hypervisor will have different requirements regarding which op‐
411 tions are required and which are optional. A hypervisor can support
412 providing a default value for any of the options.
413
414 The virttype option specifies the virtualization type used. The value
415 to be used is either from the 'type' attribute of the <domain/> top
416 level element from the domain XML or the 'type' attribute found within
417 each <guest/> element from the virsh capabilities output. The emula‐
418 torbin option specifies the path to the emulator. The value to be used
419 is either the <emulator> element in the domain XML or the virsh capa‐
420 bilities output. The arch option specifies the architecture to be used
421 for the domain. The value to be used is either the "arch" attribute
422 from the domain's XML <os/> element and <type/> subelement or the
423 "name" attribute of an <arch/> element from the virsh capabililites
424 output. The machine specifies the machine type for the emulator. The
425 value to be used is either the "machine" attribute from the domain's
426 XML <os/> element and <type/> subelement or one from a list of machines
427 from the virsh capabilities output for a specific architecture and do‐
428 main type.
429
430 For the QEMU hypervisor, a virttype of either 'qemu' or 'kvm' must be
431 supplied along with either the emulatorbin or arch in order to generate
432 output for the default machine. Supplying a machine value will gener‐
433 ate output for the specific machine.
434
435 pool-capabilities
436 Syntax:
437
438 pool-capabilities
439
440 Print an XML document describing the storage pool capabilities for the
441 connected storage driver. This may be useful if you intend to create a
442 new storage pool and need to know the available pool types and sup‐
443 ported storage pool source and target volume formats as well as the re‐
444 quired source elements to create the pool.
445
446 inject-nmi
447 Syntax:
448
449 inject-nmi domain
450
451 Inject NMI to the guest.
452
453 list
454 Syntax:
455
456 list [--inactive | --all]
457 [--managed-save] [--title]
458 { [--table] | --name | --uuid | --id }
459 [--persistent] [--transient]
460 [--with-managed-save] [--without-managed-save]
461 [--autostart] [--no-autostart]
462 [--with-snapshot] [--without-snapshot]
463 [--with-checkpoint] [--without-checkpoint]
464 [--state-running] [--state-paused]
465 [--state-shutoff] [--state-other]
466
467 Prints information about existing domains. If no options are specified
468 it prints out information about running domains.
469
470 Example 1:
471
472 An example format for the list is as follows:
473
474 ``virsh`` list
475 Id Name State
476 ----------------------------------------------------
477 0 Domain-0 running
478 2 fedora paused
479
480 Name is the name of the domain. ID the domain numeric id. State is
481 the run state (see below).
482
483 STATES
484
485 The State field lists what state each domain is currently in. A domain
486 can be in one of the following possible states:
487
488 • running
489
490 The domain is currently running on a CPU
491
492 • idle
493
494 The domain is idle, and not running or runnable. This can be caused
495 because the domain is waiting on IO (a traditional wait state) or has
496 gone to sleep because there was nothing else for it to do.
497
498 • paused
499
500 The domain has been paused, usually occurring through the administra‐
501 tor running virsh suspend. When in a paused state the domain will
502 still consume allocated resources like memory, but will not be eligi‐
503 ble for scheduling by the hypervisor.
504
505 • in shutdown
506
507 The domain is in the process of shutting down, i.e. the guest operat‐
508 ing system has been notified and should be in the process of stopping
509 its operations gracefully.
510
511 • shut off
512
513 The domain is not running. Usually this indicates the domain has
514 been shut down completely, or has not been started.
515
516 • crashed
517
518 The domain has crashed, which is always a violent ending. Usually
519 this state can only occur if the domain has been configured not to
520 restart on crash.
521
522 • pmsuspended
523
524 The domain has been suspended by guest power management, e.g. entered
525 into s3 state.
526
527 Normally only active domains are listed. To list inactive domains spec‐
528 ify --inactive or --all to list both active and inactive domains.
529
530 Filtering
531
532 To further filter the list of domains you may specify one or more of
533 filtering flags supported by the list command. These flags are grouped
534 by function. Specifying one or more flags from a group enables the
535 filter group. Note that some combinations of flags may yield no re‐
536 sults. Supported filtering flags and groups:
537
538 Persistence
539 Flag --persistent is used to include persistent guests in the returned
540 list. To include transient guests specify --transient.
541
542 Existence of managed save image
543 To list domains having a managed save image specify flag --with-man‐
544 aged-save. For domains that don't have a managed save image specify
545 --without-managed-save.
546
547 Domain state
548 The following filter flags select a domain by its state: --state-run‐
549 ning for running domains, --state-paused for paused domains,
550 --state-shutoff for turned off domains and --state-other for all other
551 states as a fallback.
552
553 Autostarting domains
554 To list autostarting domains use the flag --autostart. To list domains
555 with this feature disabled use --no-autostart.
556
557 Snapshot existence
558 Domains that have snapshot images can be listed using flag --with-snap‐
559 shot, domains without a snapshot --without-snapshot.
560
561 Checkpoint existence
562 Domains that have checkpoints can be listed using flag --with-check‐
563 point, domains without a checkpoint --without-checkpoint.
564
565 When talking to older servers, this command is forced to use a series
566 of API calls with an inherent race, where a domain might not be listed
567 or might appear more than once if it changed state between calls while
568 the list was being collected. Newer servers do not have this problem.
569
570 If --managed-save is specified, then domains that have managed save
571 state (only possible if they are in the shut off state, so you need to
572 specify --inactive or --all to actually list them) will instead show as
573 saved in the listing. This flag is usable only with the default --table
574 output. Note that this flag does not filter the list of domains.
575
576 If --name is specified, domain names are printed instead of the table
577 formatted one per line. If --uuid is specified domain's UUID's are
578 printed instead of names. If --id is specified then domain's ID's are
579 printed indead of names. However, it is possible to combine --name,
580 --uuid and --id to select only desired fields for printing. Flag --ta‐
581 ble specifies that the legacy table-formatted output should be used,
582 but it is mutually exclusive with --name, --uuid and --id. This is the
583 default and will be used if neither of --name, --uuid or --id is speci‐
584 fied. If neither --name nor --uuid is specified, but --id is, then only
585 active domains are listed, even with the --all parameter as otherwise
586 the output would just contain bunch of lines with just -1.
587
588 If --title is specified, then the short domain description (title) is
589 printed in an extra column. This flag is usable only with the default
590 --table output.
591
592 Example 2:
593
594 $ virsh list --title
595 Id Name State Title
596 -------------------------------------------
597 0 Domain-0 running Mailserver 1
598 2 fedora paused
599
600 freecell
601 Syntax:
602
603 freecell [{ [--cellno] cellno | --all }]
604
605 Prints the available amount of memory on the machine or within a NUMA
606 cell. The freecell command can provide one of three different displays
607 of available memory on the machine depending on the options specified.
608 With no options, it displays the total free memory on the machine.
609 With the --all option, it displays the free memory in each cell and the
610 total free memory on the machine. Finally, with a numeric argument or
611 with --cellno plus a cell number it will display the free memory for
612 the specified cell only.
613
614 freepages
615 Syntax:
616
617 freepages [{ [--cellno] cellno [--pagesize] pagesize | --all }]
618
619 Prints the available amount of pages within a NUMA cell. cellno refers
620 to the NUMA cell you're interested in. pagesize is a scaled integer
621 (see NOTES above). Alternatively, if --all is used, info on each pos‐
622 sible combination of NUMA cell and page size is printed out.
623
624 allocpages
625 Syntax:
626
627 allocpages [--pagesize] pagesize [--pagecount] pagecount [[--cellno] cellno] [--add] [--all]
628
629 Change the size of pages pool of pagesize on the host. If --add is
630 specified, then pagecount pages are added into the pool. However, if
631 --add wasn't specified, then the pagecount is taken as the new absolute
632 size of the pool (this may be used to free some pages and size the pool
633 down). The cellno modifier can be used to narrow the modification down
634 to a single host NUMA cell. On the other end of spectrum lies --all
635 which executes the modification on all NUMA cells.
636
637 cpu-baseline
638 Syntax:
639
640 cpu-baseline FILE [--features] [--migratable]
641
642 Compute baseline CPU which will be supported by all host CPUs given in
643 <file>. (See hypervisor-cpu-baseline command to get a CPU which can be
644 provided by a specific hypervisor.) The list of host CPUs is built by
645 extracting all <cpu> elements from the <file>. Thus, the <file> can
646 contain either a set of <cpu> elements separated by new lines or even a
647 set of complete <capabilities> elements printed by capabilities com‐
648 mand. If --features is specified, then the resulting XML description
649 will explicitly include all features that make up the CPU, without this
650 option features that are part of the CPU model will not be listed in
651 the XML description. If --migratable is specified, features that
652 block migration will not be included in the resulting CPU.
653
654 cpu-compare
655 Syntax:
656
657 cpu-compare FILE [--error] [--validate]
658
659 Compare CPU definition from XML <file> with host CPU. (See hypervi‐
660 sor-cpu-compare command for comparing the CPU definition with the CPU
661 which a specific hypervisor is able to provide on the host.) The XML
662 <file> may contain either host or guest CPU definition. The host CPU
663 definition is the <cpu> element and its contents as printed by capabil‐
664 ities command. The guest CPU definition is the <cpu> element and its
665 contents from domain XML definition or the CPU definition created from
666 the host CPU model found in domain capabilities XML (printed by domca‐
667 pabilities command). In addition to the <cpu> element itself, this com‐
668 mand accepts full domain XML, capabilities XML, or domain capabilities
669 XML containing the CPU definition. For more information on guest CPU
670 definition see: https://libvirt.org/formatdomain.html#elementsCPU. If
671 --error is specified, the command will return an error when the given
672 CPU is incompatible with host CPU and a message providing more details
673 about the incompatibility will be printed out. If --validate is speci‐
674 fied, validates the format of the XML document against an internal RNG
675 schema.
676
677 cpu-models
678 Syntax:
679
680 cpu-models arch
681
682 Print the list of CPU models known by libvirt for the specified archi‐
683 tecture. Whether a specific hypervisor is able to create a domain
684 which uses any of the printed CPU models is a separate question which
685 can be answered by looking at the domain capabilities XML returned by
686 domcapabilities command. Moreover, for some architectures libvirt does
687 not know any CPU models and the usable CPU models are only limited by
688 the hypervisor. This command will print that all CPU models are ac‐
689 cepted for these architectures and the actual list of supported CPU
690 models can be checked in the domain capabilities XML.
691
692 echo
693 Syntax:
694
695 echo [--shell] [--xml] [err...] [arg...]
696
697 Echo back each arg, separated by space. If --shell is specified, then
698 the output will be single-quoted where needed, so that it is suitable
699 for reuse in a shell context. If --xml is specified, then the output
700 will be escaped for use in XML. If --err is specified, prefix "error:
701 " and output to stderr instead of stdout.
702
703 hypervisor-cpu-compare
704 Syntax:
705
706 hypervisor-cpu-compare FILE [virttype] [emulator] [arch] [machine] [--error] [--validate]
707
708 Compare CPU definition from XML <file> with the CPU the hypervisor is
709 able to provide on the host. (This is different from cpu-compare which
710 compares the CPU definition with the host CPU without considering any
711 specific hypervisor and its abilities.)
712
713 The XML FILE may contain either a host or guest CPU definition. The
714 host CPU definition is the <cpu> element and its contents as printed by
715 the capabilities command. The guest CPU definition is the <cpu> element
716 and its contents from the domain XML definition or the CPU definition
717 created from the host CPU model found in the domain capabilities XML
718 (printed by the domcapabilities command). In addition to the <cpu> ele‐
719 ment itself, this command accepts full domain XML, capabilities XML, or
720 domain capabilities XML containing the CPU definition. For more infor‐
721 mation on guest CPU definition see:
722 https://libvirt.org/formatdomain.html#elementsCPU.
723
724 The virttype option specifies the virtualization type (usable in the
725 'type' attribute of the <domain> top level element from the domain
726 XML). emulator specifies the path to the emulator, arch specifies the
727 CPU architecture, and machine specifies the machine type. If --error is
728 specified, the command will return an error when the given CPU is in‐
729 compatible with the host CPU and a message providing more details about
730 the incompatibility will be printed out. If --validate is specified,
731 validates the format of the XML document against an internal RNG
732 schema.
733
734 hypervisor-cpu-baseline
735 Syntax:
736
737 hypervisor-cpu-baseline FILE [virttype] [emulator] [arch] [machine] [--features] [--migratable]
738
739 Compute a baseline CPU which will be compatible with all CPUs defined
740 in an XML file and with the CPU the hypervisor is able to provide on
741 the host. (This is different from cpu-baseline which does not consider
742 any hypervisor abilities when computing the baseline CPU.)
743
744 The XML FILE may contain either host or guest CPU definitions describ‐
745 ing the host CPU model. The host CPU definition is the <cpu> element
746 and its contents as printed by capabilities command. The guest CPU def‐
747 inition may be created from the host CPU model found in domain capabil‐
748 ities XML (printed by domcapabilities command). In addition to the
749 <cpu> elements, this command accepts full capabilities XMLs, or domain
750 capabilities XMLs containing the CPU definitions. It is recommended to
751 use only the CPU definitions from domain capabilities, as on some ar‐
752 chitectures using the host CPU definition may either fail or provide
753 unexpected results.
754
755 When FILE contains only a single CPU definition, the command will print
756 the same CPU with restrictions imposed by the capabilities of the hy‐
757 pervisor. Specifically, running th virsh hypervisor-cpu-baseline com‐
758 mand with no additional options on the result of virsh domcapabilities
759 will transform the host CPU model from domain capabilities XML to a
760 form directly usable in domain XML.
761
762 The virttype option specifies the virtualization type (usable in the
763 'type' attribute of the <domain> top level element from the domain
764 XML). emulator specifies the path to the emulator, arch specifies the
765 CPU architecture, and machine specifies the machine type. If --features
766 is specified, then the resulting XML description will explicitly in‐
767 clude all features that make up the CPU, without this option features
768 that are part of the CPU model will not be listed in the XML descrip‐
769 tion. If --migratable is specified, features that block migration will
770 not be included in the resulting CPU.
771
773 The following commands manipulate domains directly, as stated previ‐
774 ously most commands take domain as the first parameter. The domain can
775 be specified as a short integer, a name or a full UUID.
776
777 autostart
778 Syntax:
779
780 autostart [--disable] domain
781
782 Configure a domain to be automatically started at boot.
783
784 The option --disable disables autostarting.
785
786 blkdeviotune
787 Syntax:
788
789 blkdeviotune domain device [[--config] [--live] | [--current]]
790 [[total-bytes-sec] | [read-bytes-sec] [write-bytes-sec]]
791 [[total-iops-sec] | [read-iops-sec] [write-iops-sec]]
792 [[total-bytes-sec-max] | [read-bytes-sec-max] [write-bytes-sec-max]]
793 [[total-iops-sec-max] | [read-iops-sec-max] [write-iops-sec-max]]
794 [[total-bytes-sec-max-length] |
795 [read-bytes-sec-max-length] [write-bytes-sec-max-length]]
796 [[total-iops-sec-max-length] |
797 [read-iops-sec-max-length] [write-iops-sec-max-length]]
798 [size-iops-sec] [group-name]
799
800 Set or query the block disk io parameters for a block device of domain.
801 device specifies a unique target name (<target dev='name'/>) or source
802 file (<source file='name'/>) for one of the disk devices attached to
803 domain (see also domblklist for listing these names).
804
805 If no limit is specified, it will query current I/O limits setting.
806 Otherwise, alter the limits with these flags: --total-bytes-sec speci‐
807 fies total throughput limit as a scaled integer, the default being
808 bytes per second if no suffix is specified. --read-bytes-sec specifies
809 read throughput limit as a scaled integer, the default being bytes per
810 second if no suffix is specified. --write-bytes-sec specifies write
811 throughput limit as a scaled integer, the default being bytes per sec‐
812 ond if no suffix is specified. --total-iops-sec specifies total I/O
813 operations limit per second. --read-iops-sec specifies read I/O opera‐
814 tions limit per second. --write-iops-sec specifies write I/O opera‐
815 tions limit per second. --total-bytes-sec-max specifies maximum total
816 throughput limit as a scaled integer, the default being bytes per sec‐
817 ond if no suffix is specified --read-bytes-sec-max specifies maximum
818 read throughput limit as a scaled integer, the default being bytes per
819 second if no suffix is specified. --write-bytes-sec-max specifies max‐
820 imum write throughput limit as a scaled integer, the default being
821 bytes per second if no suffix is specified. --total-iops-sec-max spec‐
822 ifies maximum total I/O operations limit per second.
823 --read-iops-sec-max specifies maximum read I/O operations limit per
824 second. --write-iops-sec-max specifies maximum write I/O operations
825 limit per second. --total-bytes-sec-max-length specifies duration in
826 seconds to allow maximum total throughput limit.
827 --read-bytes-sec-max-length specifies duration in seconds to allow max‐
828 imum read throughput limit. --write-bytes-sec-max-length specifies du‐
829 ration in seconds to allow maximum write throughput limit. --to‐
830 tal-iops-sec-max-length specifies duration in seconds to allow maximum
831 total I/O operations limit. --read-iops-sec-max-length specifies dura‐
832 tion in seconds to allow maximum read I/O operations limit.
833 --write-iops-sec-max-length specifies duration in seconds to allow max‐
834 imum write I/O operations limit. --size-iops-sec specifies size I/O
835 operations limit per second. --group-name specifies group name to
836 share I/O quota between multiple drives. For a QEMU domain, if no name
837 is provided, then the default is to have a single group for each de‐
838 vice.
839
840 Older versions of virsh only accepted these options with underscore in‐
841 stead of dash, as in --total_bytes_sec.
842
843 Bytes and iops values are independent, but setting only one value (such
844 as --read-bytes-sec) resets the other two in that category to unlim‐
845 ited. An explicit 0 also clears any limit. A non-zero value for a
846 given total cannot be mixed with non-zero values for read or write.
847
848 It is up to the hypervisor to determine how to handle the length val‐
849 ues. For the QEMU hypervisor, if an I/O limit value or maximum value
850 is set, then the default value of 1 second will be displayed. Supplying
851 a 0 will reset the value back to the default.
852
853 If --live is specified, affect a running guest. If --config is speci‐
854 fied, affect the next start of a persistent guest. If --current is
855 specified, it is equivalent to either --live or --config, depending on
856 the current state of the guest. When setting the disk io parameters
857 both --live and --config flags may be given, but --current is exclu‐
858 sive. For querying only one of --live, --config or --current can be
859 specified. If no flag is specified, behavior is different depending on
860 hypervisor.
861
862 blkiotune
863 Syntax:
864
865 blkiotune domain [--weight weight] [--device-weights device-weights]
866 [--device-read-iops-sec device-read-iops-sec]
867 [--device-write-iops-sec device-write-iops-sec]
868 [--device-read-bytes-sec device-read-bytes-sec]
869 [--device-write-bytes-sec device-write-bytes-sec]
870 [[--config] [--live] | [--current]]
871
872 Display or set the blkio parameters. QEMU/KVM supports --weight.
873 --weight is in range [100, 1000]. After kernel 2.6.39, the value could
874 be in the range [10, 1000].
875
876 device-weights is a single string listing one or more device/weight
877 pairs, in the format of /path/to/device,weight,/path/to/device,weight.
878 Each weight is in the range [100, 1000], [10, 1000] after kernel
879 2.6.39, or the value 0 to remove that device from per-device listings.
880 Only the devices listed in the string are modified; any existing
881 per-device weights for other devices remain unchanged.
882
883 device-read-iops-sec is a single string listing one or more de‐
884 vice/read_iops_sec pairs, int the format of /path/to/de‐
885 vice,read_iops_sec,/path/to/device,read_iops_sec. Each read_iops_sec
886 is a number which type is unsigned int, value 0 to remove that device
887 from per-device listing. Only the devices listed in the string are
888 modified; any existing per-device read_iops_sec for other devices re‐
889 main unchanged.
890
891 device-write-iops-sec is a single string listing one or more de‐
892 vice/write_iops_sec pairs, int the format of /path/to/de‐
893 vice,write_iops_sec,/path/to/device,write_iops_sec. Each
894 write_iops_sec is a number which type is unsigned int, value 0 to re‐
895 move that device from per-device listing. Only the devices listed in
896 the string are modified; any existing per-device write_iops_sec for
897 other devices remain unchanged.
898
899 device-read-bytes-sec is a single string listing one or more de‐
900 vice/read_bytes_sec pairs, int the format of /path/to/de‐
901 vice,read_bytes_sec,/path/to/device,read_bytes_sec. Each
902 read_bytes_sec is a number which type is unsigned long long, value 0 to
903 remove that device from per-device listing. Only the devices listed in
904 the string are modified; any existing per-device read_bytes_sec for
905 other devices remain unchanged.
906
907 device-write-bytes-sec is a single string listing one or more de‐
908 vice/write_bytes_sec pairs, int the format of /path/to/de‐
909 vice,write_bytes_sec,/path/to/device,write_bytes_sec. Each
910 write_bytes_sec is a number which type is unsigned long long, value 0
911 to remove that device from per-device listing. Only the devices listed
912 in the string are modified; any existing per-device write_bytes_sec for
913 other devices remain unchanged.
914
915 If --live is specified, affect a running guest. If --config is speci‐
916 fied, affect the next start of a persistent guest. If --current is
917 specified, it is equivalent to either --live or --config, depending on
918 the current state of the guest. Both --live and --config flags may be
919 given, but --current is exclusive. If no flag is specified, behavior is
920 different depending on hypervisor.
921
922 blockcommit
923 Syntax:
924
925 blockcommit domain path [bandwidth] [--bytes] [base]
926 [--shallow] [top] [--delete] [--keep-relative]
927 [--wait [--async] [--verbose]] [--timeout seconds]
928 [--active] [{--pivot | --keep-overlay}]
929
930 Reduce the length of a backing image chain, by committing changes at
931 the top of the chain (snapshot or delta files) into backing images. By
932 default, this command attempts to flatten the entire chain. If base
933 and/or top are specified as files within the backing chain, then the
934 operation is constrained to committing just that portion of the chain;
935 --shallow can be used instead of base to specify the immediate backing
936 file of the resulting top image to be committed. The files being com‐
937 mitted are rendered invalid, possibly as soon as the operation starts;
938 using the --delete flag will attempt to remove these invalidated files
939 at the successful completion of the commit operation. When the
940 --keep-relative flag is used, the backing file paths will be kept rela‐
941 tive.
942
943 When top is omitted or specified as the active image, it is also possi‐
944 ble to specify --active to trigger a two-phase active commit. In the
945 first phase, top is copied into base and the job can only be canceled,
946 with top still containing data not yet in base. In the second phase,
947 top and base remain identical until a call to blockjob with the --abort
948 flag (keeping top as the active image that tracks changes from that
949 point in time) or the --pivot flag (making base the new active image
950 and invalidating top).
951
952 By default, this command returns as soon as possible, and data for the
953 entire disk is committed in the background; the progress of the opera‐
954 tion can be checked with blockjob. However, if --wait is specified,
955 then this command will block until the operation completes (or for
956 --active, enters the second phase), or until the operation is canceled
957 because the optional timeout in seconds elapses or SIGINT is sent (usu‐
958 ally with Ctrl-C). Using --verbose along with --wait will produce pe‐
959 riodic status updates. If job cancellation is triggered, --async will
960 return control to the user as fast as possible, otherwise the command
961 may continue to block a little while longer until the job is done
962 cleaning up. Using --pivot is shorthand for combining --active --wait
963 with an automatic blockjob --pivot; and using --keep-overlay is short‐
964 hand for combining --active --wait with an automatic blockjob --abort.
965
966 path specifies fully-qualified path of the disk; it corresponds to a
967 unique target name (<target dev='name'/>) or source file (<source
968 file='name'/>) for one of the disk devices attached to domain (see also
969 domblklist for listing these names). bandwidth specifies copying band‐
970 width limit in MiB/s, although for QEMU, it may be non-zero only for an
971 online domain. For further information on the bandwidth argument see
972 the corresponding section for the blockjob command.
973
974 blockcopy
975 Syntax:
976
977 blockcopy domain path { dest [format] [--blockdev] | --xml file }
978 [--shallow] [--reuse-external] [bandwidth]
979 [--wait [--async] [--verbose]] [{--pivot | --finish}]
980 [--timeout seconds] [granularity] [buf-size] [--bytes]
981 [--transient-job]
982
983 Copy a disk backing image chain to a destination. Either dest as the
984 destination file name, or --xml with the name of an XML file containing
985 a top-level <disk> element describing the destination, must be present.
986 Additionally, if dest is given, format should be specified to declare
987 the format of the destination (if format is omitted, then libvirt will
988 reuse the format of the source, or with --reuse-external will be forced
989 to probe the destination format, which could be a potential security
990 hole). The command supports --raw as a boolean flag synonym for --for‐
991 mat=raw. When using dest, the destination is treated as a regular file
992 unless --blockdev is used to signal that it is a block device. By de‐
993 fault, this command flattens the entire chain; but if --shallow is
994 specified, the copy shares the backing chain.
995
996 If --reuse-external is specified, then the destination must exist and
997 have sufficient space to hold the copy. If --shallow is used in con‐
998 junction with --reuse-external then the pre-created image must have
999 guest visible contents identical to guest visible contents of the back‐
1000 ing file of the original image. This may be used to modify the backing
1001 file names on the destination.
1002
1003 By default, the copy job runs in the background, and consists of two
1004 phases. Initially, the job must copy all data from the source, and
1005 during this phase, the job can only be canceled to revert back to the
1006 source disk, with no guarantees about the destination. After this
1007 phase completes, both the source and the destination remain mirrored
1008 until a call to blockjob with the --abort and --pivot flags pivots over
1009 to the copy, or a call without --pivot leaves the destination as a
1010 faithful copy of that point in time. However, if --wait is specified,
1011 then this command will block until the mirroring phase begins, or can‐
1012 cel the operation if the optional timeout in seconds elapses or SIGINT
1013 is sent (usually with Ctrl-C). Using --verbose along with --wait will
1014 produce periodic status updates. Using --pivot (similar to blockjob
1015 --pivot) or --finish (similar to blockjob --abort) implies --wait, and
1016 will additionally end the job cleanly rather than leaving things in the
1017 mirroring phase. If job cancellation is triggered by timeout or by
1018 --finish, --async will return control to the user as fast as possible,
1019 otherwise the command may continue to block a little while longer until
1020 the job has actually cancelled.
1021
1022 path specifies fully-qualified path of the disk. bandwidth specifies
1023 copying bandwidth limit in MiB/s. Specifying a negative value is inter‐
1024 preted as an unsigned long long value that might be essentially unlim‐
1025 ited, but more likely would overflow; it is safer to use 0 for that
1026 purpose. For further information on the bandwidth argument see the cor‐
1027 responding section for the blockjob command. Specifying granularity
1028 allows fine-tuning of the granularity that will be copied when a dirty
1029 region is detected; larger values trigger less I/O overhead but may end
1030 up copying more data overall (the default value is usually correct);
1031 hypervisors may restrict this to be a power of two or fall within a
1032 certain range. Specifying buf-size will control how much data can be
1033 simultaneously in-flight during the copy; larger values use more memory
1034 but may allow faster completion (the default value is usually correct).
1035
1036 --transient-job allows specifying that the user does not require the
1037 job to be recovered if the VM crashes or is turned off before the job
1038 completes. This flag removes the restriction of copy jobs to transient
1039 domains if that restriction is applied by the hypervisor.
1040
1041 blockjob
1042 Syntax:
1043
1044 blockjob domain path { [--abort] [--async] [--pivot] |
1045 [--info] [--raw] [--bytes] | [bandwidth] }
1046
1047 Manage active block operations. There are three mutually-exclusive
1048 modes: --info, bandwidth, and --abort. --async and --pivot imply abort
1049 mode; --raw implies info mode; and if no mode was given, --info mode is
1050 assumed.
1051
1052 path specifies fully-qualified path of the disk; it corresponds to a
1053 unique target name (<target dev='name'/>) or source file (<source
1054 file='name'/>) for one of the disk devices attached to domain (see also
1055 domblklist for listing these names).
1056
1057 In --abort mode, the active job on the specified disk will be aborted.
1058 If --async is also specified, this command will return immediately,
1059 rather than waiting for the cancellation to complete. If --pivot is
1060 specified, this requests that an active copy or active commit job be
1061 pivoted over to the new image.
1062
1063 In --info mode, the active job information on the specified disk will
1064 be printed. By default, the output is a single human-readable summary
1065 line; this format may change in future versions. Adding --raw lists
1066 each field of the struct, in a stable format. If the --bytes flag is
1067 set, then the command errors out if the server could not supply bytes/s
1068 resolution; when omitting the flag, raw output is listed in MiB/s and
1069 human-readable output automatically selects the best resolution sup‐
1070 ported by the server.
1071
1072 bandwidth can be used to set bandwidth limit for the active job in
1073 MiB/s. If --bytes is specified then the bandwidth value is interpreted
1074 in bytes/s. Specifying a negative value is interpreted as an unsigned
1075 long value or essentially unlimited. The hypervisor can choose whether
1076 to reject the value or convert it to the maximum value allowed. Option‐
1077 ally a scaled positive number may be used as bandwidth (see NOTES
1078 above). Using --bytes with a scaled value permits a finer granularity
1079 to be selected. A scaled value used without --bytes will be rounded
1080 down to MiB/s. Note that the --bytes may be unsupported by the hypervi‐
1081 sor.
1082
1083 Note that the progress reported for blockjobs corresponding to a
1084 pull-mode backup don't report progress of the backup but rather usage
1085 of temporary space required for the backup.
1086
1087 blockpull
1088 Syntax:
1089
1090 blockpull domain path [bandwidth] [--bytes] [base]
1091 [--wait [--verbose] [--timeout seconds] [--async]]
1092 [--keep-relative]
1093
1094 Populate a disk from its backing image chain. By default, this command
1095 flattens the entire chain; but if base is specified, containing the
1096 name of one of the backing files in the chain, then that file becomes
1097 the new backing file and only the intermediate portion of the chain is
1098 pulled. Once all requested data from the backing image chain has been
1099 pulled, the disk no longer depends on that portion of the backing
1100 chain.
1101
1102 By default, this command returns as soon as possible, and data for the
1103 entire disk is pulled in the background; the progress of the operation
1104 can be checked with blockjob. However, if --wait is specified, then
1105 this command will block until the operation completes, or cancel the
1106 operation if the optional timeout in seconds elapses or SIGINT is sent
1107 (usually with Ctrl-C). Using --verbose along with --wait will produce
1108 periodic status updates. If job cancellation is triggered, --async
1109 will return control to the user as fast as possible, otherwise the com‐
1110 mand may continue to block a little while longer until the job is done
1111 cleaning up.
1112
1113 Using the --keep-relative flag will keep the backing chain names rela‐
1114 tive.
1115
1116 path specifies fully-qualified path of the disk; it corresponds to a
1117 unique target name (<target dev='name'/>) or source file (<source
1118 file='name'/>) for one of the disk devices attached to domain (see also
1119 domblklist for listing these names). bandwidth specifies copying band‐
1120 width limit in MiB/s. For further information on the bandwidth argument
1121 see the corresponding section for the blockjob command.
1122
1123 blockresize
1124 Syntax:
1125
1126 blockresize domain path size
1127
1128 Resize a block device of domain while the domain is running, path spec‐
1129 ifies the absolute path of the block device; it corresponds to a unique
1130 target name (<target dev='name'/>) or source file (<source
1131 file='name'/>) for one of the disk devices attached to domain (see also
1132 domblklist for listing these names).
1133
1134 size is a scaled integer (see NOTES above) which defaults to KiB
1135 (blocks of 1024 bytes) if there is no suffix. You must use a suffix of
1136 "B" to get bytes (note that for historical reasons, this differs from
1137 vol-resize which defaults to bytes without a suffix).
1138
1139 console
1140 Syntax:
1141
1142 console domain [devname] [--safe] [--force]
1143
1144 Connect the virtual serial console for the guest. The optional devname
1145 parameter refers to the device alias of an alternate console, serial or
1146 parallel device configured for the guest. If omitted, the primary con‐
1147 sole will be opened.
1148
1149 If the flag --safe is specified, the connection is only attempted if
1150 the driver supports safe console handling. This flag specifies that the
1151 server has to ensure exclusive access to console devices. Optionally
1152 the --force flag may be specified, requesting to disconnect any exist‐
1153 ing sessions, such as in a case of a broken connection.
1154
1155 cpu-stats
1156 Syntax:
1157
1158 cpu-stats domain [--total] [start] [count]
1159
1160 Provide cpu statistics information of a domain. The domain should be
1161 running. Default it shows stats for all CPUs, and a total. Use --total
1162 for only the total stats, start for only the per-cpu stats of the CPUs
1163 from start, count for only count CPUs' stats.
1164
1165 create
1166 Syntax:
1167
1168 create FILE [--console] [--paused] [--autodestroy]
1169 [--pass-fds N,M,...] [--validate]
1170
1171 Create a domain from an XML <file>. Optionally, --validate option can
1172 be passed to validate the format of the input XML file against an in‐
1173 ternal RNG schema (identical to using virt-xml-validate(1) tool). Do‐
1174 mains created using this command are going to be either transient (tem‐
1175 porary ones that will vanish once destroyed) or existing persistent
1176 guests that will run with one-time use configuration, leaving the per‐
1177 sistent XML untouched (this can come handy during an automated testing
1178 of various configurations all based on the original XML). See the ex‐
1179 ample below for usage demonstration.
1180
1181 The domain will be paused if the --paused option is used and supported
1182 by the driver; otherwise it will be running. If --console is requested,
1183 attach to the console after creation. If --autodestroy is requested,
1184 then the guest will be automatically destroyed when virsh closes its
1185 connection to libvirt, or otherwise exits.
1186
1187 If --pass-fds is specified, the argument is a comma separated list of
1188 open file descriptors which should be pass on into the guest. The file
1189 descriptors will be re-numbered in the guest, starting from 3. This is
1190 only supported with container based virtualization.
1191
1192 Example:
1193
1194 1. prepare a template from an existing domain (skip directly to 3a if
1195 writing one from scratch)
1196
1197 # virsh dumpxml <domain> > domain.xml
1198
1199 2. edit the template using an editor of your choice and:
1200
1201 a. DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or
1202
1203 b. DON'T CHANGE! either <name> or <uuid>
1204
1205 # $EDITOR domain.xml
1206
1207 3. create a domain from domain.xml, depending on whether following 2a
1208 or 2b respectively:
1209
1210 a. the domain is going to be transient
1211
1212 b. an existing persistent guest will run with a modified one-time
1213 configuration
1214
1215 # virsh create domain.xml
1216
1217 define
1218 Syntax:
1219
1220 define FILE [--validate]
1221
1222 Define a domain from an XML <file>. Optionally, the format of the input
1223 XML file can be validated against an internal RNG schema with --vali‐
1224 date (identical to using virt-xml-validate(1) tool). The domain defini‐
1225 tion is registered but not started. If domain is already running, the
1226 changes will take effect on the next boot.
1227
1228 desc
1229 Syntax:
1230
1231 desc domain [[--live] [--config] |
1232 [--current]] [--title] [--edit] [--new-desc
1233 New description or title message]
1234
1235 Show or modify description and title of a domain. These values are user
1236 fields that allow storing arbitrary textual data to allow easy identi‐
1237 fication of domains. Title should be short, although it's not enforced.
1238 (See also metadata that works with XML based domain metadata.)
1239
1240 Flags --live or --config select whether this command works on live or
1241 persistent definitions of the domain. If both --live and --config are
1242 specified, the --config option takes precedence on getting the current
1243 description and both live configuration and config are updated while
1244 setting the description. --current is exclusive and implied if none of
1245 these was specified.
1246
1247 Flag --edit specifies that an editor with the contents of current de‐
1248 scription or title should be opened and the contents saved back after‐
1249 wards.
1250
1251 Flag --title selects operation on the title field instead of descrip‐
1252 tion.
1253
1254 If neither of --edit and --new-desc are specified the note or descrip‐
1255 tion is displayed instead of being modified.
1256
1257 destroy
1258 Syntax:
1259
1260 destroy domain [--graceful]
1261
1262 Immediately terminate the domain domain. This doesn't give the domain
1263 OS any chance to react, and it's the equivalent of ripping the power
1264 cord out on a physical machine. In most cases you will want to use the
1265 shutdown command instead. However, this does not delete any storage
1266 volumes used by the guest, and if the domain is persistent, it can be
1267 restarted later.
1268
1269 If domain is transient, then the metadata of any snapshots will be lost
1270 once the guest stops running, but the snapshot contents still exist,
1271 and a new domain with the same name and UUID can restore the snapshot
1272 metadata with snapshot-create. Similarly, the metadata of any check‐
1273 points will be lost, but can be restored with checkpoint-create.
1274
1275 If --graceful is specified, don't resort to extreme measures (e.g.
1276 SIGKILL) when the guest doesn't stop after a reasonable timeout; return
1277 an error instead.
1278
1279 domblkerror
1280 Syntax:
1281
1282 domblkerror domain
1283
1284 Show errors on block devices. This command usually comes handy when
1285 domstate command says that a domain was paused due to I/O error. The
1286 domblkerror command lists all block devices in error state and the er‐
1287 ror seen on each of them.
1288
1289 domblkinfo
1290 Syntax:
1291
1292 domblkinfo domain [block-device --all] [--human]
1293
1294 Get block device size info for a domain. A block-device corresponds to
1295 a unique target name (<target dev='name'/>) or source file (<source
1296 file='name'/>) for one of the disk devices attached to domain (see also
1297 domblklist for listing these names). If --human is set, the output will
1298 have a human readable output. If --all is set, the output will be a
1299 table showing all block devices size info associated with domain. The
1300 --all option takes precedence of the others.
1301
1302 domblklist
1303 Syntax:
1304
1305 domblklist domain [--inactive] [--details]
1306
1307 Print a table showing the brief information of all block devices asso‐
1308 ciated with domain. If --inactive is specified, query the block devices
1309 that will be used on the next boot, rather than those currently in use
1310 by a running domain. If --details is specified, disk type and device
1311 value will also be printed. Other contexts that require a block device
1312 name (such as domblkinfo or snapshot-create for disk snapshots) will
1313 accept either target or unique source names printed by this command.
1314
1315 domblkstat
1316 Syntax:
1317
1318 domblkstat domain [block-device] [--human]
1319
1320 Get device block stats for a running domain. A block-device corre‐
1321 sponds to a unique target name (<target dev='name'/>) or source file
1322 (<source file='name'/>) for one of the disk devices attached to domain
1323 (see also domblklist for listing these names). On a LXC or QEMU domain,
1324 omitting the block-device yields device block stats summarily for the
1325 entire domain.
1326
1327 Use --human for a more human readable output.
1328
1329 Availability of these fields depends on hypervisor. Unsupported fields
1330 are missing from the output. Other fields may appear if communicating
1331 with a newer version of libvirtd.
1332
1333 Explanation of fields (fields appear in the following order):
1334
1335 • rd_req - count of read operations
1336
1337 • rd_bytes - count of read bytes
1338
1339 • wr_req - count of write operations
1340
1341 • wr_bytes - count of written bytes
1342
1343 • errs - error count
1344
1345 • flush_operations - count of flush operations
1346
1347 • rd_total_times - total time read operations took (ns)
1348
1349 • wr_total_times - total time write operations took (ns)
1350
1351 • flush_total_times - total time flush operations took (ns)
1352
1353 • <-- other fields provided by hypervisor -->
1354
1355 domblkthreshold
1356 Syntax:
1357
1358 domblkthreshold domain dev threshold
1359
1360 Set the threshold value for delivering the block-threshold event. dev
1361 specifies the disk device target or backing chain element of given de‐
1362 vice using the 'target[1]' syntax. threshold is a scaled value of the
1363 offset. If the block device should write beyond that offset the event
1364 will be delivered.
1365
1366 domcontrol
1367 Syntax:
1368
1369 domcontrol domain
1370
1371 Returns state of an interface to VMM used to control a domain. For
1372 states other than "ok" or "error" the command also prints number of
1373 seconds elapsed since the control interface entered its current state.
1374
1375 domdirtyrate-calc
1376 Syntax:
1377
1378 domdirtyrate-calc <domain> [--seconds <sec>]
1379
1380 Calculate an active domain's memory dirty rate which may be expected by
1381 user in order to decide whether it's proper to be migrated out or not.
1382 The seconds parameter can be used to calculate dirty rate in a specific
1383 time which allows 60s at most now and would be default to 1s if miss‐
1384 ing. The calculated dirty rate information is available by calling
1385 'domstats --dirtyrate'.
1386
1387 domdisplay
1388 Syntax:
1389
1390 domdisplay domain [--include-password] [[--type] type] [--all]
1391
1392 Output a URI which can be used to connect to the graphical display of
1393 the domain via VNC, SPICE or RDP. The particular graphical display
1394 type can be selected using the type parameter (e.g. "vnc", "spice",
1395 "rdp"). If --include-password is specified, the SPICE channel password
1396 will be included in the URI. If --all is specified, then all show all
1397 possible graphical displays, for a VM could have more than one graphi‐
1398 cal displays.
1399
1400 domfsfreeze
1401 Syntax:
1402
1403 domfsfreeze domain [[--mountpoint] mountpoint...]
1404
1405 Freeze mounted filesystems within a running domain to prepare for con‐
1406 sistent snapshots.
1407
1408 The --mountpoint option takes a parameter mountpoint, which is a mount
1409 point path of the filesystem to be frozen. This option can occur multi‐
1410 ple times. If this is not specified, every mounted filesystem is
1411 frozen.
1412
1413 Note: snapshot-create command has a --quiesce option to freeze and thaw
1414 the filesystems automatically to keep snapshots consistent. domfs‐
1415 freeze command is only needed when a user wants to utilize the native
1416 snapshot features of storage devices not supported by libvirt.
1417
1418 domfsinfo
1419 Syntax:
1420
1421 domfsinfo domain
1422
1423 Show a list of mounted filesystems within the running domain. The list
1424 contains mountpoints, names of a mounted device in the guest, filesys‐
1425 tem types, and unique target names used in the domain XML (<target
1426 dev='name'/>).
1427
1428 Note that this command requires a guest agent configured and running in
1429 the domain's guest OS.
1430
1431 domfsthaw
1432 Syntax:
1433
1434 domfsthaw domain [[--mountpoint] mountpoint...]
1435
1436 Thaw mounted filesystems within a running domain, which have been
1437 frozen by domfsfreeze command.
1438
1439 The --mountpoint option takes a parameter mountpoint, which is a mount
1440 point path of the filesystem to be thawed. This option can occur multi‐
1441 ple times. If this is not specified, every mounted filesystem is
1442 thawed.
1443
1444 domfstrim
1445 Syntax:
1446
1447 domfstrim domain [--minimum bytes] [--mountpoint mountPoint]
1448
1449 Issue a fstrim command on all mounted filesystems within a running do‐
1450 main. It discards blocks which are not in use by the filesystem. If
1451 --minimum bytes is specified, it tells guest kernel length of contigu‐
1452 ous free range. Smaller than this may be ignored (this is a hint and
1453 the guest may not respect it). By increasing this value, the fstrim op‐
1454 eration will complete more quickly for filesystems with badly frag‐
1455 mented free space, although not all blocks will be discarded. The de‐
1456 fault value is zero, meaning "discard every free block". Moreover, if a
1457 user wants to trim only one mount point, it can be specified via op‐
1458 tional --mountpoint parameter.
1459
1460 domhostname
1461 Syntax:
1462
1463 domhostname domain [--source lease|agent]
1464
1465 Returns the hostname of a domain, if the hypervisor makes it available.
1466
1467 The --source argument specifies what data source to use for the host‐
1468 names, currently 'lease' to read DHCP leases or 'agent' to query the
1469 guest OS via an agent. If unspecified, driver returns the default
1470 method available (some drivers support only one type of source).
1471
1472 domid
1473 Syntax:
1474
1475 domid domain-name-or-uuid
1476
1477 Convert a domain name (or UUID) to a domain id
1478
1479 domif-getlink
1480 Syntax:
1481
1482 domif-getlink domain interface-device [--config]
1483
1484 Query link state of the domain's virtual interface. If --config is
1485 specified, query the persistent configuration, for compatibility pur‐
1486 poses, --persistent is alias of --config.
1487
1488 interface-device can be the interface's target name or the MAC address.
1489
1490 domif-setlink
1491 Syntax:
1492
1493 domif-setlink domain interface-device state [--config]
1494
1495 Modify link state of the domain's virtual interface. Possible values
1496 for state are "up" and "down". If --config is specified, only the per‐
1497 sistent configuration of the domain is modified, for compatibility pur‐
1498 poses, --persistent is alias of --config. interface-device can be the
1499 interface's target name or the MAC address.
1500
1501 domifaddr
1502 Syntax:
1503
1504 domifaddr domain [interface] [--full]
1505 [--source lease|agent|arp]
1506
1507 Get a list of interfaces of a running domain along with their IP and
1508 MAC addresses, or limited output just for one interface if interface is
1509 specified. Note that interface can be driver dependent, it can be the
1510 name within guest OS or the name you would see in domain XML. Moreover,
1511 the whole command may require a guest agent to be configured for the
1512 queried domain under some hypervisors, notably QEMU.
1513
1514 If --full is specified, the interface name and MAC address is always
1515 displayed when the interface has multiple IP addresses or aliases; oth‐
1516 erwise, only the interface name and MAC address is displayed for the
1517 first name and MAC address with "-" for the others using the same name
1518 and MAC address.
1519
1520 The --source argument specifies what data source to use for the ad‐
1521 dresses, currently 'lease' to read DHCP leases, 'agent' to query the
1522 guest OS via an agent, or 'arp' to get IP from host's arp tables. If
1523 unspecified, 'lease' is the default.
1524
1525 backup-begin
1526 Syntax:
1527
1528 backup-begin domain [backupxml] [checkpointxml] [--reuse-external]
1529
1530 Begin a new backup job. If backupxml is omitted, this defaults to a
1531 full backup using a push model to filenames generated by libvirt; sup‐
1532 plying XML allows fine-tuning such as requesting an incremental backup
1533 relative to an earlier checkpoint, controlling which disks participate
1534 or which filenames are involved, or requesting the use of a pull model
1535 backup. The backup-dumpxml command shows any resulting values assigned
1536 by libvirt. For more information on backup XML, see:
1537 https://libvirt.org/formatbackup.html
1538
1539 If --reuse-external is used it instructs libvirt to reuse temporary and
1540 output files provided by the user in backupxml.
1541
1542 If checkpointxml is specified, a second file with a top-level element
1543 of domaincheckpoint is used to create a simultaneous checkpoint, for
1544 doing a later incremental backup relative to the time the backup was
1545 created. See checkpoint-create for more details on checkpoints.
1546
1547 This command returns as soon as possible, and the backup job runs in
1548 the background; the progress of a push model backup can be checked with
1549 domjobinfo or by waiting for an event with event (the progress of a
1550 pull model backup is under the control of whatever third party connects
1551 to the NBD export). The job is ended with domjobabort.
1552
1553 backup-dumpxml
1554 Syntax:
1555
1556 backup-dumpxml domain
1557
1558 Output XML describing the current backup job.
1559
1560 domiflist
1561 Syntax:
1562
1563 domiflist domain [--inactive]
1564
1565 Print a table showing the brief information of all virtual interfaces
1566 associated with domain. If --inactive is specified, query the virtual
1567 interfaces that will be used on the next boot, rather than those cur‐
1568 rently in use by a running domain. Other contexts that require a MAC
1569 address of virtual interface (such as detach-interface or
1570 domif-setlink) will accept the MAC address printed by this command.
1571
1572 domifstat
1573 Syntax:
1574
1575 domifstat domain interface-device
1576
1577 Get network interface stats for a running domain. The network interface
1578 stats are only available for interfaces that have a physical source in‐
1579 terface. This does not include, for example, a 'user' interface type
1580 since it is a virtual LAN with NAT to the outside world. interface-de‐
1581 vice can be the interface target by name or MAC address.
1582
1583 domiftune
1584 Syntax:
1585
1586 domiftune domain interface-device [[--config] [--live] | [--current]]
1587 [*--inbound average,peak,burst,floor*]
1588 [*--outbound average,peak,burst*]
1589
1590 Set or query the domain's network interface's bandwidth parameters.
1591 interface-device can be the interface's target name (<target
1592 dev='name'/>), or the MAC address.
1593
1594 If no --inbound or --outbound is specified, this command will query and
1595 show the bandwidth settings. Otherwise, it will set the inbound or out‐
1596 bound bandwidth. average,peak,burst,floor is the same as in command at‐
1597 tach-interface. Values for average, peak and floor are expressed in
1598 kilobytes per second, while burst is expressed in kilobytes in a single
1599 burst at peak speed as described in the Network XML documentation at
1600 https://libvirt.org/formatnetwork.html#elementQoS.
1601
1602 To clear inbound or outbound settings, use --inbound or --outbound re‐
1603 spectfully with average value of zero.
1604
1605 If --live is specified, affect a running guest. If --config is speci‐
1606 fied, affect the next start of a persistent guest. If --current is
1607 specified, it is equivalent to either --live or --config, depending on
1608 the current state of the guest. Both --live and --config flags may be
1609 given, but --current is exclusive. If no flag is specified, behavior is
1610 different depending on hypervisor.
1611
1612 dominfo
1613 Syntax:
1614
1615 dominfo domain
1616
1617 Returns basic information about the domain.
1618
1619 domjobabort
1620 Syntax:
1621
1622 domjobabort domain
1623
1624 Abort the currently running domain job.
1625
1626 domjobinfo
1627 Syntax:
1628
1629 domjobinfo domain [--completed [--keep-completed]] [--anystats] [--rawstats]
1630
1631 Returns information about jobs running on a domain. --completed tells
1632 virsh to return information about a recently finished job. Statistics
1633 of a completed job are automatically destroyed once read (unless
1634 --keep-completed is used) or when libvirtd is restarted.
1635
1636 Normally only statistics for running and successful completed jobs are
1637 printed. --anystats can be used to also display statistics for failed
1638 jobs.
1639
1640 In case --rawstats is used, all fields are printed as received from the
1641 server without any attempts to interpret the data. The "Job type:"
1642 field is special, since it's reported by the API and not part of stats.
1643
1644 Note that time information returned for completed migrations may be
1645 completely irrelevant unless both source and destination hosts have
1646 synchronized time (i.e., NTP daemon is running on both of them).
1647
1648 dommemstat
1649 Syntax:
1650
1651 dommemstat domain [--period seconds] [[--config] [--live] | [--current]]
1652
1653 Get memory stats for a running domain.
1654
1655 Availability of these fields depends on hypervisor. Unsupported fields
1656 are missing from the output. Other fields may appear if communicating
1657 with a newer version of libvirtd.
1658
1659 Explanation of fields:
1660
1661 • swap_in - The amount of data read from swap space (in KiB)
1662
1663 • swap_out - The amount of memory written out to swap space
1664 (in KiB)
1665
1666 • major_fault - The number of page faults where disk IO was re‐
1667 quired
1668
1669 • minor_fault - The number of other page faults
1670
1671 • unused - The amount of memory left unused by the system
1672 (in KiB)
1673
1674 • available - The amount of usable memory as seen by the domain
1675 (in KiB)
1676
1677 • actual - Current balloon value (in KiB)
1678
1679 • rss - Resident Set Size of the running domain's process
1680 (in KiB)
1681
1682 • usable - The amount of memory which can be reclaimed by
1683 balloon without causing host swapping (in KiB)
1684
1685 • last-update - Timestamp of the last update of statistics (in
1686 seconds)
1687
1688 • disk_caches - The amount of memory that can be reclaimed with‐
1689 out additional I/O, typically disk caches (in KiB)
1690
1691 • hugetlb_pgalloc - The number of successful huge page allocations
1692 initiated from within the domain
1693
1694 • hugetlb_pgfail - The number of failed huge page allocations initi‐
1695 ated from within the domain
1696
1697 For QEMU/KVM with a memory balloon, setting the optional --period to a
1698 value larger than 0 in seconds will allow the balloon driver to return
1699 additional statistics which will be displayed by subsequent dommemstat
1700 commands. Setting the --period to 0 will stop the balloon driver col‐
1701 lection, but does not clear the statistics in the balloon driver. Re‐
1702 quires at least QEMU/KVM 1.5 to be running on the host.
1703
1704 The --live, --config, and --current flags are only valid when using the
1705 --period option in order to set the collection period for the balloon
1706 driver. If --live is specified, only the running guest collection pe‐
1707 riod is affected. If --config is specified, affect the next start of a
1708 persistent guest. If --current is specified, it is equivalent to either
1709 --live or --config, depending on the current state of the guest.
1710
1711 Both --live and --config flags may be given, but --current is exclu‐
1712 sive. If no flag is specified, behavior is different depending on the
1713 guest state.
1714
1715 domname
1716 Syntax:
1717
1718 domname domain-id-or-uuid
1719
1720 Convert a domain Id (or UUID) to domain name
1721
1722 dompmsuspend
1723 Syntax:
1724
1725 dompmsuspend domain target [--duration]
1726
1727 Suspend a running domain into one of these states (possible target val‐
1728 ues):
1729
1730 • mem - equivalent of S3 ACPI state
1731
1732 • disk - equivalent of S4 ACPI state
1733
1734 • hybrid - RAM is saved to disk but not powered off
1735
1736 The --duration argument specifies number of seconds before the domain
1737 is woken up after it was suspended (see also dompmwakeup). Default is 0
1738 for unlimited suspend time. (This feature isn't currently supported by
1739 any hypervisor driver and 0 should be used.).
1740
1741 Note that this command requires a guest agent configured and running in
1742 the domain's guest OS.
1743
1744 Beware that at least for QEMU, the domain's process will be terminated
1745 when target disk is used and a new process will be launched when lib‐
1746 virt is asked to wake up the domain. As a result of this, any runtime
1747 changes, such as device hotplug or memory settings, are lost unless
1748 such changes were made with --config flag.
1749
1750 dompmwakeup
1751 Syntax:
1752
1753 dompmwakeup domain
1754
1755 Wakeup a domain from pmsuspended state (either suspended by dompmsus‐
1756 pend or from the guest itself). Injects a wakeup into the guest that is
1757 in pmsuspended state, rather than waiting for the previously requested
1758 duration (if any) to elapse. This operation does not necessarily fail
1759 if the domain is running.
1760
1761 domrename
1762 Syntax:
1763
1764 domrename domain new-name
1765
1766 Rename a domain. This command changes current domain name to the new
1767 name specified in the second argument.
1768
1769 Note: Domain must be inactive.
1770
1771 domstate
1772 Syntax:
1773
1774 domstate domain [--reason]
1775
1776 Returns state about a domain. --reason tells virsh to also print rea‐
1777 son for the state.
1778
1779 domstats
1780 Syntax:
1781
1782 domstats [--raw] [--enforce] [--backing] [--nowait] [--state]
1783 [--cpu-total] [--balloon] [--vcpu] [--interface]
1784 [--block] [--perf] [--iothread] [--memory] [--dirtyrate]
1785 [[--list-active] [--list-inactive]
1786 [--list-persistent] [--list-transient] [--list-running]y
1787 [--list-paused] [--list-shutoff] [--list-other]] | [domain ...]
1788
1789 Get statistics for multiple or all domains. Without any argument this
1790 command prints all available statistics for all domains.
1791
1792 The list of domains to gather stats for can be either limited by list‐
1793 ing the domains as a space separated list, or by specifying one of the
1794 filtering flags --list-NNN. (The approaches can't be combined.)
1795
1796 By default some of the returned fields may be converted to more human
1797 friendly values by a set of pretty-printers. To suppress this behavior
1798 use the --raw flag.
1799
1800 The individual statistics groups are selectable via specific flags. By
1801 default all supported statistics groups are returned. Supported statis‐
1802 tics groups flags are: --state, --cpu-total, --balloon, --vcpu, --in‐
1803 terface, --block, --perf, --iothread, --memory, --dirtyrate.
1804
1805 Note that - depending on the hypervisor type and version or the domain
1806 state - not all of the following statistics may be returned.
1807
1808 When selecting the --state group the following fields are returned:
1809
1810 • state.state - state of the VM, returned as number from virDomainState
1811 enum
1812
1813 • state.reason - reason for entering given state, returned as int from
1814 virDomain*Reason enum corresponding to given state
1815
1816 --cpu-total returns:
1817
1818 • cpu.time - total cpu time spent for this domain in nanoseconds
1819
1820 • cpu.user - user cpu time spent in nanoseconds
1821
1822 • cpu.system - system cpu time spent in nanoseconds
1823
1824 • cpu.haltpoll.success.time - cpu halt polling success time spent in
1825 nanoseconds
1826
1827 • cpu.haltpoll.fail.time - cpu halt polling fail time spent in nanosec‐
1828 onds
1829
1830 • cpu.cache.monitor.count - the number of cache monitors for this do‐
1831 main
1832
1833 • cpu.cache.monitor.<num>.name - the name of cache monitor <num>
1834
1835 • cpu.cache.monitor.<num>.vcpus - vcpu list of cache monitor <num>
1836
1837 • cpu.cache.monitor.<num>.bank.count - the number of cache banks in
1838 cache monitor <num>
1839
1840 • cpu.cache.monitor.<num>.bank.<index>.id - host allocated cache id for
1841 bank <index> in cache monitor <num>
1842
1843 • cpu.cache.monitor.<num>.bank.<index>.bytes - the number of bytes of
1844 last level cache that the domain is using on cache bank <index>
1845
1846 --balloon returns:
1847
1848 • balloon.current - the memory in KiB currently used
1849
1850 • balloon.maximum - the maximum memory in KiB allowed
1851
1852 • balloon.swap_in - the amount of data read from swap space (in KiB)
1853
1854 • balloon.swap_out - the amount of memory written out to swap space (in
1855 KiB)
1856
1857 • balloon.major_fault - the number of page faults when disk IO was re‐
1858 quired
1859
1860 • balloon.minor_fault - the number of other page faults
1861
1862 • balloon.unused - the amount of memory left unused by the system (in
1863 KiB)
1864
1865 • balloon.available - the amount of usable memory as seen by the domain
1866 (in KiB)
1867
1868 • balloon.rss - Resident Set Size of running domain's process (in KiB)
1869
1870 • balloon.usable - the amount of memory which can be reclaimed by bal‐
1871 loon without causing host swapping (in KiB)
1872
1873 • balloon.last-update - timestamp of the last update of statistics (in
1874 seconds)
1875
1876 • balloon.disk_caches - the amount of memory that can be reclaimed
1877 without additional I/O, typically disk (in KiB)
1878
1879 • balloon.hugetlb_pgalloc - the number of successful huge page alloca‐
1880 tions from inside the domain via virtio balloon
1881
1882 • balloon.hugetlb_pgfail - the number of failed huge page allocations
1883 from inside the domain via virtio balloon
1884
1885 --vcpu returns:
1886
1887 • vcpu.current - current number of online virtual CPUs
1888
1889 • vcpu.maximum - maximum number of online virtual CPUs
1890
1891 • vcpu.<num>.state - state of the virtual CPU <num>, as number from
1892 virVcpuState enum
1893
1894 • vcpu.<num>.time - virtual cpu time spent by virtual CPU <num> (in mi‐
1895 croseconds)
1896
1897 • vcpu.<num>.wait - virtual cpu time spent by virtual CPU <num> waiting
1898 on I/O (in microseconds)
1899
1900 • vcpu.<num>.halted - virtual CPU <num> is halted: yes or no (may indi‐
1901 cate the processor is idle or even disabled, depending on the archi‐
1902 tecture)
1903
1904 • vcpu.<num>.delay - time the vCPU <num> thread was enqueued by the
1905 host scheduler, but was waiting in the queue instead of running. Ex‐
1906 posed to the VM as a steal time.
1907
1908 --interface returns:
1909
1910 • net.count - number of network interfaces on this domain
1911
1912 • net.<num>.name - name of the interface <num>
1913
1914 • net.<num>.rx.bytes - number of bytes received
1915
1916 • net.<num>.rx.pkts - number of packets received
1917
1918 • net.<num>.rx.errs - number of receive errors
1919
1920 • net.<num>.rx.drop - number of receive packets dropped
1921
1922 • net.<num>.tx.bytes - number of bytes transmitted
1923
1924 • net.<num>.tx.pkts - number of packets transmitted
1925
1926 • net.<num>.tx.errs - number of transmission errors
1927
1928 • net.<num>.tx.drop - number of transmit packets dropped
1929
1930 --perf returns the statistics of all enabled perf events:
1931
1932 • perf.cmt - the cache usage in Byte currently used
1933
1934 • perf.mbmt - total system bandwidth from one level of cache
1935
1936 • perf.mbml - bandwidth of memory traffic for a memory controller
1937
1938 • perf.cpu_cycles - the count of cpu cycles (total/elapsed)
1939
1940 • perf.instructions - the count of instructions
1941
1942 • perf.cache_references - the count of cache hits
1943
1944 • perf.cache_misses - the count of caches misses
1945
1946 • perf.branch_instructions - the count of branch instructions
1947
1948 • perf.branch_misses - the count of branch misses
1949
1950 • perf.bus_cycles - the count of bus cycles
1951
1952 • perf.stalled_cycles_frontend - the count of stalled frontend cpu cy‐
1953 cles
1954
1955 • perf.stalled_cycles_backend - the count of stalled backend cpu cycles
1956
1957 • perf.ref_cpu_cycles - the count of ref cpu cycles
1958
1959 • perf.cpu_clock - the count of cpu clock time
1960
1961 • perf.task_clock - the count of task clock time
1962
1963 • perf.page_faults - the count of page faults
1964
1965 • perf.context_switches - the count of context switches
1966
1967 • perf.cpu_migrations - the count of cpu migrations
1968
1969 • perf.page_faults_min - the count of minor page faults
1970
1971 • perf.page_faults_maj - the count of major page faults
1972
1973 • perf.alignment_faults - the count of alignment faults
1974
1975 • perf.emulation_faults - the count of emulation faults
1976
1977 See the perf command for more details about each event.
1978
1979 --block returns information about disks associated with each domain.
1980 Using the --backing flag extends this information to cover all re‐
1981 sources in the backing chain, rather than the default of limiting in‐
1982 formation to the active layer for each guest disk. Information listed
1983 includes:
1984
1985 • block.count - number of block devices being listed
1986
1987 • block.<num>.name - name of the target of the block device <num> (the
1988 same name for multiple entries if --backing is present)
1989
1990 • block.<num>.backingIndex - when --backing is present, matches up with
1991 the <backingStore> index listed in domain XML for backing files
1992
1993 • block.<num>.path - file source of block device <num>, if it is a lo‐
1994 cal file or block device
1995
1996 • block.<num>.rd.reqs - number of read requests
1997
1998 • block.<num>.rd.bytes - number of read bytes
1999
2000 • block.<num>.rd.times - total time (ns) spent on reads
2001
2002 • block.<num>.wr.reqs - number of write requests
2003
2004 • block.<num>.wr.bytes - number of written bytes
2005
2006 • block.<num>.wr.times - total time (ns) spent on writes
2007
2008 • block.<num>.fl.reqs - total flush requests
2009
2010 • block.<num>.fl.times - total time (ns) spent on cache flushing
2011
2012 • block.<num>.errors - Xen only: the 'oo_req' value
2013
2014 • block.<num>.allocation - offset of highest written sector in bytes
2015
2016 • block.<num>.capacity - logical size of source file in bytes
2017
2018 • block.<num>.physical - physical size of source file in bytes
2019
2020 • block.<num>.threshold - threshold (in bytes) for delivering the
2021 VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event. See domblkthreshold.
2022
2023 --iothread returns information about IOThreads on the running guest if
2024 supported by the hypervisor.
2025
2026 The "poll-max-ns" for each thread is the maximum nanoseconds to allow
2027 each polling interval to occur. A polling interval is a period of time
2028 allowed for a thread to process data before being the guest gives up
2029 its CPU quantum back to the host. A value set too small will not allow
2030 the IOThread to run long enough on a CPU to process data. A value set
2031 too high will consume too much CPU time per IOThread failing to allow
2032 other threads running on the CPU to get time. The polling interval is
2033 not available for statistical purposes.
2034
2035 •
2036
2037 iothread.count - maximum number of IOThreads in the subsequent list
2038 as unsigned int. Each IOThread in the list will will use it's
2039 iothread_id value as the <id>. There may be fewer <id> entries
2040 than the iothread.count value if the polling values are not
2041 supported.
2042
2043 • iothread.<id>.poll-max-ns - maximum polling time in nanoseconds used
2044 by the <id> IOThread. A value of 0 (zero) indicates polling is dis‐
2045 abled.
2046
2047 • iothread.<id>.poll-grow - polling time grow value. A value of 0
2048 (zero) growth is managed by the hypervisor.
2049
2050 • iothread.<id>.poll-shrink - polling time shrink value. A value of
2051 (zero) indicates shrink is managed by hypervisor.
2052
2053 --memory returns:
2054
2055 • memory.bandwidth.monitor.count - the number of memory bandwidth moni‐
2056 tors for this domain
2057
2058 • memory.bandwidth.monitor.<num>.name - the name of monitor <num>
2059
2060 • memory.bandwidth.monitor.<num>.vcpus - the vcpu list of monitor <num>
2061
2062 •
2063
2064 memory.bandwidth.monitor.<num>.node.count - the number of memory
2065 controller in monitor <num>
2066
2067 • memory.bandwidth.monitor.<num>.node.<index>.id - host allocated mem‐
2068 ory controller id for controller <index> of monitor <num>
2069
2070 • memory.bandwidth.monitor.<num>.node.<index>.bytes.local - the accumu‐
2071 lative bytes consumed by @vcpus that passing through the memory con‐
2072 troller in the same processor that the scheduled host CPU belongs to.
2073
2074 • memory.bandwidth.monitor.<num>.node.<index>.bytes.total - the total
2075 bytes consumed by @vcpus that passing through all memory controllers,
2076 either local or remote controller.
2077
2078 --dirtyrate returns:
2079
2080 • dirtyrate.calc_status - the status of last memory dirty rate calcula‐
2081 tion, returned as number from virDomainDirtyRateStatus enum.
2082
2083 • dirtyrate.calc_start_time - the start time of last memory dirty rate
2084 calculation.
2085
2086 • dirtyrate.calc_period - the period of last memory dirty rate calcula‐
2087 tion.
2088
2089 • dirtyrate.megabytes_per_second - the calculated memory dirty rate in
2090 MiB/s.
2091
2092 Selecting a specific statistics groups doesn't guarantee that the dae‐
2093 mon supports the selected group of stats. Flag --enforce forces the
2094 command to fail if the daemon doesn't support the selected group.
2095
2096 When collecting stats libvirtd may wait for some time if there's al‐
2097 ready another job running on given domain for it to finish. This may
2098 cause unnecessary delay in delivering stats. Using --nowait suppresses
2099 this behaviour. On the other hand some statistics might be missing for
2100 such domain.
2101
2102 domtime
2103 Syntax:
2104
2105 domtime domain { [--now] [--pretty] [--sync] [--time time] }
2106
2107 Gets or sets the domain's system time. When run without any arguments
2108 (but domain), the current domain's system time is printed out. The
2109 --pretty modifier can be used to print the time in more human readable
2110 form.
2111
2112 When --time time is specified, the domain's time is not gotten but set
2113 instead. The --now modifier acts like if it was an alias for --time
2114 $now, which means it sets the time that is currently on the host virsh
2115 is running at. In both cases (setting and getting), time is in seconds
2116 relative to Epoch of 1970-01-01 in UTC. The --sync modifies the set
2117 behavior a bit: The time passed is ignored, but the time to set is read
2118 from domain's RTC instead. Please note, that some hypervisors may re‐
2119 quire a guest agent to be configured in order to get or set the guest
2120 time.
2121
2122 domuuid
2123 Syntax:
2124
2125 domuuid domain-name-or-id
2126
2127 Convert a domain name or id to domain UUID
2128
2129 domxml-from-native
2130 Syntax:
2131
2132 domxml-from-native format config
2133
2134 Convert the file config in the native guest configuration format named
2135 by format to a domain XML format. For QEMU/KVM hypervisor, the format
2136 argument must be qemu-argv. For Xen hypervisor, the format argument may
2137 be xen-xm, xen-xl, or xen-sxpr. For LXC hypervisor, the format argument
2138 must be lxc-tools. For VMware/ESX hypervisor, the format argument must
2139 be vmware-vmx. For the Bhyve hypervisor, the format argument must be
2140 bhyve-argv.
2141
2142 domxml-to-native
2143 Syntax:
2144
2145 domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-uuid }
2146
2147 Convert the file xml into domain XML format or convert an existing
2148 --domain to the native guest configuration format named by format. The
2149 xml and --domain arguments are mutually exclusive. For the types of
2150 format argument, refer to domxml-from-native.
2151
2152 dump
2153 Syntax:
2154
2155 dump domain corefilepath [--bypass-cache]
2156 { [--live] | [--crash] | [--reset] }
2157 [--verbose] [--memory-only] [--format string]
2158
2159 Dumps the core of a domain to a file for analysis. If --live is speci‐
2160 fied, the domain continues to run until the core dump is complete,
2161 rather than pausing up front. If --crash is specified, the domain is
2162 halted with a crashed status, rather than merely left in a paused
2163 state. If --reset is specified, the domain is reset after successful
2164 dump. Note, these three switches are mutually exclusive. If --by‐
2165 pass-cache is specified, the save will avoid the file system cache, al‐
2166 though this may slow down the operation. If --memory-only is speci‐
2167 fied, the file is elf file, and will only include domain's memory and
2168 cpu common register value. It is very useful if the domain uses host
2169 devices directly. --format string is used to specify the format of
2170 'memory-only' dump, and string can be one of: elf,
2171 kdump-zlib(kdump-compressed format with zlib-compressed),
2172 kdump-lzo(kdump-compressed format with lzo-compressed),
2173 kdump-snappy(kdump-compressed format with snappy-compressed),
2174 win-dmp(Windows full crashdump format).
2175
2176 The progress may be monitored using domjobinfo virsh command and can‐
2177 celed with domjobabort command (sent by another virsh instance). An‐
2178 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2179 process running dump command. --verbose displays the progress of dump.
2180
2181 NOTE: Some hypervisors may require the user to manually ensure proper
2182 permissions on file and path specified by argument corefilepath.
2183
2184 NOTE: Crash dump in a old kvmdump format is being obsolete and cannot
2185 be loaded and processed by crash utility since its version 6.1.0. A
2186 --memory-only option is required in order to produce valid ELF file
2187 which can be later processed by the crash utility.
2188
2189 dumpxml
2190 Syntax:
2191
2192 dumpxml domain [--inactive] [--security-info] [--update-cpu] [--migratable]
2193
2194 Output the domain information as an XML dump to stdout, this format can
2195 be used by the create command. Additional options affecting the XML
2196 dump may be used. --inactive tells virsh to dump domain configuration
2197 that will be used on next start of the domain as opposed to the current
2198 domain configuration. Using --security-info will also include security
2199 sensitive information in the XML dump. --update-cpu updates domain CPU
2200 requirements according to host CPU. With --migratable one can request
2201 an XML that is suitable for migrations, i.e., compatible with older
2202 libvirt releases and possibly amended with internal run-time options.
2203 This option may automatically enable other options (--update-cpu, --se‐
2204 curity-info, ...) as necessary.
2205
2206 edit
2207 Syntax:
2208
2209 edit domain
2210
2211 Edit the XML configuration file for a domain, which will affect the
2212 next boot of the guest.
2213
2214 This is equivalent to:
2215
2216 virsh dumpxml --inactive --security-info domain > domain.xml
2217 vi domain.xml (or make changes with your other text editor)
2218 virsh define domain.xml
2219
2220 except that it does some error checking.
2221
2222 The editor used can be supplied by the $VISUAL or $EDITOR environment
2223 variables, and defaults to vi.
2224
2225 emulatorpin
2226 Syntax:
2227
2228 emulatorpin domain [cpulist] [[--live] [--config] | [--current]]
2229
2230 Query or change the pinning of domain's emulator threads to host physi‐
2231 cal CPUs.
2232
2233 See vcpupin for cpulist.
2234
2235 If --live is specified, affect a running guest. If --config is speci‐
2236 fied, affect the next start of a persistent guest. If --current is
2237 specified, it is equivalent to either --live or --config, depending on
2238 the current state of the guest. Both --live and --config flags may be
2239 given if cpulist is present, but --current is exclusive. If no flag is
2240 specified, behavior is different depending on hypervisor.
2241
2242 event
2243 Syntax:
2244
2245 event {[domain] { event | --all } [--loop] [--timeout seconds] [--timestamp] | --list}
2246
2247 Wait for a class of domain events to occur, and print appropriate de‐
2248 tails of events as they happen. The events can optionally be filtered
2249 by domain. Using --list as the only argument will provide a list of
2250 possible event values known by this client, although the connection
2251 might not allow registering for all these events. It is also possible
2252 to use --all instead of event to register for all possible event types
2253 at once.
2254
2255 By default, this command is one-shot, and returns success once an event
2256 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
2257 If --timeout is specified, the command gives up waiting for events af‐
2258 ter seconds have elapsed. With --loop, the command prints all events
2259 until a timeout or interrupt key.
2260
2261 When --timestamp is used, a human-readable timestamp will be printed
2262 before the event.
2263
2264 get-user-sshkeys
2265 Syntax:
2266
2267 get-user-sshkeys domain user
2268
2269 Print SSH authorized keys for given user in the guest domain. Please
2270 note, that an entry in the file has internal structure as defined by
2271 sshd(8) and virsh/libvirt does handle keys as opaque strings, i.e. does
2272 not interpret them.
2273
2274 guest-agent-timeout
2275 Syntax:
2276
2277 guest-agent-timeout domain [--timeout value]
2278
2279 Set how long to wait for a response from guest agent commands. By de‐
2280 fault, agent commands block forever waiting for a response. value must
2281 be a positive value (wait for given amount of seconds) or one of the
2282 following values:
2283
2284 • -2 - block forever waiting for a result (used when --timeout is omit‐
2285 ted),
2286
2287 • -1 - reset timeout to the default value (currently defined as 5 sec‐
2288 onds in libvirt daemon),
2289
2290 • 0 - do not wait at all,
2291
2292 guestinfo
2293 Syntax:
2294
2295 guestinfo domain [--user] [--os] [--timezone] [--hostname] [--filesystem]
2296 [--disk]
2297
2298 Print information about the guest from the point of view of the guest
2299 agent. Note that this command requires a guest agent to be configured
2300 and running in the domain's guest OS.
2301
2302 When run without any arguments, this command prints all information
2303 types that are supported by the guest agent. You can limit the types of
2304 information that are returned by specifying one or more flags. If a
2305 requested information type is not supported, the processes will provide
2306 an exit code of 1. Available information types flags are --user, --os,
2307 --timezone, --hostname, --filesystem and --disk.
2308
2309 Note that depending on the hypervisor type and the version of the guest
2310 agent running within the domain, not all of the following information
2311 may be returned.
2312
2313 When selecting the --user information type, the following fields may be
2314 returned:
2315
2316 • user.count - the number of active users on this domain
2317
2318 • user.<num>.name - username of user <num>
2319
2320 • user.<num>.domain - domain of the user <num> (may only be present on
2321 certain guets types)
2322
2323 • user.<num>.login-time - the login time of user <num> in milliseconds
2324 since the epoch
2325
2326 --os returns:
2327
2328 • os.id - a string identifying the operating system
2329
2330 • os.name - the name of the operating system
2331
2332 • os.pretty-name - a pretty name for the operating system
2333
2334 • os.version - the version of the operating system
2335
2336 • os.version-id - the version id of the operating system
2337
2338 • os.kernel-release - the release of the operating system kernel
2339
2340 • os.kernel-version - the version of the operating system kernel
2341
2342 • os.machine - the machine hardware name
2343
2344 • os.variant - a specific variant or edition of the operating system
2345
2346 • os.variant-id - the id for a specific variant or edition of the oper‐
2347 ating system
2348
2349 --timezone returns:
2350
2351 • timezone.name - the name of the timezone
2352
2353 • timezone.offset - the offset to UTC in seconds
2354
2355 --hostname returns:
2356
2357 • hostname - the hostname of the domain
2358
2359 --filesystem returns:
2360
2361 • fs.count - the number of filesystems defined on this domain
2362
2363 • fs.<num>.mountpoint - the path to the mount point for filesystem
2364 <num>
2365
2366 • fs.<num>.name - device name in the guest (e.g. sda1) for filesystem
2367 <num>
2368
2369 • fs.<num>.fstype - the type of filesystem <num>
2370
2371 • fs.<num>.total-bytes - the total size of filesystem <num>
2372
2373 • fs.<num>.used-bytes - the number of bytes used in filesystem <num>
2374
2375 • fs.<num>.disk.count - the number of disks targeted by filesystem
2376 <num>
2377
2378 • fs.<num>.disk.<num>.alias - the device alias of disk <num> (e.g. sda)
2379
2380 • fs.<num>.disk.<num>.serial - the serial number of disk <num>
2381
2382 • fs.<num>.disk.<num>.device - the device node of disk <num>
2383
2384 --disk returns:
2385
2386 • disk.count - the number of disks defined on this domain
2387
2388 • disk.<num>.name - device node (Linux) or device UNC (Windows)
2389
2390 • disk.<num>.partition - whether this is a partition or disk
2391
2392 • disk.<num>.dependency.count - the number of device dependencies
2393
2394 • disk.<num>.dependency.<num>.name - a dependency name
2395
2396 • disk.<num>.serial - optional disk serial number
2397
2398 • disk.<num>.alias - the device alias of the disk (e.g. sda)
2399
2400 • disk.<num>.guest_alias - optional alias assigned to the disk
2401
2402 guestvcpus
2403 Syntax:
2404
2405 guestvcpus domain [[--enable] | [--disable]] [cpulist]
2406
2407 Query or change state of vCPUs from guest's point of view using the
2408 guest agent. When invoked without cpulist the guest is queried for
2409 available guest vCPUs, their state and possibility to be offlined.
2410
2411 If cpulist is provided then one of --enable or --disable must be pro‐
2412 vided too. The desired operation is then executed on the domain.
2413
2414 See vcpupin for information on cpulist.
2415
2416 iothreadadd
2417 Syntax:
2418
2419 iothreadadd domain iothread_id [[--config] [--live] | [--current]]
2420
2421 Add a new IOThread to the domain using the specified iothread_id. If
2422 the iothread_id already exists, the command will fail. The iothread_id
2423 must be greater than zero.
2424
2425 If --live is specified, affect a running guest. If the guest is not
2426 running an error is returned. If --config is specified, affect the
2427 next start of a persistent guest. If --current is specified, it is
2428 equivalent to either --live or --config, depending on the current state
2429 of the guest.
2430
2431 iothreaddel
2432 Syntax:
2433
2434 iothreaddel domain iothread_id [[--config] [--live] | [--current]]
2435
2436 Delete an IOThread from the domain using the specified iothread_id. If
2437 an IOThread is currently assigned to a disk resource such as via the
2438 attach-disk command, then the attempt to remove the IOThread will fail.
2439 If the iothread_id does not exist an error will occur.
2440
2441 If --live is specified, affect a running guest. If the guest is not
2442 running an error is returned. If --config is specified, affect the
2443 next start of a persistent guest. If --current is specified, it is
2444 equivalent to either --live or --config, depending on the current state
2445 of the guest.
2446
2447 iothreadinfo
2448 Syntax:
2449
2450 iothreadinfo domain [[--live] [--config] | [--current]]
2451
2452 Display basic domain IOThreads information including the IOThread ID
2453 and the CPU Affinity for each IOThread.
2454
2455 If --live is specified, get the IOThreads data from the running guest.
2456 If the guest is not running, an error is returned. If --config is
2457 specified, get the IOThreads data from the next start of a persistent
2458 guest. If --current is specified or --live and --config are not speci‐
2459 fied, then get the IOThread data based on the current guest state,
2460 which can either be live or offline.
2461
2462 iothreadpin
2463 Syntax:
2464
2465 iothreadpin domain iothread cpulist [[--live] [--config] | [--current]]
2466
2467 Change the pinning of a domain IOThread to host physical CPUs. In order
2468 to retrieve a list of all IOThreads, use iothreadinfo. To pin an io‐
2469 thread specify the cpulist desired for the IOThread ID as listed in the
2470 iothreadinfo output.
2471
2472 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
2473 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
2474 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
2475 clusive. If you want to reset iothreadpin setting, that is, to pin an
2476 iothread to all physical cpus, simply specify 'r' as a cpulist.
2477
2478 If --live is specified, affect a running guest. If the guest is not
2479 running, an error is returned. If --config is specified, affect the
2480 next start of a persistent guest. If --current is specified, it is
2481 equivalent to either --live or --config, depending on the current state
2482 of the guest. Both --live and --config flags may be given if cpulist
2483 is present, but --current is exclusive. If no flag is specified, be‐
2484 havior is different depending on hypervisor.
2485
2486 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
2487 cal to "9-14,0-7,15" but not identical to "^8,0-15".
2488
2489 iothreadset
2490 Syntax:
2491
2492 iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor]
2493 [--poll-shrink divisor]]
2494 [[--config] [--live] | [--current]]
2495
2496 Modifies an existing iothread of the domain using the specified io‐
2497 thread_id. The --poll-max-ns provides the maximum polling interval to
2498 be allowed for an IOThread in ns. If a 0 (zero) is provided, then
2499 polling for the IOThread is disabled. The --poll-grow is the factor by
2500 which the current polling time will be adjusted in order to reach the
2501 maximum polling time. If a 0 (zero) is provided, then the default fac‐
2502 tor will be used. The --poll-shrink is the quotient by which the cur‐
2503 rent polling time will be reduced in order to get below the maximum
2504 polling interval. If a 0 (zero) is provided, then the default quotient
2505 will be used. The polling values are purely dynamic for a running
2506 guest. Saving, destroying, stopping, etc. the guest will result in the
2507 polling values returning to hypervisor defaults at the next start, re‐
2508 store, etc.
2509
2510 If --live is specified, affect a running guest. If the guest is not
2511 running an error is returned. If --current is specified or --live is
2512 not specified, then handle as if --live was specified. (Where "cur‐
2513 rent" here means whatever the present guest state is: live or offline.)
2514
2515 managedsave
2516 Syntax:
2517
2518 managedsave domain [--bypass-cache] [{--running | --paused}] [--verbose]
2519
2520 Save and destroy (stop) a running domain, so it can be restarted from
2521 the same state at a later time. When the virsh start command is next
2522 run for the domain, it will automatically be started from this saved
2523 state. If --bypass-cache is specified, the save will avoid the file
2524 system cache, although this may slow down the operation.
2525
2526 The progress may be monitored using domjobinfo virsh command and can‐
2527 celed with domjobabort command (sent by another virsh instance). An‐
2528 other option is to send SIGINT (usually with Ctrl-C) to the virsh
2529 process running managedsave command. --verbose displays the progress of
2530 save.
2531
2532 Normally, starting a managed save will decide between running or paused
2533 based on the state the domain was in when the save was done; passing
2534 either the --running or --paused flag will allow overriding which state
2535 the start should use.
2536
2537 The dominfo command can be used to query whether a domain currently has
2538 any managed save image.
2539
2540 managedsave-define
2541 Syntax:
2542
2543 managedsave-define domain xml [{--running | --paused}]
2544
2545 Update the domain XML that will be used when domain is later started.
2546 The xml argument must be a file name containing the alternative XML,
2547 with changes only in the host-specific portions of the domain XML. For
2548 example, it can be used to change disk file paths.
2549
2550 The managed save image records whether the domain should be started to
2551 a running or paused state. Normally, this command does not alter the
2552 recorded state; passing either the --running or --paused flag will al‐
2553 low overriding which state the start should use.
2554
2555 managedsave-dumpxml
2556 Syntax:
2557
2558 managedsave-dumpxml domain [--security-info]
2559
2560 Extract the domain XML that was in effect at the time the saved state
2561 file file was created with the managedsave command. Using --secu‐
2562 rity-info will also include security sensitive information.
2563
2564 managedsave-edit
2565 Syntax:
2566
2567 managedsave-edit domain [{--running | --paused}]
2568
2569 Edit the XML configuration associated with a saved state file of a do‐
2570 main was created by the managedsave command.
2571
2572 The managed save image records whether the domain should be started to
2573 a running or paused state. Normally, this command does not alter the
2574 recorded state; passing either the --running or --paused flag will al‐
2575 low overriding which state the restore should use.
2576
2577 This is equivalent to:
2578
2579 virsh managedsave-dumpxml domain-name > state-file.xml
2580 vi state-file.xml (or make changes with your other text editor)
2581 virsh managedsave-define domain-name state-file-xml
2582
2583 except that it does some error checking.
2584
2585 The editor used can be supplied by the $VISUAL or $EDITOR environment
2586 variables, and defaults to vi.
2587
2588 managedsave-remove
2589 Syntax:
2590
2591 managedsave-remove domain
2592
2593 Remove the managedsave state file for a domain, if it exists. This en‐
2594 sures the domain will do a full boot the next time it is started.
2595
2596 maxvcpus
2597 Syntax:
2598
2599 maxvcpus [type]
2600
2601 Provide the maximum number of virtual CPUs supported for a guest VM on
2602 this connection. If provided, the type parameter must be a valid type
2603 attribute for the <domain> element of XML.
2604
2605 memtune
2606 Syntax:
2607
2608 memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-limit size]
2609 [--min-guarantee size] [[--config] [--live] | [--current]]
2610
2611 Allows you to display or set the domain memory parameters. Without
2612 flags, the current settings are displayed; with a flag, the appropriate
2613 limit is adjusted if supported by the hypervisor. LXC and QEMU/KVM
2614 support --hard-limit, --soft-limit, and --swap-hard-limit. --min-guar‐
2615 antee is supported only by ESX hypervisor. Each of these limits are
2616 scaled integers (see NOTES above), with a default of kibibytes (blocks
2617 of 1024 bytes) if no suffix is present. Libvirt rounds up to the near‐
2618 est kibibyte. Some hypervisors require a larger granularity than KiB,
2619 and requests that are not an even multiple will be rounded up. For ex‐
2620 ample, vSphere/ESX rounds the parameter up to mebibytes (1024
2621 kibibytes).
2622
2623 If --live is specified, affect a running guest. If --config is speci‐
2624 fied, affect the next start of a persistent guest. If --current is
2625 specified, it is equivalent to either --live or --config, depending on
2626 the current state of the guest. Both --live and --config flags may be
2627 given, but --current is exclusive. If no flag is specified, behavior is
2628 different depending on hypervisor.
2629
2630 For QEMU/KVM, the parameters are applied to the QEMU process as a
2631 whole. Thus, when counting them, one needs to add up guest RAM, guest
2632 video RAM, and some memory overhead of QEMU itself. The last piece is
2633 hard to determine so one needs guess and try.
2634
2635 For LXC, the displayed hard_limit value is the current memory setting
2636 from the XML or the results from a virsh setmem command.
2637
2638 • --hard-limit
2639
2640 The maximum memory the guest can use.
2641
2642 • --soft-limit
2643
2644 The memory limit to enforce during memory contention.
2645
2646 • --swap-hard-limit
2647
2648 The maximum memory plus swap the guest can use. This has to be more
2649 than hard-limit value provided.
2650
2651 • --min-guarantee
2652
2653 The guaranteed minimum memory allocation for the guest.
2654
2655 Specifying -1 as a value for these limits is interpreted as unlimited.
2656
2657 metadata
2658 Syntax:
2659
2660 metadata domain [[--live] [--config] | [--current]]
2661 [--edit] [uri] [key] [set] [--remove]
2662
2663 Show or modify custom XML metadata of a domain. The metadata is a user
2664 defined XML that allows storing arbitrary XML data in the domain defi‐
2665 nition. Multiple separate custom metadata pieces can be stored in the
2666 domain XML. The pieces are identified by a private XML namespace pro‐
2667 vided via the uri argument. (See also desc that works with textual
2668 metadata of a domain.)
2669
2670 Flags --live or --config select whether this command works on live or
2671 persistent definitions of the domain. If both --live and --config are
2672 specified, the --config option takes precedence on getting the current
2673 description and both live configuration and config are updated while
2674 setting the description. --current is exclusive and implied if none of
2675 these was specified.
2676
2677 Flag --remove specifies that the metadata element specified by the uri
2678 argument should be removed rather than updated.
2679
2680 Flag --edit specifies that an editor with the metadata identified by
2681 the uri argument should be opened and the contents saved back after‐
2682 wards. Otherwise the new contents can be provided via the set argu‐
2683 ment.
2684
2685 When setting metadata via --edit or set the key argument must be speci‐
2686 fied and is used to prefix the custom elements to bind them to the pri‐
2687 vate namespace.
2688
2689 If neither of --edit and set are specified the XML metadata correspond‐
2690 ing to the uri namespace is displayed instead of being modified.
2691
2692 migrate
2693 Syntax:
2694
2695 migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]]
2696 [--persistent] [--undefinesource] [--suspend] [--copy-storage-all]
2697 [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose]
2698 [--rdma-pin-all] [--abort-on-error] [--postcopy] [--postcopy-after-precopy]
2699 domain desturi [migrateuri] [graphicsuri] [listen-address] [dname]
2700 [--timeout seconds [--timeout-suspend | --timeout-postcopy]]
2701 [--xml file] [--migrate-disks disk-list] [--disks-port port]
2702 [--compressed] [--comp-methods method-list]
2703 [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads]
2704 [--comp-xbzrle-cache] [--auto-converge] [auto-converge-initial]
2705 [auto-converge-increment] [--persistent-xml file] [--tls]
2706 [--postcopy-bandwidth bandwidth]
2707 [--parallel [--parallel-connections connections]]
2708 [--bandwidth bandwidth] [--tls-destination hostname]
2709 [--disks-uri URI]
2710
2711 Migrate domain to another host. Add --live for live migration; <--p2p>
2712 for peer-2-peer migration; --direct for direct migration; or --tun‐
2713 nelled for tunnelled migration. --offline migrates domain definition
2714 without starting the domain on destination and without stopping it on
2715 source host. Offline migration may be used with inactive domains and
2716 it must be used with --persistent option. --persistent leaves the do‐
2717 main persistent on destination host, --undefinesource undefines the do‐
2718 main on the source host, and --suspend leaves the domain paused on the
2719 destination host. --copy-storage-all indicates migration with
2720 non-shared storage with full disk copy, --copy-storage-inc indicates
2721 migration with non-shared storage with incremental copy (same base im‐
2722 age shared between source and destination). In both cases the disk im‐
2723 ages have to exist on destination host, the --copy-storage-... options
2724 only tell libvirt to transfer data from the images on source host to
2725 the images found at the same place on the destination host. By default
2726 only non-shared non-readonly images are transferred. Use --mi‐
2727 grate-disks to explicitly specify a list of disk targets to transfer
2728 via the comma separated disk-list argument. --change-protection en‐
2729 forces that no incompatible configuration changes will be made to the
2730 domain while the migration is underway; this flag is implicitly enabled
2731 when supported by the hypervisor, but can be explicitly used to reject
2732 the migration if the hypervisor lacks change protection support.
2733 --verbose displays the progress of migration. --abort-on-error cancels
2734 the migration if a soft error (for example I/O error) happens during
2735 the migration. --postcopy enables post-copy logic in migration, but
2736 does not actually start post-copy, i.e., migration is started in
2737 pre-copy mode. Once migration is running, the user may switch to
2738 post-copy using the migrate-postcopy command sent from another virsh
2739 instance or use --postcopy-after-precopy along with --postcopy to let
2740 libvirt automatically switch to post-copy after the first pass of
2741 pre-copy is finished. The maximum bandwidth consumed during the
2742 post-copy phase may be limited using --postcopy-bandwidth. The maximum
2743 bandwidth consumed during the pre-copy phase may be limited using
2744 --bandwidth.
2745
2746 --auto-converge forces convergence during live migration. The initial
2747 guest CPU throttling rate can be set with auto-converge-initial. If the
2748 initial throttling rate is not enough to ensure convergence, the rate
2749 is periodically increased by auto-converge-increment.
2750
2751 --rdma-pin-all can be used with RDMA migration (i.e., when migrateuri
2752 starts with rdma://) to tell the hypervisor to pin all domain's memory
2753 at once before migration starts rather than letting it pin memory pages
2754 as needed. For QEMU/KVM this requires hard_limit memory tuning element
2755 (in the domain XML) to be used and set to the maximum memory configured
2756 for the domain plus any memory consumed by the QEMU process itself. Be‐
2757 ware of setting the memory limit too high (and thus allowing the domain
2758 to lock most of the host's memory). Doing so may be dangerous to both
2759 the domain and the host itself since the host's kernel may run out of
2760 memory.
2761
2762 Note: Individual hypervisors usually do not support all possible types
2763 of migration. For example, QEMU does not support direct migration.
2764
2765 In some cases libvirt may refuse to migrate the domain because doing so
2766 may lead to potential problems such as data corruption, and thus the
2767 migration is considered unsafe. For QEMU domain, this may happen if the
2768 domain uses disks without explicitly setting cache mode to "none". Mi‐
2769 grating such domains is unsafe unless the disk images are stored on co‐
2770 herent clustered filesystem, such as GFS2 or GPFS. If you are sure the
2771 migration is safe or you just do not care, use --unsafe to force the
2772 migration.
2773
2774 dname is used for renaming the domain to new name during migration,
2775 which also usually can be omitted. Likewise, --xml file is usually
2776 omitted, but can be used to supply an alternative XML file for use on
2777 the destination to supply a larger set of changes to any host-specific
2778 portions of the domain XML, such as accounting for naming differences
2779 between source and destination in accessing underlying storage. If
2780 --persistent is enabled, --persistent-xml file can be used to supply an
2781 alternative XML file which will be used as the persistent guest defini‐
2782 tion on the destination host.
2783
2784 --timeout seconds tells virsh to run a specified action when live mi‐
2785 gration exceeds that many seconds. It can only be used with --live.
2786 If --timeout-suspend is specified, the domain will be suspended after
2787 the timeout and the migration will complete offline; this is the de‐
2788 fault if no --timeout-\`` option is specified on the command line.
2789 When *--timeout-postcopy is used, virsh will switch migration from
2790 pre-copy to post-copy upon timeout; migration has to be started with
2791 --postcopy option for this to work.
2792
2793 --compressed activates compression, the compression method is chosen
2794 with --comp-methods. Supported methods are "mt" and "xbzrle" and can be
2795 used in any combination. When no methods are specified, a hypervisor
2796 default methods will be used. QEMU defaults to "xbzrle". Compression
2797 methods can be tuned further. --comp-mt-level sets compression level.
2798 Values are in range from 0 to 9, where 1 is maximum speed and 9 is max‐
2799 imum compression. --comp-mt-threads and --comp-mt-dthreads set the num‐
2800 ber of compress threads on source and the number of decompress threads
2801 on target respectively. --comp-xbzrle-cache sets size of page cache in
2802 bytes.
2803
2804 Providing --tls causes the migration to use the host configured TLS
2805 setup (see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in or‐
2806 der to perform the migration of the domain. Usage requires proper TLS
2807 setup for both source and target. Normally the TLS certificate from the
2808 destination host must match the host's name for TLS verification to
2809 succeed. When the certificate does not match the destination hostname
2810 and the expected certificate's hostname is known, --tls-destination can
2811 be used to pass the expected hostname when starting the migration.
2812
2813 --parallel option will cause migration data to be sent over multiple
2814 parallel connections. The number of such connections can be set using
2815 --parallel-connections. Parallel connections may help with saturating
2816 the network link between the source and the target and thus speeding up
2817 the migration.
2818
2819 Running migration can be canceled by interrupting virsh (usually using
2820 Ctrl-C) or by domjobabort command sent from another virsh instance.
2821
2822 The desturi and migrateuri parameters can be used to control which des‐
2823 tination the migration uses. desturi is important for managed migra‐
2824 tion, but unused for direct migration; migrateuri is required for di‐
2825 rect migration, but can usually be automatically determined for managed
2826 migration.
2827
2828 Note: The desturi parameter for normal migration and peer2peer migra‐
2829 tion has different semantics:
2830
2831 • normal migration: the desturi is an address of the target host as
2832 seen from the client machine.
2833
2834 • peer2peer migration: the desturi is an address of the target host as
2835 seen from the source machine.
2836
2837 In a special circumstance where you require a complete control of the
2838 connection and/or libvirt does not have network access to the remote
2839 side you can use a UNIX transport in the URI and specify a socket path
2840 in the query, for example with the qemu driver you could use this:
2841
2842 qemu+unix:///system?socket=/path/to/socket
2843
2844 When migrateuri is not specified, libvirt will automatically determine
2845 the hypervisor specific URI. Some hypervisors, including QEMU, have an
2846 optional "migration_host" configuration parameter (useful when the host
2847 has multiple network interfaces). If this is unspecified, libvirt de‐
2848 termines a name by looking up the target host's configured hostname.
2849
2850 There are a few scenarios where specifying migrateuri may help:
2851
2852 • The configured hostname is incorrect, or DNS is broken. If a host
2853 has a hostname which will not resolve to match one of its public IP
2854 addresses, then libvirt will generate an incorrect URI. In this case
2855 migrateuri should be explicitly specified, using an IP address, or a
2856 correct hostname.
2857
2858 • The host has multiple network interfaces. If a host has multiple
2859 network interfaces, it might be desirable for the migration data
2860 stream to be sent over a specific interface for either security or
2861 performance reasons. In this case migrateuri should be explicitly
2862 specified, using an IP address associated with the network to be
2863 used.
2864
2865 • The firewall restricts what ports are available. When libvirt gener‐
2866 ates a migration URI, it will pick a port number using hypervisor
2867 specific rules. Some hypervisors only require a single port to be
2868 open in the firewalls, while others require a whole range of port
2869 numbers. In the latter case migrateuri might be specified to choose
2870 a specific port number outside the default range in order to comply
2871 with local firewall policies.
2872
2873 • The desturi uses UNIX transport method. In this advanced case lib‐
2874 virt should not guess a migrateuri and it should be specified using
2875 UNIX socket path URI:
2876
2877 unix:///path/to/socket
2878
2879 See https://libvirt.org/migration.html#uris for more details on migra‐
2880 tion URIs.
2881
2882 Optional graphicsuri overrides connection parameters used for automati‐
2883 cally reconnecting a graphical clients at the end of migration. If
2884 omitted, libvirt will compute the parameters based on target host IP
2885 address. In case the client does not have a direct access to the net‐
2886 work virtualization hosts are connected to and needs to connect through
2887 a proxy, graphicsuri may be used to specify the address the client
2888 should connect to. The URI is formed as follows:
2889
2890 protocol://hostname[:port]/[?parameters]
2891
2892 where protocol is either "spice" or "vnc" and parameters is a list of
2893 protocol specific parameters separated by '&'. Currently recognized pa‐
2894 rameters are "tlsPort" and "tlsSubject". For example,
2895
2896 spice://target.host.com:1234/?tlsPort=4567
2897
2898 Optional listen-address sets the listen address that hypervisor on the
2899 destination side should bind to for incoming migration. Both IPv4 and
2900 IPv6 addresses are accepted as well as hostnames (the resolving is done
2901 on destination). Some hypervisors do not support specifying the listen
2902 address and will return an error if this parameter is used. This param‐
2903 eter cannot be used if desturi uses UNIX transport method.
2904
2905 Optional disks-port sets the port that hypervisor on destination side
2906 should bind to for incoming disks traffic. Currently it is supported
2907 only by QEMU.
2908
2909 Optional disks-uri can also be specified (mutually exclusive with
2910 disks-port) to specify what the remote hypervisor should bind/connect
2911 to when migrating disks. This can be tcp://address:port to specify a
2912 listen address (which overrides --migrate-uri and --listen-address for
2913 the disk migration) and a port or unix:///path/to/socket in case you
2914 need the disk migration to happen over a UNIX socket with that speci‐
2915 fied path. In this case you need to make sure the same socket path is
2916 accessible to both source and destination hypervisors and connecting to
2917 the socket on the source (after hypervisor creates it on the destina‐
2918 tion) will actually connect to the destination. If you are using
2919 SELinux (at least on the source host) you need to make sure the socket
2920 on the source is accessible to libvirtd/QEMU for connection. Libvirt
2921 cannot change the context of the existing socket because it is differ‐
2922 ent from the file representation of the socket and the context is cho‐
2923 sen by its creator (usually by using setsockcreatecon{,_raw}() func‐
2924 tions).
2925
2926 migrate-compcache
2927 Syntax:
2928
2929 migrate-compcache domain [--size bytes]
2930
2931 Sets and/or gets size of the cache (in bytes) used for compressing re‐
2932 peatedly transferred memory pages during live migration. When called
2933 without size, the command just prints current size of the compression
2934 cache. When size is specified, the hypervisor is asked to change com‐
2935 pression cache to size bytes and then the current size is printed (the
2936 result may differ from the requested size due to rounding done by the
2937 hypervisor). The size option is supposed to be used while the domain is
2938 being live-migrated as a reaction to migration progress and increasing
2939 number of compression cache misses obtained from domjobinfo.
2940
2941 migrate-getmaxdowntime
2942 Syntax:
2943
2944 migrate-getmaxdowntime domain
2945
2946 Get the maximum tolerable downtime for a domain which is being live-mi‐
2947 grated to another host. This is the number of milliseconds the guest
2948 is allowed to be down at the end of live migration.
2949
2950 migrate-getspeed
2951 Syntax:
2952
2953 migrate-getspeed domain [--postcopy]
2954
2955 Get the maximum migration bandwidth (in MiB/s) for a domain. If the
2956 --postcopy option is specified, the command will get the maximum band‐
2957 width allowed during a post-copy migration phase.
2958
2959 migrate-postcopy
2960 Syntax:
2961
2962 migrate-postcopy domain
2963
2964 Switch the current migration from pre-copy to post-copy. This is only
2965 supported for a migration started with --postcopy option.
2966
2967 migrate-setmaxdowntime
2968 Syntax:
2969
2970 migrate-setmaxdowntime domain downtime
2971
2972 Set maximum tolerable downtime for a domain which is being live-mi‐
2973 grated to another host. The downtime is a number of milliseconds the
2974 guest is allowed to be down at the end of live migration.
2975
2976 migrate-setspeed
2977 Syntax:
2978
2979 migrate-setspeed domain bandwidth [--postcopy]
2980
2981 Set the maximum migration bandwidth (in MiB/s) for a domain which is
2982 being migrated to another host. bandwidth is interpreted as an unsigned
2983 long long value. Specifying a negative value results in an essentially
2984 unlimited value being provided to the hypervisor. The hypervisor can
2985 choose whether to reject the value or convert it to the maximum value
2986 allowed. If the --postcopy option is specified, the command will set
2987 the maximum bandwidth allowed during a post-copy migration phase.
2988
2989 numatune
2990 Syntax:
2991
2992 numatune domain [--mode mode] [--nodeset nodeset]
2993 [[--config] [--live] | [--current]]
2994
2995 Set or get a domain's numa parameters, corresponding to the <numatune>
2996 element of domain XML. Without flags, the current settings are dis‐
2997 played.
2998
2999 mode can be one of `strict', `interleave' and `preferred' or any valid
3000 number from the virDomainNumatuneMemMode enum in case the daemon sup‐
3001 ports it. For a running domain, the mode can't be changed, and the
3002 nodeset can be changed only if the domain was started with a mode of
3003 `strict'.
3004
3005 nodeset is a list of numa nodes used by the host for running the do‐
3006 main. Its syntax is a comma separated list, with '-' for ranges and
3007 '^' for excluding a node.
3008
3009 If --live is specified, set scheduler information of a running guest.
3010 If --config is specified, affect the next start of a persistent guest.
3011 If --current is specified, it is equivalent to either --live or --con‐
3012 fig, depending on the current state of the guest.
3013
3014 For running guests in Linux hosts, the changes made in the domain's
3015 numa parameters does not imply that the guest memory will be moved to a
3016 different nodeset immediately. The memory migration depends on the
3017 guest activity, and the memory of an idle guest will remain in its pre‐
3018 vious nodeset for longer. The presence of VFIO devices will also lock
3019 parts of the guest memory in the same nodeset used to start the guest,
3020 regardless of nodeset changes.
3021
3022 perf
3023 Syntax:
3024
3025 perf domain [--enable eventSpec] [--disable eventSpec]
3026 [[--config] [--live] | [--current]]
3027
3028 Get the current perf events setting or enable/disable specific perf
3029 events for a guest domain.
3030
3031 Perf is a performance analyzing tool in Linux, and it can instrument
3032 CPU performance counters, tracepoints, kprobes, and uprobes (dynamic
3033 tracing). Perf supports a list of measurable events, and can measure
3034 events coming from different sources. For instance, some event are pure
3035 kernel counters, in this case they are called software events, includ‐
3036 ing context-switches, minor-faults, etc.. Now dozens of events from
3037 different sources can be supported by perf.
3038
3039 Currently only QEMU/KVM supports this command. The --enable and --dis‐
3040 able option combined with eventSpec can be used to enable or disable
3041 specific performance event. eventSpec is a string list of one or more
3042 events separated by commas. Valid event names are as follows:
3043
3044 Valid perf event names
3045
3046 • cmt - A PQos (Platform Qos) feature to monitor the usage of cache by
3047 applications running on the platform.
3048
3049 • mbmt - Provides a way to monitor the total system memory bandwidth
3050 between one level of cache and another.
3051
3052 • mbml - Provides a way to limit the amount of data (bytes/s) send
3053 through the memory controller on the socket.
3054
3055 • cache_misses - Provides the count of cache misses by applications
3056 running on the platform.
3057
3058 • cache_references - Provides the count of cache hits by applications
3059 running on th e platform.
3060
3061 • instructions - Provides the count of instructions executed by appli‐
3062 cations running on the platform.
3063
3064 • cpu_cycles - Provides the count of cpu cycles (total/elapsed). May be
3065 used with instructions in order to get a cycles per instruction.
3066
3067 • branch_instructions - Provides the count of branch instructions exe‐
3068 cuted by applications running on the platform.
3069
3070 • branch_misses - Provides the count of branch misses executed by ap‐
3071 plications running on the platform.
3072
3073 • bus_cycles - Provides the count of bus cycles executed by applica‐
3074 tions running on the platform.
3075
3076 • stalled_cycles_frontend - Provides the count of stalled cpu cycles in
3077 the frontend of the instruction processor pipeline by applications
3078 running on the platform.
3079
3080 • stalled_cycles_backend - Provides the count of stalled cpu cycles in
3081 the backend of the instruction processor pipeline by applications
3082 running on the platform.
3083
3084 • ref_cpu_cycles - Provides the count of total cpu cycles not affected
3085 by CPU frequency scaling by applications running on the platform.
3086
3087 • cpu_clock - Provides the cpu clock time consumed by applications run‐
3088 ning on the platform.
3089
3090 • task_clock - Provides the task clock time consumed by applications
3091 running on the platform.
3092
3093 • page_faults - Provides the count of page faults by applications run‐
3094 ning on the platform.
3095
3096 • context_switches - Provides the count of context switches by applica‐
3097 tions running on the platform.
3098
3099 • cpu_migrations - Provides the count cpu migrations by applications
3100 running on the platform.
3101
3102 • page_faults_min - Provides the count minor page faults by applica‐
3103 tions running on the platform.
3104
3105 • page_faults_maj - Provides the count major page faults by applica‐
3106 tions running on the platform.
3107
3108 • alignment_faults - Provides the count alignment faults by applica‐
3109 tions running on the platform.
3110
3111 • emulation_faults - Provides the count emulation faults by applica‐
3112 tions running on the platform.
3113
3114 Note: The statistics can be retrieved using the domstats command using
3115 the --perf flag.
3116
3117 If --live is specified, affect a running guest. If --config is speci‐
3118 fied, affect the next start of a persistent guest. If --current is
3119 specified, it is equivalent to either --live or --config, depending on
3120 the current state of the guest. Both --live and --config flags may be
3121 given, but --current is exclusive. If no flag is specified, behavior is
3122 different depending on hypervisor.
3123
3124 reboot
3125 Syntax:
3126
3127 reboot domain [--mode MODE-LIST]
3128
3129 Reboot a domain. This acts just as if the domain had the reboot com‐
3130 mand run from the console. The command returns as soon as it has exe‐
3131 cuted the reboot action, which may be significantly before the domain
3132 actually reboots.
3133
3134 The exact behavior of a domain when it reboots is set by the on_reboot
3135 parameter in the domain's XML definition.
3136
3137 By default the hypervisor will try to pick a suitable shutdown method.
3138 To specify an alternative method, the --mode parameter can specify a
3139 comma separated list which includes acpi, agent, initctl, signal and
3140 paravirt. The order in which drivers will try each mode is undefined,
3141 and not related to the order specified to virsh. For strict control
3142 over ordering, use a single mode at a time and repeat the command.
3143
3144 reset
3145 Syntax:
3146
3147 reset domain
3148
3149 Reset a domain immediately without any guest shutdown. reset emulates
3150 the power reset button on a machine, where all guest hardware sees the
3151 RST line set and reinitializes internal state.
3152
3153 Note: Reset without any guest OS shutdown risks data loss.
3154
3155 restore
3156 Syntax:
3157
3158 restore state-file [--bypass-cache] [--xml file]
3159 [{--running | --paused}]
3160
3161 Restores a domain from a virsh save state file. See save for more info.
3162
3163 If --bypass-cache is specified, the restore will avoid the file system
3164 cache, although this may slow down the operation.
3165
3166 --xml file is usually omitted, but can be used to supply an alternative
3167 XML file for use on the restored guest with changes only in the
3168 host-specific portions of the domain XML. For example, it can be used
3169 to account for file naming differences in underlying storage due to
3170 disk snapshots taken after the guest was saved.
3171
3172 Normally, restoring a saved image will use the state recorded in the
3173 save image to decide between running or paused; passing either the
3174 --running or --paused flag will allow overriding which state the domain
3175 should be started in.
3176
3177 Note: To avoid corrupting file system contents within the domain, you
3178 should not reuse the saved state file for a second restore unless you
3179 have also reverted all storage volumes back to the same contents as
3180 when the state file was created.
3181
3182 resume
3183 Syntax:
3184
3185 resume domain
3186
3187 Moves a domain out of the suspended state. This will allow a previ‐
3188 ously suspended domain to now be eligible for scheduling by the under‐
3189 lying hypervisor.
3190
3191 save
3192 Syntax:
3193
3194 save domain state-file [--bypass-cache] [--xml file]
3195 [{--running | --paused}] [--verbose]
3196
3197 Saves a running domain (RAM, but not disk state) to a state file so
3198 that it can be restored later. Once saved, the domain will no longer
3199 be running on the system, thus the memory allocated for the domain will
3200 be free for other domains to use. virsh restore restores from this
3201 state file. If --bypass-cache is specified, the save will avoid the
3202 file system cache, although this may slow down the operation.
3203
3204 The progress may be monitored using domjobinfo virsh command and can‐
3205 celed with domjobabort command (sent by another virsh instance). An‐
3206 other option is to send SIGINT (usually with Ctrl-C) to the virsh
3207 process running save command. --verbose displays the progress of save.
3208
3209 This is roughly equivalent to doing a hibernate on a running computer,
3210 with all the same limitations. Open network connections may be severed
3211 upon restore, as TCP timeouts may have expired.
3212
3213 --xml file is usually omitted, but can be used to supply an alternative
3214 XML file for use on the restored guest with changes only in the
3215 host-specific portions of the domain XML. For example, it can be used
3216 to account for file naming differences that are planned to be made via
3217 disk snapshots of underlying storage after the guest is saved.
3218
3219 Normally, restoring a saved image will decide between running or paused
3220 based on the state the domain was in when the save was done; passing
3221 either the --running or --paused flag will allow overriding which state
3222 the restore should use.
3223
3224 Domain saved state files assume that disk images will be unchanged be‐
3225 tween the creation and restore point. For a more complete system re‐
3226 store point, where the disk state is saved alongside the memory state,
3227 see the snapshot family of commands.
3228
3229 save-image-define
3230 Syntax:
3231
3232 save-image-define file xml [{--running | --paused}]
3233
3234 Update the domain XML that will be used when file is later used in the
3235 restore command. The xml argument must be a file name containing the
3236 alternative XML, with changes only in the host-specific portions of the
3237 domain XML. For example, it can be used to account for file naming
3238 differences resulting from creating disk snapshots of underlying stor‐
3239 age after the guest was saved.
3240
3241 The save image records whether the domain should be restored to a run‐
3242 ning or paused state. Normally, this command does not alter the
3243 recorded state; passing either the --running or --paused flag will al‐
3244 low overriding which state the restore should use.
3245
3246 save-image-dumpxml
3247 Syntax:
3248
3249 save-image-dumpxml file [--security-info]
3250
3251 Extract the domain XML that was in effect at the time the saved state
3252 file file was created with the save command. Using --security-info
3253 will also include security sensitive information.
3254
3255 save-image-edit
3256 Syntax:
3257
3258 save-image-edit file [{--running | --paused}]
3259
3260 Edit the XML configuration associated with a saved state file file cre‐
3261 ated by the save command.
3262
3263 The save image records whether the domain should be restored to a run‐
3264 ning or paused state. Normally, this command does not alter the
3265 recorded state; passing either the --running or --paused flag will al‐
3266 low overriding which state the restore should use.
3267
3268 This is equivalent to:
3269
3270 virsh save-image-dumpxml state-file > state-file.xml
3271 vi state-file.xml (or make changes with your other text editor)
3272 virsh save-image-define state-file state-file-xml
3273
3274 except that it does some error checking.
3275
3276 The editor used can be supplied by the $VISUAL or $EDITOR environment
3277 variables, and defaults to vi.
3278
3279 schedinfo
3280 Syntax:
3281
3282 schedinfo domain [[--config] [--live] | [--current]] [[--set] parameter=value]...
3283 schedinfo [--weight number] [--cap number] domain
3284
3285 Allows you to show (and set) the domain scheduler parameters. The pa‐
3286 rameters available for each hypervisor are:
3287
3288 LXC (posix scheduler) : cpu_shares, vcpu_period, vcpu_quota
3289
3290 QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota, emula‐
3291 tor_period, emulator_quota, global_period, global_quota, iothread_pe‐
3292 riod, iothread_quota
3293
3294 Xen (credit scheduler): weight, cap
3295
3296 ESX (allocation scheduler): reservation, limit, shares
3297
3298 If --live is specified, set scheduler information of a running guest.
3299 If --config is specified, affect the next start of a persistent guest.
3300 If --current is specified, it is equivalent to either --live or --con‐
3301 fig, depending on the current state of the guest.
3302
3303 Note: The cpu_shares parameter has a valid value range of 2-262144.
3304
3305 Note: The weight and cap parameters are defined only for the XEN_CREDIT
3306 scheduler.
3307
3308 Note: The vcpu_period, emulator_period, and iothread_period parameters
3309 have a valid value range of 1000-1000000 or 0, and the vcpu_quota, emu‐
3310 lator_quota, and iothread_quota parameters have a valid value range of
3311 1000-17592186044415 or less than 0. The value 0 for either parameter is
3312 the same as not specifying that parameter.
3313
3314 screenshot
3315 Syntax:
3316
3317 screenshot domain [imagefilepath] [--screen screenID]
3318
3319 Takes a screenshot of a current domain console and stores it into a
3320 file. Optionally, if the hypervisor supports more displays for a do‐
3321 main, screenID allows specifying which screen will be captured. It is
3322 the sequential number of screen. In case of multiple graphics cards,
3323 heads are enumerated before devices, e.g. having two graphics cards,
3324 both with four heads, screen ID 5 addresses the second head on the sec‐
3325 ond card.
3326
3327 send-key
3328 Syntax:
3329
3330 send-key domain [--codeset codeset] [--holdtime holdtime] keycode...
3331
3332 Parse the keycode sequence as keystrokes to send to domain. Each key‐
3333 code can either be a numeric value or a symbolic name from the corre‐
3334 sponding codeset. If --holdtime is given, each keystroke will be held
3335 for that many milliseconds. The default codeset is linux, but use of
3336 the --codeset option allows other codesets to be chosen.
3337
3338 If multiple keycodes are specified, they are all sent simultaneously to
3339 the guest, and they may be received in random order. If you need dis‐
3340 tinct keypresses, you must use multiple send-key invocations.
3341
3342 • linux
3343
3344 The numeric values are those defined by the Linux generic input event
3345 subsystem. The symbolic names match the corresponding Linux key con‐
3346 stant macro names.
3347
3348 See virkeycode-linux(7) and virkeyname-linux(7)
3349
3350 • xt
3351
3352 The numeric values are those defined by the original XT keyboard con‐
3353 troller. No symbolic names are provided
3354
3355 See virkeycode-xt(7)
3356
3357 • atset1
3358
3359 The numeric values are those defined by the AT keyboard controller,
3360 set 1 (aka XT compatible set). Extended keycoes from atset1 may dif‐
3361 fer from extended keycodes in the xt codeset. No symbolic names are
3362 provided
3363
3364 See virkeycode-atset1(7)
3365
3366 • atset2
3367
3368 The numeric values are those defined by the AT keyboard controller,
3369 set 2. No symbolic names are provided
3370
3371 See virkeycode-atset2(7)
3372
3373 • atset3
3374
3375 The numeric values are those defined by the AT keyboard controller,
3376 set 3 (aka PS/2 compatible set). No symbolic names are provided
3377
3378 See virkeycode-atset3(7)
3379
3380 • os_x
3381
3382 The numeric values are those defined by the macOS keyboard input sub‐
3383 system. The symbolic names match the corresponding macOS key constant
3384 macro names
3385
3386 See virkeycode-osx(7) and virkeyname-osx(7)
3387
3388 • xt_kbd
3389
3390 The numeric values are those defined by the Linux KBD device. These
3391 are a variant on the original XT codeset, but often with different
3392 encoding for extended keycodes. No symbolic names are provided.
3393
3394 See virkeycode-xtkbd(7)
3395
3396 • win32
3397
3398 The numeric values are those defined by the Win32 keyboard input sub‐
3399 system. The symbolic names match the corresponding Win32 key constant
3400 macro names
3401
3402 See virkeycode-win32(7) and virkeyname-win32(7)
3403
3404 • usb
3405
3406 The numeric values are those defined by the USB HID specification for
3407 keyboard input. No symbolic names are provided
3408
3409 See virkeycode-usb(7)
3410
3411 • qnum
3412
3413 The numeric values are those defined by the QNUM extension for send‐
3414 ing raw keycodes. These are a variant on the XT codeset, but extended
3415 keycodes have the low bit of the second byte set, instead of the high
3416 bit of the first byte. No symbolic names are provided.
3417
3418 See virkeycode-qnum(7)
3419
3420 Examples:
3421
3422 # send three strokes 'k', 'e', 'y', using xt codeset. these
3423 # are all pressed simultaneously and may be received by the guest
3424 # in random order
3425 virsh send-key dom --codeset xt 37 18 21
3426
3427 # send one stroke 'right-ctrl+C'
3428 virsh send-key dom KEY_RIGHTCTRL KEY_C
3429
3430 # send a tab, held for 1 second
3431 virsh send-key --holdtime 1000 0xf
3432
3433 send-process-signal
3434 Syntax:
3435
3436 send-process-signal domain-id pid signame
3437
3438 Send a signal signame to the process identified by pid running in the
3439 virtual domain domain-id. The pid is a process ID in the virtual domain
3440 namespace.
3441
3442 The signame argument may be either an integer signal constant number,
3443 or one of the symbolic names:
3444
3445 "nop", "hup", "int", "quit", "ill",
3446 "trap", "abrt", "bus", "fpe", "kill",
3447 "usr1", "segv", "usr2", "pipe", "alrm",
3448 "term", "stkflt", "chld", "cont", "stop",
3449 "tstp", "ttin", "ttou", "urg", "xcpu",
3450 "xfsz", "vtalrm", "prof", "winch", "poll",
3451 "pwr", "sys", "rt0", "rt1", "rt2", "rt3",
3452 "rt4", "rt5", "rt6", "rt7", "rt8", "rt9",
3453 "rt10", "rt11", "rt12", "rt13", "rt14", "rt15",
3454 "rt16", "rt17", "rt18", "rt19", "rt20", "rt21",
3455 "rt22", "rt23", "rt24", "rt25", "rt26", "rt27",
3456 "rt28", "rt29", "rt30", "rt31", "rt32"
3457
3458 The symbol name may optionally be prefixed with sig or sig_ and may be
3459 in uppercase or lowercase.
3460
3461 Examples:
3462
3463 virsh send-process-signal myguest 1 15
3464 virsh send-process-signal myguest 1 term
3465 virsh send-process-signal myguest 1 sigterm
3466 virsh send-process-signal myguest 1 SIG_HUP
3467
3468 set-lifecycle-action
3469 Syntax:
3470
3471 set-lifecycle-action domain type action
3472 [[--config] [--live] | [--current]]
3473
3474 Set the lifecycle action for specified lifecycle type. The valid types
3475 are "poweroff", "reboot" and "crash", and for each of them valid action
3476 is one of "destroy", "restart", "rename-restart", "preserve". For type
3477 "crash", additional actions "coredump-destroy" and "coredump-restart"
3478 are supported.
3479
3480 set-user-password
3481 Syntax:
3482
3483 set-user-password domain user password [--encrypted]
3484
3485 Set the password for the user account in the guest domain.
3486
3487 If --encrypted is specified, the password is assumed to be already en‐
3488 crypted by the method required by the guest OS.
3489
3490 For QEMU/KVM, this requires the guest agent to be configured and run‐
3491 ning.
3492
3493 set-user-sshkeys
3494 Syntax:
3495
3496 set-user-sshkeys domain user [--file FILE] [{--reset | --remove}]
3497
3498 Append keys read from FILE into user's SSH authorized keys file in the
3499 guest domain. In the FILE keys must be on separate lines and each line
3500 must follow authorized keys format as defined by sshd(8).
3501
3502 If --reset is specified, then the guest authorized keys file content is
3503 removed before appending new keys. As a special case, if --reset is
3504 provided and no FILE was provided then no new keys are added and the
3505 authorized keys file is cleared out.
3506
3507 If --remove is specified, then instead of adding any new keys then keys
3508 read from FILE are removed from the authorized keys file. It is not
3509 considered an error if the key does not exist in the file.
3510
3511 setmaxmem
3512 Syntax:
3513
3514 setmaxmem domain size [[--config] [--live] | [--current]]
3515
3516 Change the maximum memory allocation limit for a guest domain. If
3517 --live is specified, affect a running guest. If --config is specified,
3518 affect the next start of a persistent guest. If --current is speci‐
3519 fied, it is equivalent to either --live or --config, depending on the
3520 current state of the guest. Both --live and --config flags may be
3521 given, but --current is exclusive. If no flag is specified, behavior is
3522 different depending on hypervisor.
3523
3524 Some hypervisors such as QEMU/KVM don't support live changes (espe‐
3525 cially increasing) of the maximum memory limit. Even persistent con‐
3526 figuration changes might not be performed with some hypervisors/config‐
3527 uration (e.g. on NUMA enabled domains on QEMU). For complex configura‐
3528 tion changes use command edit instead).
3529
3530 size is a scaled integer (see NOTES above); it defaults to kibibytes
3531 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3532 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3533 rounds up to the nearest kibibyte. Some hypervisors require a larger
3534 granularity than KiB, and requests that are not an even multiple will
3535 be rounded up. For example, vSphere/ESX rounds the parameter up to
3536 mebibytes (1024 kibibytes).
3537
3538 setmem
3539 Syntax:
3540
3541 setmem domain size [[--config] [--live] | [--current]]
3542
3543 Change the memory allocation for a guest domain. If --live is speci‐
3544 fied, perform a memory balloon of a running guest. If --config is
3545 specified, affect the next start of a persistent guest. If --current
3546 is specified, it is equivalent to either --live or --config, depending
3547 on the current state of the guest. Both --live and --config flags may
3548 be given, but --current is exclusive. If no flag is specified, behavior
3549 is different depending on hypervisor.
3550
3551 size is a scaled integer (see NOTES above); it defaults to kibibytes
3552 (blocks of 1024 bytes) unless you provide a suffix (and the older op‐
3553 tion name --kilobytes is available as a deprecated synonym) . Libvirt
3554 rounds up to the nearest kibibyte. Some hypervisors require a larger
3555 granularity than KiB, and requests that are not an even multiple will
3556 be rounded up. For example, vSphere/ESX rounds the parameter up to
3557 mebibytes (1024 kibibytes).
3558
3559 For Xen, you can only adjust the memory of a running domain if the do‐
3560 main is paravirtualized or running the PV balloon driver.
3561
3562 For LXC, the value being set is the cgroups value for limit_in_bytes or
3563 the maximum amount of user memory (including file cache). When viewing
3564 memory inside the container, this is the /proc/meminfo "MemTotal"
3565 value. When viewing the value from the host, use the virsh memtune com‐
3566 mand. In order to view the current memory in use and the maximum value
3567 allowed to set memory, use the virsh dominfo command.
3568
3569 setvcpus
3570 Syntax:
3571
3572 setvcpus domain count [--maximum] [[--config] [--live] | [--current]] [--guest] [--hotpluggable]
3573
3574 Change the number of virtual CPUs active in a guest domain. By de‐
3575 fault, this command works on active guest domains. To change the set‐
3576 tings for an inactive guest domain, use the --config flag.
3577
3578 The count value may be limited by host, hypervisor, or a limit coming
3579 from the original description of the guest domain. For Xen, you can
3580 only adjust the virtual CPUs of a running domain if the domain is par‐
3581 avirtualized.
3582
3583 If the --config flag is specified, the change is made to the stored XML
3584 configuration for the guest domain, and will only take effect when the
3585 guest domain is next started.
3586
3587 If --live is specified, the guest domain must be active, and the change
3588 takes place immediately. Both the --config and --live flags may be
3589 specified together if supported by the hypervisor. If this command is
3590 run before the guest has finished booting, the guest may fail to
3591 process the change.
3592
3593 If --current is specified, it is equivalent to either --live or --con‐
3594 fig, depending on the current state of the guest.
3595
3596 When no flags are given, the --live flag is assumed and the guest do‐
3597 main must be active. In this situation it is up to the hypervisor
3598 whether the --config flag is also assumed, and therefore whether the
3599 XML configuration is adjusted to make the change persistent.
3600
3601 If --guest is specified, then the count of cpus is modified in the
3602 guest instead of the hypervisor. This flag is usable only for live do‐
3603 mains and may require guest agent to be configured in the guest.
3604
3605 To allow adding vcpus to persistent definitions that can be later ho‐
3606 tunplugged after the domain is booted it is necessary to specify the
3607 --hotpluggable flag. Vcpus added to live domains supporting vcpu unplug
3608 are automatically marked as hotpluggable.
3609
3610 The --maximum flag controls the maximum number of virtual cpus that can
3611 be hot-plugged the next time the domain is booted. As such, it must
3612 only be used with the --config flag, and not with the --live or the
3613 --current flag. Note that it may not be possible to change the maximum
3614 vcpu count if the processor topology is specified for the guest.
3615
3616 setvcpu
3617 Syntax:
3618
3619 setvcpu domain vcpulist [--enable] | [--disable]
3620 [[--live] [--config] | [--current]]
3621
3622 Change state of individual vCPUs using hot(un)plug mechanism.
3623
3624 See vcpupin for information on format of vcpulist. Hypervisor drivers
3625 may require that vcpulist contains exactly vCPUs belonging to one hot‐
3626 pluggable entity. This is usually just a single vCPU but certain archi‐
3627 tectures such as ppc64 require a full core to be specified at once.
3628
3629 Note that hypervisors may refuse to disable certain vcpus such as vcpu
3630 0 or others.
3631
3632 If --live is specified, affect a running domain. If --config is speci‐
3633 fied, affect the next startup of a persistent guest. If --current is
3634 specified, it is equivalent to either --live or --config, depending on
3635 the current state of the guest. This is the default. Both --live and
3636 --config flags may be given, but --current is exclusive.
3637
3638 shutdown
3639 Syntax:
3640
3641 shutdown domain [--mode MODE-LIST]
3642
3643 Gracefully shuts down a domain. This coordinates with the domain OS to
3644 perform graceful shutdown, so there is no guarantee that it will suc‐
3645 ceed, and may take a variable length of time depending on what services
3646 must be shutdown in the domain.
3647
3648 The exact behavior of a domain when it shuts down is set by the
3649 on_poweroff parameter in the domain's XML definition.
3650
3651 If domain is transient, then the metadata of any snapshots and check‐
3652 points will be lost once the guest stops running, but the underlying
3653 contents still exist, and a new domain with the same name and UUID can
3654 restore the snapshot metadata with snapshot-create, and the checkpoint
3655 metadata with checkpoint-create.
3656
3657 By default the hypervisor will try to pick a suitable shutdown method.
3658 To specify an alternative method, the --mode parameter can specify a
3659 comma separated list which includes acpi, agent, initctl, signal and
3660 paravirt. The order in which drivers will try each mode is undefined,
3661 and not related to the order specified to virsh. For strict control
3662 over ordering, use a single mode at a time and repeat the command.
3663
3664 start
3665 Syntax:
3666
3667 start domain-name-or-uuid [--console] [--paused]
3668 [--autodestroy] [--bypass-cache] [--force-boot]
3669 [--pass-fds N,M,...]
3670
3671 Start a (previously defined) inactive domain, either from the last man‐
3672 agedsave state, or via a fresh boot if no managedsave state is present.
3673 The domain will be paused if the --paused option is used and supported
3674 by the driver; otherwise it will be running. If --console is re‐
3675 quested, attach to the console after creation. If --autodestroy is re‐
3676 quested, then the guest will be automatically destroyed when virsh
3677 closes its connection to libvirt, or otherwise exits. If --by‐
3678 pass-cache is specified, and managedsave state exists, the restore will
3679 avoid the file system cache, although this may slow down the operation.
3680 If --force-boot is specified, then any managedsave state is discarded
3681 and a fresh boot occurs.
3682
3683 If --pass-fds is specified, the argument is a comma separated list of
3684 open file descriptors which should be pass on into the guest. The file
3685 descriptors will be re-numbered in the guest, starting from 3. This is
3686 only supported with container based virtualization.
3687
3688 suspend
3689 Syntax:
3690
3691 suspend domain
3692
3693 Suspend a running domain. It is kept in memory but won't be scheduled
3694 anymore.
3695
3696 ttyconsole
3697 Syntax:
3698
3699 ttyconsole domain
3700
3701 Output the device used for the TTY console of the domain. If the infor‐
3702 mation is not available the processes will provide an exit code of 1.
3703
3704 undefine
3705 Syntax:
3706
3707 undefine domain [--managed-save] [--snapshots-metadata]
3708 [--checkpoints-metadata] [--nvram] [--keep-nvram]
3709 [ {--storage volumes | --remove-all-storage
3710 [--delete-storage-volume-snapshots]} --wipe-storage]
3711
3712 Undefine a domain. If the domain is running, this converts it to a
3713 transient domain, without stopping it. If the domain is inactive, the
3714 domain configuration is removed.
3715
3716 The --managed-save flag guarantees that any managed save image (see the
3717 managedsave command) is also cleaned up. Without the flag, attempts to
3718 undefine a domain with a managed save image will fail.
3719
3720 The --snapshots-metadata flag guarantees that any snapshots (see the
3721 snapshot-list command) are also cleaned up when undefining an inactive
3722 domain. Without the flag, attempts to undefine an inactive domain with
3723 snapshot metadata will fail. If the domain is active, this flag is ig‐
3724 nored.
3725
3726 The --checkpoints-metadata flag guarantees that any checkpoints (see
3727 the checkpoint-list command) are also cleaned up when undefining an in‐
3728 active domain. Without the flag, attempts to undefine an inactive do‐
3729 main with checkpoint metadata will fail. If the domain is active, this
3730 flag is ignored.
3731
3732 --nvram and --keep-nvram specify accordingly to delete or keep nvram
3733 (/domain/os/nvram/) file. If the domain has an nvram file and the flags
3734 are omitted, the undefine will fail.
3735
3736 The --storage flag takes a parameter volumes, which is a comma sepa‐
3737 rated list of volume target names or source paths of storage volumes to
3738 be removed along with the undefined domain. Volumes can be undefined
3739 and thus removed only on inactive domains. Volume deletion is only at‐
3740 tempted after the domain is undefined; if not all of the requested vol‐
3741 umes could be deleted, the error message indicates what still remains
3742 behind. If a volume path is not found in the domain definition, it's
3743 treated as if the volume was successfully deleted. Only volumes managed
3744 by libvirt in storage pools can be removed this way. (See domblklist
3745 for list of target names associated to a domain). Example: --storage
3746 vda,/path/to/storage.img
3747
3748 The --remove-all-storage flag specifies that all of the domain's stor‐
3749 age volumes should be deleted.
3750
3751 The --delete-storage-volume-snapshots (previously --delete-snapshots)
3752 flag specifies that any snapshots associated with the storage volume
3753 should be deleted as well. Requires the --remove-all-storage flag to be
3754 provided. Not all storage drivers support this option, presently only
3755 rbd. Using this when also removing volumes handled by a storage driver
3756 which does not support the flag will result in failure.
3757
3758 The flag --wipe-storage specifies that the storage volumes should be
3759 wiped before removal.
3760
3761 NOTE: For an inactive domain, the domain name or UUID must be used as
3762 the domain.
3763
3764 vcpucount
3765 Syntax:
3766
3767 vcpucount domain [{--maximum | --active}
3768 {--config | --live | --current}] [--guest]
3769
3770 Print information about the virtual cpu counts of the given domain. If
3771 no flags are specified, all possible counts are listed in a table; oth‐
3772 erwise, the output is limited to just the numeric value requested. For
3773 historical reasons, the table lists the label "current" on the rows
3774 that can be queried in isolation via the --active flag, rather than re‐
3775 lating to the --current flag.
3776
3777 --maximum requests information on the maximum cap of vcpus that a do‐
3778 main can add via setvcpus, while --active shows the current usage;
3779 these two flags cannot both be specified. --config requires a persis‐
3780 tent guest and requests information regarding the next time the domain
3781 will be booted, --live requires a running domain and lists current val‐
3782 ues, and --current queries according to the current state of the domain
3783 (corresponding to --live if running, or --config if inactive); these
3784 three flags are mutually exclusive.
3785
3786 If --guest is specified, then the count of cpus is reported from the
3787 perspective of the guest. This flag is usable only for live domains and
3788 may require guest agent to be configured in the guest.
3789
3790 vcpuinfo
3791 Syntax:
3792
3793 vcpuinfo domain [--pretty]
3794
3795 Returns basic information about the domain virtual CPUs, like the num‐
3796 ber of vCPUs, the running time, the affinity to physical processors.
3797
3798 With --pretty, cpu affinities are shown as ranges.
3799
3800 Example:
3801
3802 $ virsh vcpuinfo fedora
3803 VCPU: 0
3804 CPU: 0
3805 State: running
3806 CPU time: 7,0s
3807 CPU Affinity: yyyy
3808
3809 VCPU: 1
3810 CPU: 1
3811 State: running
3812 CPU time: 0,7s
3813 CPU Affinity: yyyy
3814
3815 STATES
3816
3817 The State field displays the current operating state of a virtual CPU
3818
3819 • offline
3820
3821 The virtual CPU is offline and not usable by the domain. This state
3822 is not supported by all hypervisors.
3823
3824 • running
3825
3826 The virtual CPU is available to the domain and is operating.
3827
3828 • blocked
3829
3830 The virtual CPU is available to the domain but is waiting for a re‐
3831 source. This state is not supported by all hypervisors, in which
3832 case running may be reported instead.
3833
3834 • no state
3835
3836 The virtual CPU state could not be determined. This could happen if
3837 the hypervisor is newer than virsh.
3838
3839 • N/A
3840
3841 There's no information about the virtual CPU state available. This
3842 can be the case if the domain is not running or the hypervisor does
3843 not report the virtual CPU state.
3844
3845 vcpupin
3846 Syntax:
3847
3848 vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]]
3849
3850 Query or change the pinning of domain VCPUs to host physical CPUs. To
3851 pin a single vcpu, specify cpulist; otherwise, you can query one vcpu
3852 or omit vcpu to list all at once.
3853
3854 cpulist is a list of physical CPU numbers. Its syntax is a comma sepa‐
3855 rated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2')
3856 can also be allowed. The '-' denotes the range and the '^' denotes ex‐
3857 clusive. For pinning the vcpu to all physical cpus specify 'r' as a
3858 cpulist. If --live is specified, affect a running guest. If --config
3859 is specified, affect the next start of a persistent guest. If --cur‐
3860 rent is specified, it is equivalent to either --live or --config, de‐
3861 pending on the current state of the guest. Both --live and --config
3862 flags may be given if cpulist is present, but --current is exclusive.
3863 If no flag is specified, behavior is different depending on hypervisor.
3864
3865 Note: The expression is sequentially evaluated, so "0-15,^8" is identi‐
3866 cal to "9-14,0-7,15" but not identical to "^8,0-15".
3867
3868 vncdisplay
3869 Syntax:
3870
3871 vncdisplay domain
3872
3873 Output the IP address and port number for the VNC display. If the in‐
3874 formation is not available the processes will provide an exit code of
3875 1.
3876
3878 The following commands manipulate devices associated to domains. The
3879 domain can be specified as a short integer, a name or a full UUID. To
3880 better understand the values allowed as options for the command reading
3881 the documentation at https://libvirt.org/formatdomain.html on the for‐
3882 mat of the device sections to get the most accurate set of accepted
3883 values.
3884
3885 attach-device
3886 Syntax:
3887
3888 attach-device domain FILE [[[--live] [--config] | [--current]] | [--persistent]]
3889
3890 Attach a device to the domain, using a device definition in an XML file
3891 using a device definition element such as <disk> or <interface> as the
3892 top-level element. See the documentation at
3893 https://libvirt.org/formatdomain.html#elementsDevices to learn about
3894 libvirt XML format for a device. If --config is specified the command
3895 alters the persistent guest configuration with the device attach taking
3896 effect the next time libvirt starts the domain. For cdrom and floppy
3897 devices, this command only replaces the media within an existing de‐
3898 vice; consider using update-device for this usage. For passthrough
3899 host devices, see also nodedev-detach, needed if the PCI device does
3900 not use managed mode.
3901
3902 If --live is specified, affect a running domain. If --config is speci‐
3903 fied, affect the next startup of a persistent guest. If --current is
3904 specified, it is equivalent to either --live or --config, depending on
3905 the current state of the guest. Both --live and --config flags may be
3906 given, but --current is exclusive. When no flag is specified legacy API
3907 is used whose behavior depends on the hypervisor driver.
3908
3909 For compatibility purposes, --persistent behaves like --config for an
3910 offline domain, and like --live --config for a running domain.
3911
3912 Note: using of partial device definition XML files may lead to unex‐
3913 pected results as some fields may be autogenerated and thus match de‐
3914 vices other than expected.
3915
3916 attach-disk
3917 Syntax:
3918
3919 attach-disk domain source target [[[--live] [--config] |
3920 [--current]] | [--persistent]] [--targetbus bus]
3921 [--driver driver] [--subdriver subdriver] [--iothread iothread]
3922 [--cache cache] [--io io] [--type type] [--alias alias]
3923 [--mode mode] [--sourcetype sourcetype]
3924 [--source-protocol protocol] [--source-host-name hostname:port]
3925 [--source-host-transport transport] [--source-host-socket socket]
3926 [--serial serial] [--wwn wwn] [--rawio] [--address address]
3927 [--multifunction] [--print-xml]
3928
3929 Attach a new disk device to the domain. source is path for the files
3930 and devices unless --source-protocol is specified, in which case source
3931 is the name of a network disk. target controls the bus or device under
3932 which the disk is exposed to the guest OS. It indicates the "logical"
3933 device name; the optional targetbus attribute specifies the type of
3934 disk device to emulate; possible values are driver specific, with typi‐
3935 cal values being ide, scsi, virtio, xen, usb, sata, or sd, if omitted,
3936 the bus type is inferred from the style of the device name (e.g. a de‐
3937 vice named 'sda' will typically be exported using a SCSI bus). driver
3938 can be file, tap or phy for the Xen hypervisor depending on the kind of
3939 access; or qemu for the QEMU emulator. Further details to the driver
3940 can be passed using subdriver. For Xen subdriver can be aio, while for
3941 QEMU subdriver should match the format of the disk source, such as raw
3942 or qcow2. Hypervisor default will be used if subdriver is not speci‐
3943 fied. However, the default may not be correct, esp. for QEMU as for
3944 security reasons it is configured not to detect disk formats. type can
3945 indicate lun, cdrom or floppy as alternative to the disk default, al‐
3946 though this use only replaces the media within the existing virtual
3947 cdrom or floppy device; consider using update-device for this usage in‐
3948 stead. alias can set user supplied alias. mode can specify the two
3949 specific mode readonly or shareable. sourcetype can indicate the type
3950 of source (block|file|network) cache can be one of "default", "none",
3951 "writethrough", "writeback", "directsync" or "unsafe". io controls
3952 specific policies on I/O; QEMU guests support "threads", "native" and
3953 "io_uring". iothread is the number within the range of domain IO‐
3954 Threads to which this disk may be attached (QEMU only). serial is the
3955 serial of disk device. wwn is the wwn of disk device. rawio indicates
3956 the disk needs rawio capability. address is the address of disk device
3957 in the form of pci:domain.bus.slot.function, scsi:controller.bus.unit,
3958 ide:controller.bus.unit, usb:bus.port, sata:controller.bus.unit or
3959 ccw:cssid.ssid.devno. Virtio-ccw devices must have their cssid set to
3960 0xfe. multifunction indicates specified pci address is a multifunction
3961 pci device address.
3962
3963 There is also support for using a network disk. As specified, the user
3964 can provide a --source-protocol in which case the source parameter will
3965 be interpreted as the source name. --source-protocol must be provided
3966 if the user intends to provide a network disk or host information.
3967 Host information can be provided using the tags --source-host-name,
3968 --source-host-transport, and --source-host-socket, which respectively
3969 denote the name of the host, the host's transport method, and the
3970 socket that the host uses. --source-host-socket and --source-host-name
3971 cannot both be provided, and the user must provide a
3972 --source-host-transport if they want to provide a --source-host-socket.
3973 The --source-host-name parameter supports host:port syntax if the user
3974 wants to provide a port as well.
3975
3976 If --print-xml is specified, then the XML of the disk that would be at‐
3977 tached is printed instead.
3978
3979 If --live is specified, affect a running domain. If --config is speci‐
3980 fied, affect the next startup of a persistent guest. If --current is
3981 specified, it is equivalent to either --live or --config, depending on
3982 the current state of the guest. Both --live and --config flags may be
3983 given, but --current is exclusive. When no flag is specified legacy API
3984 is used whose behavior depends on the hypervisor driver.
3985
3986 For compatibility purposes, --persistent behaves like --config for an
3987 offline domain, and like --live --config for a running domain. Like‐
3988 wise, --shareable is an alias for --mode shareable.
3989
3990 attach-interface
3991 Syntax:
3992
3993 attach-interface domain type source [[[--live]
3994 [--config] | [--current]] | [--persistent]]
3995 [--target target] [--mac mac] [--script script] [--model model]
3996 [--inbound average,peak,burst,floor] [--outbound average,peak,burst]
3997 [--alias alias] [--managed] [--print-xml]
3998
3999 Attach a new network interface to the domain.
4000
4001 type can be one of the:
4002
4003 network to indicate connection via a libvirt virtual network,
4004
4005 bridge to indicate connection via a bridge device on the host,
4006
4007 direct to indicate connection directly to one of the host's network in‐
4008 terfaces or bridges,
4009
4010 hostdev to indicate connection using a passthrough of PCI device on the
4011 host.
4012
4013 source indicates the source of the connection. The source depends on
4014 the type of the interface:
4015
4016 network name of the virtual network,
4017
4018 bridge the name of the bridge device,
4019
4020 direct the name of the host's interface or bridge,
4021
4022 hostdev the PCI address of the host's interface formatted as do‐
4023 main:bus:slot.function.
4024
4025 --target is used to specify the tap/macvtap device to be used to con‐
4026 nect the domain to the source. Names starting with 'vnet' are consid‐
4027 ered as auto-generated and are blanked out/regenerated each time the
4028 interface is attached.
4029
4030 --mac specifies the MAC address of the network interface; if a MAC ad‐
4031 dress is not given, a new address will be automatically generated (and
4032 stored in the persistent configuration if "--config" is given on the
4033 command line).
4034
4035 --script is used to specify a path to a custom script to be called
4036 while attaching to a bridge - this will be called instead of the de‐
4037 fault script not in addition to it. This is valid only for interfaces
4038 of bridge type and only for Xen domains.
4039
4040 --model specifies the network device model to be presented to the do‐
4041 main.
4042
4043 alias can set user supplied alias.
4044
4045 --inbound and --outbound control the bandwidth of the interface. At
4046 least one from the average, floor pair must be specified. The other
4047 two peak and burst are optional, so "average,peak", "average,,burst",
4048 "average,,,floor", "average" and ",,,floor" are also legal. Values for
4049 average, floor and peak are expressed in kilobytes per second, while
4050 burst is expressed in kilobytes in a single burst at peak speed as de‐
4051 scribed in the Network XML documentation at
4052 https://libvirt.org/formatnetwork.html#elementQoS.
4053
4054 --managed is usable only for hostdev type and tells libvirt that the
4055 interface should be managed, which means detached and reattached
4056 from/to the host by libvirt.
4057
4058 If --print-xml is specified, then the XML of the interface that would
4059 be attached is printed instead.
4060
4061 If --live is specified, affect a running domain. If --config is speci‐
4062 fied, affect the next startup of a persistent guest. If --current is
4063 specified, affect the current domain state, which can either be live or
4064 offline. Both --live and --config flags may be given, but --current is
4065 exclusive. When no flag is specified legacy API is used whose behavior
4066 depends on the hypervisor driver.
4067
4068 For compatibility purposes, --persistent behaves like --config for an
4069 offline domain, and like --live --config for a running domain.
4070
4071 Note: the optional target value is the name of a device to be created
4072 as the back-end on the node. If not provided a device named "vnetN" or
4073 "vifN" will be created automatically.
4074
4075 detach-device
4076 Syntax:
4077
4078 detach-device domain FILE [[[--live] [--config] |
4079 [--current]] | [--persistent]]
4080
4081 Detach a device from the domain, takes the same kind of XML descrip‐
4082 tions as command attach-device. For passthrough host devices, see also
4083 nodedev-reattach, needed if the device does not use managed mode.
4084
4085 Note: The supplied XML description of the device should be as specific
4086 as its definition in the domain XML. The set of attributes used to
4087 match the device are internal to the drivers. Using a partial defini‐
4088 tion, or attempting to detach a device that is not present in the do‐
4089 main XML, but shares some specific attributes with one that is present,
4090 may lead to unexpected results.
4091
4092 Quirk: Device unplug is asynchronous in most cases and requires guest
4093 cooperation. This means that it's up to the discretion of the guest to
4094 disallow or delay the unplug arbitrarily. As the libvirt API used in
4095 this command was designed as synchronous it returns success after some
4096 timeout even if the device was not unplugged yet to allow further in‐
4097 teractions with the domain e.g. if the guest is unresponsive. Callers
4098 which need to make sure that the device was unplugged can use libvirt
4099 events (see virsh event) to be notified when the device is removed.
4100 Note that the event may arrive before the command returns.
4101
4102 If --live is specified, affect a running domain. If --config is speci‐
4103 fied, affect the next startup of a persistent guest. If --current is
4104 specified, it is equivalent to either --live or --config, depending on
4105 the current state of the guest. Both --live and --config flags may be
4106 given, but --current is exclusive. When no flag is specified legacy API
4107 is used whose behavior depends on the hypervisor driver.
4108
4109 For compatibility purposes, --persistent behaves like --config for an
4110 offline domain, and like --live --config for a running domain.
4111
4112 Note that older versions of virsh used --config as an alias for --per‐
4113 sistent.
4114
4115 detach-device-alias
4116 Syntax:
4117
4118 detach-device-alias domain alias [[[--live] [--config] | [--current]]]]
4119
4120 Detach a device with given alias from the domain. This command returns
4121 successfully after the unplug request was sent to the hypervisor. The
4122 actual removal of the device is notified asynchronously via libvirt
4123 events (see virsh event).
4124
4125 If --live is specified, affect a running domain. If --config is speci‐
4126 fied, affect the next startup of a persistent guest. If --current is
4127 specified, it is equivalent to either --live or --config, depending on
4128 the current state of the guest. Both --live and --config flags may be
4129 given, but --current is exclusive.
4130
4131 detach-disk
4132 Syntax:
4133
4134 detach-disk domain target [[[--live] [--config] |
4135 [--current]] | [--persistent]] [--print-xml]
4136
4137 Detach a disk device from a domain. The target is the device as seen
4138 from the domain.
4139
4140 If --live is specified, affect a running domain. If --config is speci‐
4141 fied, affect the next startup of a persistent guest. If --current is
4142 specified, it is equivalent to either --live or --config, depending on
4143 the current state of the guest. Both --live and --config flags may be
4144 given, but --current is exclusive. When no flag is specified legacy API
4145 is used whose behavior depends on the hypervisor driver.
4146
4147 For compatibility purposes, --persistent behaves like --config for an
4148 offline domain, and like --live --config for a running domain.
4149
4150 Note that older versions of virsh used --config as an alias for --per‐
4151 sistent.
4152
4153 If --print-xml is specified, then the XML which would be used to detach
4154 the disk is printed instead.
4155
4156 Please see documentation for detach-device for known quirks.
4157
4158 detach-interface
4159 Syntax:
4160
4161 detach-interface domain type [--mac mac]
4162 [[[--live] [--config] | [--current]] | [--persistent]]
4163
4164 Detach a network interface from a domain. type can be either network
4165 to indicate a physical network device or bridge to indicate a bridge to
4166 a device. It is recommended to use the mac option to distinguish be‐
4167 tween the interfaces if more than one are present on the domain.
4168
4169 If --live is specified, affect a running domain. If --config is speci‐
4170 fied, affect the next startup of a persistent guest. If --current is
4171 specified, it is equivalent to either --live or --config, depending on
4172 the current state of the guest. Both --live and --config flags may be
4173 given, but --current is exclusive. When no flag is specified legacy API
4174 is used whose behavior depends on the hypervisor driver.
4175
4176 For compatibility purposes, --persistent behaves like --config for an
4177 offline domain, and like --live --config for a running domain.
4178
4179 Note that older versions of virsh used --config as an alias for --per‐
4180 sistent.
4181
4182 Please see documentation for detach-device for known quirks.
4183
4184 update-device
4185 Syntax:
4186
4187 update-device domain file [--force] [[[--live]
4188 [--config] | [--current]] | [--persistent]]
4189
4190 Update the characteristics of a device associated with domain, based on
4191 the device definition in an XML file. The --force option can be used
4192 to force device update, e.g., to eject a CD-ROM even if it is
4193 locked/mounted in the domain. See the documentation at
4194 https://libvirt.org/formatdomain.html#elementsDevices to learn about
4195 libvirt XML format for a device.
4196
4197 If --live is specified, affect a running domain. If --config is speci‐
4198 fied, affect the next startup of a persistent guest. If --current is
4199 specified, it is equivalent to either --live or --config, depending on
4200 the current state of the guest. Both --live and --config flags may be
4201 given, but --current is exclusive. Not specifying any flag is the same
4202 as specifying --current.
4203
4204 For compatibility purposes, --persistent behaves like --config for an
4205 offline domain, and like --live --config for a running domain.
4206
4207 Note that older versions of virsh used --config as an alias for --per‐
4208 sistent.
4209
4210 Note: using of partial device definition XML files may lead to unex‐
4211 pected results as some fields may be autogenerated and thus match de‐
4212 vices other than expected.
4213
4214 change-media
4215 Syntax:
4216
4217 change-media domain path [--eject] [--insert]
4218 [--update] [source] [--force] [[--live] [--config] |
4219 [--current]] [--print-xml] [--block]
4220
4221 Change media of CDROM or floppy drive. path can be the fully-qualified
4222 path or the unique target name (<target dev='hdc'>) of the disk device.
4223 source specifies the path of the media to be inserted or updated. The
4224 --block flag allows setting the backing type in case a block device is
4225 used as media for the CDROM or floppy drive instead of a file.
4226
4227 --eject indicates the media will be ejected. --insert indicates the
4228 media will be inserted. source must be specified. If the device has
4229 source (e.g. <source file='media'>), and source is not specified, --up‐
4230 date is equal to --eject. If the device has no source, and source is
4231 specified, --update is equal to --insert. If the device has source, and
4232 source is specified, --update behaves like combination of --eject and
4233 --insert. If none of --eject, --insert, and --update is specified,
4234 --update is used by default. The --force option can be used to force
4235 media changing. If --live is specified, alter live configuration of
4236 running guest. If --config is specified, alter persistent configura‐
4237 tion, effect observed on next startup of the guest. --current can be
4238 either or both of live and config, depends on the hypervisor's imple‐
4239 mentation. Both --live and --config flags may be given, but --current
4240 is exclusive. If no flag is specified, behavior is different depending
4241 on hypervisor. If --print-xml is specified, the XML that would be used
4242 to change media is printed instead of changing the media.
4243
4245 The following commands manipulate host devices that are intended to be
4246 passed through to guest domains via <hostdev> elements in a domain's
4247 <devices> section. A node device key is generally specified by the bus
4248 name followed by its address, using underscores between all components,
4249 such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
4250 The nodedev-list gives the full list of host devices that are known to
4251 libvirt, although this includes devices that cannot be assigned to a
4252 guest (for example, attempting to detach the PCI device that controls
4253 the host's hard disk controller where the guest's disk images live
4254 could cause the host system to lock up or reboot).
4255
4256 For more information on node device definition see:
4257 https://libvirt.org/formatnode.html.
4258
4259 Passthrough devices cannot be simultaneously used by the host and its
4260 guest domains, nor by multiple active guests at once. If the <hostdev>
4261 description of a PCI device includes the attribute managed='yes', and
4262 the hypervisor driver supports it, then the device is in managed mode,
4263 and attempts to use that passthrough device in an active guest will au‐
4264 tomatically behave as if nodedev-detach (guest start, device hot-plug)
4265 and nodedev-reattach (guest stop, device hot-unplug) were called at the
4266 right points. If a PCI device is not marked as managed, then it must
4267 manually be detached before guests can use it, and manually reattached
4268 to be returned to the host. Also, if a device is manually detached,
4269 then the host does not regain control of the device without a matching
4270 reattach, even if the guests use the device in managed mode.
4271
4272 nodedev-create
4273 Syntax:
4274
4275 nodedev-create FILE
4276
4277 Create a device on the host node that can then be assigned to virtual
4278 machines. Normally, libvirt is able to automatically determine which
4279 host nodes are available for use, but this allows registration of host
4280 hardware that libvirt did not automatically detect. file contains xml
4281 for a top-level <device> description of a node device.
4282
4283 nodedev-destroy
4284 Syntax:
4285
4286 nodedev-destroy device
4287
4288 Destroy (stop) a device on the host. device can be either device name
4289 or wwn pair in "wwnn,wwpn" format (only works for vHBA currently).
4290 Note that this makes libvirt quit managing a host device, and may even
4291 make that device unusable by the rest of the physical host until a re‐
4292 boot.
4293
4294 nodedev-detach
4295 Syntax:
4296
4297 nodedev-detach nodedev [--driver backend_driver]
4298
4299 Detach nodedev from the host, so that it can safely be used by guests
4300 via <hostdev> passthrough. This is reversed with nodedev-reattach, and
4301 is done automatically for managed devices.
4302
4303 Different backend drivers expect the device to be bound to different
4304 dummy devices. For example, QEMU's "kvm" backend driver (the default)
4305 expects the device to be bound to pci-stub, but its "vfio" backend
4306 driver expects the device to be bound to vfio-pci. The --driver parame‐
4307 ter can be used to specify the desired backend driver.
4308
4309 nodedev-dumpxml
4310 Syntax:
4311
4312 nodedev-dumpxml device
4313
4314 Dump a <device> XML representation for the given node device, including
4315 such information as the device name, which bus owns the device, the
4316 vendor and product id, and any capabilities of the device usable by
4317 libvirt (such as whether device reset is supported). device can be ei‐
4318 ther device name or wwn pair in "wwnn,wwpn" format (only works for
4319 HBA).
4320
4321 nodedev-list
4322 Syntax:
4323
4324 nodedev-list cap --tree
4325
4326 List all of the devices available on the node that are known by lib‐
4327 virt. cap is used to filter the list by capability types, the types
4328 must be separated by comma, e.g. --cap pci,scsi. Valid capability types
4329 include 'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host',
4330 'scsi_target', 'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic',
4331 'drm', 'mdev', 'mdev_types', 'ccw', 'css', 'ap_card', 'ap_queue',
4332 'ap_matrix'. If --tree is used, the output is formatted in a tree rep‐
4333 resenting parents of each node. cap and --tree are mutually exclusive.
4334
4335 nodedev-reattach
4336 Syntax:
4337
4338 nodedev-reattach nodedev
4339
4340 Declare that nodedev is no longer in use by any guests, and that the
4341 host can resume normal use of the device. This is done automatically
4342 for PCI devices in managed mode and USB devices, but must be done ex‐
4343 plicitly to match any explicit nodedev-detach.
4344
4345 nodedev-reset
4346 Syntax:
4347
4348 nodedev-reset nodedev
4349
4350 Trigger a device reset for nodedev, useful prior to transferring a node
4351 device between guest passthrough or the host. Libvirt will often do
4352 this action implicitly when required, but this command allows an ex‐
4353 plicit reset when needed.
4354
4355 nodedev-event
4356 Syntax:
4357
4358 nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list}
4359
4360 Wait for a class of node device events to occur, and print appropriate
4361 details of events as they happen. The events can optionally be fil‐
4362 tered by nodedev. Using --list as the only argument will provide a
4363 list of possible event values known by this client, although the con‐
4364 nection might not allow registering for all these events.
4365
4366 By default, this command is one-shot, and returns success once an event
4367 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4368 If --timeout is specified, the command gives up waiting for events af‐
4369 ter seconds have elapsed. With --loop, the command prints all events
4370 until a timeout or interrupt key.
4371
4372 When --timestamp is used, a human-readable timestamp will be printed
4373 before the event.
4374
4376 The following commands manipulate networks. Libvirt has the capability
4377 to define virtual networks which can then be used by domains and linked
4378 to actual network devices. For more detailed information about this
4379 feature see the documentation at https://libvirt.org/formatnetwork.html
4380 . Many of the commands for virtual networks are similar to the ones
4381 used for domains, but the way to name a virtual network is either by
4382 its name or UUID.
4383
4384 net-autostart
4385 Syntax:
4386
4387 net-autostart network [--disable]
4388
4389 Configure a virtual network to be automatically started at boot. The
4390 --disable option disable autostarting.
4391
4392 net-create
4393 Syntax:
4394
4395 net-create file
4396
4397 Create a transient (temporary) virtual network from an XML file and in‐
4398 stantiate (start) the network. See the documentation at
4399 https://libvirt.org/formatnetwork.html to get a description of the XML
4400 network format used by libvirt.
4401
4402 net-define
4403 Syntax:
4404
4405 net-define file
4406
4407 Define an inactive persistent virtual network or modify an existing
4408 persistent one from the XML file.
4409
4410 net-destroy
4411 Syntax:
4412
4413 net-destroy network
4414
4415 Destroy (stop) a given transient or persistent virtual network speci‐
4416 fied by its name or UUID. This takes effect immediately.
4417
4418 net-dumpxml
4419 Syntax:
4420
4421 net-dumpxml network [--inactive]
4422
4423 Output the virtual network information as an XML dump to stdout. If
4424 --inactive is specified, then physical functions are not expanded into
4425 their associated virtual functions.
4426
4427 net-edit
4428 Syntax:
4429
4430 net-edit network
4431
4432 Edit the XML configuration file for a network.
4433
4434 This is equivalent to:
4435
4436 virsh net-dumpxml --inactive network > network.xml
4437 vi network.xml (or make changes with your other text editor)
4438 virsh net-define network.xml
4439
4440 except that it does some error checking.
4441
4442 The editor used can be supplied by the $VISUAL or $EDITOR environment
4443 variables, and defaults to vi.
4444
4445 net-event
4446 Syntax:
4447
4448 net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list}
4449
4450 Wait for a class of network events to occur, and print appropriate de‐
4451 tails of events as they happen. The events can optionally be filtered
4452 by network. Using --list as the only argument will provide a list of
4453 possible event values known by this client, although the connection
4454 might not allow registering for all these events.
4455
4456 By default, this command is one-shot, and returns success once an event
4457 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
4458 If --timeout is specified, the command gives up waiting for events af‐
4459 ter seconds have elapsed. With --loop, the command prints all events
4460 until a timeout or interrupt key.
4461
4462 When --timestamp is used, a human-readable timestamp will be printed
4463 before the event.
4464
4465 net-info
4466 Syntax:
4467
4468 net-info network
4469
4470 Returns basic information about the network object.
4471
4472 net-list
4473 Syntax:
4474
4475 net-list [--inactive | --all]
4476 { [--table] | --name | --uuid }
4477 [--persistent] [<--transient>]
4478 [--autostart] [<--no-autostart>]
4479
4480 Returns the list of active networks, if --all is specified this will
4481 also include defined but inactive networks, if --inactive is specified
4482 only the inactive ones will be listed. You may also want to filter the
4483 returned networks by --persistent to list the persistent ones, --tran‐
4484 sient to list the transient ones, --autostart to list the ones with au‐
4485 tostart enabled, and --no-autostart to list the ones with autostart
4486 disabled.
4487
4488 If --name is specified, network names are printed instead of the table
4489 formatted one per line. If --uuid is specified network's UUID's are
4490 printed instead of names. Flag --table specifies that the legacy ta‐
4491 ble-formatted output should be used. This is the default. All of these
4492 are mutually exclusive.
4493
4494 NOTE: When talking to older servers, this command is forced to use a
4495 series of API calls with an inherent race, where a pool might not be
4496 listed or might appear more than once if it changed state between calls
4497 while the list was being collected. Newer servers do not have this
4498 problem.
4499
4500 net-name
4501 Syntax:
4502
4503 net-name network-UUID
4504
4505 Convert a network UUID to network name.
4506
4507 net-start
4508 Syntax:
4509
4510 net-start network
4511
4512 Start a (previously defined) inactive network.
4513
4514 net-undefine
4515 Syntax:
4516
4517 net-undefine network
4518
4519 Undefine the configuration for a persistent network. If the network is
4520 active, make it transient.
4521
4522 net-uuid
4523 Syntax:
4524
4525 net-uuid network-name
4526
4527 Convert a network name to network UUID.
4528
4529 net-update
4530 Syntax:
4531
4532 net-update network command section xml
4533 [--parent-index index] [[--live] [--config] | [--current]]
4534
4535 Update the given section of an existing network definition, with the
4536 changes optionally taking effect immediately, without needing to de‐
4537 stroy and re-start the network.
4538
4539 command is one of "add-first", "add-last", "add" (a synonym for
4540 add-last), "delete", or "modify".
4541
4542 section is one of "bridge", "domain", "ip", "ip-dhcp-host",
4543 "ip-dhcp-range", "forward", "forward-interface", "forward-pf", "port‐
4544 group", "dns-host", "dns-txt", or "dns-srv", each section being named
4545 by a concatenation of the xml element hierarchy leading to the element
4546 being changed. For example, "ip-dhcp-host" will change a <host> element
4547 that is contained inside a <dhcp> element inside an <ip> element of the
4548 network.
4549
4550 xml is either the text of a complete xml element of the type being
4551 changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the
4552 name of a file that contains a complete xml element. Disambiguation is
4553 done by looking at the first character of the provided text - if the
4554 first character is "<", it is xml text, if the first character is not
4555 "<", it is the name of a file that contains the xml text to be used.
4556
4557 The --parent-index option is used to specify which of several parent
4558 elements the requested element is in (0-based). For example, a dhcp
4559 <host> element could be in any one of multiple <ip> elements in the
4560 network; if a parent-index isn't provided, the "most appropriate" <ip>
4561 element will be selected (usually the only one that already has a
4562 <dhcp> element), but if --parent-index is given, that particular in‐
4563 stance of <ip> will get the modification.
4564
4565 If --live is specified, affect a running network. If --config is spec‐
4566 ified, affect the next startup of a persistent network. If --current
4567 is specified, it is equivalent to either --live or --config, depending
4568 on the current state of the guest. Both --live and --config flags may
4569 be given, but --current is exclusive. Not specifying any flag is the
4570 same as specifying --current.
4571
4572 net-dhcp-leases
4573 Syntax:
4574
4575 net-dhcp-leases network [mac]
4576
4577 Get a list of dhcp leases for all network interfaces connected to the
4578 given virtual network or limited output just for one interface if mac
4579 is specified.
4580
4582 The following commands manipulate network ports. Libvirt virtual net‐
4583 works have ports created when a virtual machine has a virtual network
4584 interface added. In general there should be no need to use any of the
4585 commands here, since the hypervisor drivers run these commands are the
4586 right point in a virtual machine's lifecycle. They can be useful for
4587 debugging problems and / or recovering from bugs / stale state.
4588
4589 net-port-list
4590 Syntax:
4591
4592 net-port-list { [--table] | --uuid } network
4593
4594 List all network ports recorded against the network.
4595
4596 If --uuid is specified network ports' UUID's are printed instead of a
4597 table. Flag --table specifies that the legacy table-formatted output
4598 should be used. This is the default. All of these are mutually exclu‐
4599 sive.
4600
4601 net-port-create
4602 Syntax:
4603
4604 net-port-create network file
4605
4606 Allocate a new network port reserving resources based on the port de‐
4607 scription.
4608
4609 net-port-dumpxml
4610 Syntax:
4611
4612 net-port-dumpxml network port
4613
4614 Output the network port information as an XML dump to stdout.
4615
4616 net-port-delete
4617 Syntax:
4618
4619 net-port-delete network port
4620
4621 Delete record of the network port and release its resources
4622
4624 The following commands manipulate host interfaces. Often, these host
4625 interfaces can then be used by name within domain <interface> elements
4626 (such as a system-created bridge interface), but there is no require‐
4627 ment that host interfaces be tied to any particular guest configuration
4628 XML at all.
4629
4630 Many of the commands for host interfaces are similar to the ones used
4631 for domains, and the way to name an interface is either by its name or
4632 its MAC address. However, using a MAC address for an iface argument
4633 only works when that address is unique (if an interface and a bridge
4634 share the same MAC address, which is often the case, then using that
4635 MAC address results in an error due to ambiguity, and you must resort
4636 to a name instead).
4637
4638 iface-bridge
4639 Syntax:
4640
4641 iface-bridge interface bridge [--no-stp] [delay] [--no-start]
4642
4643 Create a bridge device named bridge, and attach the existing network
4644 device interface to the new bridge. The new bridge defaults to start‐
4645 ing immediately, with STP enabled and a delay of 0; these settings can
4646 be altered with --no-stp, --no-start, and an integer number of seconds
4647 for delay. All IP address configuration of interface will be moved to
4648 the new bridge device.
4649
4650 See also iface-unbridge for undoing this operation.
4651
4652 iface-define
4653 Syntax:
4654
4655 iface-define file
4656
4657 Define an inactive persistent physical host interface or modify an ex‐
4658 isting persistent one from the XML file.
4659
4660 iface-destroy
4661 Syntax:
4662
4663 iface-destroy interface
4664
4665 Destroy (stop) a given host interface, such as by running "if-down" to
4666 disable that interface from active use. This takes effect immediately.
4667
4668 iface-dumpxml
4669 Syntax:
4670
4671 iface-dumpxml interface [--inactive]
4672
4673 Output the host interface information as an XML dump to stdout. If
4674 --inactive is specified, then the output reflects the persistent state
4675 of the interface that will be used the next time it is started.
4676
4677 iface-edit
4678 Syntax:
4679
4680 iface-edit interface
4681
4682 Edit the XML configuration file for a host interface.
4683
4684 This is equivalent to:
4685
4686 virsh iface-dumpxml iface > iface.xml
4687 vi iface.xml (or make changes with your other text editor)
4688 virsh iface-define iface.xml
4689
4690 except that it does some error checking.
4691
4692 The editor used can be supplied by the $VISUAL or $EDITOR environment
4693 variables, and defaults to vi.
4694
4695 iface-list
4696 Syntax:
4697
4698 iface-list [--inactive | --all]
4699
4700 Returns the list of active host interfaces. If --all is specified this
4701 will also include defined but inactive interfaces. If --inactive is
4702 specified only the inactive ones will be listed.
4703
4704 iface-name
4705 Syntax:
4706
4707 iface-name interface
4708
4709 Convert a host interface MAC to interface name, if the MAC address is
4710 unique among the host's interfaces.
4711
4712 interface specifies the interface MAC address.
4713
4714 iface-mac
4715 Syntax:
4716
4717 iface-mac interface
4718
4719 Convert a host interface name to MAC address.
4720
4721 interface specifies the interface name.
4722
4723 iface-start
4724 Syntax:
4725
4726 iface-start interface
4727
4728 Start a (previously defined) host interface, such as by running
4729 "if-up".
4730
4731 iface-unbridge
4732 Syntax:
4733
4734 iface-unbridge bridge [--no-start]
4735
4736 Tear down a bridge device named bridge, releasing its underlying inter‐
4737 face back to normal usage, and moving all IP address configuration from
4738 the bridge device to the underlying device. The underlying interface
4739 is restarted unless --no-start is present; this flag is present for
4740 symmetry, but generally not recommended.
4741
4742 See also iface-bridge for creating a bridge.
4743
4744 iface-undefine
4745 Syntax:
4746
4747 iface-undefine interface
4748
4749 Undefine the configuration for an inactive host interface.
4750
4751 iface-begin
4752 Syntax:
4753
4754 iface-begin
4755
4756 Create a snapshot of current host interface settings, which can later
4757 be committed (iface-commit) or restored (iface-rollback). If a snap‐
4758 shot already exists, then this command will fail until the previous
4759 snapshot has been committed or restored. Undefined behavior results if
4760 any external changes are made to host interfaces outside of the libvirt
4761 API between the beginning of a snapshot and its eventual commit or
4762 rollback.
4763
4764 iface-commit
4765 Syntax:
4766
4767 iface-commit
4768
4769 Declare all changes since the last iface-begin as working, and delete
4770 the rollback point. If no interface snapshot has already been started,
4771 then this command will fail.
4772
4773 iface-rollback
4774 Syntax:
4775
4776 iface-rollback
4777
4778 Revert all host interface settings back to the state recorded in the
4779 last iface-begin. If no interface snapshot has already been started,
4780 then this command will fail. Rebooting the host also serves as an im‐
4781 plicit rollback point.
4782
4784 The following commands manipulate storage pools. Libvirt has the capa‐
4785 bility to manage various storage solutions, including files, raw parti‐
4786 tions, and domain-specific formats, used to provide the storage volumes
4787 visible as devices within virtual machines. For more detailed informa‐
4788 tion about this feature, see the documentation at
4789 https://libvirt.org/formatstorage.html . Many of the commands for pools
4790 are similar to the ones used for domains.
4791
4792 find-storage-pool-sources
4793 Syntax:
4794
4795 find-storage-pool-sources type [srcSpec]
4796
4797 Returns XML describing all possible available storage pool sources that
4798 could be used to create or define a storage pool of a given type. If
4799 srcSpec is provided, it is a file that contains XML to further restrict
4800 the query for pools.
4801
4802 Not all storage pools support discovery in this manner. Furthermore,
4803 for those that do support discovery, only specific XML elements are re‐
4804 quired in order to return valid data, while other elements and even at‐
4805 tributes of some elements are ignored since they are not necessary to
4806 find the pool based on the search criteria. The following lists the
4807 supported type options and the expected minimal XML elements used to
4808 perform the search.
4809
4810 For a "netfs" or "gluster" pool, the minimal expected XML required is
4811 the <host> element with a "name" attribute describing the IP address or
4812 hostname to be used to find the pool. The "port" attribute will be ig‐
4813 nored as will any other provided XML elements in srcSpec.
4814
4815 For a "logical" pool, the contents of the srcSpec file are ignored, al‐
4816 though if provided the file must at least exist.
4817
4818 For an "iscsi" or "iscsi-direct" pool, the minimal expect XML required
4819 is the <host> element with a "name" attribute describing the IP address
4820 or hostname to be used to find the pool (the iSCSI server address). Op‐
4821 tionally, the "port" attribute may be provided, although it will de‐
4822 fault to 3260. Optionally, an <initiator> XML element with a "name" at‐
4823 tribute may be provided to further restrict the iSCSI target search to
4824 a specific initiator for multi-iqn iSCSI storage pools.
4825
4826 find-pool-sources-as
4827 Syntax:
4828
4829 find-storage-pool-sources-as type [host] [port] [initiator]
4830
4831 Rather than providing srcSpec XML file for find-storage-pool-sources
4832 use this command option in order to have virsh generate the query XML
4833 file using the optional arguments. The command will return the same
4834 output XML as find-storage-pool-sources.
4835
4836 Use host to describe a specific host to use for networked storage, such
4837 as netfs, gluster, and iscsi type pools.
4838
4839 Use port to further restrict which networked port to utilize for the
4840 connection if required by the specific storage backend, such as iscsi.
4841
4842 Use initiator to further restrict the iscsi type pool searches to spe‐
4843 cific target initiators.
4844
4845 pool-autostart
4846 Syntax:
4847
4848 pool-autostart pool-or-uuid [--disable]
4849
4850 Configure whether pool should automatically start at boot.
4851
4852 pool-build
4853 Syntax:
4854
4855 pool-build pool-or-uuid [--overwrite] [--no-overwrite]
4856
4857 Build a given pool.
4858
4859 Options --overwrite and --no-overwrite can only be used for pool-build
4860 a filesystem, disk, or logical pool.
4861
4862 For a file system pool if neither flag is specified, then pool-build
4863 just makes the target path directory and no attempt to run mkfs on the
4864 target volume device. If --no-overwrite is specified, it probes to de‐
4865 termine if a filesystem already exists on the target device, returning
4866 an error if one exists or using mkfs to format the target device if
4867 not. If --overwrite is specified, mkfs is always executed and any ex‐
4868 isting data on the target device is overwritten unconditionally.
4869
4870 For a disk pool, if neither of them is specified or --no-overwrite is
4871 specified, pool-build will check the target volume device for existing
4872 filesystems or partitions before attempting to write a new label on the
4873 target volume device. If the target volume device already has a label,
4874 the command will fail. If --overwrite is specified, then no check will
4875 be made on the target volume device prior to writing a new label. Writ‐
4876 ing of the label uses the pool source format type or "dos" if not spec‐
4877 ified.
4878
4879 For a logical pool, if neither of them is specified or --no-overwrite
4880 is specified, pool-build will check the target volume devices for ex‐
4881 isting filesystems or partitions before attempting to initialize and
4882 format each device for usage by the logical pool. If any target volume
4883 device already has a label, the command will fail. If --overwrite is
4884 specified, then no check will be made on the target volume devices
4885 prior to initializing and formatting each device. Once all the target
4886 volume devices are properly formatted via pvcreate, the volume group
4887 will be created using all the devices.
4888
4889 pool-create
4890 Syntax:
4891
4892 pool-create file [--build] [[--overwrite] | [--no-overwrite]]
4893
4894 Create and start a pool object from the XML file.
4895
4896 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
4897 creation in order to remove the need for a follow-up command to build
4898 the pool. The --overwrite and --no-overwrite flags follow the same
4899 rules as pool-build. If just --build is provided, then pool-build is
4900 called with no flags.
4901
4902 pool-create-as
4903 Syntax:
4904
4905 pool-create-as name type
4906 [--source-host hostname] [--source-path path] [--source-dev path]
4907 [--source-name name] [--target path] [--source-format format]
4908 [--source-initiator initiator-iqn]
4909 [--auth-type authtype --auth-username username
4910 [--secret-usage usage | --secret-uuid uuid]]
4911 [--source-protocol-ver ver]
4912 [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn]
4913 [--adapter-parent parent |
4914 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
4915 --adapter-parent-fabric-wwn parent_fabric_wwn]]
4916 [--build] [[--overwrite] | [--no-overwrite]] [--print-xml]
4917
4918 Create and start a pool object name from the raw parameters. If
4919 --print-xml is specified, then print the XML of the pool object without
4920 creating the pool. Otherwise, the pool has the specified type. When
4921 using pool-create-as for a pool of type "disk", the existing partitions
4922 found on the --source-dev path will be used to populate the disk pool.
4923 Therefore, it is suggested to use pool-define-as and pool-build with
4924 the --overwrite in order to properly initialize the disk pool.
4925
4926 [--source-host hostname] provides the source hostname for pools backed
4927 by storage from a remote server (pool types netfs, iscsi, rbd, sheep‐
4928 dog, gluster).
4929
4930 [--source-path path] provides the source directory path for pools
4931 backed by directories (pool type dir).
4932
4933 [--source-dev path] provides the source path for pools backed by physi‐
4934 cal devices (pool types fs, logical, disk, iscsi, zfs).
4935
4936 [--source-name name] provides the source name for pools backed by stor‐
4937 age from a named element (pool types logical, rbd, sheepdog, gluster).
4938
4939 [--target path] is the path for the mapping of the storage pool into
4940 the host file system.
4941
4942 [--source-format format] provides information about the format of the
4943 pool (pool types fs, netfs, disk, logical).
4944
4945 [--source-initiator initiator-iqn] provides the initiator iqn for iscsi
4946 connection of the pool (pool type iscsi-direct).
4947
4948 [--auth-type authtype --auth-username username [--secret-usage usage |
4949 --secret-uuid uuid]] provides the elements required to generate authen‐
4950 tication credentials for the storage pool. The authtype is either chap
4951 for iscsi type pools or ceph for rbd type pools. Either the secret us‐
4952 age or uuid value may be provided, but not both.
4953
4954 [--source-protocol-ver ver] provides the NFS protocol version number
4955 used to contact the server's NFS service via nfs mount option
4956 'nfsvers=n'. It is expect the ver value is an unsigned integer.
4957
4958 [--adapter-name name] defines the scsi_hostN adapter name to be used
4959 for the scsi_host adapter type pool.
4960
4961 [--adapter-wwnn wwnn --adapter-wwpn wwpn [--adapter-parent parent |
4962 --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn |
4963 --adapter-parent-fabric-wwn parent_fabric_wwn]] defines the wwnn and
4964 wwpn to be used for the fc_host adapter type pool. Optionally provide
4965 the parent scsi_hostN node device to be used for the vHBA either by
4966 parent name, parent_wwnn and parent_wwpn, or parent_fabric_wwn. The
4967 parent name could change between reboots if the hardware environment
4968 changes, so providing the parent_wwnn and parent_wwpn ensure usage of
4969 the same physical HBA even if the scsi_hostN node device changes. Usage
4970 of the parent_fabric_wwn allows a bit more flexibility to choose an HBA
4971 on the same storage fabric in order to define the pool.
4972
4973 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after
4974 creation in order to remove the need for a follow-up command to build
4975 the pool. The --overwrite and --no-overwrite flags follow the same
4976 rules as pool-build. If just --build is provided, then pool-build is
4977 called with no flags.
4978
4979 For a "logical" pool only [--name] needs to be provided. The
4980 [--source-name] if provided must match the Volume Group name. If not
4981 provided, one will be generated using the [--name]. If provided the
4982 [--target] is ignored and a target source is generated using the
4983 [--source-name] (or as generated from the [--name]).
4984
4985 pool-define
4986 Syntax:
4987
4988 pool-define file
4989
4990 Define an inactive persistent storage pool or modify an existing per‐
4991 sistent one from the XML file.
4992
4993 pool-define-as
4994 Syntax:
4995
4996 pool-define-as name type
4997 [--source-host hostname] [--source-path path] [--source-dev path]
4998 [*--source-name name*] [*--target path*] [*--source-format format*]
4999 [--source-initiator initiator-iqn]
5000 [*--auth-type authtype* *--auth-username username*
5001 [*--secret-usage usage* | *--secret-uuid uuid*]]
5002 [*--source-protocol-ver ver*]
5003 [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*]
5004 [*--adapter-parent parent*]] [*--print-xml*]
5005
5006 Create, but do not start, a pool object name from the raw parameters.
5007 If --print-xml is specified, then print the XML of the pool object
5008 without defining the pool. Otherwise, the pool has the specified type.
5009
5010 Use the same arguments as pool-create-as, except for the --build,
5011 --overwrite, and --no-overwrite options.
5012
5013 pool-destroy
5014 Syntax:
5015
5016 pool-destroy pool-or-uuid
5017
5018 Destroy (stop) a given pool object. Libvirt will no longer manage the
5019 storage described by the pool object, but the raw data contained in the
5020 pool is not changed, and can be later recovered with pool-create.
5021
5022 pool-delete
5023 Syntax:
5024
5025 pool-delete pool-or-uuid
5026
5027 Destroy the resources used by a given pool object. This operation is
5028 non-recoverable. The pool object will still exist after this command,
5029 ready for the creation of new storage volumes.
5030
5031 pool-dumpxml
5032 Syntax:
5033
5034 pool-dumpxml [--inactive] pool-or-uuid
5035
5036 Returns the XML information about the pool object. --inactive tells
5037 virsh to dump pool configuration that will be used on next start of the
5038 pool as opposed to the current pool configuration.
5039
5040 pool-edit
5041 Syntax:
5042
5043 pool-edit pool-or-uuid
5044
5045 Edit the XML configuration file for a storage pool.
5046
5047 This is equivalent to:
5048
5049 virsh pool-dumpxml pool > pool.xml
5050 vi pool.xml (or make changes with your other text editor)
5051 virsh pool-define pool.xml
5052
5053 except that it does some error checking.
5054
5055 The editor used can be supplied by the $VISUAL or $EDITOR environment
5056 variables, and defaults to vi.
5057
5058 pool-info
5059 Syntax:
5060
5061 pool-info [--bytes] pool-or-uuid
5062
5063 Returns basic information about the pool object. If --bytes is speci‐
5064 fied the sizes of basic info are not converted to human friendly units.
5065
5066 pool-list
5067 Syntax:
5068
5069 pool-list [--inactive] [--all]
5070 [--persistent] [--transient]
5071 [--autostart] [--no-autostart]
5072 [[--details] [--uuid]
5073 [--name] [<type>]
5074
5075 List pool objects known to libvirt. By default, only active pools are
5076 listed; --inactive lists just the inactive pools, and --all lists all
5077 pools.
5078
5079 In addition, there are several sets of filtering flags. --persistent is
5080 to list the persistent pools, --transient is to list the transient
5081 pools. --autostart lists the autostarting pools, --no-autostart lists
5082 the pools with autostarting disabled. If --uuid is specified only
5083 pool's UUIDs are printed. If --name is specified only pool's names are
5084 printed. If both --name and --uuid are specified, pool's UUID and names
5085 are printed side by side without any header. Option --details is mutu‐
5086 ally exclusive with options --uuid and --name.
5087
5088 You may also want to list pools with specified types using type, the
5089 pool types must be separated by comma, e.g. --type dir,disk. The valid
5090 pool types include 'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi',
5091 'scsi', 'mpath', 'rbd', 'sheepdog', 'gluster', 'zfs', 'vstorage' and
5092 'iscsi-direct'.
5093
5094 The --details option instructs virsh to additionally display pool per‐
5095 sistence and capacity related information where available.
5096
5097 NOTE: When talking to older servers, this command is forced to use a
5098 series of API calls with an inherent race, where a pool might not be
5099 listed or might appear more than once if it changed state between calls
5100 while the list was being collected. Newer servers do not have this
5101 problem.
5102
5103 pool-name
5104 Syntax:
5105
5106 pool-name uuid
5107
5108 Convert the uuid to a pool name.
5109
5110 pool-refresh
5111 Syntax:
5112
5113 pool-refresh pool-or-uuid
5114
5115 Refresh the list of volumes contained in pool.
5116
5117 pool-start
5118 Syntax:
5119
5120 pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]
5121
5122 Start the storage pool, which is previously defined but inactive.
5123
5124 [--build] [[--overwrite] | [--no-overwrite]] perform a pool-build prior
5125 to pool-start to ensure the pool environment is in an expected state
5126 rather than needing to run the build command prior to startup. The
5127 --overwrite and --no-overwrite flags follow the same rules as
5128 pool-build. If just --build is provided, then pool-build is called with
5129 no flags.
5130
5131 Note: A storage pool that relies on remote resources such as an "iscsi"
5132 or a (v)HBA backed "scsi" pool may need to be refreshed multiple times
5133 in order to have all the volumes detected (see pool-refresh). This is
5134 because the corresponding volume devices may not be present in the
5135 host's filesystem during the initial pool startup or the current re‐
5136 fresh attempt. The number of refresh retries is dependent upon the net‐
5137 work connection and the time the host takes to export the corresponding
5138 devices.
5139
5140 pool-undefine
5141 Syntax:
5142
5143 pool-undefine pool-or-uuid
5144
5145 Undefine the configuration for an inactive pool.
5146
5147 pool-uuid
5148 Syntax:
5149
5150 pool-uuid pool
5151
5152 Returns the UUID of the named pool.
5153
5154 pool-event
5155 Syntax:
5156
5157 pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list}
5158
5159 Wait for a class of storage pool events to occur, and print appropriate
5160 details of events as they happen. The events can optionally be fil‐
5161 tered by pool. Using --list as the only argument will provide a list
5162 of possible event values known by this client, although the connection
5163 might not allow registering for all these events.
5164
5165 By default, this command is one-shot, and returns success once an event
5166 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
5167 If --timeout is specified, the command gives up waiting for events af‐
5168 ter seconds have elapsed. With --loop, the command prints all events
5169 until a timeout or interrupt key.
5170
5171 When --timestamp is used, a human-readable timestamp will be printed
5172 before the event.
5173
5175 vol-create
5176 Syntax:
5177
5178 vol-create pool-or-uuid FILE [--prealloc-metadata]
5179
5180 Create a volume from an XML <file>.
5181
5182 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5183 ume in.
5184
5185 FILE is the XML <file> with the volume definition. An easy way to cre‐
5186 ate the XML <file> is to use the vol-dumpxml command to obtain the def‐
5187 inition of a pre-existing volume.
5188
5189 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5190 don't support full allocation). This option creates a sparse image file
5191 with metadata, resulting in higher performance compared to images with
5192 no preallocation and only slightly higher initial disk space usage.
5193
5194 Example:
5195
5196 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
5197 vi newvolume.xml (or make changes with your other text editor)
5198 virsh vol-create differentstoragepool newvolume.xml
5199
5200 vol-create-from
5201 Syntax:
5202
5203 vol-create-from pool-or-uuid FILE vol-name-or-key-or-path
5204 [--inputpool pool-or-uuid] [--prealloc-metadata] [--reflink]
5205
5206 Create a volume, using another volume as input.
5207
5208 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5209 ume in.
5210
5211 FILE is the XML <file> with the volume definition.
5212
5213 vol-name-or-key-or-path is the name or key or path of the source vol‐
5214 ume.
5215
5216 --inputpool pool-or-uuid is the name or uuid of the storage pool the
5217 source volume is in.
5218
5219 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5220 don't support full allocation). This option creates a sparse image file
5221 with metadata, resulting in higher performance compared to images with
5222 no preallocation and only slightly higher initial disk space usage.
5223
5224 When --reflink is specified, perform a COW lightweight copy, where the
5225 data blocks are copied only when modified. If this is not possible,
5226 the copy fails.
5227
5228 vol-create-as
5229 Syntax:
5230
5231 vol-create-as pool-or-uuid name capacity [--allocation size] [--format string]
5232 [--backing-vol vol-name-or-key-or-path]
5233 [--backing-vol-format string] [--prealloc-metadata] [--print-xml]
5234
5235 Create a volume from a set of arguments unless --print-xml is speci‐
5236 fied, in which case just the XML of the volume object is printed out
5237 without any actual object creation.
5238
5239 pool-or-uuid is the name or UUID of the storage pool to create the vol‐
5240 ume in.
5241
5242 name is the name of the new volume. For a disk pool, this must match
5243 the partition name as determined from the pool's source device path and
5244 the next available partition. For example, a source device path of
5245 /dev/sdb and there are no partitions on the disk, then the name must be
5246 sdb1 with the next name being sdb2 and so on.
5247
5248 capacity is the size of the volume to be created, as a scaled integer
5249 (see NOTES above), defaulting to bytes if there is no suffix.
5250
5251 --allocation size is the initial size to be allocated in the volume,
5252 also as a scaled integer defaulting to bytes.
5253
5254 --format string is used in file based storage pools to specify the vol‐
5255 ume file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use ex‐
5256 tended for disk storage pools in order to create an extended partition
5257 (other values are validity checked but not preserved when libvirtd is
5258 restarted or the pool is refreshed).
5259
5260 --backing-vol vol-name-or-key-or-path is the source backing volume to
5261 be used if taking a snapshot of an existing volume.
5262
5263 --backing-vol-format string is the format of the snapshot backing vol‐
5264 ume; raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, how‐
5265 ever, meant for file based storage pools.
5266
5267 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5268 don't support full allocation). This option creates a sparse image file
5269 with metadata, resulting in higher performance compared to images with
5270 no preallocation and only slightly higher initial disk space usage.
5271
5272 vol-clone
5273 Syntax:
5274
5275 vol-clone vol-name-or-key-or-path name
5276 [--pool pool-or-uuid] [--prealloc-metadata] [--reflink]
5277
5278 Clone an existing volume within the parent pool. Less powerful, but
5279 easier to type, version of vol-create-from.
5280
5281 vol-name-or-key-or-path is the name or key or path of the source vol‐
5282 ume.
5283
5284 name is the name of the new volume.
5285
5286 --pool pool-or-uuid is the name or UUID of the storage pool that con‐
5287 tains the source volume and will contain the new volume. If the source
5288 volume name is provided instead of the key or path, then providing the
5289 pool is necessary to find the volume to be cloned; otherwise, the first
5290 volume found by the key or path will be used.
5291
5292 [--prealloc-metadata] preallocate metadata (for qcow2 images which
5293 don't support full allocation). This option creates a sparse image file
5294 with metadata, resulting in higher performance compared to images with
5295 no preallocation and only slightly higher initial disk space usage.
5296
5297 When --reflink is specified, perform a COW lightweight copy, where the
5298 data blocks are copied only when modified. If this is not possible,
5299 the copy fails.
5300
5301 vol-delete
5302 Syntax:
5303
5304 vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots]
5305
5306 Delete a given volume.
5307
5308 vol-name-or-key-or-path is the volume name or key or path of the volume
5309 to delete.
5310
5311 [--pool pool-or-uuid] is the name or UUID of the storage pool the vol‐
5312 ume is in. If the volume name is provided instead of the key or path,
5313 then providing the pool is necessary to find the volume to be deleted;
5314 otherwise, the first volume found by the key or path will be used.
5315
5316 The --delete-snapshots flag specifies that any snapshots associated
5317 with the storage volume should be deleted as well. Not all storage
5318 drivers support this option, presently only rbd.
5319
5320 vol-upload
5321 Syntax:
5322
5323 vol-upload vol-name-or-key-or-path local-file
5324 [--pool pool-or-uuid] [--offset bytes]
5325 [--length bytes] [--sparse]
5326
5327 Upload the contents of local-file to a storage volume.
5328
5329 vol-name-or-key-or-path is the name or key or path of the volume where
5330 the local-file will be uploaded.
5331
5332 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5333 is in. If the volume name is provided instead of the key or path, then
5334 providing the pool is necessary to find the volume to be uploaded into;
5335 otherwise, the first volume found by the key or path will be used.
5336
5337 --offset is the position in the storage volume at which to start writ‐
5338 ing the data. The value must be 0 or larger.
5339
5340 --length is an upper bound of the amount of data to be uploaded. A
5341 negative value is interpreted as an unsigned long long value to essen‐
5342 tially include everything from the offset to the end of the volume.
5343
5344 If --sparse is specified, this command will preserve volume sparseness.
5345
5346 An error will occur if the local-file is greater than the specified
5347 length.
5348
5349 See the description for the libvirt virStorageVolUpload API for details
5350 regarding possible target volume and pool changes as a result of the
5351 pool refresh when the upload is attempted.
5352
5353 vol-download
5354 Syntax:
5355
5356 vol-download vol-name-or-key-or-path local-file
5357 [--pool pool-or-uuid] [--offset bytes] [--length bytes]
5358 [--sparse]
5359
5360 Download the contents of a storage volume to local-file.
5361
5362 vol-name-or-key-or-path is the name or key or path of the volume to
5363 download into local-file.
5364
5365 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5366 is in. If the volume name is provided instead of the key or path, then
5367 providing the pool is necessary to find the volume to be uploaded into;
5368 otherwise, the first volume found by the key or path will be used.
5369
5370 --offset is the position in the storage volume at which to start read‐
5371 ing the data. The value must be 0 or larger.
5372
5373 --length is an upper bound of the amount of data to be downloaded. A
5374 negative value is interpreted as an unsigned long long value to essen‐
5375 tially include everything from the offset to the end of the volume.
5376
5377 If --sparse is specified, this command will preserve volume sparseness.
5378
5379 vol-wipe
5380 Syntax:
5381
5382 vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm]
5383
5384 Wipe a volume, ensure data previously on the volume is not accessible
5385 to future reads.
5386
5387 vol-name-or-key-or-path is the name or key or path of the volume to
5388 wipe. It is possible to choose different wiping algorithms instead of
5389 re-writing volume with zeroes.
5390
5391 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5392 is in. If the volume name is provided instead of the key or path, then
5393 providing the pool is necessary to find the volume to be wiped; other‐
5394 wise, the first volume found by the key or path will be used.
5395
5396 Use the --algorithm switch choosing from the list of the following al‐
5397 gorithms in order to define which algorithm to use for the wipe.
5398
5399 Supported algorithms
5400
5401 • zero - 1-pass all zeroes
5402
5403 • nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for sani‐
5404 tizing removable and non-removable hard disks: random x2, 0x00, ver‐
5405 ify.
5406
5407 • dod - 4-pass DoD 5220.22-M section 8-306 procedure for sani‐
5408 tizing removable and non-removable rigid disks: random, 0x00, 0xff,
5409 verify.
5410
5411 • bsi - 9-pass method recommended by the German Center of Secu‐
5412 rity in Information Technologies (https://www.bsi.bund.de): 0xff,
5413 0xfe, 0xfd, 0xfb, 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
5414
5415 • gutmann - The canonical 35-pass sequence described in Gutmann's
5416 paper.
5417
5418 • schneier - 7-pass method described by Bruce Schneier in "Applied
5419 Cryptography" (1996): 0x00, 0xff, random x5.
5420
5421 • pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7.
5422
5423 • pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
5424
5425 • random - 1-pass pattern: random.
5426
5427 • trim - 1-pass trimming the volume using TRIM or DISCARD
5428
5429 Note: The scrub binary will be used to handle the 'nnsa', 'dod', 'bsi',
5430 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33' algorithms. The
5431 availability of the algorithms may be limited by the version of the
5432 scrub binary installed on the host. The 'zero' algorithm will write ze‐
5433 roes to the entire volume. For some volumes, such as sparse or rbd vol‐
5434 umes, this may result in completely filling the volume with zeroes mak‐
5435 ing it appear to be completely full. As an alternative, the 'trim' al‐
5436 gorithm does not overwrite all the data in a volume, rather it expects
5437 the storage driver to be able to discard all bytes in a volume. It is
5438 up to the storage driver to handle how the discarding occurs. Not all
5439 storage drivers or volume types can support 'trim'.
5440
5441 vol-dumpxml
5442 Syntax:
5443
5444 vol-dumpxml vol-name-or-key-or-path [--pool pool-or-uuid]
5445
5446 Output the volume information as an XML dump to stdout.
5447
5448 vol-name-or-key-or-path is the name or key or path of the volume to
5449 output the XML.
5450
5451 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5452 is in. If the volume name is provided instead of the key or path, then
5453 providing the pool is necessary to find the volume to be uploaded into;
5454 otherwise, the first volume found by the key or path will be used.
5455
5456 vol-info
5457 Syntax:
5458
5459 vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical]
5460
5461 Returns basic information about the given storage volume.
5462
5463 vol-name-or-key-or-path is the name or key or path of the volume to re‐
5464 turn information for.
5465
5466 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5467 is in. If the volume name is provided instead of the key or path, then
5468 providing the pool is necessary to find the volume to be uploaded into;
5469 otherwise, the first volume found by the key or path will be used.
5470
5471 If --bytes is specified the sizes are not converted to human friendly
5472 units.
5473
5474 If --physical is specified, then the host physical size is returned and
5475 displayed instead of the allocation value. The physical value for some
5476 file types, such as qcow2 may have a different (larger) physical value
5477 than is shown for allocation. Additionally sparse files will have dif‐
5478 ferent physical and allocation values.
5479
5480 vol-list
5481 Syntax:
5482
5483 vol-list [--pool pool-or-uuid] [--details]
5484
5485 Return the list of volumes in the given storage pool.
5486
5487 --pool pool-or-uuid is the name or UUID of the storage pool.
5488
5489 The --details option instructs virsh to additionally display volume
5490 type and capacity related information where available.
5491
5492 vol-pool
5493 Syntax:
5494
5495 vol-pool vol-key-or-path [--uuid]
5496
5497 Return the pool name or UUID for a given volume. By default, the pool
5498 name is returned.
5499
5500 vol-key-or-path is the key or path of the volume to return the pool in‐
5501 formation.
5502
5503 If the --uuid option is given, the pool UUID is returned instead.
5504
5505 vol-path
5506 Syntax:
5507
5508 vol-path vol-name-or-key [--pool pool-or-uuid]
5509
5510 Return the path for a given volume.
5511
5512 vol-name-or-key is the name or key of the volume to return the path.
5513
5514 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5515 is in. If the volume name is provided instead of the key, then provid‐
5516 ing the pool is necessary to find the volume to be uploaded into; oth‐
5517 erwise, the first volume found by the key will be used.
5518
5519 vol-name
5520 Syntax:
5521
5522 vol-name vol-key-or-path
5523
5524 Return the name for a given volume.
5525
5526 vol-key-or-path is the key or path of the volume to return the name.
5527
5528 vol-key
5529 Syntax:
5530
5531 vol-key vol-name-or-path [--pool pool-or-uuid]
5532
5533 Return the volume key for a given volume.
5534
5535 vol-name-or-path is the name or path of the volume to return the volume
5536 key.
5537
5538 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5539 is in. If the volume name is provided instead of the path, then provid‐
5540 ing the pool is necessary to find the volume to be uploaded into; oth‐
5541 erwise, the first volume found by the path will be used.
5542
5543 vol-resize
5544 Syntax:
5545
5546 vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink]
5547
5548 Resize the capacity of the given volume, in bytes.
5549
5550 vol-name-or-key-or-path is the name or key or path of the volume to re‐
5551 size.
5552
5553 capacity is a scaled integer (see NOTES above) for the volume, which
5554 defaults to bytes if there is no suffix.
5555
5556 --pool pool-or-uuid is the name or UUID of the storage pool the volume
5557 is in. If the volume name is provided instead of the key or path, then
5558 providing the pool is necessary to find the volume to be uploaded into;
5559 otherwise, the first volume found by the key or path will be used.
5560
5561 The new capacity might be sparse unless --allocate is specified.
5562
5563 Normally, capacity is the new size, but if --delta is present, then it
5564 is added to the existing size.
5565
5566 Attempts to shrink the volume will fail unless --shrink is present.
5567 The capacity cannot be negative unless --shrink is provided, but a neg‐
5568 ative sign is not necessary.
5569
5570 This command is only safe for storage volumes not in use by an active
5571 guest; see also blockresize for live resizing.
5572
5574 The following commands manipulate "secrets" (e.g. passwords,
5575 passphrases and encryption keys). Libvirt can store secrets indepen‐
5576 dently from their use, and other objects (e.g. volumes or domains) can
5577 refer to the secrets for encryption or possibly other uses. Secrets
5578 are identified using a UUID. See https://libvirt.org/formatsecret.html
5579 for documentation of the XML format used to represent properties of se‐
5580 crets.
5581
5582 secret-define
5583 Syntax:
5584
5585 secret-define file
5586
5587 Create a secret with the properties specified in file, with no associ‐
5588 ated secret value. If file does not specify a UUID, choose one auto‐
5589 matically. If file specifies a UUID of an existing secret, replace its
5590 properties by properties defined in file, without affecting the secret
5591 value.
5592
5593 secret-dumpxml
5594 Syntax:
5595
5596 secret-dumpxml secret
5597
5598 Output properties of secret (specified by its UUID) as an XML dump to
5599 stdout.
5600
5601 secret-event
5602 Syntax:
5603
5604 secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list}
5605
5606 Wait for a class of secret events to occur, and print appropriate de‐
5607 tails of events as they happen. The events can optionally be filtered
5608 by secret. Using --list as the only argument will provide a list of
5609 possible event values known by this client, although the connection
5610 might not allow registering for all these events.
5611
5612 By default, this command is one-shot, and returns success once an event
5613 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
5614 If --timeout is specified, the command gives up waiting for events af‐
5615 ter seconds have elapsed. With --loop, the command prints all events
5616 until a timeout or interrupt key.
5617
5618 When --timestamp is used, a human-readable timestamp will be printed
5619 before the event.
5620
5621 secret-set-value
5622 Syntax:
5623
5624 secret-set-value secret (--file filename [--plain] | --interactive | base64)
5625
5626 Set the value associated with secret (specified by its UUID) to the
5627 value Base64-encoded value base64 or Base-64-encoded contents of file
5628 named filename. Using the --plain flag is together with --file allows
5629 one to use the file contents directly as the secret value.
5630
5631 If --interactive flag is used the secret value is read as a password
5632 from the terminal.
5633
5634 Note that --file, --interactive and base64 options are mutually exclu‐
5635 sive.
5636
5637 Passing secrets via the base64 option on command line is INSECURE and
5638 deprecated. Use the --file option instead.
5639
5640 secret-get-value
5641 Syntax:
5642
5643 secret-get-value [--plain] secret
5644
5645 Output the value associated with secret (specified by its UUID) to std‐
5646 out, encoded using Base64.
5647
5648 If the --plain flag is used the value is not base64 encoded, but rather
5649 printed raw. Note that unless virsh is started in quiet mode (virsh -q)
5650 it prints a newline at the end of the command. This newline is not part
5651 of the secret.
5652
5653 secret-undefine
5654 Syntax:
5655
5656 secret-undefine secret
5657
5658 Delete a secret (specified by its UUID), including the associated
5659 value, if any.
5660
5661 secret-list
5662 Syntax:
5663
5664 secret-list [--ephemeral] [--no-ephemeral]
5665 [--private] [--no-private]
5666
5667 Returns the list of secrets. You may also want to filter the returned
5668 secrets by --ephemeral to list the ephemeral ones, --no-ephemeral to
5669 list the non-ephemeral ones, --private to list the private ones, and
5670 --no-private to list the non-private ones.
5671
5673 The following commands manipulate domain snapshots. Snapshots take the
5674 disk, memory, and device state of a domain at a point-of-time, and save
5675 it for future use. They have many uses, from saving a "clean" copy of
5676 an OS image to saving a domain's state before a potentially destructive
5677 operation. Snapshots are identified with a unique name. See
5678 https://libvirt.org/formatsnapshot.html for documentation of the XML
5679 format used to represent properties of snapshots.
5680
5681 snapshot-create
5682 Syntax:
5683
5684 snapshot-create domain [xmlfile] {[--redefine [--current]] |
5685 [--no-metadata] [--halt] [--disk-only] [--reuse-external]
5686 [--quiesce] [--atomic] [--live]} [--validate]
5687
5688 Create a snapshot for domain domain with the properties specified in
5689 xmlfile. Optionally, the --validate option can be passed to validate
5690 the format of the input XML file against an internal RNG schema (iden‐
5691 tical to using the virt-xml-validate(1) tool). Normally, the only prop‐
5692 erties settable for a domain snapshot are the <name> and <description>
5693 elements, as well as <disks> if --disk-only is given; the rest of the
5694 fields are ignored, and automatically filled in by libvirt. If xmlfile
5695 is completely omitted, then libvirt will choose a value for all fields.
5696 The new snapshot will become current, as listed by snapshot-current.
5697
5698 If --halt is specified, the domain will be left in an inactive state
5699 after the snapshot is created.
5700
5701 If --disk-only is specified, the snapshot will only include disk con‐
5702 tent rather than the usual full system snapshot with vm state. Disk
5703 snapshots are captured faster than full system snapshots, but reverting
5704 to a disk snapshot may require fsck or journal replays, since it is
5705 like the disk state at the point when the power cord is abruptly
5706 pulled; and mixing --halt and --disk-only loses any data that was not
5707 flushed to disk at the time.
5708
5709 If --redefine is specified, then all XML elements produced by snap‐
5710 shot-dumpxml are valid; this can be used to migrate snapshot hierarchy
5711 from one machine to another, to recreate hierarchy for the case of a
5712 transient domain that goes away and is later recreated with the same
5713 name and UUID, or to make slight alterations in the snapshot metadata
5714 (such as host-specific aspects of the domain XML embedded in the snap‐
5715 shot). When this flag is supplied, the xmlfile argument is mandatory,
5716 and the domain's current snapshot will not be altered unless the --cur‐
5717 rent flag is also given.
5718
5719 If --no-metadata is specified, then the snapshot data is created, but
5720 any metadata is immediately discarded (that is, libvirt does not treat
5721 the snapshot as current, and cannot revert to the snapshot unless --re‐
5722 define is later used to teach libvirt about the metadata again).
5723
5724 If --reuse-external is specified, and the snapshot XML requests an ex‐
5725 ternal snapshot with a destination of an existing file, then the desti‐
5726 nation must exist and be pre-created with correct format and metadata.
5727 The file is then reused; otherwise, a snapshot is refused to avoid los‐
5728 ing contents of the existing files.
5729
5730 If --quiesce is specified, libvirt will try to use guest agent to
5731 freeze and unfreeze domain's mounted file systems. However, if domain
5732 has no guest agent, snapshot creation will fail. Currently, this re‐
5733 quires --disk-only to be passed as well.
5734
5735 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
5736 ther succeeds, or fails with no changes; not all hypervisors support
5737 this. If this flag is not specified, then some hypervisors may fail
5738 after partially performing the action, and dumpxml must be used to see
5739 whether any partial changes occurred.
5740
5741 If --live is specified, libvirt takes the snapshot while the guest is
5742 running. Both disk snapshot and domain memory snapshot are taken. This
5743 increases the size of the memory image of the external snapshot. This
5744 is currently supported only for full system external snapshots.
5745
5746 Existence of snapshot metadata will prevent attempts to undefine a per‐
5747 sistent guest. However, for transient domains, snapshot metadata is
5748 silently lost when the domain quits running (whether by command such as
5749 destroy or by internal guest action).
5750
5751 For now, it is not possible to create snapshots in a domain that has
5752 checkpoints, although this restriction will be lifted in a future re‐
5753 lease.
5754
5755 snapshot-create-as
5756 Syntax:
5757
5758 snapshot-create-as domain {[--print-xml] [--no-metadata]
5759 [--halt] [--reuse-external]} [name]
5760 [description] [--disk-only [--quiesce]] [--atomic] [--validate]
5761 [[--live] [--memspec memspec]] [--diskspec] diskspec]...
5762
5763 Create a snapshot for domain domain with the given <name> and <descrip‐
5764 tion>; if either value is omitted, libvirt will choose a value. If
5765 --print-xml is specified, then XML appropriate for snapshot-create is
5766 output, rather than actually creating a snapshot. Otherwise, if --halt
5767 is specified, the domain will be left in an inactive state after the
5768 snapshot is created, and if --disk-only is specified, the snapshot will
5769 not include vm state.
5770
5771 The --memspec option can be used to control whether a full system snap‐
5772 shot is internal or external. The --memspec flag is mandatory, fol‐
5773 lowed by a memspec of the form [file=]name[,snapshot=type], where type
5774 can be no, internal, or external. To include a literal comma in
5775 file=name, escape it with a second comma. --memspec cannot be used to‐
5776 gether with --disk-only.
5777
5778 The --diskspec option can be used to control how --disk-only and exter‐
5779 nal full system snapshots create external files. This option can occur
5780 multiple times, according to the number of <disk> elements in the do‐
5781 main xml. Each <diskspec> is in the form disk[,snap‐
5782 shot=type][,driver=type][,stype=type][,file=name]. A diskspec must be
5783 provided for disks backed by block devices as libvirt doesn't auto-gen‐
5784 erate file names for those. The optional stype parameter allows one to
5785 control the type of the source file. Supported values are 'file' (de‐
5786 fault) and 'block'. To exclude a disk from an external snapshot use
5787 --diskspec disk,snapshot=no.
5788
5789 To include a literal comma in disk or in file=name, escape it with a
5790 second comma. A literal --diskspec must precede each diskspec unless
5791 all three of domain, name, and description are also present. For exam‐
5792 ple, a diskspec of "vda,snapshot=external,file=/path/to,,new" results
5793 in the following XML:
5794
5795 <disk name='vda' snapshot='external'>
5796 <source file='/path/to,new'/>
5797 </disk>
5798
5799 If --reuse-external is specified, and the domain XML or diskspec option
5800 requests an external snapshot with a destination of an existing file,
5801 then the destination must exist and be pre-created with correct format
5802 and metadata. The file is then reused; otherwise, a snapshot is refused
5803 to avoid losing contents of the existing files.
5804
5805 If --quiesce is specified, libvirt will try to use guest agent to
5806 freeze and unfreeze domain's mounted file systems. However, if domain
5807 has no guest agent, snapshot creation will fail. Currently, this re‐
5808 quires --disk-only to be passed as well.
5809
5810 If --no-metadata is specified, then the snapshot data is created, but
5811 any metadata is immediately discarded (that is, libvirt does not treat
5812 the snapshot as current, and cannot revert to the snapshot unless snap‐
5813 shot-create is later used to teach libvirt about the metadata again).
5814
5815 If --atomic is specified, libvirt will guarantee that the snapshot ei‐
5816 ther succeeds, or fails with no changes; not all hypervisors support
5817 this. If this flag is not specified, then some hypervisors may fail
5818 after partially performing the action, and dumpxml must be used to see
5819 whether any partial changes occurred.
5820
5821 If --live is specified, libvirt takes the snapshot while the guest is
5822 running. This increases the size of the memory image of the external
5823 snapshot. This is currently supported only for external full system
5824 snapshots.
5825
5826 For now, it is not possible to create snapshots in a domain that has
5827 checkpoints, although this restriction will be lifted in a future re‐
5828 lease.
5829
5830 Optionally, the --validate option can be passed to validate XML docu‐
5831 ment which is internally generated by this command against the internal
5832 RNG schema.
5833
5834 snapshot-current
5835 Syntax:
5836
5837 snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
5838
5839 Without snapshotname, this will output the snapshot XML for the do‐
5840 main's current snapshot (if any). If --name is specified, just the
5841 current snapshot name instead of the full xml. Otherwise, using --se‐
5842 curity-info will also include security sensitive information in the
5843 XML.
5844
5845 With snapshotname, this is a request to make the existing named snap‐
5846 shot become the current snapshot, without reverting the domain.
5847
5848 snapshot-edit
5849 Syntax:
5850
5851 snapshot-edit domain [snapshotname] [--current] {[--rename] | [--clone]}
5852
5853 Edit the XML configuration file for snapshotname of a domain. If both
5854 snapshotname and --current are specified, also force the edited snap‐
5855 shot to become the current snapshot. If snapshotname is omitted, then
5856 --current must be supplied, to edit the current snapshot.
5857
5858 This is equivalent to:
5859
5860 virsh snapshot-dumpxml dom name > snapshot.xml
5861 vi snapshot.xml (or make changes with your other text editor)
5862 virsh snapshot-create dom snapshot.xml --redefine [--current]
5863
5864 except that it does some error checking.
5865
5866 The editor used can be supplied by the $VISUAL or $EDITOR environment
5867 variables, and defaults to vi.
5868
5869 If --rename is specified, then the edits can change the snapshot name.
5870 If --clone is specified, then changing the snapshot name will create a
5871 clone of the snapshot metadata. If neither is specified, then the ed‐
5872 its must not change the snapshot name. Note that changing a snapshot
5873 name must be done with care, since the contents of some snapshots, such
5874 as internal snapshots within a single qcow2 file, are accessible only
5875 from the original name.
5876
5877 snapshot-info
5878 Syntax:
5879
5880 snapshot-info domain {snapshot | --current}
5881
5882 Output basic information about a named <snapshot>, or the current snap‐
5883 shot with --current.
5884
5885 snapshot-list
5886 Syntax:
5887
5888 snapshot-list domain [--metadata] [--no-metadata]
5889 [{--parent | --roots | [{--tree | --name}]}] [--topological]
5890 [{[--from] snapshot | --current} [--descendants]]
5891 [--leaves] [--no-leaves] [--inactive] [--active]
5892 [--disk-only] [--internal] [--external]
5893
5894 List all of the available snapshots for the given domain, defaulting to
5895 show columns for the snapshot name, creation time, and domain state.
5896
5897 Normally, table form output is sorted by snapshot name; using --topo‐
5898 logical instead sorts so that no child is listed before its ancestors
5899 (although there may be more than one possible ordering with this prop‐
5900 erty).
5901
5902 If --parent is specified, add a column to the output table giving the
5903 name of the parent of each snapshot. If --roots is specified, the list
5904 will be filtered to just snapshots that have no parents. If --tree is
5905 specified, the output will be in a tree format, listing just snapshot
5906 names. These three options are mutually exclusive. If --name is speci‐
5907 fied only the snapshot name is printed. This option is mutually exclu‐
5908 sive with --tree.
5909
5910 If --from is provided, filter the list to snapshots which are children
5911 of the given snapshot; or if --current is provided, start at the cur‐
5912 rent snapshot. When used in isolation or with --parent, the list is
5913 limited to direct children unless --descendants is also present. When
5914 used with --tree, the use of --descendants is implied. This option is
5915 not compatible with --roots. Note that the starting point of --from or
5916 --current is not included in the list unless the --tree option is also
5917 present.
5918
5919 If --leaves is specified, the list will be filtered to just snapshots
5920 that have no children. Likewise, if --no-leaves is specified, the list
5921 will be filtered to just snapshots with children. (Note that omitting
5922 both options does no filtering, while providing both options will ei‐
5923 ther produce the same list or error out depending on whether the server
5924 recognizes the flags). Filtering options are not compatible with
5925 --tree.
5926
5927 If --metadata is specified, the list will be filtered to just snapshots
5928 that involve libvirt metadata, and thus would prevent undefine of a
5929 persistent guest, or be lost on destroy of a transient domain. Like‐
5930 wise, if --no-metadata is specified, the list will be filtered to just
5931 snapshots that exist without the need for libvirt metadata.
5932
5933 If --inactive is specified, the list will be filtered to snapshots that
5934 were taken when the domain was shut off. If --active is specified, the
5935 list will be filtered to snapshots that were taken when the domain was
5936 running, and where the snapshot includes the memory state to revert to
5937 that running state. If --disk-only is specified, the list will be fil‐
5938 tered to snapshots that were taken when the domain was running, but
5939 where the snapshot includes only disk state.
5940
5941 If --internal is specified, the list will be filtered to snapshots that
5942 use internal storage of existing disk images. If --external is speci‐
5943 fied, the list will be filtered to snapshots that use external files
5944 for disk images or memory state.
5945
5946 snapshot-dumpxml
5947 Syntax:
5948
5949 snapshot-dumpxml domain snapshot [--security-info]
5950
5951 Output the snapshot XML for the domain's snapshot named snapshot. Us‐
5952 ing --security-info will also include security sensitive information.
5953 Use snapshot-current to easily access the XML of the current snapshot.
5954
5955 snapshot-parent
5956 Syntax:
5957
5958 snapshot-parent domain {snapshot | --current}
5959
5960 Output the name of the parent snapshot, if any, for the given snapshot,
5961 or for the current snapshot with --current.
5962
5963 snapshot-revert
5964 Syntax:
5965
5966 snapshot-revert domain {snapshot | --current} [{--running | --paused}] [--force]
5967
5968 Revert the given domain to the snapshot specified by snapshot, or to
5969 the current snapshot with --current. Be aware that this is a destruc‐
5970 tive action; any changes in the domain since the last snapshot was
5971 taken will be lost. Also note that the state of the domain after snap‐
5972 shot-revert is complete will be the state of the domain at the time the
5973 original snapshot was taken.
5974
5975 Normally, reverting to a snapshot leaves the domain in the state it was
5976 at the time the snapshot was created, except that a disk snapshot with
5977 no vm state leaves the domain in an inactive state. Passing either the
5978 --running or --paused flag will perform additional state changes (such
5979 as booting an inactive domain, or pausing a running domain). Since
5980 transient domains cannot be inactive, it is required to use one of
5981 these flags when reverting to a disk snapshot of a transient domain.
5982
5983 There are a number of cases where a snapshot revert involves extra
5984 risk, which requires the use of --force to proceed:
5985
5986 • One is the case of a snapshot that lacks full domain information
5987 for reverting configuration (such as snapshots created prior to
5988 libvirt 0.9.5); since libvirt cannot prove that the current con‐
5989 figuration matches what was in use at the time of the snapshot,
5990 supplying --force assures libvirt that the snapshot is compatible
5991 with the current configuration (and if it is not, the domain will
5992 likely fail to run).
5993
5994 • Another is the case of reverting from a running domain to an ac‐
5995 tive state where a new hypervisor has to be created rather than
5996 reusing the existing hypervisor, because it implies drawbacks such
5997 as breaking any existing VNC or Spice connections; this condition
5998 happens with an active snapshot that uses a provably incompatible
5999 configuration, as well as with an inactive snapshot that is com‐
6000 bined with the --start or --pause flag.
6001
6002 • Also, libvirt will refuse to restore snapshots of inactive QEMU
6003 domains while there is managed saved state. This is because those
6004 snapshots do not contain memory state and will therefore not re‐
6005 place the existing memory state. This ends up switching a disk un‐
6006 derneath a running system and will likely cause extensive filesys‐
6007 tem corruption or crashes due to swap content mismatches when run.
6008
6009 snapshot-delete
6010 Syntax:
6011
6012 snapshot-delete domain {snapshot | --current}
6013 [--metadata] [{--children | --children-only}]
6014
6015 Delete the snapshot for the domain named snapshot, or the current snap‐
6016 shot with --current. If this snapshot has child snapshots, changes
6017 from this snapshot will be merged into the children. If --children is
6018 passed, then delete this snapshot and any children of this snapshot.
6019 If --children-only is passed, then delete any children of this snap‐
6020 shot, but leave this snapshot intact. These two flags are mutually ex‐
6021 clusive.
6022
6023 If --metadata is specified, then only delete the snapshot metadata
6024 maintained by libvirt, while leaving the snapshot contents intact for
6025 access by external tools; otherwise deleting a snapshot also removes
6026 the data contents from that point in time.
6027
6029 The following commands manipulate domain checkpoints. Checkpoints
6030 serve as a point in time to identify which portions of a guest's disks
6031 have changed after that time, making it possible to perform incremental
6032 and differential backups. Checkpoints are identified with a unique
6033 name. See https://libvirt.org/formatcheckpoint.html for documentation
6034 of the XML format used to represent properties of checkpoints.
6035
6036 checkpoint-create
6037 Syntax:
6038
6039 checkpoint-create domain [xmlfile] { --redefine [--redefine-validate] | [--quiesce]}
6040
6041 Create a checkpoint for domain domain with the properties specified in
6042 xmlfile describing a <domaincheckpoint> top-level element. The format
6043 of the input XML file will be validated against an internal RNG schema
6044 (identical to using the virt-xml-validate(1) tool). If xmlfile is com‐
6045 pletely omitted, then libvirt will create a checkpoint with a name
6046 based on the current time.
6047
6048 If --redefine is specified, then all XML elements produced by check‐
6049 point-dumpxml are valid; this can be used to migrate checkpoint hierar‐
6050 chy from one machine to another, to recreate hierarchy for the case of
6051 a transient domain that goes away and is later recreated with the same
6052 name and UUID, or to make slight alterations in the checkpoint metadata
6053 (such as host-specific aspects of the domain XML embedded in the check‐
6054 point). When this flag is supplied, the xmlfile argument is mandatory.
6055
6056 If --redefine-validate is specified along with --redefine the hypervi‐
6057 sor performs validation of metadata associated with the checkpoint
6058 stored in places besides the checkpoint XML. Note that some hypervisors
6059 may require that the domain is running to perform validation.
6060
6061 If --quiesce is specified, libvirt will try to use guest agent to
6062 freeze and unfreeze domain's mounted file systems. However, if domain
6063 has no guest agent, checkpoint creation will fail.
6064
6065 Existence of checkpoint metadata will prevent attempts to undefine a
6066 persistent guest. However, for transient domains, checkpoint metadata
6067 is silently lost when the domain quits running (whether by command such
6068 as destroy or by internal guest action).
6069
6070 For now, it is not possible to create checkpoints in a domain that has
6071 snapshots, although this restriction will be lifted in a future re‐
6072 lease.
6073
6074 checkpoint-create-as
6075 Syntax:
6076
6077 checkpoint-create-as domain [--print-xml] [name]
6078 [description] [--quiesce] [--diskspec] diskspec]...
6079
6080 Create a checkpoint for domain domain with the given <name> and <de‐
6081 scription>; if either value is omitted, libvirt will choose a value.
6082 If --print-xml is specified, then XML appropriate for checkpoint-create
6083 is output, rather than actually creating a checkpoint.
6084
6085 The --diskspec option can be used to control which guest disks partici‐
6086 pate in the checkpoint. This option can occur multiple times, according
6087 to the number of <disk> elements in the domain xml. Each <diskspec> is
6088 in the form disk[,checkpoint=type][,bitmap=name]. A literal --diskspec
6089 must precede each diskspec unless all three of domain, name, and de‐
6090 scription are also present. For example, a diskspec of "vda,check‐
6091 point=bitmap,bitmap=map1" results in the following XML:
6092
6093 <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
6094
6095 If --quiesce is specified, libvirt will try to use guest agent to
6096 freeze and unfreeze domain's mounted file systems. However, if domain
6097 has no guest agent, checkpoint creation will fail.
6098
6099 For now, it is not possible to create checkpoints in a domain that has
6100 snapshots, although this restriction will be lifted in a future re‐
6101 lease.
6102
6103 checkpoint-edit
6104 Syntax:
6105
6106 checkpoint-edit domain checkpointname
6107
6108 Edit the XML configuration file for checkpointname of a domain.
6109
6110 This is equivalent to:
6111
6112 virsh checkpoint-dumpxml dom name > checkpoint.xml
6113 vi checkpoint.xml (or make changes with your other text editor)
6114 virsh checkpoint-create dom checkpoint.xml --redefine
6115
6116 except that it does some error checking, including that the edits
6117 should not attempt to change the checkpoint name.
6118
6119 The editor used can be supplied by the $VISUAL or $EDITOR environment
6120 variables, and defaults to vi.
6121
6122 checkpoint-info
6123 Syntax:
6124
6125 checkpoint-info domain checkpoint
6126
6127 Output basic information about a named <checkpoint>.
6128
6129 checkpoint-list
6130 Syntax:
6131
6132 checkpoint-list domain [{--parent | --roots |
6133 [{--tree | --name}]}] [--topological]
6134 [[--from] checkpoint | [--descendants]]
6135 [--leaves] [--no-leaves]
6136
6137 List all of the available checkpoints for the given domain, defaulting
6138 to show columns for the checkpoint name and creation time.
6139
6140 Normally, table form output is sorted by checkpoint name; using --topo‐
6141 logical instead sorts so that no child is listed before its ancestors
6142 (although there may be more than one possible ordering with this prop‐
6143 erty).
6144
6145 If --parent is specified, add a column to the output table giving the
6146 name of the parent of each checkpoint. If --roots is specified, the
6147 list will be filtered to just checkpoints that have no parents. If
6148 --tree is specified, the output will be in a tree format, listing just
6149 checkpoint names. These three options are mutually exclusive. If
6150 --name is specified only the checkpoint name is printed. This option is
6151 mutually exclusive with --tree.
6152
6153 If --from is provided, filter the list to checkpoints which are chil‐
6154 dren of the given checkpoint. When used in isolation or with --parent,
6155 the list is limited to direct children unless --descendants is also
6156 present. When used with --tree, the use of --descendants is implied.
6157 This option is not compatible with --roots. Note that the starting
6158 point of --from is not included in the list unless the --tree option is
6159 also present.
6160
6161 If --leaves is specified, the list will be filtered to just checkpoints
6162 that have no children. Likewise, if --no-leaves is specified, the list
6163 will be filtered to just checkpoints with children. (Note that omit‐
6164 ting both options does no filtering, while providing both options will
6165 either produce the same list or error out depending on whether the
6166 server recognizes the flags). Filtering options are not compatible
6167 with --tree.
6168
6169 checkpoint-dumpxml
6170 Syntax:
6171
6172 checkpoint-dumpxml domain checkpoint [--security-info] [--no-domain] [--size]
6173
6174 Output the checkpoint XML for the domain's checkpoint named checkpoint.
6175 Using --security-info will also include security sensitive information.
6176
6177 Using --size will add XML indicating the current size in bytes of guest
6178 data that has changed since the checkpoint was created (although remem‐
6179 ber that guest activity between a size check and actually creating a
6180 backup can result in the backup needing slightly more space). Note that
6181 some hypervisors may require that domain is running when --size is
6182 used.
6183
6184 Using --no-domain will omit the <domain> element from the output for a
6185 more compact view.
6186
6187 checkpoint-parent
6188 Syntax:
6189
6190 checkpoint-parent domain checkpoint
6191
6192 Output the name of the parent checkpoint, if any, for the given check‐
6193 point.
6194
6195 checkpoint-delete
6196 Syntax:
6197
6198 checkpoint-delete domain checkpoint
6199 [--metadata] [{--children | --children-only}]
6200
6201 Delete the checkpoint for the domain named checkpoint. The record of
6202 which portions of the disk changed since the checkpoint are merged into
6203 the parent checkpoint (if any). If --children is passed, then delete
6204 this checkpoint and any children of this checkpoint. If --chil‐
6205 dren-only is passed, then delete any children of this checkpoint, but
6206 leave this checkpoint intact. These two flags are mutually exclusive.
6207
6208 If --metadata is specified, then only delete the checkpoint metadata
6209 maintained by libvirt, while leaving the checkpoint contents intact for
6210 access by external tools; otherwise deleting a checkpoint also removes
6211 the ability to perform an incremental backup from that point in time.
6212
6214 The following commands manipulate network filters. Network filters al‐
6215 low filtering of the network traffic coming from and going to virtual
6216 machines. Individual network traffic filters are written in XML and
6217 may contain references to other network filters, describe traffic fil‐
6218 tering rules, or contain both. Network filters are referenced by vir‐
6219 tual machines from within their interface description. A network filter
6220 may be referenced by multiple virtual machines' interfaces.
6221
6222 nwfilter-define
6223 Syntax:
6224
6225 nwfilter-define xmlfile
6226
6227 Make a new network filter known to libvirt. If a network filter with
6228 the same name already exists, it will be replaced with the new XML.
6229 Any running virtual machine referencing this network filter will have
6230 its network traffic rules adapted. If for any reason the network traf‐
6231 fic filtering rules cannot be instantiated by any of the running vir‐
6232 tual machines, then the new XML will be rejected.
6233
6234 nwfilter-undefine
6235 Syntax:
6236
6237 nwfilter-undefine nwfilter-name
6238
6239 Delete a network filter. The deletion will fail if any running virtual
6240 machine is currently using this network filter.
6241
6242 nwfilter-list
6243 Syntax:
6244
6245 nwfilter-list
6246
6247 List all of the available network filters.
6248
6249 nwfilter-dumpxml
6250 Syntax:
6251
6252 nwfilter-dumpxml nwfilter-name
6253
6254 Output the network filter XML.
6255
6256 nwfilter-edit
6257 Syntax:
6258
6259 nwfilter-edit nwfilter-name
6260
6261 Edit the XML of a network filter.
6262
6263 This is equivalent to:
6264
6265 virsh nwfilter-dumpxml myfilter > myfilter.xml
6266 vi myfilter.xml (or make changes with your other text editor)
6267 virsh nwfilter-define myfilter.xml
6268
6269 except that it does some error checking. The new network filter may be
6270 rejected due to the same reason as mentioned in nwfilter-define.
6271
6272 The editor used can be supplied by the $VISUAL or $EDITOR environment
6273 variables, and defaults to vi.
6274
6276 The following commands manipulate network filter bindings. Network fil‐
6277 ter bindings track the association between a network port and a network
6278 filter. Generally the bindings are managed automatically by the hyper‐
6279 visor drivers when adding/removing NICs on a guest.
6280
6281 If an admin is creating/deleting TAP devices for non-guest usage, how‐
6282 ever, the network filter binding commands provide a way to make use of
6283 the network filters directly.
6284
6285 nwfilter-binding-create
6286 Syntax:
6287
6288 nwfilter-binding-create xmlfile
6289
6290 Associate a network port with a network filter. The network filter
6291 backend will immediately attempt to instantiate the filter rules on the
6292 port. This command may be used to associate a filter with a currently
6293 running guest that does not have a filter defined for a specific net‐
6294 work port. Since the bindings are generally automatically managed by
6295 the hypervisor, using this command to define a filter for a network
6296 port and then starting the guest afterwards may prevent the guest from
6297 starting if it attempts to use the network port and finds a filter al‐
6298 ready defined.
6299
6300 nwfilter-binding-delete
6301 Syntax:
6302
6303 nwfilter-binding-delete port-name
6304
6305 Disassociate a network port from a network filter. The network filter
6306 backend will immediately tear down the filter rules that exist on the
6307 port. This command may be used to remove the network port binding for a
6308 filter currently in use for the guest while the guest is running with‐
6309 out needing to restart the guest. Restoring the network port binding
6310 filter for the running guest would be accomplished by using nwfil‐
6311 ter-binding-create.
6312
6313 nwfilter-binding-list
6314 Syntax:
6315
6316 nwfilter-binding-list
6317
6318 List all of the network ports which have filters associated with them.
6319
6320 nwfilter-binding-dumpxml
6321 Syntax:
6322
6323 nwfilter-binding-dumpxml port-name
6324
6325 Output the network filter binding XML for the network device called
6326 port-name.
6327
6329 NOTE: Use of the following commands is strongly discouraged. They can
6330 cause libvirt to become confused and do the wrong thing on subsequent
6331 operations. Once you have used these commands, please do not report
6332 problems to the libvirt developers; the reports will be ignored. If
6333 you find that these commands are the only way to accomplish something,
6334 then it is better to request that the feature be added as a first-class
6335 citizen in the regular libvirt library.
6336
6337 qemu-attach
6338 Syntax:
6339
6340 qemu-attach pid
6341
6342 Attach an externally launched QEMU process to the libvirt QEMU driver.
6343 The QEMU process must have been created with a monitor connection using
6344 the UNIX driver. Ideally the process will also have had the '-name' ar‐
6345 gument specified.
6346
6347 $ qemu-kvm -cdrom ~/demo.iso \
6348 -monitor unix:/tmp/demo,server,nowait \
6349 -name foo \
6350 -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea &
6351 $ QEMUPID=$!
6352 $ virsh qemu-attach $QEMUPID
6353
6354 Not all functions of libvirt are expected to work reliably after at‐
6355 taching to an externally launched QEMU process. There may be issues
6356 with the guest ABI changing upon migration and device hotplug or hotun‐
6357 plug may not work. The attached environment should be considered pri‐
6358 marily read-only.
6359
6360 qemu-monitor-command
6361 Syntax:
6362
6363 qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] } command...
6364
6365 Send an arbitrary monitor command command to domain domain through the
6366 QEMU monitor. The results of the command will be printed on stdout.
6367
6368 If more than one argument is provided for command, they are concate‐
6369 nated with a space in between before passing the single command to the
6370 monitor.
6371
6372 Note that libvirt uses the QMP to talk to qemu so command must be valid
6373 JSON in QMP format to work properly.
6374
6375 If --pretty is given the QMP reply is pretty-printed.
6376
6377 If --return-value is given the 'return' key of the QMP response object
6378 is extracted rather than passing through the full reply from QEMU.
6379
6380 If --hmp is passed, the command is considered to be a human monitor
6381 command and libvirt will automatically convert it into QMP and convert
6382 the result back.
6383
6384 qemu-agent-command
6385 Syntax:
6386
6387 qemu-agent-command domain [--timeout seconds | --async | --block] command...
6388
6389 Send an arbitrary guest agent command command to domain domain through
6390 QEMU agent. --timeout, --async and --block options are exclusive.
6391 --timeout requires timeout seconds seconds and it must be positive.
6392 When --aysnc is given, the command waits for timeout whether success or
6393 failed. And when --block is given, the command waits forever with
6394 blocking timeout.
6395
6396 qemu-monitor-event
6397 Syntax:
6398
6399 qemu-monitor-event [domain] [--event event-name]
6400 [--loop] [--timeout seconds] [--pretty] [--regex] [--no-case]
6401 [--timestamp]
6402
6403 Wait for arbitrary QEMU monitor events to occur, and print out the de‐
6404 tails of events as they happen. The events can optionally be filtered
6405 by domain or event-name. The 'query-events' QMP command can be used
6406 via qemu-monitor-command to learn what events are supported. If
6407 --regex is used, event-name is a basic regular expression instead of a
6408 literal string. If --no-case is used, event-name will match case-in‐
6409 sensitively.
6410
6411 By default, this command is one-shot, and returns success once an event
6412 occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.
6413 If --timeout is specified, the command gives up waiting for events af‐
6414 ter seconds have elapsed. With --loop, the command prints all events
6415 until a timeout or interrupt key. If --pretty is specified, any JSON
6416 event details are pretty-printed for better legibility.
6417
6418 When --timestamp is used, a human-readable timestamp will be printed
6419 before the event, and the timing information provided by QEMU will be
6420 omitted.
6421
6422 lxc-enter-namespace
6423 Syntax:
6424
6425 lxc-enter-namespace domain [--noseclabel] --
6426 /path/to/binary [arg1, [arg2, ...]]
6427
6428 Enter the namespace of domain and execute the command /path/to/binary
6429 passing the requested args. The binary path is relative to the con‐
6430 tainer root filesystem, not the host root filesystem. The binary will
6431 inherit the environment variables / console visible to virsh. The com‐
6432 mand will be run with the same sVirt context and cgroups placement as
6433 processes within the container. This command only works when connected
6434 to the LXC hypervisor driver. This command succeeds only if
6435 /path/to/binary has 0 exit status.
6436
6437 By default the new process will run with the security label of the new
6438 parent container. Use the --noseclabel option to instead have the
6439 process keep the same security label as virsh.
6440
6442 The following environment variables can be set to alter the behaviour
6443 of virsh
6444
6445 • VIRSH_DEBUG=<0 to 4>
6446
6447 Turn on verbose debugging of virsh commands. Valid levels are
6448
6449 • VIRSH_DEBUG=0
6450
6451 DEBUG - Messages at ALL levels get logged
6452
6453 • VIRSH_DEBUG=1
6454
6455 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
6456
6457 • VIRSH_DEBUG=2
6458
6459 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
6460
6461 • VIRSH_DEBUG=3
6462
6463 WARNING - Logs messages at levels WARNING and ERROR
6464
6465 • VIRSH_DEBUG=4
6466
6467 ERROR - Messages at only ERROR level gets logged.
6468
6469 • VIRSH_LOG_FILE=``LOGFILE``
6470
6471 The file to log virsh debug messages.
6472
6473 • VIRSH_DEFAULT_CONNECT_URI
6474
6475 The hypervisor to connect to by default. Set this to a URI, in the
6476 same format as accepted by the connect option. This environment vari‐
6477 able is deprecated in favour of the global LIBVIRT_DEFAULT_URI vari‐
6478 able which serves the same purpose.
6479
6480 • LIBVIRT_DEFAULT_URI
6481
6482 The hypervisor to connect to by default. Set this to a URI, in the
6483 same format as accepted by the connect option. This overrides the de‐
6484 fault URI set in any client config file and prevents libvirt from
6485 probing for drivers.
6486
6487 • VISUAL
6488
6489 The editor to use by the edit and related options.
6490
6491 • EDITOR
6492
6493 The editor to use by the edit and related options, if VISUAL is not
6494 set.
6495
6496 • VIRSH_HISTSIZE
6497
6498 The number of commands to remember in the command history. The de‐
6499 fault value is 500.
6500
6501 • LIBVIRT_DEBUG=LEVEL
6502
6503 Turn on verbose debugging of all libvirt API calls. Valid levels are
6504
6505 • LIBVIRT_DEBUG=1
6506
6507 Messages at level DEBUG or above
6508
6509 • LIBVIRT_DEBUG=2
6510
6511 Messages at level INFO or above
6512
6513 • LIBVIRT_DEBUG=3
6514
6515 Messages at level WARNING or above
6516
6517 • LIBVIRT_DEBUG=4
6518
6519 Messages at level ERROR
6520
6521 For further information about debugging options consult
6522 https://libvirt.org/logging.html
6523
6525 Please report all bugs you discover. This should be done via either:
6526
6527 1. the mailing list
6528
6529 https://libvirt.org/contact.html
6530
6531 2. the bug tracker
6532
6533 https://libvirt.org/bugs.html
6534
6535 Alternatively, you may report bugs to your software distributor / ven‐
6536 dor.
6537
6539 Please refer to the AUTHORS file distributed with libvirt.
6540
6542 Copyright (C) 2005, 2007-2015 Red Hat, Inc., and the authors listed in
6543 the libvirt AUTHORS file.
6544
6546 virsh is distributed under the terms of the GNU LGPL v2+. This is free
6547 software; see the source for copying conditions. There is NO warranty;
6548 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
6549
6551 virt-install(1), virt-xml-validate(1), virt-top(1), virt-df(1),
6552 https://libvirt.org/
6553
6554
6555
6556
6557 VIRSH(1)