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