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