1VIRSH(1) Virtualization Support VIRSH(1)
2
6 virsh - management user interface
7
9 virsh [OPTION]... [COMMAND_STRING]
10 virsh [OPTION]... COMMAND [ARG]...
12
14 The virsh program is the main interface for managing virsh guest
15 domains. The program can be used to create, pause, and shutdown
16 domains. It can also be used to list current domains. Libvirt is a C
17 toolkit to interact with the virtualization capabilities of recent
18 versions of Linux (and other OSes). It is free software available under
19 the GNU Lesser General Public License. Virtualization of the Linux
20 Operating System means the ability to run multiple instances of
21 Operating Systems concurrently on a single hardware system where the
22 basic resources are driven by a Linux instance. The library aims at
23 providing a long term stable C API. It currently supports Xen, QEmu,
24 KVM, LXC, OpenVZ, VirtualBox and VMware ESX.
25 The basic structure of most virsh usage is:
27 virsh [OPTION]... <command> <domain> [ARG]...
29 Where command is one of the commands listed below; domain is the
31 numeric domain id, or the domain name, or the domain UUID; and ARGS are
32 command specific options. There are a few exceptions to this rule in
33 the cases where the command in question acts on all domains, the entire
34 machine, or directly on the xen hypervisor. Those exceptions will be
35 clear for each of those commands. Note: it is permissible to give
36 numeric names to domains, however, doing so will result in a domain
37 that can only be identified by domain id. In other words, if a numeric
38 value is supplied it will be interpreted as a domain id, not as a name.
39 The virsh program can be used either to run one COMMAND by giving the
41 command and its arguments on the shell command line, or a
42 COMMAND_STRING which is a single shell argument consisting of multiple
43 COMMAND actions and their arguments joined with whitespace, and
44 separated by semicolons between commands. Within COMMAND_STRING, virsh
45 understands the same single, double, and backslash escapes as the
46 shell, although you must add another layer of shell escaping in
47 creating the single shell argument. If no command is given in the
48 command line, virsh will then start a minimal interpreter waiting for
49 your commands, and the quit command will then exit the program.
50 The virsh program understands the following OPTIONS.
52 -h, --help
54 Ignore all other arguments, and behave as if the help command were
55 given instead.
56 -v, --version[=short]
58 Ignore all other arguments, and prints the version of the libvirt
59 library virsh is coming from
60 -V, --version=long
62 Ignore all other arguments, and prints the version of the libvirt
63 library virsh is coming from and which options and driver are
64 compiled in.
65 -c, --connect URI
67 Connect to the specified URI, as if by the connect command, instead
68 of the default connection.
69 -d, --debug LEVEL
71 Enable debug messages at integer LEVEL and above. LEVEL can range
72 from 0 to 4 (default). See the documentation of VIRSH_DEBUG
73 environment variable below for the description of each LEVEL.
74 -l, --log FILE
76 Output logging details to FILE.
77 -q, --quiet
79 Avoid extra informational messages.
80 -r, --readonly
82 Make the initial connection read-only, as if by the --readonly
83 option of the connect command.
84 -t, --timing
86 Output elapsed time information for each command.
87 -e, --escape string
89 Set alternative escape sequence for console command. By default,
90 telnet's ^] is used. Allowed characters when using hat notation
91 are: alphabetic character, @, [, ], \, ^, _.
92
94 Most virsh operations rely upon the libvirt library being able to
95 connect to an already running libvirtd service. This can usually be
96 done using the command service libvirtd start.
97 Most virsh commands require root privileges to run due to the
99 communications channels used to talk to the hypervisor. Running as non
100 root will return an error.
101 Most virsh commands act synchronously, except maybe shutdown, setvcpus
103 and setmem. In those cases the fact that the virsh program returned,
104 may not mean the action is complete and you must poll periodically to
105 detect that the guest completed the operation.
106 virsh strives for backward compatibility. Although the help command
108 only lists the preferred usage of a command, if an older version of
109 virsh supported an alternate spelling of a command or option (such as
110 --tunnelled instead of --tunneled), then scripts using that older
111 spelling will continue to work.
112 Several virsh commands take an optionally scaled integer; if no scale
114 is provided, then the default is listed in the command (for historical
115 reasons, some commands default to bytes, while other commands default
116 to kibibytes). The following case-insensitive suffixes can be used to
117 select a specfic scale:
118 b, byte byte 1
119 KB kilobyte 1,000
120 k, KiB kibibyte 1,024
121 MB megabyte 1,000,000
122 M, MiB mebibyte 1,048,576
123 GB gigabyte 1,000,000,000
124 G, GiB gibibyte 1,073,741,824
125 TB terabyte 1,000,000,000,000
126 T, TiB tebibyte 1,099,511,627,776
127 PB petabyte 1,000,000,000,000,000
128 P, PiB pebibyte 1,125,899,906,842,624
129 EB exabyte 1,000,000,000,000,000,000
130 E, EiB exbibyte 1,152,921,504,606,846,976
131
133 The following commands are generic i.e. not specific to a domain.
134 help [command-or-group]
136 This lists each of the virsh commands. When used without options,
137 all commands are listed, one per line, grouped into related
138 categories, displaying the keyword for each group.
139 To display only commands for a specific group, give the keyword for
141 that group as an option. For example:
142 virsh # help host
144 Host and Hypervisor (help keyword 'host'):
146 capabilities capabilities
147 connect (re)connect to hypervisor
148 freecell NUMA free memory
149 hostname print the hypervisor hostname
150 qemu-attach Attach to existing QEMU process
151 qemu-monitor-command QEMU Monitor Command
152 qemu-agent-command QEMU Guest Agent Command
153 sysinfo print the hypervisor sysinfo
154 uri print the hypervisor canonical URI
155 To display detailed information for a specific command, give its
157 name as the option instead. For example:
158 virsh # help list
160 NAME
161 list - list domains
162 SYNOPSIS
164 list [--inactive] [--all]
165 DESCRIPTION
167 Returns list of domains.
168 OPTIONS
170 --inactive list inactive domains
171 --all list inactive & active domains
172 quit, exit
174 quit this interactive terminal
175 version
177 Will print out the major version info about what this built from.
178 Example
180 virsh version
182 Compiled against library: libvir 0.0.6
184 Using library: libvir 0.0.6
186 Using API: Xen 3.0.0
188 Running hypervisor: Xen 3.0.0
190 cd [directory]
192 Will change current directory to directory. The default directory
193 for the cd command is the home directory or, if there is no HOME
194 variable in the environment, the root directory.
195 This command is only available in interactive mode.
197 pwd Will print the current directory.
199 connect URI [--readonly]
201 (Re)-Connect to the hypervisor. When the shell is first started,
202 this is automatically run with the URI parameter requested by the
203 "-c" option on the command line. The URI parameter specifies how to
204 connect to the hypervisor. The documentation page at
205 <http://libvirt.org/uri.html> list the values supported, but the
206 most common are:
207 xen:///
209 this is used to connect to the local Xen hypervisor, this is
210 the default
211 qemu:///system
213 connect locally as root to the daemon supervising QEmu and KVM
214 domains
215 qemu:///session
217 connect locally as a normal user to his own set of QEmu and KVM
218 domains
219 lxc:///
221 connect to a local linux container
222 For remote access see the documentation page at
224 <http://libvirt.org/uri.html> on how to make URIs. The --readonly
225 option allows for read-only connection
226 uri Prints the hypervisor canonical URI, can be useful in shell mode.
228 hostname
230 Print the hypervisor hostname.
231 sysinfo
233 Print the XML representation of the hypervisor sysinfo, if
234 available.
235 nodeinfo
237 Returns basic information about the node, like number and type of
238 CPU, and size of the physical memory. The output corresponds to
239 virNodeInfo structure. Specifically, the "CPU socket(s)" field
240 means number of CPU sockets per NUMA cell.
241 nodecpustats [cpu] [--percent]
243 Returns cpu stats of the node. If cpu is specified, this will
244 prints specified cpu statistics only. If --percent is specified,
245 this will prints percentage of each kind of cpu statistics during 1
246 second.
247 nodememstats [cell]
249 Returns memory stats of the node. If cell is specified, this will
250 prints specified cell statistics only.
251 nodesuspend [target] [duration]
253 Puts the node (host machine) into a system-wide sleep state such as
254 Suspend-to-RAM, Suspend-to-Disk or Hybrid-Suspend and sets up a
255 Real-Time-Clock interrupt to fire (to wake up the node) after a
256 time delay specified by the 'duration' parameter. The duration time
257 should be at least 60 seconds.
258 node-memory-tune [shm-pages-to-scan] [shm-sleep-millisecs]
260 Allows you to display or set the node memory parameters. shm-
261 pages-to-scan can be used to set the number of pages to scan before
262 the shared memory service goes to sleep; shm-sleep-millisecs can be
263 used to set the number of millisecs the shared memory service
264 should sleep before next scan; shm-merge-across-nodes specifies if
265 pages from different numa nodes can be merged. When set to 0, only
266 pages which physically reside in the memory area of same NUMA node
267 can be merged. When set to 1, pages from all nodes can be merged.
268 Default to 1.
269 capabilities
271 Print an XML document describing the capabilities of the hypervisor
272 we are currently connected to. This includes a section on the host
273 capabilities in terms of CPU and features, and a set of description
274 for each kind of guest which can be virtualized. For a more
275 complete description see:
276 <http://libvirt.org/formatcaps.html> The XML also show the NUMA
277 topology information if available.
278 inject-nmi domain
280 Inject NMI to the guest.
281 list [--inactive | --all] [--managed-save] [--title] { [--table] |
283 --name | --uuid } [--persistent] [--transient] [--with-managed-save]
284 [--without-managed-save] [--autostart] [--no-autostart]
285 [--with-snapshot] [--without-snapshot] [--state-running]
286 [--state-paused] [--state-shutoff] [--state-other]
287 Prints information about existing domains. If no options are
288 specified it prints out information about running domains.
289 An example format for the list is as follows:
291 virsh list
293 Id Name State
294 ----------------------------------------------------
295 0 Domain-0 running
296 2 fedora paused
297 Name is the name of the domain. ID the domain numeric id. State
299 is the run state (see below).
300 STATES
302 The State field lists 8 states for a domain, and which ones the
304 current domain is in.
305 running
307 The domain is currently running on a CPU
308 idle
310 The domain is idle, and not running or runnable. This can be
311 caused because the domain is waiting on IO (a traditional wait
312 state) or has gone to sleep because there was nothing else for
313 it to do.
314 paused
316 The domain has been paused, usually occurring through the
317 administrator running virsh suspend. When in a paused state
318 the domain will still consume allocated resources like memory,
319 but will not be eligible for scheduling by the hypervisor.
320 shutdown
322 The domain is in the process of shutting down, i.e. the guest
323 operating system has been notified and should be in the process
324 of stopping its operations gracefully.
325 shut off
327 The domain is not running. Usually this indicates the domain
328 has been shut down completely, or has not been started.
329 crashed
331 The domain has crashed, which is always a violent ending.
332 Usually this state can only occur if the domain has been
333 configured not to restart on crash.
334 dying
336 The domain is in process of dying, but hasn't completely
337 shutdown or crashed.
338 pmsuspended
340 The domain has been suspended by guest power management, e.g.
341 entered into s3 state.
342 Normally only active domains are listed. To list inactive domains
344 specify --inactive or --all to list both active and inactive
345 domains.
346 To further filter the list of domains you may specify one or more
348 of filtering flags supported by the list command. These flags are
349 grouped by function. Specifying one or more flags from a group
350 enables the filter group. Note that some combinations of flags may
351 yield no results. Supported filtering flags and groups:
352 Persistence
354 Flag --persistent is used to include persistent domains in the
355 returned list. To include transient domains specify
356 --transient.
357 Existence of managed save image
359 To list domains having a managed save image specify flag
360 --with-managed-save. For domains that don't have a managed save
361 image specify --without-managed-save.
362 Domain state
364 The following filter flags select a domain by its state:
365 --state-running for running domains, --state-paused for paused
366 domains, --state-shutoff for turned off domains and
367 --state-other for all other states as a fallback.
368 Autostarting domains
370 To list autostarting domains use the flag --autostart. To list
371 domains with this feature disabled use --no-autostart.
372 Snapshot existence
374 Domains that have snapshot images can be listed using flag
375 --with-snapshot, domains without a snapshot --without-snapshot.
376 When talking to older servers, this command is forced to use a
378 series of API calls with an inherent race, where a domain might not
379 be listed or might appear more than once if it changed state
380 between calls while the list was being collected. Newer servers do
381 not have this problem.
382 If --managed-save is specified, then domains that have managed save
384 state (only possible if they are in the shut off state, so you need
385 to specify --inactive or --all to actually list them) will instead
386 show as saved in the listing. This flag is usable only with the
387 default --table output. Note that this flag does not filter the
388 list of domains.
389 If --name is specified, domain names are printed instead of the
391 table formatted one per line. If --uuid is specified domain's
392 UUID's are printed instead of names. Flag --table specifies that
393 the legacy table-formatted output should be used. This is the
394 default. All of these are mutually exclusive.
395 If --title is specified, then the short domain description (title)
397 is printed in an extra column. This flag is usable only with the
398 default --table output.
399 Example:
401 virsh list --title
403 Id Name State Title
404 --------------------------------------------------------------------------
405 0 Domain-0 running Mailserver 1
406 2 fedora paused
407 freecell [{ [--cellno] cellno | --all }]
409 Prints the available amount of memory on the machine or within a
410 NUMA cell. The freecell command can provide one of three different
411 displays of available memory on the machine depending on the
412 options specified. With no options, it displays the total free
413 memory on the machine. With the --all option, it displays the free
414 memory in each cell and the total free memory on the machine.
415 Finally, with a numeric argument or with --cellno plus a cell
416 number it will display the free memory for the specified cell only.
417 cpu-baseline FILE
419 Compute baseline CPU which will be supported by all host CPUs given
420 in <file>. The list of host CPUs is built by extracting all <cpu>
421 elements from the <file>. Thus, the <file> can contain either a set
422 of <cpu> elements separated by new lines or even a set of complete
423 <capabilities> elements printed by capabilities command.
424 cpu-compare FILE
426 Compare CPU definition from XML <file> with host CPU. The XML
427 <file> may contain either host or guest CPU definition. The host
428 CPU definition is the <cpu> element and its contents as printed by
429 capabilities command. The guest CPU definition is the <cpu> element
430 and its contents from domain XML definition. For more information
431 on guest CPU definition see:
432 <http://libvirt.org/formatdomain.html#elementsCPU>
433 echo [--shell] [--xml] [arg...]
435 Echo back each arg, separated by space. If --shell is specified,
436 then the output will be single-quoted where needed, so that it is
437 suitable for reuse in a shell context. If --xml is specified, then
438 the output will be escaped for use in XML.
439
441 The following commands manipulate domains directly, as stated
442 previously most commands take domain as the first parameter. The domain
443 can be specified as a short integer, a name or a full UUID.
444 autostart [--disable] domain
446 Configure a domain to be automatically started at boot.
447 The option --disable disables autostarting.
449 console domain [devname] [--safe] [--force]
451 Connect the virtual serial console for the guest. The optional
452 devname parameter refers to the device alias of an alternate
453 console, serial or parallel device configured for the guest. If
454 omitted, the primary console will be opened.
455 If the flag --safe is specified, the connection is only attempted
457 if the driver supports safe console handling. This flag specifies
458 that the server has to ensure exclusive access to console devices.
459 Optionally the --force flag may be specified, requesting to
460 disconnect any existing sessions, such as in a case of a broken
461 connection.
462 create FILE [--console] [--paused] [--autodestroy]
464 Create a domain from an XML <file>. An easy way to create the XML
465 <file> is to use the dumpxml command to obtain the definition of a
466 pre-existing guest. The domain will be paused if the --paused
467 option is used and supported by the driver; otherwise it will be
468 running. If --console is requested, attach to the console after
469 creation. If --autodestroy is requested, then the guest will be
470 automatically destroyed when virsh closes its connection to
471 libvirt, or otherwise exits.
472 Example
474 virsh dumpxml <domain> > domain.xml
476 vi domain.xml (or make changes with your other text editor)
477 virsh create domain.xml
478 define FILE
480 Define a domain from an XML <file>. The domain definition is
481 registered but not started. If domain is already running, the
482 changes will take effect on the next boot.
483 desc domain [[--live] [--config] | [--current]] [--title] [--edit]
485 [--new-desc New description or title message]
486 Show or modify description and title of a domain. These values are
487 user fields that allow to store arbitrary textual data to allow
488 easy identification of domains. Title should be short, although
489 it's not enforced.
490 Flags --live or --config select whether this command works on live
492 or persistent definitions of the domain. If both --live and
493 --config are specified, the --config option takes precedence on
494 getting the current description and both live configuration and
495 config are updated while setting the description. --current is
496 exclusive and implied if none of these was specified.
497 Flag --edit specifies that an editor with the contents of current
499 description or title should be opened and the contents saved back
500 afterwards.
501 Flag --title selects operation on the title field instead of
503 description.
504 If neither of --edit and --new-desc are specified the note or
506 description is displayed instead of being modified.
507 destroy domain [--graceful]
509 Immediately terminate the domain domain. This doesn't give the
510 domain OS any chance to react, and it's the equivalent of ripping
511 the power cord out on a physical machine. In most cases you will
512 want to use the shutdown command instead. However, this does not
513 delete any storage volumes used by the guest, and if the domain is
514 persistent, it can be restarted later.
515 If domain is transient, then the metadata of any snapshots will be
517 lost once the guest stops running, but the snapshot contents still
518 exist, and a new domain with the same name and UUID can restore the
519 snapshot metadata with snapshot-create.
520 If --graceful is specified, don't resort to extreme measures (e.g.
522 SIGKILL) when the guest doesn't stop after a reasonable timeout;
523 return an error instead.
524 domblkstat domain block-device [--human]
526 Get device block stats for a running domain. A block-device
527 corresponds to a unique target name (<target dev='name'/>) or
528 source file (<source file='name'/>) for one of the disk devices
529 attached to domain (see also domblklist for listing these names).
530 Use --human for a more human readable output.
532 Availability of these fields depends on hypervisor. Unsupported
534 fields are missing from the output. Other fields may appear if
535 communicating with a newer version of libvirtd.
536 Explanation of fields (fields appear in the folowing order):
538 rd_req - count of read operations
539 rd_bytes - count of read bytes
540 wr_req - count of write operations
541 wr_bytes - count of written bytes
542 errs - error count
543 flush_operations - count of flush operations
544 rd_total_times - total time read operations took (ns)
545 wr_total_times - total time write operations took (ns)
546 flush_total_times - total time flush operations took (ns)
547 <-- other fields provided by hypervisor -->
548 domifstat domain interface-device
550 Get network interface stats for a running domain.
551 domif-setlink domain interface-device state [--config]
553 Modify link state of the domain's virtual interface. Possible
554 values for state are "up" and "down. If --config is specified, only
555 the persistent configuration of the domain is modified, for
556 compatibility purposes, --persistent is alias of --config.
557 interface-device can be the interface's target name or the MAC
558 address.
559 domif-getlink domain interface-device [--config]
561 Query link state of the domain's virtual interface. If --config is
562 specified, query the persistent configuration, for compatibility
563 purposes, --persistent is alias of --config.
564 interface-device can be the interface's target name or the MAC
566 address.
567 domiftune domain interface-device [[--config] [--live] | [--current]]
569 [--inbound average,peak,burst] [--outbound average,peak,burst]
570 Set or query the domain's network interface's bandwidth parameters.
571 interface-device can be the interface's target name (<target
572 dev='name'/>), or the MAC address.
573 If no --inbound or --outbound is specified, this command will query
575 and show the bandwidth settings. Otherwise, it will set the inbound
576 or outbound bandwidth. average,peak,burst is the same as in command
577 attach-interface.
578 If --live is specified, affect a running guest. If --config is
580 specified, affect the next boot of a persistent guest. If
581 --current is specified, affect the current guest state. Both
582 --live and --current flags may be given, but --current is
583 exclusive. If no flag is specified, behavior is different depending
584 on hypervisor.
585 dommemstat domain
587 Get memory stats for a running domain.
588 domblkerror domain
590 Show errors on block devices. This command usually comes handy
591 when domstate command says that a domain was paused due to I/O
592 error. The domblkerror command lists all block devices in error
593 state and the error seen on each of them.
594 domblkinfo domain block-device
596 Get block device size info for a domain. A block-device
597 corresponds to a unique target name (<target dev='name'/>) or
598 source file (<source file='name'/>) for one of the disk devices
599 attached to domain (see also domblklist for listing these names).
600 domblklist domain [--inactive] [--details]
602 Print a table showing the brief information of all block devices
603 associated with domain. If --inactive is specified, query the block
604 devices that will be used on the next boot, rather than those
605 currently in use by a running domain. If --details is specified,
606 disk type and device value will also be printed. Other contexts
607 that require a block device name (such as domblkinfo or snapshot-
608 create for disk snapshots) will accept either target or unique
609 source names printed by this command.
610 domiflist domain [--inactive]
612 Print a table showing the brief information of all virtual
613 interfaces associated with domain. If --inactive is specified,
614 query the virtual interfaces that will be used on the next boot,
615 rather than those currently in use by a running domain. Other
616 contexts that require a MAC address of virtual interface (such as
617 detach-interface or domif-setlink) will accept the MAC address
618 printed by this command.
619 blockcommit domain path [bandwidth] {[base] | [--shallow]} [top]
621 [--delete] [--wait [--verbose] [--timeout seconds]]
622 Reduce the length of a backing image chain, by committing changes
623 at the top of the chain (snapshot or delta files) into backing
624 images. By default, this command attempts to flatten the entire
625 chain. If base and/or top are specified as files within the
626 backing chain, then the operation is constrained to committing just
627 that portion of the chain; --shallow can be used instead of base to
628 specify the immediate backing file of the resulting top image to be
629 committed. The files being committed are rendered invalid,
630 possibly as soon as the operation starts; using the --delete flag
631 will remove these files at the successful completion of the commit
632 operation.
633 By default, this command returns as soon as possible, and data for
635 the entire disk is committed in the background; the progress of the
636 operation can be checked with blockjob. However, if --wait is
637 specified, then this command will block until the operation
638 completes, or cancel the operation if the optional timeout in
639 seconds elapses or SIGINT is sent (usually with "Ctrl-C"). Using
640 --verbose along with --wait will produce periodic status updates.
641 path specifies fully-qualified path of the disk; it corresponds to
643 a unique target name (<target dev='name'/>) or source file (<source
644 file='name'/>) for one of the disk devices attached to domain (see
645 also domblklist for listing these names). bandwidth specifies
646 copying bandwidth limit in MiB/s, although for qemu, it may be non-
647 zero only for an online domain.
648 blockcopy domain path dest [bandwidth] [--shallow] [--reuse-external]
650 [--raw] [--wait [--verbose] [{--pivot | --finish}] [--timeout seconds]
651 [--async]]
652 Copy a disk backing image chain to dest. By default, this command
653 flattens the entire chain; but if --shallow is specified, the copy
654 shares the backing chain.
655 If --reuse-external is specified, then dest must exist and have
657 contents identical to the resulting backing file (that is, it must
658 start with contents matching the backing file disk if --shallow is
659 used, otherwise it must start empty); this option is typically used
660 to set up a relative backing file name in the destination.
661 The format of the destination is determined by the first match in
663 the following list: if --raw is specified, it will be raw; if
664 --reuse-external is specified, the existing destination is probed
665 for a format; and in all other cases, the destination format will
666 match the source format.
667 By default, the copy job runs in the background, and consists of
669 two phases. Initially, the job must copy all data from the source,
670 and during this phase, the job can only be canceled to revert back
671 to the source disk, with no guarantees about the destination.
672 After this phase completes, both the source and the destination
673 remain mirrored until a call to blockjob with the --abort and
674 --pivot flags pivots over to the copy, or a call without --pivot
675 leaves the destination as a faithful copy of that point in time.
676 However, if --wait is specified, then this command will block until
677 the mirroring phase begins, or cancel the operation if the optional
678 timeout in seconds elapses or SIGINT is sent (usually with
679 "Ctrl-C"). Using --verbose along with --wait will produce periodic
680 status updates. Using --pivot or --finish along with --wait will
681 additionally end the job cleanly rather than leaving things in the
682 mirroring phase. If job cancellation is triggered, --async will
683 return control to the user as fast as possible, otherwise the
684 command may continue to block a little while longer until the job
685 is done cleaning up.
686 path specifies fully-qualified path of the disk. bandwidth
688 specifies copying bandwidth limit in MiB/s.
689 blockpull domain path [bandwidth] [base] [--wait [--verbose] [--timeout
691 seconds] [--async]]
692 Populate a disk from its backing image chain. By default, this
693 command flattens the entire chain; but if base is specified,
694 containing the name of one of the backing files in the chain, then
695 that file becomes the new backing file and only the intermediate
696 portion of the chain is pulled. Once all requested data from the
697 backing image chain has been pulled, the disk no longer depends on
698 that portion of the backing chain.
699 By default, this command returns as soon as possible, and data for
701 the entire disk is pulled in the background; the progress of the
702 operation can be checked with blockjob. However, if --wait is
703 specified, then this command will block until the operation
704 completes, or cancel the operation if the optional timeout in
705 seconds elapses or SIGINT is sent (usually with "Ctrl-C"). Using
706 --verbose along with --wait will produce periodic status updates.
707 If job cancellation is triggered, --async will return control to
708 the user as fast as possible, otherwise the command may continue to
709 block a little while longer until the job is done cleaning up.
710 path specifies fully-qualified path of the disk; it corresponds to
712 a unique target name (<target dev='name'/>) or source file (<source
713 file='name'/>) for one of the disk devices attached to domain (see
714 also domblklist for listing these names). bandwidth specifies
715 copying bandwidth limit in MiB/s.
716 blkdeviotune domain device [[--config] [--live] | [--current]] [[total-
718 bytes-sec] | [read-bytes-sec] [write-bytes-sec]] [[total-iops-sec] |
719 [read-iops-sec] [write-iops-sec]]
720 Set or query the block disk io parameters for a block device of
721 domain. device specifies a unique target name (<target
722 dev='name'/>) or source file (<source file='name'/>) for one of the
723 disk devices attached to domain (see also domblklist for listing
724 these names).
725 If no limit is specified, it will query current I/O limits setting.
727 Otherwise, alter the limits with these flags: --total-bytes-sec
728 specifies total throughput limit in bytes per second.
729 --read-bytes-sec specifies read throughput limit in bytes per
730 second. --write-bytes-sec specifies write throughput limit in
731 bytes per second. --total-iops-sec specifies total I/O operations
732 limit per second. --read-iops-sec specifies read I/O operations
733 limit per second. --write-iops-sec specifies write I/O operations
734 limit per second.
735 Older versions of virsh only accepted these options with underscore
737 instead of dash, as in --total_bytes_sec.
738 Bytes and iops values are independent, but setting only one value
740 (such as --read-bytes-sec) resets the other two in that category to
741 unlimited. An explicit 0 also clears any limit. A non-zero value
742 for a given total cannot be mixed with non-zero values for read or
743 write.
744 If --live is specified, affect a running guest. If --config is
746 specified, affect the next boot of a persistent guest. If
747 --current is specified, affect the current guest state. Both
748 --live and --current flags may be given, but --current is
749 exclusive. If no flag is specified, behavior is different depending
750 on hypervisor.
751 blockjob domain path { [--abort] [--async] [--pivot] | [--info] |
753 [bandwidth] }
754 Manage active block operations. There are three modes: --info,
755 bandwidth, and --abort; --info is default except that --async or
756 --pivot implies --abort.
757 path specifies fully-qualified path of the disk; it corresponds to
759 a unique target name (<target dev='name'/>) or source file (<source
760 file='name'/>) for one of the disk devices attached to domain (see
761 also domblklist for listing these names).
762 If --abort is specified, the active job on the specified disk will
764 be aborted. If --async is also specified, this command will return
765 immediately, rather than waiting for the cancelation to complete.
766 If --pivot is specified, this requests that an active copy job be
767 pivoted over to the new copy. If --info is specified, the active
768 job information on the specified disk will be printed. bandwidth
769 can be used to set bandwidth limit for the active job.
770 blockresize domain path size
772 Resize a block device of domain while the domain is running, path
773 specifies the absolute path of the block device; it corresponds to
774 a unique target name (<target dev='name'/>) or source file (<source
775 file='name'/>) for one of the disk devices attached to domain (see
776 also domblklist for listing these names).
777 size is a scaled integer (see NOTES above) which defaults to KiB
779 (blocks of 1024 bytes) if there is no suffix. You must use a
780 suffix of "B" to get bytes (note that for historical reasons, this
781 differs from vol-resize which defaults to bytes without a suffix).
782 domdisplay domain [--include-password]
784 Output a URI which can be used to connect to the graphical display
785 of the domain via VNC, SPICE or RDP. If --include-password is
786 specified, the SPICE channel password will be included in the URI.
787 domhostname domain
789 Returns the hostname of a domain, if the hypervisor makes it
790 available.
791 dominfo domain
793 Returns basic information about the domain.
794 domuuid domain-name-or-id
796 Convert a domain name or id to domain UUID
797 domid domain-name-or-uuid
799 Convert a domain name (or UUID) to a domain id
800 domjobabort domain
802 Abort the currently running domain job.
803 domjobinfo domain
805 Returns information about jobs running on a domain.
806 domname domain-id-or-uuid
808 Convert a domain Id (or UUID) to domain name
809 domstate domain [--reason]
811 Returns state about a domain. --reason tells virsh to also print
812 reason for the state.
813 domcontrol domain
815 Returns state of an interface to VMM used to control a domain. For
816 states other than "ok" or "error" the command also prints number of
817 seconds elapsed since the control interface entered its current
818 state.
819 domxml-from-native format config
821 Convert the file config in the native guest configuration format
822 named by format to a domain XML format. For QEMU/KVM hypervisor,
823 the format argument must be qemu-argv. For Xen hypervisor, the
824 format argument may be xen-xm or xen-sxpr.
825 domxml-to-native format xml
827 Convert the file xml in domain XML format to the native guest
828 configuration format named by format. For QEMU/KVM hypervisor, the
829 format argument must be qemu-argv. For Xen hypervisor, the format
830 argument may be xen-xm or xen-sxpr.
831 dump domain corefilepath [--bypass-cache] { [--live] | [--crash] |
833 [--reset] } [--verbose] [--memory-only]
834 Dumps the core of a domain to a file for analysis. If --live is
835 specified, the domain continues to run until the core dump is
836 complete, rather than pausing up front. If --crash is specified,
837 the domain is halted with a crashed status, rather than merely left
838 in a paused state. If --reset is specified, the domain is reset
839 after successful dump. Note, these three switches are mutually
840 exclusive. If --bypass-cache is specified, the save will avoid the
841 file system cache, although this may slow down the operation. If
842 --memory-only is specified, the file is elf file, and will only
843 include domain's memory and cpu common register value. It is very
844 useful if the domain uses host devices directly.
845 The progress may be monitored using domjobinfo virsh command and
847 canceled with domjobabort command (sent by another virsh instance).
848 Another option is to send SIGINT (usually with "Ctrl-C") to the
849 virsh process running dump command. --verbose displays the progress
850 of dump.
851 NOTE: Some hypervisors may require the user to manually ensure
853 proper permissions on file and path specified by argument
854 corefilepath.
855 dumpxml domain [--inactive] [--security-info] [--update-cpu]
857 [--migratable]
858 Output the domain information as an XML dump to stdout, this format
859 can be used by the create command. Additional options affecting the
860 XML dump may be used. --inactive tells virsh to dump domain
861 configuration that will be used on next start of the domain as
862 opposed to the current domain configuration. Using --security-info
863 will also include security sensitive information in the XML dump.
864 --update-cpu updates domain CPU requirements according to host CPU.
865 With --migratable one can request an XML that is suitable for
866 migrations, i.e., compatible with older libvirt releases and
867 possibly amended with internal run-time options. This option may
868 automatically enable other options (--update-cpu, --security-info,
869 ...) as necessary.
870 edit domain
872 Edit the XML configuration file for a domain, which will affect the
873 next boot of the guest.
874 This is equivalent to:
876 virsh dumpxml --inactive --security-info domain > domain.xml
878 vi domain.xml (or make changes with your other text editor)
879 virsh define domain.xml
880 except that it does some error checking.
882 The editor used can be supplied by the $VISUAL or $EDITOR
884 environment variables, and defaults to "vi".
885 managedsave domain [--bypass-cache] [{--running | --paused}]
887 [--verbose]
888 Save and destroy (stop) a running domain, so it can be restarted
889 from the same state at a later time. When the virsh start command
890 is next run for the domain, it will automatically be started from
891 this saved state. If --bypass-cache is specified, the save will
892 avoid the file system cache, although this may slow down the
893 operation.
894 The progress may be monitored using domjobinfo virsh command and
896 canceled with domjobabort command (sent by another virsh instance).
897 Another option is to send SIGINT (usually with "Ctrl-C") to the
898 virsh process running managedsave command. --verbose displays the
899 progress of save.
900 Normally, starting a managed save will decide between running or
902 paused based on the state the domain was in when the save was done;
903 passing either the --running or --paused flag will allow overriding
904 which state the start should use.
905 The dominfo command can be used to query whether a domain currently
907 has any managed save image.
908 managedsave-remove domain
910 Remove the managedsave state file for a domain, if it exists. This
911 ensures the domain will do a full boot the next time it is started.
912 maxvcpus [type]
914 Provide the maximum number of virtual CPUs supported for a guest VM
915 on this connection. If provided, the type parameter must be a
916 valid type attribute for the <domain> element of XML.
917 cpu-stats domain [--total] [start] [count]
919 Provide cpu statistics information of a domain. The domain should
920 be running. Default it shows stats for all CPUs, and a total. Use
921 --total for only the total stats, start for only the per-cpu stats
922 of the CPUs from start, count for only count CPUs' stats.
923 migrate [--live] [--direct] [--p2p [--tunnelled]] [--persistent]
925 [--undefinesource] [--suspend] [--copy-storage-all]
926 [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose]
927 [--abort-on-error] domain desturi [migrateuri] [dname] [--timeout
928 seconds] [--xml file]
929 Migrate domain to another host. Add --live for live migration;
930 --p2p for peer-2-peer migration; --direct for direct migration; or
931 --tunnelled for tunnelled migration. --persistent leaves the
932 domain persistent on destination host, --undefinesource undefines
933 the domain on the source host, and --suspend leaves the domain
934 paused on the destination host. --copy-storage-all indicates
935 migration with non-shared storage with full disk copy,
936 --copy-storage-inc indicates migration with non-shared storage with
937 incremental copy (same base image shared between source and
938 destination). In both cases the disk images have to exist on
939 destination host, the --copy-storage-... options only tell libvirt
940 to transfer data from the images on source host to the images found
941 at the same place on the destination host. --change-protection
942 enforces that no incompatible configuration changes will be made to
943 the domain while the migration is underway; this flag is implicitly
944 enabled when supported by the hypervisor, but can be explicitly
945 used to reject the migration if the hypervisor lacks change
946 protection support. --verbose displays the progress of migration.
947 --abort-on-error cancels the migration if a soft error (for example
948 I/O error) happens during the migration.
949 Note: Individual hypervisors usually do not support all possible
951 types of migration. For example, QEMU does not support direct
952 migration.
953 In some cases libvirt may refuse to migrate the domain because
955 doing so may lead to potential problems such as data corruption,
956 and thus the migration is considered unsafe. For QEMU domain, this
957 may happen if the domain uses disks without explicitly setting
958 cache mode to "none". Migrating such domains is unsafe unless the
959 disk images are stored on coherent clustered filesystem, such as
960 GFS2 or GPFS. If you are sure the migration is safe or you just do
961 not care, use --unsafe to force the migration.
962 The desturi is the connection URI of the destination host, and
964 migrateuri is the migration URI, which usually can be omitted (see
965 below). dname is used for renaming the domain to new name during
966 migration, which also usually can be omitted. Likewise, --xml file
967 is usually omitted, but can be used to supply an alternative XML
968 file for use on the destination to supply a larger set of changes
969 to any host-specific portions of the domain XML, such as accounting
970 for naming differences between source and destination in accessing
971 underlying storage.
972 --timeout seconds forces guest to suspend when live migration
974 exceeds that many seconds, and then the migration will complete
975 offline. It can only be used with --live.
976 Running migration can be canceled by interrupting virsh (usually
978 using "Ctrl-C") or by domjobabort command sent from another virsh
979 instance.
980 Note: The desturi parameter for normal migration and peer2peer
982 migration has different semantics:
983 · normal migration: the desturi is an address of the target host
985 as seen from the client machine.
986 · peer2peer migration: the desturi is an address of the target
988 host as seen from the source machine.
989 When migrateuri is not specified, libvirt will automatically
991 determine the hypervisor specific URI, by looking up the target
992 host's configured hostname. There are a few scenarios where
993 specifying migrateuri may help:
994 · The configured hostname is incorrect, or DNS is broken. If a
996 host has a hostname which will not resolve to match one of its
997 public IP addresses, then libvirt will generate an incorrect
998 URI. In this case migrateuri should be explicitly specified,
999 using an IP address, or a correct hostname.
1000 · The host has multiple network interaces. If a host has
1002 multiple network interfaces, it might be desirable for the
1003 migration data stream to be sent over a specific interface for
1004 either security or performance reasons. In this case
1005 migrateuri should be explicitly specified, using an IP address
1006 associated with the network to be used.
1007 · The firewall restricts what ports are available. When libvirt
1009 generates a migration URI, it will pick a port number using
1010 hypervisor specific rules. Some hypervisors only require a
1011 single port to be open in the firewalls, while others require a
1012 whole range of port numbers. In the latter case migrateuri
1013 might be specified to choose a specific port number outside the
1014 default range in order to comply with local firewall policies.
1015 migrate-setmaxdowntime domain downtime
1017 Set maximum tolerable downtime for a domain which is being live-
1018 migrated to another host. The downtime is a number of milliseconds
1019 the guest is allowed to be down at the end of live migration.
1020 migrate-setspeed domain bandwidth
1022 Set the maximum migration bandwidth (in MiB/s) for a domain which
1023 is being migrated to another host.
1024 migrate-getspeed domain
1026 Get the maximum migration bandwidth (in MiB/s) for a domain.
1027 numatune domain [--mode mode] [--nodeset nodeset] [[--config] [--live]
1029 | [--current]]
1030 Set or get a domain's numa parameters, corresponding to the
1031 <numatune> element of domain XML. Without flags, the current
1032 settings are displayed.
1033 mode can be one of `strict', `interleave' and `preferred'. For a
1035 running domain, the mode can't be changed, and the nodeset can be
1036 changed only if the domain was started with a mode of `strict'.
1037 nodeset is a list of numa nodes used by the host for running the
1039 domain. Its syntax is a comma separated list, with '-' for ranges
1040 and '^' for excluding a node.
1041 If --live is specified, set scheduler information of a running
1043 guest. If --config is specified, affect the next boot of a
1044 persistent guest. If --current is specified, affect the current
1045 guest state.
1046 reboot domain [--mode acpi|agent]
1048 Reboot a domain. This acts just as if the domain had the reboot
1049 command run from the console. The command returns as soon as it
1050 has executed the reboot action, which may be significantly before
1051 the domain actually reboots.
1052 The exact behavior of a domain when it reboots is set by the
1054 on_reboot parameter in the domain's XML definition.
1055 By default the hypervisor will try to pick a suitable shutdown
1057 method. To specify an alternative method, the --mode parameter can
1058 specify "acpi" or "agent".
1059 reset domain
1061 Reset a domain immediately without any guest shutdown. reset
1062 emulates the power reset button on a machine, where all guest
1063 hardware sees the RST line set and reinitializes internal state.
1064 Note: Reset without any guest OS shutdown risks data loss.
1066 restore state-file [--bypass-cache] [--xml file] [{--running |
1068 --paused}]
1069 Restores a domain from a virsh save state file. See save for more
1070 info.
1071 If --bypass-cache is specified, the restore will avoid the file
1073 system cache, although this may slow down the operation.
1074 --xml file is usually omitted, but can be used to supply an
1076 alternative XML file for use on the restored guest with changes
1077 only in the host-specific portions of the domain XML. For example,
1078 it can be used to account for file naming differences in underlying
1079 storage due to disk snapshots taken after the guest was saved.
1080 Normally, restoring a saved image will use the state recorded in
1082 the save image to decide between running or paused; passing either
1083 the --running or --paused flag will allow overriding which state
1084 the domain should be started in.
1085 Note: To avoid corrupting file system contents within the domain,
1087 you should not reuse the saved state file for a second restore
1088 unless you have also reverted all storage volumes back to the same
1089 contents as when the state file was created.
1090 save domain state-file [--bypass-cache] [--xml file] [{--running |
1092 --paused}] [--verbose]
1093 Saves a running domain (RAM, but not disk state) to a state file so
1094 that it can be restored later. Once saved, the domain will no
1095 longer be running on the system, thus the memory allocated for the
1096 domain will be free for other domains to use. virsh restore
1097 restores from this state file. If --bypass-cache is specified, the
1098 save will avoid the file system cache, although this may slow down
1099 the operation.
1100 The progress may be monitored using domjobinfo virsh command and
1102 canceled with domjobabort command (sent by another virsh instance).
1103 Another option is to send SIGINT (usually with "Ctrl-C") to the
1104 virsh process running save command. --verbose displays the progress
1105 of save.
1106 This is roughly equivalent to doing a hibernate on a running
1108 computer, with all the same limitations. Open network connections
1109 may be severed upon restore, as TCP timeouts may have expired.
1110 --xml file is usually omitted, but can be used to supply an
1112 alternative XML file for use on the restored guest with changes
1113 only in the host-specific portions of the domain XML. For example,
1114 it can be used to account for file naming differences that are
1115 planned to be made via disk snapshots of underlying storage after
1116 the guest is saved.
1117 Normally, restoring a saved image will decide between running or
1119 paused based on the state the domain was in when the save was done;
1120 passing either the --running or --paused flag will allow overriding
1121 which state the restore should use.
1122 Domain saved state files assume that disk images will be unchanged
1124 between the creation and restore point. For a more complete system
1125 restore point, where the disk state is saved alongside the memory
1126 state, see the snapshot family of commands.
1127 save-image-define file xml [{--running | --paused}]
1129 Update the domain XML that will be used when file is later used in
1130 the restore command. The xml argument must be a file name
1131 containing the alternative XML, with changes only in the host-
1132 specific portions of the domain XML. For example, it can be used
1133 to account for file naming differences resulting from creating disk
1134 snapshots of underlying storage after the guest was saved.
1135 The save image records whether the domain should be restored to a
1137 running or paused state. Normally, this command does not alter the
1138 recorded state; passing either the --running or --paused flag will
1139 allow overriding which state the restore should use.
1140 save-image-dumpxml file [--security-info]
1142 Extract the domain XML that was in effect at the time the saved
1143 state file file was created with the save command. Using
1144 --security-info will also include security sensitive information.
1145 save-image-edit file [{--running | --paused}]
1147 Edit the XML configuration associated with a saved state file file
1148 created by the save command.
1149 The save image records whether the domain should be restored to a
1151 running or paused state. Normally, this command does not alter the
1152 recorded state; passing either the --running or --paused flag will
1153 allow overriding which state the restore should use.
1154 This is equivalent to:
1156 virsh save-image-dumpxml state-file > state-file.xml
1158 vi state-file.xml (or make changes with your other text editor)
1159 virsh save-image-define state-file state-file-xml
1160 except that it does some error checking.
1162 The editor used can be supplied by the $VISUAL or $EDITOR
1164 environment variables, and defaults to "vi".
1165 schedinfo [--set parameter=value] domain [[--config] [--live] |
1167 [--current]]
1168 schedinfo [--weight number] [--cap number] domain
1169 Allows you to show (and set) the domain scheduler parameters. The
1170 parameters available for each hypervisor are:
1171 LXC (posix scheduler) : cpu_shares
1173 QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota,
1175 emulator_period, emulator_quota
1176 Xen (credit scheduler): weight, cap
1178 ESX (allocation scheduler): reservation, limit, shares
1180 If --live is specified, set scheduler information of a running
1182 guest. If --config is specified, affect the next boot of a
1183 persistent guest. If --current is specified, affect the current
1184 guest state.
1185 Note: The cpu_shares parameter has a valid value range of 0-262144;
1187 Negative values are wrapped to positive, and larger values are
1188 capped at the maximum. Therefore, -1 is a useful shorthand for
1189 262144. On the Linux kernel, the values 0 and 1 are automatically
1190 converted to a minimal value of 2.
1191 Note: The weight and cap parameters are defined only for the
1193 XEN_CREDIT scheduler and are now DEPRECATED.
1194 Note: The vcpu_period/emulator_period parameters have a valid value
1196 range of 1000-1000000 or 0, and the vcpu_quota/emulator_quota
1197 parameters have a valid value range of 1000-18446744073709551 or
1198 less than 0. The value 0 for either parameter is the same as not
1199 specifying that parameter.
1200 screenshot domain [imagefilepath] [--screen screenID]
1202 Takes a screenshot of a current domain console and stores it into a
1203 file. Optionally, if hypervisor supports more displays for a
1204 domain, screenID allows to specify which screen will be captured.
1205 It is the sequential number of screen. In case of multiple graphics
1206 cards, heads are enumerated before devices, e.g. having two
1207 graphics cards, both with four heads, screen ID 5 addresses the
1208 second head on the second card.
1209 send-key domain [--codeset codeset] [--holdtime holdtime] keycode...
1211 Parse the keycode sequence as keystrokes to send to domain. Each
1212 keycode can either be a numeric value or a symbolic name from the
1213 corresponding codeset. If --holdtime is given, each keystroke will
1214 be held for that many milliseconds. The default codeset is linux,
1215 but use of the --codeset option allows other codesets to be chosen.
1216 linux
1218 The numeric values are those defined by the Linux generic input
1219 event subsystem. The symbolic names match the corresponding
1220 Linux key constant macro names.
1221 xt The numeric values are those defined by the original XT
1223 keyboard controller. No symbolic names are provided
1224 atset1
1226 The numeric values are those defined by the AT keyboard
1227 controller, set 1 (aka XT compatible set). Extended keycoes
1228 from atset1 may differ from extended keycodes in the xt
1229 codeset. No symbolic names are provided
1230 atset2
1232 The numeric values are those defined by the AT keyboard
1233 controller, set 2. No symbolic names are provided
1234 atset3
1236 The numeric values are those defined by the AT keyboard
1237 controller, set 3 (aka PS/2 compatible set). No symbolic names
1238 are provided
1239 os_x
1241 The numeric values are those defined by the OS-X keyboard input
1242 subsystem. The symbolic names match the corresponding OS-X key
1243 constant macro names
1244 xt_kbd
1246 The numeric values are those defined by the Linux KBD device.
1247 These are a variant on the original XT codeset, but often with
1248 different encoding for extended keycodes. No symbolic names are
1249 provided.
1250 win32
1252 The numeric values are those defined by the Win32 keyboard
1253 input subsystem. The symbolic names match the corresponding
1254 Win32 key constant macro names
1255 usb The numeric values are those defined by the USB HID
1257 specification for keyboard input. No symbolic names are
1258 provided
1259 rfb The numeric values are those defined by the RFB extension for
1261 sending raw keycodes. These are a variant on the XT codeset,
1262 but extended keycodes have the low bit of the second byte set,
1263 instead of the high bit of the first byte. No symbolic names
1264 are provided.
1265 Examples
1267 # send three strokes 'k', 'e', 'y', using xt codeset
1268 virsh send-key dom --codeset xt 37 18 21
1269 # send one stroke 'right-ctrl+C'
1270 virsh send-key dom KEY_RIGHTCTRL KEY_C
1271 # send a tab, held for 1 second
1272 virsh send-key --holdtime 1000 0xf
1273 setmem domain size [[--config] [--live] | [--current]]
1275 Change the memory allocation for a guest domain. If --live is
1276 specified, perform a memory balloon of a running guest. If
1277 --config is specified, affect the next boot of a persistent guest.
1278 If --current is specified, affect the current guest state. Both
1279 --live and --config flags may be given, but --current is exclusive.
1280 If no flag is specified, behavior is different depending on
1281 hypervisor.
1282 size is a scaled integer (see NOTES above); it defaults to
1284 kibibytes (blocks of 1024 bytes) unless you provide a suffix (and
1285 the older option name --kilobytes is available as a deprecated
1286 synonym) . Libvirt rounds up to the nearest kibibyte. Some
1287 hypervisors require a larger granularity than KiB, and requests
1288 that are not an even multiple will be rounded up. For example,
1289 vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
1290 For Xen, you can only adjust the memory of a running domain if the
1292 domain is paravirtualized or running the PV balloon driver.
1293 setmaxmem domain size [[--config] [--live] | [--current]]
1295 Change the maximum memory allocation limit for a guest domain. If
1296 --live is specified, affect a running guest. If --config is
1297 specified, affect the next boot of a persistent guest. If
1298 --current is specified, affect the current guest state. Both
1299 --live and --config flags may be given, but --current is exclusive.
1300 If no flag is specified, behavior is different depending on
1301 hypervisor.
1302 Some hypervisors such as QEMU/KVM don't support live changes
1304 (especially increasing) of the maximum memory limit.
1305 size is a scaled integer (see NOTES above); it defaults to
1307 kibibytes (blocks of 1024 bytes) unless you provide a suffix (and
1308 the older option name --kilobytes is available as a deprecated
1309 synonym) . Libvirt rounds up to the nearest kibibyte. Some
1310 hypervisors require a larger granularity than KiB, and requests
1311 that are not an even multiple will be rounded up. For example,
1312 vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
1313 memtune domain [--hard-limit size] [--soft-limit size]
1315 [--swap-hard-limit size] [--min-guarantee size] [[--config] [--live] |
1316 [--current]]
1317 Allows you to display or set the domain memory parameters. Without
1318 flags, the current settings are displayed; with a flag, the
1319 appropriate limit is adjusted if supported by the hypervisor. LXC
1320 and QEMU/KVM support --hard-limit, --soft-limit, and
1321 --swap-hard-limit. --min-guarantee is supported only by ESX
1322 hypervisor. Each of these limits are scaled integers (see NOTES
1323 above), with a default of kibibytes (blocks of 1024 bytes) if no
1324 suffix is present. Libvirt rounds up to the nearest kibibyte. Some
1325 hypervisors require a larger granularity than KiB, and requests
1326 that are not an even multiple will be rounded up. For example,
1327 vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
1328 If --live is specified, affect a running guest. If --config is
1330 specified, affect the next boot of a persistent guest. If
1331 --current is specified, affect the current guest state. Both
1332 --live and --config flags may be given, but --current is exclusive.
1333 If no flag is specified, behavior is different depending on
1334 hypervisor.
1335 For QEMU/KVM, the parameters are applied to the QEMU process as a
1337 whole. Thus, when counting them, one needs to add up guest RAM,
1338 guest video RAM, and some memory overhead of QEMU itself. The last
1339 piece is hard to determine so one needs guess and try.
1340 --hard-limit
1342 The maximum memory the guest can use.
1343 --soft-limit
1345 The memory limit to enforce during memory contention.
1346 --swap-hard-limit
1348 The maximum memory plus swap the guest can use. This has to be
1349 more than hard-limit value provided.
1350 --min-guarantee
1352 The guaranteed minimum memory allocation for the guest.
1353 Specifying -1 as a value for these limits is interpreted as
1355 unlimited.
1356 blkiotune domain [--weight weight] [--device-weights device-weights]
1358 [[--config] [--live] | [--current]]
1359 Display or set the blkio parameters. QEMU/KVM supports --weight.
1360 --weight is in range [100, 1000].
1361 device-weights is a single string listing one or more device/weight
1363 pairs, in the format of
1364 /path/to/device,weight,/path/to/device,weight. Each weight is in
1365 the range [100, 1000], or the value 0 to remove that device from
1366 per-device listings. Only the devices listed in the string are
1367 modified; any existing per-device weights for other devices remain
1368 unchanged.
1369 If --live is specified, affect a running guest. If --config is
1371 specified, affect the next boot of a persistent guest. If
1372 --current is specified, affect the current guest state. Both
1373 --live and --config flags may be given, but --current is exclusive.
1374 If no flag is specified, behavior is different depending on
1375 hypervisor.
1376 setvcpus domain count [--maximum] [[--config] [--live] | [--current]]
1378 [--guest]
1379 Change the number of virtual CPUs active in a guest domain. By
1380 default, this command works on active guest domains. To change the
1381 settings for an inactive guest domain, use the --config flag.
1382 The count value may be limited by host, hypervisor, or a limit
1384 coming from the original description of the guest domain. For Xen,
1385 you can only adjust the virtual CPUs of a running domain if the
1386 domain is paravirtualized.
1387 If the --config flag is specified, the change is made to the stored
1389 XML configuration for the guest domain, and will only take effect
1390 when the guest domain is next started.
1391 If --live is specified, the guest domain must be active, and the
1393 change takes place immediately. Both the --config and --live flags
1394 may be specified together if supported by the hypervisor. If this
1395 command is run before the guest has finished booting, the guest may
1396 fail to process the change.
1397 If --current is specified, affect the current guest state.
1399 When no flags are given, the --live flag is assumed and the guest
1401 domain must be active. In this situation it is up to the
1402 hypervisor whether the --config flag is also assumed, and therefore
1403 whether the XML configuration is adjusted to make the change
1404 persistent.
1405 If --guest is specified, then the count of cpus is modified in the
1407 guest instead of the hypervisor. This flag is usable only for live
1408 domains and may require guest agent to be configured in the guest.
1409 The --maximum flag controls the maximum number of virtual cpus that
1411 can be hot-plugged the next time the domain is booted. As such, it
1412 must only be used with the --config flag, and not with the --live
1413 flag.
1414 shutdown domain [--mode acpi|agent]
1416 Gracefully shuts down a domain. This coordinates with the domain
1417 OS to perform graceful shutdown, so there is no guarantee that it
1418 will succeed, and may take a variable length of time depending on
1419 what services must be shutdown in the domain.
1420 The exact behavior of a domain when it shuts down is set by the
1422 on_shutdown parameter in the domain's XML definition.
1423 If domain is transient, then the metadata of any snapshots will be
1425 lost once the guest stops running, but the snapshot contents still
1426 exist, and a new domain with the same name and UUID can restore the
1427 snapshot metadata with snapshot-create.
1428 By default the hypervisor will try to pick a suitable shutdown
1430 method. To specify an alternative method, the --mode parameter can
1431 specify "acpi" or "agent".
1432 start domain-name-or-uuid [--console] [--paused] [--autodestroy]
1434 [--bypass-cache] [--force-boot]
1435 Start a (previously defined) inactive domain, either from the last
1436 managedsave state, or via a fresh boot if no managedsave state is
1437 present. The domain will be paused if the --paused option is used
1438 and supported by the driver; otherwise it will be running. If
1439 --console is requested, attach to the console after creation. If
1440 --autodestroy is requested, then the guest will be automatically
1441 destroyed when virsh closes its connection to libvirt, or otherwise
1442 exits. If --bypass-cache is specified, and managedsave state
1443 exists, the restore will avoid the file system cache, although this
1444 may slow down the operation. If --force-boot is specified, then
1445 any managedsave state is discarded and a fresh boot occurs.
1446 suspend domain
1448 Suspend a running domain. It is kept in memory but won't be
1449 scheduled anymore.
1450 resume domain
1452 Moves a domain out of the suspended state. This will allow a
1453 previously suspended domain to now be eligible for scheduling by
1454 the underlying hypervisor.
1455 dompmsuspend domain target [--duration]
1457 Suspend a running domain into one of these states (possible target
1458 values):
1459 mem equivallent of S3 ACPI state
1460 disk equivallent of S4 ACPI state
1461 hybrid RAM is saved to disk but not powered off
1462 The --duration argument specifies number of seconds before the
1464 domain is woken up after it was suspended (see also dompmwakeup).
1465 Default is 0 for unlimited suspend time. (This feature isn't
1466 currently supported by any hypervisor driver and 0 should be
1467 used.).
1468 Note that this command requires a guest agent configured and
1470 running in the domain's guest OS.
1471 Beware that at least for QEMU, the domain's process will be
1473 terminated when target disk is used and a new process will be
1474 launched when libvirt is asked to wake up the domain. As a result
1475 of this, any runtime changes, such as device hotplug or memory
1476 settings, are lost unless such changes were made with --config
1477 flag.
1478 dompmwakeup domain
1480 Wakeup a domain from pmsuspended state (either suspended by
1481 dompmsuspend or from the guest itself). Injects a wakeup into the
1482 guest that is in pmsuspended state, rather than waiting for the
1483 previously requested duration (if any) to elapse. This operation
1484 doesn't not necessarily fail if the domain is running.
1485 ttyconsole domain
1487 Output the device used for the TTY console of the domain. If the
1488 information is not available the processes will provide an exit
1489 code of 1.
1490 undefine domain [--managed-save] [--snapshots-metadata] [ {--storage
1492 volumes | --remove-all-storage} --wipe-storage]
1493 Undefine a domain. If the domain is running, this converts it to a
1494 transient domain, without stopping it. If the domain is inactive,
1495 the domain configuration is removed.
1496 The --managed-save flag guarantees that any managed save image (see
1498 the managedsave command) is also cleaned up. Without the flag,
1499 attempts to undefine a domain with a managed save image will fail.
1500 The --snapshots-metadata flag guarantees that any snapshots (see
1502 the snapshot-list command) are also cleaned up when undefining an
1503 inactive domain. Without the flag, attempts to undefine an
1504 inactive domain with snapshot metadata will fail. If the domain is
1505 active, this flag is ignored.
1506 The --storage flag takes a parameter volumes, which is a comma
1508 separated list of volume target names or source paths of storage
1509 volumes to be removed along with the undefined domain. Volumes can
1510 be undefined and thus removed only on inactive domains. Volume
1511 deletion is only attempted after the domain is undefined; if not
1512 all of the requested volumes could be deleted, the error message
1513 indicates what still remains behind. If a volume path is not found
1514 in the domain definition, it's treated as if the volume was
1515 successfully deleted. Only volumes managed by libvirt in storage
1516 pools can be removed this way. (See domblklist for list of target
1517 names associated to a domain). Example: --storage
1518 vda,/path/to/storage.img
1519 The --remove-all-storage flag specifies that all of the domain's
1521 storage volumes should be deleted.
1522 The flag --wipe-storage specifies that the storage volumes should
1524 be wiped before removal.
1525 NOTE: For an inactive domain, the domain name or UUID must be used
1527 as the domain.
1528 vcpucount domain [{--maximum | --active} {--config | --live |
1530 --current}] [--guest]
1531 Print information about the virtual cpu counts of the given domain.
1532 If no flags are specified, all possible counts are listed in a
1533 table; otherwise, the output is limited to just the numeric value
1534 requested. For historical reasons, the table lists the label
1535 "current" on the rows that can be queried in isolation via the
1536 --active flag, rather than relating to the --current flag.
1537 --maximum requests information on the maximum cap of vcpus that a
1539 domain can add via setvcpus, while --active shows the current
1540 usage; these two flags cannot both be specified. --config requires
1541 a persistent domain and requests information regarding the next
1542 time the domain will be booted, --live requires a running domain
1543 and lists current values, and --current queries according to the
1544 current state of the domain (corresponding to --live if running, or
1545 --config if inactive); these three flags are mutually exclusive.
1546 If --guest is specified, then the count of cpus is reported from
1548 the perspective of the guest. This flag is usable only for live
1549 domains and may require guest agent to be configured in the guest.
1550 vcpuinfo domain
1552 Returns basic information about the domain virtual CPUs, like the
1553 number of vCPUs, the running time, the affinity to physical
1554 processors.
1555 vcpupin domain [vcpu] [cpulist] [[--live] [--config] | [--current]]
1557 Query or change the pinning of domain VCPUs to host physical CPUs.
1558 To pin a single vcpu, specify cpulist; otherwise, you can query one
1559 vcpu or omit vcpu to list all at once.
1560 cpulist is a list of physical CPU numbers. Its syntax is a comma
1562 separated list and a special markup using '-' and '^' (ex. '0-4',
1563 '0-3,^2') can also be allowed. The '-' denotes the range and the
1564 '^' denotes exclusive. If you want to reset vcpupin setting, that
1565 is, to pin vcpu all physical cpus, simply specify 'r' as a cpulist.
1566 If --live is specified, affect a running guest. If --config is
1567 specified, affect the next boot of a persistent guest. If
1568 --current is specified, affect the current guest state. Both
1569 --live and --config flags may be given if cpulist is present, but
1570 --current is exclusive. If no flag is specified, behavior is
1571 different depending on hypervisor.
1572 Note: The expression is sequentially evaluated, so "0-15,^8" is
1574 identical to "9-14,0-7,15" but not identical to "^8,0-15".
1575 emulatorpin domain [cpulist] [[--live] [--config] | [--current]]
1577 Query or change the pinning of domain's emulator threads to host
1578 physical CPUs.
1579 See vcpupin for cpulist.
1581 If --live is specified, affect a running guest. If --config is
1583 specified, affect the next boot of a persistent guest. If
1584 --current is specified, affect the current guest state. Both
1585 --live and --config flags may be given if cpulist is present, but
1586 --current is exclusive. If no flag is specified, behavior is
1587 different depending on hypervisor.
1588 vncdisplay domain
1590 Output the IP address and port number for the VNC display. If the
1591 information is not available the processes will provide an exit
1592 code of 1.
1593
1595 The following commands manipulate devices associated to domains. The
1596 domain can be specified as a short integer, a name or a full UUID. To
1597 better understand the values allowed as options for the command reading
1598 the documentation at <http://libvirt.org/formatdomain.html> on the
1599 format of the device sections to get the most accurate set of accepted
1600 values.
1601 attach-device domain FILE [[[--live] [--config] | [--current]] |
1603 [--persistent]]
1604 Attach a device to the domain, using a device definition in an XML
1605 file using a device definition element such as <disk> or
1606 <interface> as the top-level element. See the documentation at
1607 <http://libvirt.org/formatdomain.html#elementsDevices> to learn
1608 about libvirt XML format for a device. If --config is specified
1609 the command alters the persistent domain configuration with the
1610 device attach taking effect the next time libvirt starts the
1611 domain. For cdrom and floppy devices, this command only replaces
1612 the media within an existing device; consider using update-device
1613 for this usage. For passthrough host devices, see also nodedev-
1614 detach, needed if the device does not use managed mode.
1615 If --live is specified, affect a running domain. If --config is
1617 specified, affect the next startup of a persistent domain. If
1618 --current is specified, affect the current domain state. Both
1619 --live and --config flags may be given, but --current is exclusive.
1620 When no flag is specified legacy API is used whose behavior depends
1621 on the hypervisor driver.
1622 For compatibility purposes, --persistent behaves like --config for
1624 an offline domain, and like --live --config for a running domain.
1625 attach-disk domain source target [[[--live] [--config] | [--current]] |
1627 [--persistent]] [--driver driver] [--subdriver subdriver] [--cache
1628 cache] [--type type] [--mode mode] [--sourcetype sourcetype] [--serial
1629 serial] [--shareable] [--rawio] [--address address] [--multifunction]
1630 Attach a new disk device to the domain. source is path for the
1631 files and devices. target controls the bus or device under which
1632 the disk is exposed to the guest OS. It indicates the "logical"
1633 device name. driver can be file, tap or phy for the Xen hypervisor
1634 depending on the kind of access; or qemu for the QEMU emulator.
1635 Further details to the driver can be passed using subdriver. For
1636 Xen subdriver can be aio, while for QEMU subdriver should match the
1637 format of the disk source, such as raw or qcow2. Hypervisor
1638 default will be used if subdriver is not specified. However, the
1639 default may not be correct, esp. for QEMU as for security reasons
1640 it is configured not to detect disk formats. type can indicate
1641 lun, cdrom or floppy as alternative to the disk default, although
1642 this use only replaces the media within the existing virtual cdrom
1643 or floppy device; consider using update-device for this usage
1644 instead. mode can specify the two specific mode readonly or
1645 shareable. sourcetype can indicate the type of source (block|file)
1646 cache can be one of "default", "none", "writethrough", "writeback",
1647 "directsync" or "unsafe". serial is the serial of disk device.
1648 shareable indicates the disk device is shareable between domains.
1649 rawio indicates the disk needs rawio capability. address is the
1650 address of disk device in the form of pci:domain.bus.slot.function,
1651 scsi:controller.bus.unit or ide:controller.bus.unit. multifunction
1652 indicates specified pci address is a multifunction pci device
1653 address.
1654 If --live is specified, affect a running domain. If --config is
1656 specified, affect the next startup of a persistent domain. If
1657 --current is specified, affect the current domain state. Both
1658 --live and --config flags may be given, but --current is exclusive.
1659 When no flag is specified legacy API is used whose behavior depends
1660 on the hypervisor driver.
1661 For compatibility purposes, --persistent behaves like --config for
1663 an offline domain, and like --live --config for a running domain.
1664 attach-interface domain type source [[[--live] [--config] |
1666 [--current]] | [--persistent]] [--target target] [--mac mac] [--script
1667 script] [--model model] [--config] [--inbound average,peak,burst]
1668 [--outbound average,peak,burst]
1669 Attach a new network interface to the domain. type can be either
1670 network to indicate a physical network device or bridge to indicate
1671 a bridge to a device. source indicates the source device. target
1672 allows to indicate the target device in the guest. Names starting
1673 with 'vnet' are considered as auto-generated an hence blanked out.
1674 mac allows to specify the MAC address of the network interface.
1675 script allows to specify a path to a script handling a bridge
1676 instead of the default one. model allows to specify the model
1677 type. inbound and outbound control the bandwidth of the interface.
1678 peak and burst are optional, so "average,peak", "average,,burst"
1679 and "average" are also legal.
1680 If --live is specified, affect a running domain. If --config is
1682 specified, affect the next startup of a persistent domain. If
1683 --current is specified, affect the current domain state. Both
1684 --live and --config flags may be given, but --current is exclusive.
1685 When no flag is specified legacy API is used whose behavior depends
1686 on the hypervisor driver.
1687 For compatibility purposes, --persistent behaves like --config for
1689 an offline domain, and like --live --config for a running domain.
1690 Note: the optional target value is the name of a device to be
1692 created as the back-end on the node. If not provided a device named
1693 "vnetN" or "vifN" will be created automatically.
1694 detach-device domain FILE [[[--live] [--config] | [--current]] |
1696 [--persistent]]
1697 Detach a device from the domain, takes the same kind of XML
1698 descriptions as command attach-device. For passthrough host
1699 devices, see also nodedev-reattach, needed if the device does not
1700 use managed mode.
1701 If --live is specified, affect a running domain. If --config is
1703 specified, affect the next startup of a persistent domain. If
1704 --current is specified, affect the current domain state. Both
1705 --live and --config flags may be given, but --current is exclusive.
1706 When no flag is specified legacy API is used whose behavior depends
1707 on the hypervisor driver.
1708 For compatibility purposes, --persistent behaves like --config for
1710 an offline domain, and like --live --config for a running domain.
1711 Note that older versions of virsh used --config as an alias for
1713 --persistent.
1714 detach-disk domain target [[[--live] [--config] | [--current]] |
1716 [--persistent]]
1717 Detach a disk device from a domain. The target is the device as
1718 seen from the domain.
1719 If --live is specified, affect a running domain. If --config is
1721 specified, affect the next startup of a persistent domain. If
1722 --current is specified, affect the current domain state. Both
1723 --live and --config flags may be given, but --current is exclusive.
1724 When no flag is specified legacy API is used whose behavior depends
1725 on the hypervisor driver.
1726 For compatibility purposes, --persistent behaves like --config for
1728 an offline domain, and like --live --config for a running domain.
1729 Note that older versions of virsh used --config as an alias for
1731 --persistent.
1732 detach-interface domain type [--mac mac] [--config]
1734 Detach a network interface from a domain. type can be either
1735 network to indicate a physical network device or bridge to indicate
1736 a bridge to a device. It is recommended to use the mac option to
1737 distinguish between the interfaces if more than one are present on
1738 the domain. If --config is specified, alter persistent
1739 configuration, effect observed on next boot, for compatibility
1740 purposes, --persistent is alias of --config.
1741 update-device domain file [--force] [[[--live] [--config] |
1743 [--current]] | [--persistent]]
1744 Update the characteristics of a device associated with domain,
1745 based on the device definition in an XML file. The --force option
1746 can be used to force device update, e.g., to eject a CD-ROM even if
1747 it is locked/mounted in the domain. See the documentation at
1748 <http://libvirt.org/formatdomain.html#elementsDevices> to learn
1749 about libvirt XML format for a device.
1750 If --live is specified, affect a running domain. If --config is
1752 specified, affect the next startup of a persistent domain. If
1753 --current is specified, affect the current domain state. Both
1754 --live and --config flags may be given, but --current is exclusive.
1755 Not specifying any flag is the same as specifying --current.
1756 For compatibility purposes, --persistent behaves like --config for
1758 an offline domain, and like --live --config for a running domain.
1759 Note that older versions of virsh used --config as an alias for
1761 --persistent.
1762 change-media domain path [--eject] [--insert] [--update] [source]
1764 [--force] [[--live] [--config] | [--current]]
1765 Change media of CDROM or floppy drive. path can be the fully-
1766 qualified path or the unique target name (<target dev='hdc'>) of
1767 the disk device. source specifies the path of the media to be
1768 inserted or updated.
1769 --eject indicates the media will be ejected. --insert indicates
1771 the media will be inserted. source must be specified. If the
1772 device has source (e.g. <source file='media'>), and source is not
1773 specified, --update is equal to --eject. If the device has no
1774 source, and source is specified, --update is equal to --insert. If
1775 the device has source, and source is specified, --update behaves
1776 like combination of --eject and --insert. If none of --eject,
1777 --insert, and --update is specified, --update is used by default.
1778 The --force option can be used to force media changing. If --live
1779 is specified, alter live configuration of running guest. If
1780 --config is specified, alter persistent configuration, effect
1781 observed on next boot. --current can be either or both of live and
1782 config, depends on the hypervisor's implementation. Both --live
1783 and --config flags may be given, but --current is exclusive. If no
1784 flag is specified, behavior is different depending on hypervisor.
1785
1787 The following commands manipulate host devices that are intended to be
1788 passed through to guest domains via <hostdev> elements in a domain's
1789 <devices> section. A node device key is generally specified by the bus
1790 name followed by its address, using underscores between all components,
1791 such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
1792 The nodedev-list gives the full list of host devices that are known to
1793 libvirt, although this includes devices that cannot be assigned to a
1794 guest (for example, attempting to detach the PCI device that controls
1795 the host's hard disk controller where the guest's disk images live
1796 could cause the host system to lock up or reboot).
1797 For more information on node device definition see:
1799 <http://libvirt.org/formatnode.html>.
1800 Passthrough devices cannot be simultaneously used by the host and its
1802 guest domains, nor by multiple active guests at once. If the <hostdev>
1803 description includes the attribute managed='yes', and the hypervisor
1804 driver supports it, then the device is in managed mode, and attempts to
1805 use that passthrough device in an active guest will automatically
1806 behave as if nodedev-detach (guest start, device hot-plug) and nodedev-
1807 reattach (guest stop, device hot-unplug) were called at the right
1808 points (currently, qemu does this for PCI devices, but not USB). If a
1809 device is not marked as managed, then it must manually be detached
1810 before guests can use it, and manually reattached to be returned to the
1811 host. Also, if a device is manually detached, then the host does not
1812 regain control of the device without a matching reattach, even if the
1813 guests use the device in managed mode.
1814 nodedev-create FILE
1816 Create a device on the host node that can then be assigned to
1817 virtual machines. Normally, libvirt is able to automatically
1818 determine which host nodes are available for use, but this allows
1819 registration of host hardware that libvirt did not automatically
1820 detect. file contains xml for a top-level <device> description of
1821 a node device.
1822 nodedev-destroy nodedev
1824 Destroy (stop) a device on the host. Note that this makes libvirt
1825 quit managing a host device, and may even make that device unusable
1826 by the rest of the physical host until a reboot.
1827 nodedev-detach nodedev
1829 Detach nodedev from the host, so that it can safely be used by
1830 guests via <hostdev> passthrough. This is reversed with nodedev-
1831 reattach, and is done automatically for managed devices. For
1832 compatibility purposes, this command can also be spelled nodedev-
1833 dettach.
1834 nodedev-dumpxml nodedev
1836 Dump a <device> XML representation for the given node device,
1837 including such information as the device name, which bus owns the
1838 device, the vendor and product id, and any capabilities of the
1839 device usable by libvirt (such as whether device reset is
1840 supported).
1841 nodedev-list cap --tree
1843 List all of the devices available on the node that are known by
1844 libvirt. cap is used to filter the list by capability types, the
1845 types must be separated by comma, e.g. --cap pci,scsi, valid
1846 capability types include 'system', 'pci', 'usb_device', 'usb',
1847 'net', 'scsi_host', 'scsi_target', 'scsi', 'storage'. If --tree is
1848 used, the output is formatted in a tree representing parents of
1849 each node. cap and --tree are mutually exclusive.
1850 nodedev-reattach nodedev
1852 Declare that nodedev is no longer in use by any guests, and that
1853 the host can resume normal use of the device. This is done
1854 automatically for devices in managed mode, but must be done
1855 explicitly to match any explicit nodedev-detach.
1856 nodedev-reset nodedev
1858 Trigger a device reset for nodedev, useful prior to transferring a
1859 node device between guest passthrough or the host. Libvirt will
1860 often do this action implicitly when required, but this command
1861 allows an explicit reset when needed.
1862
1864 The following commands manipulate networks. Libvirt has the capability
1865 to define virtual networks which can then be used by domains and linked
1866 to actual network devices. For more detailed information about this
1867 feature see the documentation at
1868 <http://libvirt.org/formatnetwork.html> . Many of the commands for
1869 virtual networks are similar to the ones used for domains, but the way
1870 to name a virtual network is either by its name or UUID.
1871 net-autostart network [--disable]
1873 Configure a virtual network to be automatically started at boot.
1874 The --disable option disable autostarting.
1875 net-create file
1877 Create a virtual network from an XML file, see the documentation at
1878 <http://libvirt.org/formatnetwork.html> to get a description of the
1879 XML network format used by libvirt.
1880 net-define file
1882 Define a virtual network from an XML file, the network is just
1883 defined but not instantiated.
1884 net-destroy network
1886 Destroy (stop) a given virtual network specified by its name or
1887 UUID. This takes effect immediately.
1888 net-dumpxml network [--inactive]
1890 Output the virtual network information as an XML dump to stdout.
1891 If --inactive is specified, then physical functions are not
1892 expanded into their associated virtual functions.
1893 net-edit network
1895 Edit the XML configuration file for a network.
1896 This is equivalent to:
1898 virsh net-dumpxml --inactive network > network.xml
1900 vi network.xml (or make changes with your other text editor)
1901 virsh net-define network.xml
1902 except that it does some error checking.
1904 The editor used can be supplied by the $VISUAL or $EDITOR
1906 environment variables, and defaults to "vi".
1907 net-info network
1909 Returns basic information about the network object.
1910 net-list [--inactive | --all] [--persistent] [<--transient>]
1912 [--autostart] [<--no-autostart>]
1913 Returns the list of active networks, if --all is specified this
1914 will also include defined but inactive networks, if --inactive is
1915 specified only the inactive ones will be listed. You may also want
1916 to filter the returned networks by --persistent to list the
1917 persistent ones, --transient to list the transient ones,
1918 --autostart to list the ones with autostart enabled, and
1919 --no-autostart to list the ones with autostart disabled.
1920 NOTE: When talking to older servers, this command is forced to use
1922 a series of API calls with an inherent race, where a pool might not
1923 be listed or might appear more than once if it changed state
1924 between calls while the list was being collected. Newer servers do
1925 not have this problem.
1926 net-name network-UUID
1928 Convert a network UUID to network name.
1929 net-start network
1931 Start a (previously defined) inactive network.
1932 net-undefine network
1934 Undefine the configuration for an inactive network.
1935 net-uuid network-name
1937 Convert a network name to network UUID.
1938 net-update network command section xml [--parent-index index] [[--live]
1940 [--config] | [--current]]
1941 Update the given section of an existing network definition, with
1942 the changes optionally taking effect immediately, without needing
1943 to destroy and re-start the network.
1944 command is one of "add-first", "add-last", "add" (a synonym for
1946 add-last), "delete", or "modify".
1947 section is one of ""bridge", "domain", "ip", "ip-dhcp-host", "ip-
1949 dhcp-range", "forward", "forward-interface", "forward-pf",
1950 "portgroup", "dns-host", "dns-txt", or "dns-srv", each section
1951 being named by a concatenation of the xml element hierarchy leading
1952 to the element being changed. For example, "ip-dhcp-host" will
1953 change a <host> element that is contained inside a <dhcp> element
1954 inside an <ip> element of the network.
1955 xml is either the text of a complete xml element of the type being
1957 changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or
1958 the name of a file that contains a complete xml element.
1959 Disambiguation is done by looking at the first character of the
1960 provided text - if the first character is "<", it is xml text, if
1961 the first character is not "<", it is the name of a file that
1962 contains the xml text to be used.
1963 The --parent-index option is used to specify which of several
1965 parent elements the requested element is in (0-based). For example,
1966 a dhcp <host> element could be in any one of multiple <ip> elements
1967 in the network; if a parent-index isn't provided, the "most
1968 appropriate" <ip> element will be selected (usually the only one
1969 that already has a <dhcp> element), but if --parent-index is given,
1970 that particular instance of <ip> will get the modification.
1971 If --live is specified, affect a running network. If --config is
1973 specified, affect the next startup of a persistent network. If
1974 --current is specified, affect the current network state. Both
1975 --live and --config flags may be given, but --current is exclusive.
1976 Not specifying any flag is the same as specifying --current.
1977
1979 The following commands manipulate host interfaces. Often, these host
1980 interfaces can then be used by name within domain <interface> elements
1981 (such as a system-created bridge interface), but there is no
1982 requirement that host interfaces be tied to any particular guest
1983 configuration XML at all.
1984 Many of the commands for host interfaces are similar to the ones used
1986 for domains, and the way to name an interface is either by its name or
1987 its MAC address. However, using a MAC address for an iface argument
1988 only works when that address is unique (if an interface and a bridge
1989 share the same MAC address, which is often the case, then using that
1990 MAC address results in an error due to ambiguity, and you must resort
1991 to a name instead).
1992 iface-bridge interface bridge [--no-stp] [delay] [--no-start]
1994 Create a bridge device named bridge, and attach the existing
1995 network device interface to the new bridge. The new bridge
1996 defaults to starting immediately, with STP enabled and a delay of
1997 0; these settings can be altered with --no-stp, --no-start, and an
1998 integer number of seconds for delay. All IP address configuration
1999 of interface will be moved to the new bridge device.
2000 See also iface-unbridge for undoing this operation.
2002 iface-define file
2004 Define a host interface from an XML file, the interface is just
2005 defined but not started.
2006 iface-destroy interface
2008 Destroy (stop) a given host interface, such as by running "if-down"
2009 to disable that interface from active use. This takes effect
2010 immediately.
2011 iface-dumpxml interface [--inactive]
2013 Output the host interface information as an XML dump to stdout. If
2014 --inactive is specified, then the output reflects the persistent
2015 state of the interface that will be used the next time it is
2016 started.
2017 iface-edit interface
2019 Edit the XML configuration file for a host interface.
2020 This is equivalent to:
2022 virsh iface-dumpxml iface > iface.xml
2024 vi iface.xml (or make changes with your other text editor)
2025 virsh iface-define iface.xml
2026 except that it does some error checking.
2028 The editor used can be supplied by the $VISUAL or $EDITOR
2030 environment variables, and defaults to "vi".
2031 iface-list [--inactive | --all]
2033 Returns the list of active host interfaces. If --all is specified
2034 this will also include defined but inactive interfaces. If
2035 --inactive is specified only the inactive ones will be listed.
2036 iface-name interface
2038 Convert a host interface MAC to interface name, if the MAC address
2039 is unique among the host's interfaces.
2040 interface specifies the interface MAC address.
2042 iface-mac interface
2044 Convert a host interface name to MAC address.
2045 interface specifies the interface name.
2047 iface-start interface
2049 Start a (previously defined) host interface, such as by running
2050 "if-up".
2051 iface-unbridge bridge [--no-start]
2053 Tear down a bridge device named bridge, releasing its underlying
2054 interface back to normal usage, and moving all IP address
2055 configuration from the bridge device to the underlying device. The
2056 underlying interface is restarted unless --no-start is present;
2057 this flag is present for symmetry, but generally not recommended.
2058 See also iface-bridge for creating a bridge.
2060 iface-undefine interface
2062 Undefine the configuration for an inactive host interface.
2063 iface-begin
2065 Create a snapshot of current host interface settings, which can
2066 later be committed (iface-commit) or restored (iface-rollback). If
2067 a snapshot already exists, then this command will fail until the
2068 previous snapshot has been committed or restored. Undefined
2069 behavior results if any external changes are made to host
2070 interfaces outside of the libvirt API between the beginning of a
2071 snapshot and its eventual commit or rollback.
2072 iface-commit
2074 Declare all changes since the last iface-begin as working, and
2075 delete the rollback point. If no interface snapshot has already
2076 been started, then this command will fail.
2077 iface-rollback
2079 Revert all host interface settings back to the state recorded in
2080 the last iface-begin. If no interface snapshot has already been
2081 started, then this command will fail. Rebooting the host also
2082 serves as an implicit rollback point.
2083
2085 The following commands manipulate storage pools. Libvirt has the
2086 capability to manage various storage solutions, including files, raw
2087 partitions, and domain-specific formats, used to provide the storage
2088 volumes visible as devices within virtual machines. For more detailed
2089 information about this feature, see the documentation at
2090 <http://libvirt.org/formatstorage.html> . Many of the commands for
2091 pools are similar to the ones used for domains.
2092 find-storage-pool-sources type [srcSpec]
2094 Returns XML describing all storage pools of a given type that could
2095 be found. If srcSpec is provided, it is a file that contains XML
2096 to further restrict the query for pools.
2097 find-storage-pool-sources-as type [host] [port] [initiator]
2099 Returns XML describing all storage pools of a given type that could
2100 be found. If host, port, or initiator are provided, they control
2101 where the query is performed.
2102 pool-autostart pool-or-uuid [--disable]
2104 Configure whether pool should automatically start at boot.
2105 pool-build pool-or-uuid [--overwrite] [--no-overwrite]
2107 Build a given pool.
2108 Options --overwrite and --no-overwrite can only be used for pool-
2110 build a filesystem pool. If neither of them is specified, pool-
2111 build on a filesystem pool only makes the directory; If
2112 --no-overwrite is specified, it probes to determine if a filesystem
2113 already exists on the target device, returning an error if exists,
2114 or using mkfs to format the target device if not; If --overwrite is
2115 specified, mkfs is always executed, any existed data on the target
2116 device is overwritten unconditionally.
2117 pool-create file
2119 Create and start a pool object from the XML file.
2120 pool-create-as name --print-xml type [source-host] [source-path]
2122 [source-dev] [source-name] [<target>] [--source-format format]
2123 Create and start a pool object name from the raw parameters. If
2124 --print-xml is specified, then print the XML of the pool object
2125 without creating the pool. Otherwise, the pool has the specified
2126 type. When using pool-create-as for a pool of type "disk", the
2127 existing partitions found on the --source-dev path will be used to
2128 populate the disk pool. Therefore, it is suggested to use pool-
2129 define-as and pool-build with the --overwrite in order to properly
2130 initialize the disk pool.
2131 pool-define file
2133 Create, but do not start, a pool object from the XML file.
2134 pool-define-as name --print-xml type [source-host] [source-path]
2136 [source-dev] [source-name] [<target>] [--source-format format]
2137 Create, but do not start, a pool object name from the raw
2138 parameters. If --print-xml is specified, then print the XML of the
2139 pool object without defining the pool. Otherwise, the pool has the
2140 specified type.
2141 pool-destroy pool-or-uuid
2143 Destroy (stop) a given pool object. Libvirt will no longer manage
2144 the storage described by the pool object, but the raw data
2145 contained in the pool is not changed, and can be later recovered
2146 with pool-create.
2147 pool-delete pool-or-uuid
2149 Destroy the resources used by a given pool object. This operation
2150 is non-recoverable. The pool object will still exist after this
2151 command, ready for the creation of new storage volumes.
2152 pool-dumpxml [--inactive] pool-or-uuid
2154 Returns the XML information about the pool object. --inactive
2155 tells virsh to dump pool configuration that will be used on next
2156 start of the pool as opposed to the current pool configuration.
2157 pool-edit pool-or-uuid
2159 Edit the XML configuration file for a storage pool.
2160 This is equivalent to:
2162 virsh pool-dumpxml pool > pool.xml
2164 vi pool.xml (or make changes with your other text editor)
2165 virsh pool-define pool.xml
2166 except that it does some error checking.
2168 The editor used can be supplied by the $VISUAL or $EDITOR
2170 environment variables, and defaults to "vi".
2171 pool-info pool-or-uuid
2173 Returns basic information about the pool object.
2174 pool-list [--inactive] [--all] [--persistent] [--transient]
2176 [--autostart] [--no-autostart] [[--details] [<type>]
2177 List pool objects known to libvirt. By default, only active pools
2178 are listed; --inactive lists just the inactive pools, and --all
2179 lists all pools.
2180 In addition, there are several sets of filtering flags.
2182 --persistent is to list the persistent pools, --transient is to
2183 list the transient pools. --autostart lists the autostarting
2184 pools, --no-autostart lists the pools with autostarting disabled.
2185 You may also want to list pools with specified types using type,
2187 the pool types must be separated by comma, e.g. --type dir,disk.
2188 The valid pool types include 'dir', 'fs', 'netfs', 'logical',
2189 'disk', 'iscsi', 'scsi', 'mpath', 'rbd', and 'sheepdog'.
2190 The --details option instructs virsh to additionally display pool
2192 persistence and capacity related information where available.
2193 NOTE: When talking to older servers, this command is forced to use
2195 a series of API calls with an inherent race, where a pool might not
2196 be listed or might appear more than once if it changed state
2197 between calls while the list was being collected. Newer servers do
2198 not have this problem.
2199 pool-name uuid
2201 Convert the uuid to a pool name.
2202 pool-refresh pool-or-uuid
2204 Refresh the list of volumes contained in pool.
2205 pool-start pool-or-uuid
2207 Start the storage pool, which is previously defined but inactive.
2208 pool-undefine pool-or-uuid
2210 Undefine the configuration for an inactive pool.
2211 pool-uuid pool
2213 Returns the UUID of the named pool.
2214
2216 vol-create pool-or-uuid FILE
2217 Create a volume from an XML <file>. pool-or-uuid is the name or
2218 UUID of the storage pool to create the volume in. FILE is the XML
2219 <file> with the volume definition. An easy way to create the XML
2220 <file> is to use the vol-dumpxml command to obtain the definition
2221 of a pre-existing volume.
2222 Example
2224 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
2226 vi newvolume.xml (or make changes with your other text editor)
2227 virsh vol-create differentstoragepool newvolume.xml
2228 vol-create-from pool-or-uuid FILE [--inputpool pool-or-uuid] vol-name-
2230 or-key-or-path
2231 Create a volume, using another volume as input. pool-or-uuid is
2232 the name or UUID of the storage pool to create the volume in. FILE
2233 is the XML <file> with the volume definition. --inputpool pool-or-
2234 uuid is the name or uuid of the storage pool the source volume is
2235 in. vol-name-or-key-or-path is the name or key or path of the
2236 source volume.
2237 vol-create-as pool-or-uuid name capacity [--allocation size] [--format
2239 string] [--backing-vol vol-name-or-key-or-path] [--backing-vol-format
2240 string]
2241 Create a volume from a set of arguments. pool-or-uuid is the name
2242 or UUID of the storage pool to create the volume in. name is the
2243 name of the new volume. For a disk pool, this must match the
2244 partition name as determined from the pool's source device path and
2245 the next available partition. For example, a source device path of
2246 /dev/sdb and there are no partitions on the disk, then the name
2247 must be sdb1 with the next name being sdb2 and so on. capacity is
2248 the size of the volume to be created, as a scaled integer (see
2249 NOTES above), defaulting to bytes if there is no suffix.
2250 --allocation size is the initial size to be allocated in the
2251 volume, also as a scaled integer defaulting to bytes. --format
2252 string is used in file based storage pools to specify the volume
2253 file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use
2254 extended for disk storage pools in order to create an extended
2255 partition (other values are validity checked but not preserved when
2256 libvirtd is restarted or the pool is refreshed). --backing-vol
2257 vol-name-or-key-or-path is the source backing volume to be used if
2258 taking a snapshot of an existing volume. --backing-vol-format
2259 string is the format of the snapshot backing volume; raw, bochs,
2260 qcow, qcow2, qed, vmdk, host_device. These are, however, meant for
2261 file based storage pools.
2262 vol-clone [--pool pool-or-uuid] vol-name-or-key-or-path name
2264 Clone an existing volume. Less powerful, but easier to type,
2265 version of vol-create-from. --pool pool-or-uuid is the name or
2266 UUID of the storage pool to create the volume in. vol-name-or-key-
2267 or-path is the name or key or path of the source volume. name is
2268 the name of the new volume.
2269 vol-delete [--pool pool-or-uuid] vol-name-or-key-or-path
2271 Delete a given volume. --pool pool-or-uuid is the name or UUID of
2272 the storage pool the volume is in. vol-name-or-key-or-path is the
2273 name or key or path of the volume to delete.
2274 vol-upload [--pool pool-or-uuid] [--offset bytes] [--length bytes] vol-
2276 name-or-key-or-path local-file
2277 Upload the contents of local-file to a storage volume. --pool
2278 pool-or-uuid is the name or UUID of the storage pool the volume is
2279 in. vol-name-or-key-or-path is the name or key or path of the
2280 volume where the file will be uploaded. --offset is the position
2281 in the storage volume at which to start writing the data. --length
2282 is an upper bound of the amount of data to be uploaded. An error
2283 will occurr if the local-file is greater than the specified length.
2284 vol-download [--pool pool-or-uuid] [--offset bytes] [--length bytes]
2286 vol-name-or-key-or-path local-file
2287 Download the contents of a storage volume to local-file. --pool
2288 pool-or-uuid is the name or UUID of the storage pool the volume is
2289 in. vol-name-or-key-or-path is the name or key or path of the
2290 volume to download. --offset is the position in the storage volume
2291 at which to start reading the data. --length is an upper bound of
2292 the amount of data to be downloaded.
2293 vol-wipe [--pool pool-or-uuid] [--algorithm algorithm] vol-name-or-key-
2295 or-path
2296 Wipe a volume, ensure data previously on the volume is not
2297 accessible to future reads. --pool pool-or-uuid is the name or UUID
2298 of the storage pool the volume is in. vol-name-or-key-or-path is
2299 the name or key or path of the volume to wipe. It is possible to
2300 choose different wiping algorithms instead of re-writing volume
2301 with zeroes. This can be done via --algorithm switch.
2302 Supported algorithms
2304 zero - 1-pass all zeroes
2305 nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for
2306 sanitizing removable and non-removable hard disks:
2307 random x2, 0x00, verify.
2308 dod - 4-pass DoD 5220.22-M section 8-306 procedure for
2309 sanitizing removeable and non-removeable rigid
2310 disks: random, 0x00, 0xff, verify.
2311 bsi - 9-pass method recommended by the German Center of
2312 Security in Information Technologies
2313 (http://www.bsi.bund.de): 0xff, 0xfe, 0xfd, 0xfb,
2314 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
2315 gutmann - The canonical 35-pass sequence described in
2316 Gutmann's paper.
2317 schneier - 7-pass method described by Bruce Schneier in
2318 "Applied Cryptography" (1996): 0x00, 0xff,
2319 random x5.
2320 pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7.
2321 pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
2322 random - 1-pass pattern: random.
2323 Note: The availability of algorithms may be limited by the version
2325 of the "scrub" binary installed on the host.
2326 vol-dumpxml [--pool pool-or-uuid] vol-name-or-key-or-path
2328 Output the volume information as an XML dump to stdout. --pool
2329 pool-or-uuid is the name or UUID of the storage pool the volume is
2330 in. vol-name-or-key-or-path is the name or key or path of the
2331 volume to output the XML of.
2332 vol-info [--pool pool-or-uuid] vol-name-or-key-or-path
2334 Returns basic information about the given storage volume. --pool
2335 pool-or-uuid is the name or UUID of the storage pool the volume is
2336 in. vol-name-or-key-or-path is the name or key or path of the
2337 volume to return information for.
2338 vol-list [--pool pool-or-uuid] [--details]
2340 Return the list of volumes in the given storage pool. --pool pool-
2341 or-uuid is the name or UUID of the storage pool. The --details
2342 option instructs virsh to additionally display volume type and
2343 capacity related information where available.
2344 vol-pool [--uuid] vol-key-or-path
2346 Return the pool name or UUID for a given volume. By default, the
2347 pool name is returned. If the --uuid option is given, the pool UUID
2348 is returned instead. vol-key-or-path is the key or path of the
2349 volume to return the pool information for.
2350 vol-path [--pool pool-or-uuid] vol-name-or-key
2352 Return the path for a given volume. --pool pool-or-uuid is the
2353 name or UUID of the storage pool the volume is in. vol-name-or-key
2354 is the name or key of the volume to return the path for.
2355 vol-name vol-key-or-path
2357 Return the name for a given volume. vol-key-or-path is the key or
2358 path of the volume to return the name for.
2359 vol-key [--pool pool-or-uuid] vol-name-or-path
2361 Return the volume key for a given volume. --pool pool-or-uuid is
2362 the name or UUID of the storage pool the volume is in. vol-name-or-
2363 path is the name or path of the volume to return the volume key
2364 for.
2365 vol-resize [--pool pool-or-uuid] vol-name-or-path pool-or-uuid capacity
2367 [--allocate] [--delta] [--shrink]
2368 Resize the capacity of the given volume, in bytes. --pool pool-or-
2369 uuid is the name or UUID of the storage pool the volume is in. vol-
2370 name-or-key-or-path is the name or key or path of the volume to
2371 resize. The new capacity might be sparse unless --allocate is
2372 specified. Normally, capacity is the new size, but if --delta is
2373 present, then it is added to the existing size. Attempts to shrink
2374 the volume will fail unless --shrink is present; capacity cannot be
2375 negative unless --shrink is provided, but a negative sign is not
2376 necessary. capacity is a scaled integer (see NOTES above), which
2377 defaults to bytes if there is no suffix. This command is only safe
2378 for storage volumes not in use by an active guest; see also
2379 blockresize for live resizing.
2380
2382 The following commands manipulate "secrets" (e.g. passwords,
2383 passphrases and encryption keys). Libvirt can store secrets
2384 independently from their use, and other objects (e.g. volumes or
2385 domains) can refer to the secrets for encryption or possibly other
2386 uses. Secrets are identified using an UUID. See
2387 <http://libvirt.org/formatsecret.html> for documentation of the XML
2388 format used to represent properties of secrets.
2389 secret-define file
2391 Create a secret with the properties specified in file, with no
2392 associated secret value. If file does not specify a UUID, choose
2393 one automatically. If file specifies an UUID of an existing
2394 secret, replace its properties by properties defined in file,
2395 without affecting the secret value.
2396 secret-dumpxml secret
2398 Output properties of secret (specified by its UUID) as an XML dump
2399 to stdout.
2400 secret-set-value secret base64
2402 Set the value associated with secret (specified by its UUID) to the
2403 value Base64-encoded value base64.
2404 secret-get-value secret
2406 Output the value associated with secret (specified by its UUID) to
2407 stdout, encoded using Base64.
2408 secret-undefine secret
2410 Delete a secret (specified by its UUID), including the associated
2411 value, if any.
2412 secret-list [--ephemeral] [--no-ephemeral] [--private] [--no-private]
2414 Returns the list of secrets. You may also want to filter the
2415 returned secrets by --ephemeral to list the ephemeral ones,
2416 --no-ephemeral to list the non-ephemeral ones, --private to list
2417 the private ones, and --no-private to list the non-private ones.
2418
2420 The following commands manipulate domain snapshots. Snapshots take the
2421 disk, memory, and device state of a domain at a point-of-time, and save
2422 it for future use. They have many uses, from saving a "clean" copy of
2423 an OS image to saving a domain's state before a potentially destructive
2424 operation. Snapshots are identified with a unique name. See
2425 <http://libvirt.org/formatsnapshot.html> for documentation of the XML
2426 format used to represent properties of snapshots.
2427 snapshot-create domain [xmlfile] {[--redefine [--current]] |
2429 [--no-metadata] [--halt] [--disk-only] [--reuse-external] [--quiesce]
2430 [--atomic] [--live]}
2431 Create a snapshot for domain domain with the properties specified
2432 in xmlfile. Normally, the only properties settable for a domain
2433 snapshot are the <name> and <description> elements, as well as
2434 <disks> if --disk-only is given; the rest of the fields are
2435 ignored, and automatically filled in by libvirt. If xmlfile is
2436 completely omitted, then libvirt will choose a value for all
2437 fields. The new snapshot will become current, as listed by
2438 snapshot-current.
2439 If --halt is specified, the domain will be left in an inactive
2441 state after the snapshot is created.
2442 If --disk-only is specified, the snapshot will only include disk
2444 state rather than the usual system checkpoint with vm state. Disk
2445 snapshots are faster than full system checkpoints, but reverting to
2446 a disk snapshot may require fsck or journal replays, since it is
2447 like the disk state at the point when the power cord is abruptly
2448 pulled; and mixing --halt and --disk-only loses any data that was
2449 not flushed to disk at the time.
2450 If --redefine is specified, then all XML elements produced by
2452 snapshot-dumpxml are valid; this can be used to migrate snapshot
2453 hierarchy from one machine to another, to recreate hierarchy for
2454 the case of a transient domain that goes away and is later
2455 recreated with the same name and UUID, or to make slight
2456 alterations in the snapshot metadata (such as host-specific aspects
2457 of the domain XML embedded in the snapshot). When this flag is
2458 supplied, the xmlfile argument is mandatory, and the domain's
2459 current snapshot will not be altered unless the --current flag is
2460 also given.
2461 If --no-metadata is specified, then the snapshot data is created,
2463 but any metadata is immediately discarded (that is, libvirt does
2464 not treat the snapshot as current, and cannot revert to the
2465 snapshot unless --redefine is later used to teach libvirt about the
2466 metadata again).
2467 If --reuse-external is specified, and the snapshot XML requests an
2469 external snapshot with a destination of an existing file, then the
2470 destination must exist, and is reused; otherwise, a snapshot is
2471 refused to avoid losing contents of the existing files.
2472 If --quiesce is specified, libvirt will try to use guest agent to
2474 freeze and unfreeze domain's mounted file systems. However, if
2475 domain has no guest agent, snapshot creation will fail. Currently,
2476 this requires --disk-only to be passed as well.
2477 If --atomic is specified, libvirt will guarantee that the snapshot
2479 either succeeds, or fails with no changes; not all hypervisors
2480 support this. If this flag is not specified, then some hypervisors
2481 may fail after partially performing the action, and dumpxml must be
2482 used to see whether any partial changes occurred.
2483 If --live is specified, libvirt takes the snapshot while the guest
2485 is running. This increases the size of the memory image of the
2486 external checkpoint. This is currently supported only for external
2487 checkpoints.
2488 Existence of snapshot metadata will prevent attempts to undefine a
2490 persistent domain. However, for transient domains, snapshot
2491 metadata is silently lost when the domain quits running (whether by
2492 command such as destroy or by internal guest action).
2493 snapshot-create-as domain {[--print-xml] | [--no-metadata] [--halt]
2495 [--reuse-external]} [name] [description] [--disk-only [--quiesce]]
2496 [--atomic] [[--live] [--memspec memspec]] [--diskspec] diskspec]...
2497 Create a snapshot for domain domain with the given <name> and
2498 <description>; if either value is omitted, libvirt will choose a
2499 value. If --print-xml is specified, then XML appropriate for
2500 snapshot-create is output, rather than actually creating a
2501 snapshot. Otherwise, if --halt is specified, the domain will be
2502 left in an inactive state after the snapshot is created, and if
2503 --disk-only is specified, the snapshot will not include vm state.
2504 The --memspec option can be used to control whether a checkpoint is
2506 internal or external. The --memspec flag is mandatory, followed by
2507 a memspec of the form [file=]name[,snapshot=type], where type can
2508 be none, internal, or external. To include a literal comma in
2509 file=name, escape it with a second comma. --memspec cannot be used
2510 together with --disk-only.
2511 The --diskspec option can be used to control how --disk-only and
2513 external checkpoints create external files. This option can occur
2514 multiple times, according to the number of <disk> elements in the
2515 domain xml. Each <diskspec> is in the form
2516 disk[,snapshot=type][,driver=type][,file=name]. To include a
2517 literal comma in disk or in file=name, escape it with a second
2518 comma. A literal --diskspec must preceed each diskspec unless all
2519 three of domain, name, and description are also present. For
2520 example, a diskspec of "vda,snapshot=external,file=/path/to,,new"
2521 results in the following XML:
2522 <disk name='vda' snapshot='external'>
2523 <source file='/path/to,new'/>
2524 </disk>
2525 If --reuse-external is specified, and the domain XML or diskspec
2527 option requests an external snapshot with a destination of an
2528 existing file, then the destination must exist, and is reused;
2529 otherwise, a snapshot is refused to avoid losing contents of the
2530 existing files.
2531 If --quiesce is specified, libvirt will try to use guest agent to
2533 freeze and unfreeze domain's mounted file systems. However, if
2534 domain has no guest agent, snapshot creation will fail. Currently,
2535 this requires --disk-only to be passed as well.
2536 If --no-metadata is specified, then the snapshot data is created,
2538 but any metadata is immediately discarded (that is, libvirt does
2539 not treat the snapshot as current, and cannot revert to the
2540 snapshot unless snapshot-create is later used to teach libvirt
2541 about the metadata again). This flag is incompatible with
2542 --print-xml.
2543 If --atomic is specified, libvirt will guarantee that the snapshot
2545 either succeeds, or fails with no changes; not all hypervisors
2546 support this. If this flag is not specified, then some hypervisors
2547 may fail after partially performing the action, and dumpxml must be
2548 used to see whether any partial changes occurred.
2549 If --live is specified, libvirt takes the snapshot while the guest
2551 is running. This increases the size of the memory image of the
2552 external checkpoint. This is currently supported only for external
2553 checkpoints.
2554 snapshot-current domain {[--name] | [--security-info] | [snapshotname]}
2556 Without snapshotname, this will output the snapshot XML for the
2557 domain's current snapshot (if any). If --name is specified, just
2558 the current snapshot name instead of the full xml. Otherwise,
2559 using --security-info will also include security sensitive
2560 information in the XML.
2561 With snapshotname, this is a request to make the existing named
2563 snapshot become the current snapshot, without reverting the domain.
2564 snapshot-edit domain [snapshotname] [--current] {[--rename] |
2566 [--clone]}
2567 Edit the XML configuration file for snapshotname of a domain. If
2568 both snapshotname and --current are specified, also force the
2569 edited snapshot to become the current snapshot. If snapshotname is
2570 omitted, then --current must be supplied, to edit the current
2571 snapshot.
2572 This is equivalent to:
2574 virsh snapshot-dumpxml dom name > snapshot.xml
2576 vi snapshot.xml (or make changes with your other text editor)
2577 virsh snapshot-create dom snapshot.xml --redefine [--current]
2578 except that it does some error checking.
2580 The editor used can be supplied by the $VISUAL or $EDITOR
2582 environment variables, and defaults to "vi".
2583 If --rename is specified, then the edits can change the snapshot
2585 name. If --clone is specified, then changing the snapshot name
2586 will create a clone of the snapshot metadata. If neither is
2587 specified, then the edits must not change the snapshot name. Note
2588 that changing a snapshot name must be done with care, since the
2589 contents of some snapshots, such as internal snapshots within a
2590 single qcow2 file, are accessible only from the original name.
2591 snapshot-info domain {snapshot | --current}
2593 Output basic information about a named <snapshot>, or the current
2594 snapshot with --current.
2595 snapshot-list domain [{--parent | --roots | --tree}] [{[--from]
2597 snapshot | --current} [--descendants]] [--metadata] [--no-metadata]
2598 [--leaves] [--no-leaves] [--inactive] [--active] [--disk-only]
2599 [--internal] [--external]
2600 List all of the available snapshots for the given domain,
2601 defaulting to show columns for the snapshot name, creation time,
2602 and domain state.
2603 If --parent is specified, add a column to the output table giving
2605 the name of the parent of each snapshot. If --roots is specified,
2606 the list will be filtered to just snapshots that have no parents.
2607 If --tree is specified, the output will be in a tree format,
2608 listing just snapshot names. These three options are mutually
2609 exclusive.
2610 If --from is provided, filter the list to snapshots which are
2612 children of the given snapshot; or if --current is provided, start
2613 at the current snapshot. When used in isolation or with --parent,
2614 the list is limited to direct children unless --descendants is also
2615 present. When used with --tree, the use of --descendants is
2616 implied. This option is not compatible with --roots. Note that
2617 the starting point of --from or --current is not included in the
2618 list unless the --tree option is also present.
2619 If --leaves is specified, the list will be filtered to just
2621 snapshots that have no children. Likewise, if --no-leaves is
2622 specified, the list will be filtered to just snapshots with
2623 children. (Note that omitting both options does no filtering,
2624 while providing both options will either produce the same list or
2625 error out depending on whether the server recognizes the flags).
2626 Filtering options are not compatible with --tree.
2627 If --metadata is specified, the list will be filtered to just
2629 snapshots that involve libvirt metadata, and thus would prevent
2630 undefine of a persistent domain, or be lost on destroy of a
2631 transient domain. Likewise, if --no-metadata is specified, the
2632 list will be filtered to just snapshots that exist without the need
2633 for libvirt metadata.
2634 If --inactive is specified, the list will be filtered to snapshots
2636 that were taken when the domain was shut off. If --active is
2637 specified, the list will be filtered to snapshots that were taken
2638 when the domain was running, and where the snapshot includes the
2639 memory state to revert to that running state. If --disk-only is
2640 specified, the list will be filtered to snapshots that were taken
2641 when the domain was running, but where the snapshot includes only
2642 disk state.
2643 If --internal is specified, the list will be filtered to snapshots
2645 that use internal storage of existing disk images. If --external
2646 is specified, the list will be filtered to snapshots that use
2647 external files for disk images or memory state.
2648 snapshot-dumpxml domain snapshot [--security-info]
2650 Output the snapshot XML for the domain's snapshot named snapshot.
2651 Using --security-info will also include security sensitive
2652 information. Use snapshot-current to easily access the XML of the
2653 current snapshot.
2654 snapshot-parent domain {snapshot | --current}
2656 Output the name of the parent snapshot, if any, for the given
2657 snapshot, or for the current snapshot with --current.
2658 snapshot-revert domain {snapshot | --current} [{--running | --paused}]
2660 [--force]
2661 Revert the given domain to the snapshot specified by snapshot, or
2662 to the current snapshot with --current. Be aware that this is a
2663 destructive action; any changes in the domain since the last
2664 snapshot was taken will be lost. Also note that the state of the
2665 domain after snapshot-revert is complete will be the state of the
2666 domain at the time the original snapshot was taken.
2667 Normally, reverting to a snapshot leaves the domain in the state it
2669 was at the time the snapshot was created, except that a disk
2670 snapshot with no vm state leaves the domain in an inactive state.
2671 Passing either the --running or --paused flag will perform
2672 additional state changes (such as booting an inactive domain, or
2673 pausing a running domain). Since transient domains cannot be
2674 inactive, it is required to use one of these flags when reverting
2675 to a disk snapshot of a transient domain.
2676 There are two cases where a snapshot revert involves extra risk,
2678 which requires the use of --force to proceed. One is the case of a
2679 snapshot that lacks full domain information for reverting
2680 configuration (such as snapshots created prior to libvirt 0.9.5);
2681 since libvirt cannot prove that the current configuration matches
2682 what was in use at the time of the snapshot, supplying --force
2683 assures libvirt that the snapshot is compatible with the current
2684 configuration (and if it is not, the domain will likely fail to
2685 run). The other is the case of reverting from a running domain to
2686 an active state where a new hypervisor has to be created rather
2687 than reusing the existing hypervisor, because it implies drawbacks
2688 such as breaking any existing VNC or Spice connections; this
2689 condition happens with an active snapshot that uses a provably
2690 incompatible configuration, as well as with an inactive snapshot
2691 that is combined with the --start or --pause flag.
2692 snapshot-delete domain {snapshot | --current} [--metadata] [{--children
2694 | --children-only}]
2695 Delete the snapshot for the domain named snapshot, or the current
2696 snapshot with --current. If this snapshot has child snapshots,
2697 changes from this snapshot will be merged into the children. If
2698 --children is passed, then delete this snapshot and any children of
2699 this snapshot. If --children-only is passed, then delete any
2700 children of this snapshot, but leave this snapshot intact. These
2701 two flags are mutually exclusive.
2702 If --metadata is specified, then only delete the snapshot metadata
2704 maintained by libvirt, while leaving the snapshot contents intact
2705 for access by external tools; otherwise deleting a snapshot also
2706 removes the data contents from that point in time.
2707
2709 The following commands manipulate network filters. Network filters
2710 allow filtering of the network traffic coming from and going to virtual
2711 machines. Individual network traffic filters are written in XML and
2712 may contain references to other network filters, describe traffic
2713 filtering rules, or contain both. Network filters are referenced by
2714 virtual machines from within their interface description. A network
2715 filter may be referenced by multiple virtual machines' interfaces.
2716 nwfilter-define xmlfile
2718 Make a new network filter known to libvirt. If a network filter
2719 with the same name already exists, it will be replaced with the new
2720 XML. Any running virtual machine referencing this network filter
2721 will have its network traffic rules adapted. If for any reason the
2722 network traffic filtering rules cannot be instantiated by any of
2723 the running virtual machines, then the new XML will be rejected.
2724 nwfilter-undefine nwfilter-name
2726 Delete a network filter. The deletion will fail if any running
2727 virtual machine is currently using this network filter.
2728 nwfilter-list
2730 List all of the available network filters.
2731 nwfilter-dumpxml nwfilter-name
2733 Output the network filter XML.
2734 nwfilter-edit nwfilter-name
2736 Edit the XML of a network filter.
2737 This is equivalent to:
2739 virsh nwfilter-dumpxml myfilter > myfilter.xml
2741 vi myfilter.xml (or make changes with your other text editor)
2742 virsh nwfilter-define myfilter.xml
2743 except that it does some error checking. The new network filter
2745 may be rejected due to the same reason as mentioned in nwfilter-
2746 define.
2747 The editor used can be supplied by the $VISUAL or $EDITOR
2749 environment variables, and defaults to "vi".
2750
2752 NOTE: Use of the following commands is strongly discouraged. They can
2753 cause libvirt to become confused and do the wrong thing on subsequent
2754 operations. Once you have used this command, please do not report
2755 problems to the libvirt developers; the reports will be ignored.
2756 qemu-attach pid
2758 Attach an externally launched QEMU process to the libvirt QEMU
2759 driver. The QEMU process must have been created with a monitor
2760 connection using the UNIX driver. Ideally the process will also
2761 have had the '-name' argument specified.
2762 $ qemu-kvm -cdrom ~/demo.iso \
2764 -monitor unix:/tmp/demo,server,nowait \
2765 -name foo \
2766 -uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea &
2767 $ QEMUPID=$!
2768 $ virsh qemu-attach $QEMUPID
2769 Not all functions of libvirt are expected to work reliably after
2771 attaching to an externally launched QEMU process. There may be
2772 issues with the guest ABI changing upon migration, and hotunplug
2773 may not work.
2774 qemu-monitor-command domain [--hmp] command...
2776 Send an arbitrary monitor command command to domain domain through
2777 the qemu monitor. The results of the command will be printed on
2778 stdout. If --hmp is passed, the command is considered to be a
2779 human monitor command and libvirt will automatically convert it
2780 into QMP if needed. In that case the result will also be converted
2781 back from QMP. If more than one argument is provided for command,
2782 they are concatenated with a space in between before passing the
2783 single command to the monitor.
2784 qemu-agent-command domain [--timeout seconds | --async | --block]
2786 command...
2787 Send an arbitrary guest agent command command to domain domain
2788 through qemu agent. --timeout, --async and --block options are
2789 exclusive. --timeout requires timeout seconds seconds and it must
2790 be positive. When --aysnc is given, the command waits for timeout
2791 whether success or failed. And when --block is given, the command
2792 waits forever with blocking timeout.
2793
2795 The following environment variables can be set to alter the behaviour
2796 of "virsh"
2797 VIRSH_DEBUG=<0 to 4>
2799 Turn on verbose debugging of virsh commands. Valid levels are
2800 * VIRSH_DEBUG=0
2802 DEBUG - Messages at ALL levels get logged
2803 * VIRSH_DEBUG=1
2805 INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
2806 * VIRSH_DEBUG=2
2808 NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
2809 * VIRSH_DEBUG=3
2811 WARNING - Logs messages at levels WARNING and ERROR
2812 * VIRSH_DEBUG=4
2814 ERROR - Messages at only ERROR level gets logged.
2815 VIRSH_LOG_FILE="LOGFILE"
2817 The file to log virsh debug messages.
2818 VIRSH_DEFAULT_CONNECT_URI
2820 The hypervisor to connect to by default. Set this to a URI, in the
2821 same format as accepted by the connect option. This environment
2822 variable is deprecated in favour of the global LIBVIRT_DEFAULT_URI
2823 variable which serves the same purpose.
2824 LIBVIRT_DEFAULT_URI
2826 The hypervisor to connect to by default. Set this to a URI, in the
2827 same format as accepted by the connect option. This overrides the
2828 default URI set in any client config file and prevents libvirt from
2829 probing for drivers.
2830 VISUAL
2832 The editor to use by the edit and related options.
2833 EDITOR
2835 The editor to use by the edit and related options, if "VISUAL" is
2836 not set.
2837 LIBVIRT_DEBUG=LEVEL
2839 Turn on verbose debugging of all libvirt API calls. Valid levels
2840 are
2841 · LIBVIRT_DEBUG=1
2843 Messages at level DEBUG or above
2845 · LIBVIRT_DEBUG=2
2847 Messages at level INFO or above
2849 · LIBVIRT_DEBUG=3
2851 Messages at level WARNING or above
2853 · LIBVIRT_DEBUG=4
2855 Messages at level ERROR or above
2857 For further information about debugging options consult
2859 "http://libvirt.org/logging.html"
2860
2862 Report any bugs discovered to the libvirt community via the mailing
2863 list "http://libvirt.org/contact.html" or bug tracker
2864 "http://libvirt.org/bugs.html". Alternatively report bugs to your
2865 software distributor / vendor.
2866
2868 Please refer to the AUTHORS file distributed with libvirt.
2869 Based on the xm man page by:
2871 Sean Dague <sean at dague dot net>
2872 Daniel Stekloff <dsteklof at us dot ibm dot com>
2873
2875 Copyright (C) 2005, 2007-2010 Red Hat, Inc., and the authors listed in
2876 the libvirt AUTHORS file.
2877
2879 virsh is distributed under the terms of the GNU LGPL v2+. This is free
2880 software; see the source for copying conditions. There is NO warranty;
2881 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
2882
2884 virt-install(1), virt-xml-validate(1), virt-top(1), virt-df(1),
2885 <http://www.libvirt.org/>
2886libvirt-0.10.2 2019-06-20 VIRSH(1)