mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-10-30 09:53:10 +00:00
e88872e9a9
Similar to 'undefine --managed-save' (commit 83e849c1), we must
assume that the old API is unsafe; however, we cannot emulate
metadata-only deletion on older servers. Additionally, we have
the wrinkle that while virDomainUndefineFlags and managed save
cleanup were introduced in 0.9.4, it wasn't until 0.9.5 that
snapshots block undefine of a domain. Do the best we can given
the server we are talking to.
* tools/virsh.c (cmdUndefine): Add --snapshots-metadata flag.
* tools/virsh.pod (undefine, destroy, shutdown): Document effect
of snapshots.
2033 lines
73 KiB
Plaintext
2033 lines
73 KiB
Plaintext
=head1 NAME
|
|
|
|
virsh - management user interface
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<virsh> [I<OPTION>]... [I<COMMAND_STRING>]
|
|
|
|
B<virsh> [I<OPTION>]... I<COMMAND> [I<ARG>]...
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<virsh> program is the main interface for managing virsh guest
|
|
domains. The program can be used to create, pause, and shutdown
|
|
domains. It can also be used to list current domains. Libvirt is a C
|
|
toolkit to interact with the virtualization capabilities of recent
|
|
versions of Linux (and other OSes). It is free software available
|
|
under the GNU Lesser General Public License. Virtualization of the
|
|
Linux Operating System means the ability to run multiple instances of
|
|
Operating Systems concurrently on a single hardware system where the
|
|
basic resources are driven by a Linux instance. The library aims at
|
|
providing a long term stable C API. It currently supports Xen, QEmu,
|
|
KVM, LXC, OpenVZ, VirtualBox and VMware ESX.
|
|
|
|
The basic structure of most virsh usage is:
|
|
|
|
virsh [OPTION]... <command> <domain-id> [ARG]...
|
|
|
|
Where I<command> is one of the commands listed below, I<domain-id>
|
|
is the numeric domain id, or the domain name (which will be internally
|
|
translated to domain id), and I<ARGS> are command specific
|
|
options. There are a few exceptions to this rule in the cases where
|
|
the command in question acts on all domains, the entire machine,
|
|
or directly on the xen hypervisor. Those exceptions will be clear for
|
|
each of those commands.
|
|
|
|
The B<virsh> program can be used either to run one I<COMMAND> by giving the
|
|
command and its arguments on the shell command line, or a I<COMMAND_STRING>
|
|
which is a single shell argument consisting of multiple I<COMMAND> actions
|
|
and their arguments joined with whitespace, and separated by semicolons
|
|
between commands. Within I<COMMAND_STRING>, virsh understands the
|
|
same single, double, and backslash escapes as the shell, although you must
|
|
add another layer of shell escaping in creating the single shell argument.
|
|
If no command is given in the command line, B<virsh> will then start a minimal
|
|
interpreter waiting for your commands, and the B<quit> command will then exit
|
|
the program.
|
|
|
|
The B<virsh> program understands the following I<OPTIONS>.
|
|
|
|
=over 4
|
|
|
|
=item B<-h>, B<--help>
|
|
|
|
Ignore all other arguments, and behave as if the B<help> command were
|
|
given instead.
|
|
|
|
=item B<-v>, B<--version[=short]>
|
|
|
|
Ignore all other arguments, and prints the version of the libvirt library
|
|
virsh is coming from
|
|
|
|
=item B<-V>, B<--version=long>
|
|
|
|
Ignore all other arguments, and prints the version of the libvirt library
|
|
virsh is coming from and which options and driver are compiled in.
|
|
|
|
=item B<-c>, B<--connect> I<URI>
|
|
|
|
Connect to the specified I<URI>, as if by the B<connect> command,
|
|
instead of the default connection.
|
|
|
|
=item B<-d>, B<--debug> I<LEVEL>
|
|
|
|
Enable debug messages at integer I<LEVEL> and above. I<LEVEL> can
|
|
range from 0 to 4 (default). See the documentation of B<VIRSH_DEBUG>
|
|
environment variable for the description of each I<LEVEL>.
|
|
|
|
=item B<-l>, B<--log> I<FILE>
|
|
|
|
Output logging details to I<FILE>.
|
|
|
|
=item B<-q>, B<--quiet>
|
|
|
|
Avoid extra informational messages.
|
|
|
|
=item B<-r>, B<--readonly>
|
|
|
|
Make the initial connection read-only, as if by the I<--readonly>
|
|
option of the B<connect> command.
|
|
|
|
=item B<-t>, B<--timing>
|
|
|
|
Output elapsed time information for each command.
|
|
|
|
=back
|
|
|
|
=head1 NOTES
|
|
|
|
Most B<virsh> operations rely upon the libvirt library being able to
|
|
connect to an already running libvirtd service. This can usually be
|
|
done using the command B<service libvirtd start>.
|
|
|
|
Most B<virsh> commands require root privileges to run due to the
|
|
communications channels used to talk to the hypervisor. Running as
|
|
non root will return an error.
|
|
|
|
Most B<virsh> commands act synchronously, except maybe shutdown,
|
|
setvcpus and setmem. In those cases the fact that the B<virsh>
|
|
program returned, may not mean the action is complete and you
|
|
must poll periodically to detect that the guest completed the
|
|
operation.
|
|
|
|
=head1 GENERIC COMMANDS
|
|
|
|
The following commands are generic i.e. not specific to a domain.
|
|
|
|
=over 4
|
|
|
|
=item B<help> [I<command-or-group>]
|
|
|
|
This lists each of the virsh commands. When used without options, all
|
|
commands are listed, one per line, grouped into related categories,
|
|
displaying the keyword for each group.
|
|
|
|
To display only commands for a specific group, give the keyword for that
|
|
group as an option. For example:
|
|
|
|
virsh # help host
|
|
|
|
Host and Hypervisor (help keyword 'host'):
|
|
capabilities capabilities
|
|
connect (re)connect to hypervisor
|
|
freecell NUMA free memory
|
|
hostname print the hypervisor hostname
|
|
qemu-attach Attach to existing QEMU process
|
|
qemu-monitor-command QEMU Monitor Command
|
|
sysinfo print the hypervisor sysinfo
|
|
uri print the hypervisor canonical URI
|
|
|
|
To display detailed information for a specific command, give its name as the
|
|
option instead. For example:
|
|
|
|
virsh # help list
|
|
NAME
|
|
list - list domains
|
|
|
|
SYNOPSIS
|
|
list [--inactive] [--all]
|
|
|
|
DESCRIPTION
|
|
Returns list of domains.
|
|
|
|
OPTIONS
|
|
--inactive list inactive domains
|
|
--all list inactive & active domains
|
|
|
|
=item B<quit>, B<exit>
|
|
|
|
quit this interactive terminal
|
|
|
|
=item B<version>
|
|
|
|
Will print out the major version info about what this built from.
|
|
|
|
=over 4
|
|
|
|
B<Example>
|
|
|
|
B<virsh> version
|
|
|
|
Compiled against library: libvir 0.0.6
|
|
|
|
Using library: libvir 0.0.6
|
|
|
|
Using API: Xen 3.0.0
|
|
|
|
Running hypervisor: Xen 3.0.0
|
|
|
|
=back
|
|
|
|
=item B<cd> [I<directory>]
|
|
|
|
Will change current directory to I<directory>. The default directory
|
|
for the B<cd> command is the home directory or, if there is no I<HOME>
|
|
variable in the environment, the root directory.
|
|
|
|
This command is only available in interactive mode.
|
|
|
|
=item B<pwd>
|
|
|
|
Will print the current directory.
|
|
|
|
=item B<connect> I<URI> [I<--readonly>]
|
|
|
|
(Re)-Connect to the hypervisor. When the shell is first started, this
|
|
is automatically run with the I<URI> parameter requested by the C<-c>
|
|
option on the command line. The I<URI> parameter specifies how to
|
|
connect to the hypervisor. The documentation page at
|
|
L<http://libvirt.org/uri.html> list the values supported, but the most
|
|
common are:
|
|
|
|
=over 4
|
|
|
|
=item xen:///
|
|
|
|
this is used to connect to the local Xen hypervisor, this is the default
|
|
|
|
=item qemu:///system
|
|
|
|
connect locally as root to the daemon supervising QEmu and KVM domains
|
|
|
|
=item qemu:///session
|
|
|
|
connect locally as a normal user to his own set of QEmu and KVM domains
|
|
|
|
=item lxc:///
|
|
|
|
connect to a local linux container
|
|
|
|
=back
|
|
|
|
For remote access see the documentation page on how to make URIs.
|
|
The I<--readonly> option allows for read-only connection
|
|
|
|
=item B<uri>
|
|
|
|
Prints the hypervisor canonical URI, can be useful in shell mode.
|
|
|
|
=item B<hostname>
|
|
|
|
Print the hypervisor hostname.
|
|
|
|
=item B<sysinfo>
|
|
|
|
Print the XML representation of the hypervisor sysinfo, if available.
|
|
|
|
=item B<nodeinfo>
|
|
|
|
Returns basic information about the node, like number and type of CPU,
|
|
and size of the physical memory. The output corresponds to virNodeInfo
|
|
structure. Specifically, the "CPU socket(s)" field means number of CPU
|
|
sockets per NUMA cell.
|
|
|
|
=item B<nodecpustats> [I<cpu>] [I<--percent>]
|
|
|
|
Returns cpu stats of the node.
|
|
If I<cpu> is specified, this will prints specified cpu statistics only.
|
|
If I<--percent> is specified, this will prints percentage of each kind of cpu
|
|
statistics during 1 second.
|
|
|
|
=item B<nodememstats> [I<cell>]
|
|
|
|
Returns memory stats of the node.
|
|
If I<cell> is specified, this will prints specified cell statistics only.
|
|
|
|
=item B<capabilities>
|
|
|
|
Print an XML document describing the capabilities of the hypervisor
|
|
we are currently connected to. This includes a section on the host
|
|
capabilities in terms of CPU and features, and a set of description
|
|
for each kind of guest which can be virtualized. For a more complete
|
|
description see:
|
|
L<http://libvirt.org/formatcaps.html>
|
|
The XML also show the NUMA topology information if available.
|
|
|
|
=item B<inject-nmi> I<domain-id>
|
|
|
|
Inject NMI to the guest.
|
|
|
|
=item B<list> [I<--inactive> | I<--all>] [I<--managed-save>]
|
|
|
|
Prints information about existing domains. If no options are
|
|
specified it prints out information about running domains.
|
|
|
|
An example format for the list is as follows:
|
|
|
|
B<virsh> list
|
|
Id Name State
|
|
|
|
----------------------------------
|
|
|
|
0 Domain-0 running
|
|
2 fedora paused
|
|
|
|
|
|
Name is the name of the domain. ID the domain numeric id.
|
|
State is the run state (see below).
|
|
|
|
B<STATES>
|
|
|
|
The State field lists 7 states for a domain, and which ones the
|
|
current domain is in.
|
|
|
|
=over 4
|
|
|
|
=item B<running>
|
|
|
|
The domain is currently running on a CPU
|
|
|
|
=item B<idle>
|
|
|
|
The domain is idle, and not running or runnable. This can be caused
|
|
because the domain is waiting on IO (a traditional wait state) or has
|
|
gone to sleep because there was nothing else for it to do.
|
|
|
|
=item B<paused>
|
|
|
|
The domain has been paused, usually occurring through the administrator
|
|
running B<virsh suspend>. When in a paused state the domain will still
|
|
consume allocated resources like memory, but will not be eligible for
|
|
scheduling by the hypervisor.
|
|
|
|
=item B<send-key> I<domain-id> [I<--codeset> B<codeset>]
|
|
[I<--holdtime> B<holdtime>] I<keycode>...
|
|
|
|
Parse the I<keycode> sequence as keystrokes to send to I<domain-id>.
|
|
Each I<keycode> can either be a numeric value or a symbolic name from
|
|
the corresponding codeset. If I<--holdtime> is given, each keystroke
|
|
will be held for that many milliseconds. The default codeset is
|
|
B<linux>, but use of the I<--codeset> option allows other codesets to
|
|
be chosen.
|
|
|
|
=over 4
|
|
|
|
=item B<linux>
|
|
|
|
The numeric values are those defined by the Linux generic input
|
|
event subsystem. The symbolic names match the corresponding
|
|
Linux key constant macro names.
|
|
|
|
=item B<xt>
|
|
|
|
The numeric values are those defined by the original XT keyboard
|
|
controller. No symbolic names are provided
|
|
|
|
=item B<atset1>
|
|
|
|
The numeric values are those defined by the AT keyboard controller,
|
|
set 1 (aka XT compatible set). Extended keycoes from B<atset1>
|
|
may differ from extended keycodes in the B<xt> codeset. No symbolic
|
|
names are provided
|
|
|
|
=item B<atset2>
|
|
|
|
The numeric values are those defined by the AT keyboard controller,
|
|
set 2. No symbolic names are provided
|
|
|
|
=item B<atset3>
|
|
|
|
The numeric values are those defined by the AT keyboard controller,
|
|
set 3 (aka PS/2 compatible set). No symbolic names are provided
|
|
|
|
=item B<os_x>
|
|
|
|
The numeric values are those defined by the OS-X keyboard input
|
|
subsystem. The symbolic names match the corresponding OS-X key
|
|
constant macro names
|
|
|
|
=item B<xtkbd>
|
|
|
|
The numeric values are those defined by the Linux KBD device.
|
|
These are a variant on the original XT codeset, but often with
|
|
different encoding for extended keycodes. No symbolic names are
|
|
provided.
|
|
|
|
=item B<win32>
|
|
|
|
The numeric values are those defined by the Win32 keyboard input
|
|
subsystem. The symbolic names match the corresponding Win32 key
|
|
constant macro names
|
|
|
|
=item B<usb>
|
|
|
|
The numeric values are those defined by the USB HID specification
|
|
for keyboard input. No symbolic names are provided
|
|
|
|
=item B<rfb>
|
|
|
|
The numeric values are those defined by the RFB extension for sending
|
|
raw keycodes. These are a variant on the XT codeset, but extended
|
|
keycodes have the low bit of the second byte set, instead of the high
|
|
bit of the first byte. No symbolic names are provided.
|
|
|
|
=back
|
|
|
|
B<Examples>
|
|
# send three strokes 'k', 'e', 'y', using xt codeset
|
|
virsh send-key dom --codeset xt 37 18 21
|
|
# send one stroke 'right-ctrl+C'
|
|
virsh send-key dom KEY_RIGHTCTRL KEY_C
|
|
# send a tab, held for 1 second
|
|
virsh send-key --holdtime 1000 0xf
|
|
|
|
=item B<shutdown>
|
|
|
|
The domain is in the process of shutting down, i.e. the guest operating system
|
|
has been notified and should be in the process of stopping its operations
|
|
gracefully.
|
|
|
|
=item B<shut off>
|
|
|
|
The domain is not running. Usually this indicates the domain has been
|
|
shut down completely, or has not been started.
|
|
|
|
=item B<crashed>
|
|
|
|
The domain has crashed, which is always a violent ending. Usually
|
|
this state can only occur if the domain has been configured not to
|
|
restart on crash.
|
|
|
|
=item B<dying>
|
|
|
|
The domain is in process of dying, but hasn't completely shutdown or
|
|
crashed.
|
|
|
|
=back
|
|
|
|
If I<--managed-save> is specified, then domains that have managed save
|
|
state (only possible if they are in the B<shut off> state) will
|
|
instead show as B<saved> in the listing.
|
|
|
|
=item B<freecell> [B<cellno> | I<--all>]
|
|
|
|
Prints the available amount of memory on the machine or within a
|
|
NUMA cell if I<cellno> is provided. If I<--all> is provided instead
|
|
of I<--cellno>, then show the information on all NUMA cells.
|
|
|
|
=item B<cpu-baseline> I<FILE>
|
|
|
|
Compute baseline CPU which will be supported by all host CPUs given in <file>.
|
|
The list of host CPUs is built by extracting all <cpu> elements from the
|
|
<file>. Thus, the <file> can contain either a set of <cpu> elements separated
|
|
by new lines or even a set of complete <capabilities> elements printed by
|
|
B<capabilities> command.
|
|
|
|
=item B<cpu-compare> I<FILE>
|
|
|
|
Compare CPU definition from XML <file> with host CPU. The XML <file> may
|
|
contain either host or guest CPU definition. The host CPU definition is the
|
|
<cpu> element and its contents as printed by B<capabilities> command. The
|
|
guest CPU definition is the <cpu> element and its contents from domain XML
|
|
definition. For more information on guest CPU definition see:
|
|
L<http://libvirt.org/formatdomain.html#elementsCPU>
|
|
|
|
=back
|
|
|
|
=head1 DOMAIN COMMANDS
|
|
|
|
The following commands manipulate domains directly, as stated
|
|
previously most commands take domain-id as the first parameter. The
|
|
I<domain-id> can be specified as a short integer, a name or a full UUID.
|
|
|
|
=over 4
|
|
|
|
=item B<autostart> [I<--disable>] I<domain-id>
|
|
|
|
Configure a domain to be automatically started at boot.
|
|
|
|
The option I<--disable> disables autostarting.
|
|
|
|
=item B<console> I<domain-id> [I<devname>]
|
|
|
|
Connect the virtual serial console for the guest. The optional
|
|
I<devname> parameter refers to the device alias of an alternate
|
|
console, serial or parallel device configured for the guest.
|
|
If omitted, the primary console will be opened.
|
|
|
|
=item B<create> I<FILE> [I<--console>] [I<--paused>] [I<--autodestroy>]
|
|
|
|
Create a domain from an XML <file>. An easy way to create the XML
|
|
<file> is to use the B<dumpxml> command to obtain the definition of a
|
|
pre-existing guest. The domain will be paused if the I<--paused> option
|
|
is used and supported by the driver; otherwise it will be running.
|
|
If I<--console> is requested, attach to the console after creation.
|
|
If I<--autodestroy> is requested, then the guest will be automatically
|
|
destroyed when virsh closes its connection to libvirt, or otherwise
|
|
exits.
|
|
|
|
B<Example>
|
|
|
|
virsh dumpxml <domain-id> > domain.xml
|
|
vi domain.xml (or make changes with your other text editor)
|
|
virsh create < domain.xml
|
|
|
|
=item B<define> I<FILE>
|
|
|
|
Define a domain from an XML <file>. The domain definition is registered
|
|
but not started.
|
|
|
|
=item B<destroy> I<domain-id>
|
|
|
|
Immediately terminate the domain domain-id. This doesn't give the domain
|
|
OS any chance to react, and it's the equivalent of ripping the power
|
|
cord out on a physical machine. In most cases you will want to use
|
|
the B<shutdown> command instead. However, this does not delete any
|
|
storage volumes used by the guest, and if the domain is persistent, it
|
|
can be restarted later.
|
|
|
|
If I<domain-id> is transient, then the metadata of any snapshots will
|
|
be lost once the guest stops running, but the snapshot contents still
|
|
exist, and a new domain with the same name and UUID can restore the
|
|
snapshot metadata with B<snapshot-create>.
|
|
|
|
=item B<domblkstat> I<domain> I<block-device>
|
|
|
|
Get device block stats for a running domain.
|
|
|
|
=item B<domifstat> I<domain> I<interface-device>
|
|
|
|
Get network interface stats for a running domain.
|
|
|
|
=item B<dommemstat> I<domain>
|
|
|
|
Get memory stats for a running domain.
|
|
|
|
=item B<domblkinfo> I<domain> I<block-device>
|
|
|
|
Get block device size info for a domain.
|
|
|
|
=item B<blockpull> I<domain> I<path> [I<bandwidth>]
|
|
|
|
Populate a disk from its backing image. Once all data from its backing
|
|
image has been pulled, the disk no longer depends on the backing image.
|
|
It pulls data for the entire disk in the background, the process of the
|
|
operation can be checked with B<blockjob>.
|
|
|
|
I<path> specifies fully-qualified path of the disk.
|
|
I<bandwidth> specifies copying bandwidth limit in Mbps.
|
|
|
|
=item B<blockjob> I<domain> I<path> [I<--abort>] [I<--info>] [I<bandwidth>]
|
|
|
|
Manage active block operations.
|
|
|
|
I<path> specifies fully-qualified path of the disk.
|
|
If I<--abort> is specified, the active job on the specified disk will
|
|
be aborted.
|
|
If I<--info> is specified, the active job information on the specified
|
|
disk will be printed.
|
|
I<bandwidth> can be used to set bandwidth limit for the active job.
|
|
|
|
=item B<dominfo> I<domain-id>
|
|
|
|
Returns basic information about the domain.
|
|
|
|
=item B<domuuid> I<domain-name-or-id>
|
|
|
|
Convert a domain name or id to domain UUID
|
|
|
|
=item B<domid> I<domain-name-or-uuid>
|
|
|
|
Convert a domain name (or UUID) to a domain id
|
|
|
|
=item B<domjobabort> I<domain-id-or-uuid>
|
|
|
|
Abort the currently running domain job.
|
|
|
|
=item B<domjobinfo> I<domain-id-or-uuid>
|
|
|
|
Returns information about jobs running on a domain.
|
|
|
|
=item B<domname> I<domain-id-or-uuid>
|
|
|
|
Convert a domain Id (or UUID) to domain name
|
|
|
|
=item B<domstate> I<domain-id> [I<--reason>]
|
|
|
|
Returns state about a domain. I<--reason> tells virsh to also print
|
|
reason for the state.
|
|
|
|
=item B<domcontrol> I<domain-id>
|
|
|
|
Returns state of an interface to VMM used to control a domain. For
|
|
states other than "ok" or "error" the command also prints number of
|
|
seconds elapsed since the control interface entered its current state.
|
|
|
|
=item B<domxml-from-native> I<format> I<config>
|
|
|
|
Convert the file I<config> in the native guest configuration format
|
|
named by I<format> to a domain XML format.
|
|
|
|
=item B<domxml-to-native> I<format> I<xml>
|
|
|
|
Convert the file I<xml> in domain XML format to the native guest
|
|
configuration format named by I<format>.
|
|
|
|
=item B<dump> I<domain-id> I<corefilepath> [I<--live>] [I<--crash>]
|
|
[I<--bypass-cache>]
|
|
|
|
Dumps the core of a domain to a file for analysis.
|
|
If I<--live> is specified, the domain continues to run until the core
|
|
dump is complete, rather than pausing up front.
|
|
If I<--crash> is specified, the domain is halted with a crashed status,
|
|
rather than merely left in a paused state.
|
|
If I<--bypass-cache> is specified, the save will avoid the file system
|
|
cache, although this may slow down the operation.
|
|
|
|
=item B<dumpxml> I<domain-id> [I<--inactive>] [I<--security-info>]
|
|
[I<--update-cpu>]
|
|
|
|
Output the domain information as an XML dump to stdout, this format can be used
|
|
by the B<create> command. Additional options affecting the XML dump may be
|
|
used. I<--inactive> tells virsh to dump domain configuration that will be used
|
|
on next start of the domain as opposed to the current domain configuration.
|
|
Using I<--security-info> will also include security sensitive information
|
|
in the XML dump. I<--update-cpu> updates domain CPU requirements according to
|
|
host CPU.
|
|
|
|
=item B<echo> [I<--shell>] [I<--xml>] [I<arg>...]
|
|
|
|
Echo back each I<arg>, separated by space. If I<--shell> is
|
|
specified, then the output will be single-quoted where needed, so that
|
|
it is suitable for reuse in a shell context. If I<--xml> is
|
|
specified, then the output will be escaped for use in XML.
|
|
|
|
=item B<edit> I<domain-id>
|
|
|
|
Edit the XML configuration file for a domain.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh dumpxml domain > domain.xml
|
|
vi domain.xml (or make changes with your other text editor)
|
|
virsh define domain.xml
|
|
|
|
except that it does some error checking.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=item B<managedsave> I<domain-id> [I<--bypass-cache>]
|
|
[{I<--running> | I<--paused>}]
|
|
|
|
Save and destroy (stop) a running domain, so it can be restarted from the same
|
|
state at a later time. When the virsh B<start> command is next run for
|
|
the domain, it will automatically be started from this saved state.
|
|
If I<--bypass-cache> is specified, the save will avoid the file system
|
|
cache, although this may slow down the operation.
|
|
|
|
Normally, starting a managed save will decide between running or paused
|
|
based on the state the domain was in when the save was done; passing
|
|
either the I<--running> or I<--paused> flag will allow overriding which
|
|
state the B<start> should use.
|
|
|
|
The B<dominfo> command can be used to query whether a domain currently
|
|
has any managed save image.
|
|
|
|
=item B<managedsave-remove> I<domain-id>
|
|
|
|
Remove the B<managedsave> state file for a domain, if it exists. This
|
|
ensures the domain will do a full boot the next time it is started.
|
|
|
|
=item B<maxvcpus> [I<type>]
|
|
|
|
Provide the maximum number of virtual CPUs supported for a guest VM on
|
|
this connection. If provided, the I<type> parameter must be a valid
|
|
type attribute for the <domain> element of XML.
|
|
|
|
=item B<migrate> [I<--live>] [I<--direct>] [I<--p2p> [I<--tunnelled>]]
|
|
[I<--persistent>] [I<--undefinesource>] [I<--suspend>] [I<--copy-storage-all>]
|
|
[I<--copy-storage-inc>] [I<--change-protection>] [I<--verbose>]
|
|
I<domain-id> I<desturi> [I<migrateuri>] [I<dname>]
|
|
[I<--timeout> B<seconds>] [I<--xml> B<file>]
|
|
|
|
Migrate domain to another host. Add I<--live> for live migration; I<--p2p>
|
|
for peer-2-peer migration; I<--direct> for direct migration; or I<--tunnelled>
|
|
for tunnelled migration. I<--persistent> leaves the domain persistent on
|
|
destination host, I<--undefinesource> undefines the domain on the source host,
|
|
and I<--suspend> leaves the domain paused on the destination host.
|
|
I<--copy-storage-all> indicates migration with non-shared storage with full
|
|
disk copy, I<--copy-storage-inc> indicates migration with non-shared storage
|
|
with incremental copy (same base image shared between source and destination).
|
|
I<--change-protection> enforces that no incompatible configuration changes
|
|
will be made to the domain while the migration is underway; this flag is
|
|
implicitly enabled when supported by the hypervisor, but can be explicitly
|
|
used to reject the migration if the hypervisor lacks change protection
|
|
support. I<--verbose> displays the progress of migration.
|
|
|
|
The I<desturi> is the connection URI of the destination host, and
|
|
I<migrateuri> is the migration URI, which usually can be omitted.
|
|
I<dname> is used for renaming the domain to new name during migration, which
|
|
also usually can be omitted. Likewise, I<--xml> B<file> is usually
|
|
omitted, but can be used to supply an alternative XML file for use on
|
|
the destination to supply a larger set of changes to any host-specific
|
|
portions of the domain XML, such as accounting for naming differences
|
|
between source and destination in accessing underlying storage.
|
|
|
|
I<--timeout> B<seconds> forces guest to suspend when live migration exceeds
|
|
that many seconds, and
|
|
then the migration will complete offline. It can only be used with I<--live>.
|
|
|
|
B<Note>: The I<desturi> parameter for normal migration and peer2peer migration
|
|
has different semantics:
|
|
|
|
=over 4
|
|
|
|
=item * normal migration: the I<desturi> is an address of the target host as
|
|
seen from the client machine.
|
|
|
|
=item * peer2peer migration: the I<desturi> is an address of the target host as
|
|
seen from the source machine.
|
|
|
|
=back
|
|
|
|
=item B<migrate-setmaxdowntime> I<domain-id> I<downtime>
|
|
|
|
Set maximum tolerable downtime for a domain which is being live-migrated to
|
|
another host. The I<downtime> is a number of milliseconds the guest is allowed
|
|
to be down at the end of live migration.
|
|
|
|
=item B<migrate-setspeed> I<domain-id> I<bandwidth>
|
|
|
|
Set the maximum migration bandwidth (in Mbps) for a domain which is being
|
|
migrated to another host.
|
|
|
|
=item B<migrate-getspeed> I<domain-id>
|
|
|
|
Get the maximum migration bandwidth (in Mbps) for a domain.
|
|
|
|
=item B<reboot> I<domain-id>
|
|
|
|
Reboot a domain. This acts just as if the domain had the B<reboot>
|
|
command run from the console. The command returns as soon as it has
|
|
executed the reboot action, which may be significantly before the
|
|
domain actually reboots.
|
|
|
|
The exact behavior of a domain when it reboots is set by the
|
|
I<on_reboot> parameter in the domain's XML definition.
|
|
|
|
=item B<restore> I<state-file> [I<--bypass-cache>] [I<--xml> B<file>]
|
|
[{I<--running> | I<--paused>}]
|
|
|
|
Restores a domain from a B<virsh save> state file. See I<save> for more info.
|
|
|
|
If I<--bypass-cache> is specified, the restore will avoid the file system
|
|
cache, although this may slow down the operation.
|
|
|
|
I<--xml> B<file> is usually omitted, but can be used to supply an
|
|
alternative XML file for use on the restored guest with changes only
|
|
in the host-specific portions of the domain XML. For example, it can
|
|
be used to account for file naming differences in underlying storage
|
|
due to disk snapshots taken after the guest was saved.
|
|
|
|
Normally, restoring a saved image will use the state recorded in the
|
|
save image to decide between running or paused; passing either the
|
|
I<--running> or I<--paused> flag will allow overriding which state the
|
|
domain should be started in.
|
|
|
|
B<Note>: To avoid corrupting file system contents within the domain, you
|
|
should not reuse the saved state file for a second B<restore> unless you
|
|
have also reverted all storage volumes back to the same contents as when
|
|
the state file was created.
|
|
|
|
=item B<save> I<domain-id> I<state-file> [I<--bypass-cache>] [I<--xml> B<file>]
|
|
[{I<--running> | I<--paused>}]
|
|
|
|
Saves a running domain (RAM, but not disk state) to a state file so that
|
|
it can be restored
|
|
later. Once saved, the domain will no longer be running on the
|
|
system, thus the memory allocated for the domain will be free for
|
|
other domains to use. B<virsh restore> restores from this state file.
|
|
If I<--bypass-cache> is specified, the save will avoid the file system
|
|
cache, although this may slow down the operation.
|
|
|
|
This is roughly equivalent to doing a hibernate on a running computer,
|
|
with all the same limitations. Open network connections may be
|
|
severed upon restore, as TCP timeouts may have expired.
|
|
|
|
I<--xml> B<file> is usually omitted, but can be used to supply an
|
|
alternative XML file for use on the restored guest with changes only
|
|
in the host-specific portions of the domain XML. For example, it can
|
|
be used to account for file naming differences that are planned to
|
|
be made via disk snapshots of underlying storage after the guest is saved.
|
|
|
|
Normally, restoring a saved image will decide between running or paused
|
|
based on the state the domain was in when the save was done; passing
|
|
either the I<--running> or I<--paused> flag will allow overriding which
|
|
state the B<restore> should use.
|
|
|
|
Domain saved state files assume that disk images will be unchanged
|
|
between the creation and restore point. For a more complete system
|
|
restore point, where the disk state is saved alongside the memory
|
|
state, see the B<snapshot> family of commands.
|
|
|
|
=item B<save-image-define> I<file> I<xml> [{I<--running> | I<--paused>}]
|
|
|
|
Update the domain XML that will be used when I<file> is later
|
|
used in the B<restore> command. The I<xml> argument must be a file
|
|
name containing the alternative XML, with changes only in the
|
|
host-specific portions of the domain XML. For example, it can
|
|
be used to account for file naming differences resulting from creating
|
|
disk snapshots of underlying storage after the guest was saved.
|
|
|
|
The save image records whether the domain should be restored to a
|
|
running or paused state. Normally, this command does not alter the
|
|
recorded state; passing either the I<--running> or I<--paused> flag
|
|
will allow overriding which state the B<restore> should use.
|
|
|
|
=item B<save-image-dumpxml> I<file> [I<--security-info>]
|
|
|
|
Extract the domain XML that was in effect at the time the saved state
|
|
file I<file> was created with the B<save> command. Using
|
|
I<--security-info> will also include security sensitive information.
|
|
|
|
=item B<save-image-edit> I<file> [{I<--running> | I<--paused>}]
|
|
|
|
Edit the XML configuration associated with a saved state file I<file>
|
|
created by the B<save> command.
|
|
|
|
The save image records whether the domain should be restored to a
|
|
running or paused state. Normally, this command does not alter the
|
|
recorded state; passing either the I<--running> or I<--paused> flag
|
|
will allow overriding which state the B<restore> should use.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh save-image-dumpxml state-file > state-file.xml
|
|
vi state-file.xml (or make changes with your other text editor)
|
|
virsh save-image-define state-file state-file-xml
|
|
|
|
except that it does some error checking.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=item B<schedinfo> [I<--set> B<parameter=value>] I<domain-id> [[I<--config>]
|
|
[I<--live>] | [I<--current>]]
|
|
|
|
=item B<schedinfo> [I<--weight> B<number>] [I<--cap> B<number>]
|
|
I<domain-id>
|
|
|
|
Allows you to show (and set) the domain scheduler parameters. The parameters
|
|
available for each hypervisor are:
|
|
|
|
LXC (posix scheduler) : cpu_shares
|
|
|
|
QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota
|
|
|
|
Xen (credit scheduler): weight, cap
|
|
|
|
ESX (allocation scheduler): reservation, limit, shares
|
|
|
|
If I<--live> is specified, set scheduler information of a running guest.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified, affect the current guest state.
|
|
|
|
B<Note>: The cpu_shares parameter has a valid value range of 0-262144; Negative
|
|
values are wrapped to positive, and larger values are capped at the maximum.
|
|
Therefore, -1 is a useful shorthand for 262144.
|
|
|
|
B<Note>: The weight and cap parameters are defined only for the
|
|
XEN_CREDIT scheduler and are now I<DEPRECATED>.
|
|
|
|
B<Note>: The vcpu_period parameter has a valid value range of 1000-1000000 or
|
|
0, and the vcpu_quota parameter has a valid value range of
|
|
1000-18446744073709551 or less than 0. The value 0 for either parameter is
|
|
the same as not specifying that parameter.
|
|
|
|
=item B<screenshot> I<domain-id> [I<imagefilepath>] [I<--screen> B<screenID>]
|
|
|
|
Takes a screenshot of a current domain console and stores it into a file.
|
|
Optionally, if hypervisor supports more displays for a domain, I<screenID>
|
|
allows to specify which screen will be captured. It is the sequential number
|
|
of screen. In case of multiple graphics cards, heads are enumerated before
|
|
devices, e.g. having two graphics cards, both with four heads, screen ID 5
|
|
addresses the second head on the second card.
|
|
|
|
=item B<setmem> I<domain-id> B<kilobytes> [[I<--config>] [I<--live>] |
|
|
[I<--current>]]
|
|
|
|
Change the memory allocation for a guest domain.
|
|
If I<--live> is specified, perform a memory balloon of a running guest.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified, affect the current guest state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. If no flag is specified, behavior is different depending
|
|
on hypervisor.
|
|
|
|
Some hypervisors require a larger granularity than kilobytes, and requests
|
|
that are not an even multiple will be rounded up. For example, vSphere/ESX
|
|
rounds the parameter up unless the kB argument is evenly divisible by 1024
|
|
(that is, the kB argument happens to represent megabytes).
|
|
|
|
For Xen, you can only adjust the memory of a running domain if the domain is
|
|
paravirtualized or running the PV balloon driver.
|
|
|
|
=item B<setmaxmem> I<domain-id> B<kilobytes> [[I<--config>] [I<--live>] |
|
|
[I<--current>]]
|
|
|
|
Change the maximum memory allocation limit for a guest domain.
|
|
If I<--live> is specified, affect a running guest.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified, affect the current guest state.
|
|
Both I<--live> and I<--current> flags may be given, but I<--current> is
|
|
exclusive. If no flag is specified, behavior is different depending
|
|
on hypervisor.
|
|
|
|
This command works for at least the Xen, QEMU/KVM and vSphere/ESX hypervisors.
|
|
|
|
Some hypervisors require a larger granularity than kilobytes, rounding up
|
|
requests that are not an even multiple of the desired amount. vSphere/ESX
|
|
is one of these, requiring the parameter to be evenly divisible by 4MB. For
|
|
vSphere/ESX, 263168 (257MB) would be rounded up because it's not a multiple
|
|
of 4MB, while 266240 (260MB) is valid without rounding.
|
|
|
|
|
|
=item B<memtune> I<domain-id> [I<--hard-limit> B<kilobytes>]
|
|
[I<--soft-limit> B<kilobytes>] [I<--swap-hard-limit> B<kilobytes>]
|
|
[I<--min-guarantee> B<kilobytes>] [[I<--config>] [I<--live>] | [I<--current>]]
|
|
|
|
Allows you to display or set the domain memory parameters. Without
|
|
flags, the current settings are displayed; with a flag, the
|
|
appropriate limit is adjusted if supported by the hypervisor. LXC and
|
|
QEMU/KVM support I<--hard-limit>, I<--soft-limit>, and I<--swap-hard-limit>.
|
|
|
|
If I<--live> is specified, affect a running guest.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified, affect the current guest state.
|
|
Both I<--live> and I<--current> flags may be given, but I<--current> is
|
|
exclusive. If no flag is specified, behavior is different depending
|
|
on hypervisor.
|
|
|
|
For QEMU/KVM, the parameters are applied to the QEMU process as a whole.
|
|
Thus, when counting them, one needs to add up guest RAM, guest video RAM, and
|
|
some memory overhead of QEMU itself. The last piece is hard to determine so
|
|
one needs guess and try.
|
|
|
|
=over 4
|
|
|
|
=item I<--hard-limit>
|
|
|
|
The maximum memory the guest can use. The units for this value are kilobytes
|
|
(i.e. blocks of 1024 bytes).
|
|
|
|
=item I<--soft-limit>
|
|
|
|
The memory limit to enforce during memory contention. The units for this
|
|
value are kilobytes (i.e. blocks of 1024 bytes).
|
|
|
|
=item I<--swap-hard-limit>
|
|
|
|
The maximum memory plus swap the guest can use. The units for this value are
|
|
kilobytes (i.e. blocks of 1024 bytes). This has to be more than hard-limit
|
|
value provided.
|
|
|
|
=item I<--min-guarantee>
|
|
|
|
The guaranteed minimum memory allocation for the guest. The units for this
|
|
value are kilobytes (i.e. blocks of 1024 bytes).
|
|
|
|
=back
|
|
|
|
=item B<blkiotune> I<domain-id> [I<--weight> B<weight>] [[I<--config>]
|
|
[I<--live>] | [I<--current>]]
|
|
|
|
Display or set the blkio parameters. QEMU/KVM supports I<--weight>.
|
|
I<--weight> is in range [100, 1000].
|
|
|
|
If I<--live> is specified, affect a running guest.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified, affect the current guest state.
|
|
Both I<--live> and I<--current> flags may be given, but I<--current> is
|
|
exclusive. If no flag is specified, behavior is different depending
|
|
on hypervisor.
|
|
|
|
=item B<setvcpus> I<domain-id> I<count> [I<--maximum>] [[I<--config>]
|
|
[I<--live>] | [I<--current>]]
|
|
|
|
Change the number of virtual CPUs active in a guest domain. By default,
|
|
this command works on active guest domains. To change the settings for an
|
|
inactive guest domain, use the I<--config> flag.
|
|
|
|
The I<count> value may be limited by host, hypervisor, or a limit coming
|
|
from the original description of the guest domain. For Xen, you can only
|
|
adjust the virtual CPUs of a running domain if the domain is paravirtualized.
|
|
|
|
If the I<--config> flag is specified, the change is made to the stored XML
|
|
configuration for the guest domain, and will only take effect when the guest
|
|
domain is next started.
|
|
|
|
If I<--live> is specified, the guest domain must be active, and the change
|
|
takes place immediately. Both the I<--config> and I<--live> flags may be
|
|
specified together if supported by the hypervisor.
|
|
|
|
If I<--current> is specified, affect the current guest state.
|
|
|
|
When no flags are given, the I<--live>
|
|
flag is assumed and the guest domain must be active. In this situation it
|
|
is up to the hypervisor whether the I<--config> flag is also assumed, and
|
|
therefore whether the XML configuration is adjusted to make the change
|
|
persistent.
|
|
|
|
The I<--maximum> flag controls the maximum number of virtual cpus that can
|
|
be hot-plugged the next time the domain is booted. As such, it must only be
|
|
used with the I<--config> flag, and not with the I<--live> flag.
|
|
|
|
=item B<shutdown> I<domain-id>
|
|
|
|
Gracefully shuts down a domain. This coordinates with the domain OS
|
|
to perform graceful shutdown, so there is no guarantee that it will
|
|
succeed, and may take a variable length of time depending on what
|
|
services must be shutdown in the domain.
|
|
|
|
The exact behavior of a domain when it shuts down is set by the
|
|
I<on_shutdown> parameter in the domain's XML definition.
|
|
|
|
If I<domain-id> is transient, then the metadata of any snapshots will
|
|
be lost once the guest stops running, but the snapshot contents still
|
|
exist, and a new domain with the same name and UUID can restore the
|
|
snapshot metadata with B<snapshot-create>.
|
|
|
|
=item B<start> I<domain-name> [I<--console>] [I<--paused>] [I<--autodestroy>]
|
|
[I<--bypass-cache>] [I<--force-boot>]
|
|
|
|
Start a (previously defined) inactive domain, either from the last
|
|
B<managedsave> state, or via a fresh boot if no managedsave state is
|
|
present. The domain will be paused if the I<--paused> option is
|
|
used and supported by the driver; otherwise it will be running.
|
|
If I<--console> is requested, attach to the console after creation.
|
|
If I<--autodestroy> is requested, then the guest will be automatically
|
|
destroyed when virsh closes its connection to libvirt, or otherwise
|
|
exits. If I<--bypass-cache> is specified, and managedsave state exists,
|
|
the restore will avoid the file system cache, although this may slow
|
|
down the operation. If I<--force-boot> is specified, then any
|
|
managedsave state is discarded and a fresh boot occurs.
|
|
|
|
=item B<suspend> I<domain-id>
|
|
|
|
Suspend a running domain. It is kept in memory but won't be scheduled
|
|
anymore.
|
|
|
|
=item B<resume> I<domain-id>
|
|
|
|
Moves a domain out of the suspended state. This will allow a previously
|
|
suspended domain to now be eligible for scheduling by the underlying
|
|
hypervisor.
|
|
|
|
=item B<ttyconsole> I<domain-id>
|
|
|
|
Output the device used for the TTY console of the domain. If the information
|
|
is not available the processes will provide an exit code of 1.
|
|
|
|
=item B<undefine> I<domain-id> [I<--managed-save>] [I<--snapshots-metadata]
|
|
|
|
Undefine a domain. If the domain is running, this converts it to a
|
|
transient domain, without stopping it. If the domain is inactive,
|
|
the domain configuration is removed.
|
|
|
|
The I<--managed-save> flag guarantees that any managed save image (see
|
|
the B<managedsave> command) is also cleaned up. Without the flag, attempts
|
|
to undefine a domain with a managed save image will fail.
|
|
|
|
The I<--snapshots-metadata> flag guarantees that any snapshots (see the
|
|
B<snapshot-list> command) are also cleaned up when undefining an inactive
|
|
domain. Without the flag, attempts to undefine an inactive domain with
|
|
snapshot metadata will fail. If the domain is active, this flag is
|
|
ignored.
|
|
|
|
NOTE: For an inactive domain, the domain name or UUID must be used as the
|
|
I<domain-id>.
|
|
|
|
=item B<vcpucount> I<domain-id> [{I<--maximum> | I<--active>}
|
|
{I<--config> | I<--live> | I<--current>}]
|
|
|
|
Print information about the virtual cpu counts of the given
|
|
I<domain-id>. If no flags are specified, all possible counts are
|
|
listed in a table; otherwise, the output is limited to just the
|
|
numeric value requested. For historical reasons, the table
|
|
lists the label "current" on the rows that can be queried in isolation
|
|
via the I<--active> flag, rather than relating to the I<--current> flag.
|
|
|
|
I<--maximum> requests information on the maximum cap of vcpus that a
|
|
domain can add via B<setvcpus>, while I<--active> shows the current
|
|
usage; these two flags cannot both be specified. I<--config>
|
|
requires a persistent domain and requests information regarding the next
|
|
time the domain will be booted, I<--live> requires a running domain and
|
|
lists current values, and I<--current> queries according to the current
|
|
state of the domain (corresponding to I<--live> if running, or
|
|
I<--config> if inactive); these three flags are mutually exclusive.
|
|
Thus, this command always takes exactly zero or two flags.
|
|
|
|
=item B<vcpuinfo> I<domain-id>
|
|
|
|
Returns basic information about the domain virtual CPUs, like the number of
|
|
vCPUs, the running time, the affinity to physical processors.
|
|
|
|
=item B<vcpupin> I<domain-id> [I<vcpu>] [I<cpulist>] [[I<--live>]
|
|
[I<--config>] | [I<--current>]]
|
|
|
|
Query or change the pinning of domain VCPUs to host physical CPUs. To
|
|
pin a single I<vcpu>, specify I<cpulist>; otherwise, you can query one
|
|
I<vcpu> or omit I<vcpu> to list all at once.
|
|
|
|
I<cpulist> is a list of physical CPU numbers. Its syntax is a comma
|
|
separated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2') can
|
|
also be allowed. The '-' denotes the range and the '^' denotes exclusive.
|
|
If you want to reset vcpupin setting, that is, to pin vcpu all physical cpus,
|
|
simply specify 'r' as a cpulist.
|
|
If I<--live> is specified, affect a running guest.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified, affect the current guest state.
|
|
Both I<--live> and I<--config> flags may be given if I<cpulist> is present,
|
|
but I<--current> is exclusive.
|
|
If no flag is specified, behavior is different depending on hypervisor.
|
|
|
|
B<Note>: The expression is sequentially evaluated, so "0-15,^8" is
|
|
identical to "9-14,0-7,15" but not identical to "^8,0-15".
|
|
|
|
=item B<vncdisplay> I<domain-id>
|
|
|
|
Output the IP address and port number for the VNC display. If the information
|
|
is not available the processes will provide an exit code of 1.
|
|
|
|
=back
|
|
|
|
=head1 DEVICE COMMANDS
|
|
|
|
The following commands manipulate devices associated to domains.
|
|
The domain-id can be specified as a short integer, a name or a full UUID.
|
|
To better understand the values allowed as options for the command
|
|
reading the documentation at L<http://libvirt.org/formatdomain.html> on the
|
|
format of the device sections to get the most accurate set of accepted values.
|
|
|
|
=over 4
|
|
|
|
=item B<attach-device> I<domain-id> I<FILE>
|
|
|
|
Attach a device to the domain, using a device definition in an XML file.
|
|
See the documentation to learn about libvirt XML format for a device.
|
|
For cdrom and floppy devices, this command only replaces the media within
|
|
the single existing device; consider using B<update-device> for this usage.
|
|
|
|
=item B<attach-disk> I<domain-id> I<source> I<target>
|
|
[I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>]
|
|
[I<--type type>] [I<--mode mode>] [I<--persistent>] [I<--sourcetype soucetype>]
|
|
[I<--serial serial>] [I<--shareable>] [I<--address address>]
|
|
|
|
Attach a new disk device to the domain.
|
|
I<source> and I<target> are paths for the files and devices.
|
|
I<driver> can be I<file>, I<tap> or I<phy> depending on the kind of access.
|
|
I<type> can indicate I<cdrom> or I<floppy> as alternative to the disk default,
|
|
although this use only replaces the media within the existing virtual cdrom or
|
|
floppy device; consider using B<update-device> for this usage instead.
|
|
I<mode> can specify the two specific mode I<readonly> or I<shareable>.
|
|
I<persistent> indicates the changes will affect the next boot of the domain.
|
|
I<sourcetype> can indicate the type of source (block|file)
|
|
I<cache> can be one of "default", "none", "writethrough", "writeback", or
|
|
"directsync".
|
|
I<serial> is the serial of disk device. I<shareable> indicates the disk device
|
|
is shareable between domains.
|
|
I<address> is the address of disk device in the form of pci:domain.bus.slot.function,
|
|
scsi:controller.bus.unit or ide:controller.bus.unit.
|
|
|
|
=item B<attach-interface> I<domain-id> I<type> I<source>
|
|
[I<--target target>] [I<--mac mac>] [I<--script script>] [I<--model model>]
|
|
[I<--persistent>]
|
|
|
|
Attach a new network interface to the domain.
|
|
I<type> can be either I<network> to indicate a physical network device or I<bridge> to indicate a bridge to a device.
|
|
I<source> indicates the source device.
|
|
I<target> allows to indicate the target device in the guest.
|
|
I<mac> allows to specify the MAC address of the network interface.
|
|
I<script> allows to specify a path to a script handling a bridge instead of
|
|
the default one.
|
|
I<model> allows to specify the model type.
|
|
I<persistent> indicates the changes will affect the next boot of the domain.
|
|
|
|
=item B<detach-device> I<domain-id> I<FILE>
|
|
|
|
Detach a device from the domain, takes the same kind of XML descriptions
|
|
as command B<attach-device>.
|
|
|
|
=item B<detach-disk> I<domain-id> I<target>
|
|
|
|
Detach a disk device from a domain. The I<target> is the device as seen
|
|
from the domain.
|
|
|
|
=item B<detach-interface> I<domain-id> I<type> [I<--mac mac>]
|
|
|
|
Detach a network interface from a domain.
|
|
I<type> can be either I<network> to indicate a physical network device or I<bridge> to indicate a bridge to a device.
|
|
It is recommended to use the I<mac> option to distinguish between the interfaces
|
|
if more than one are present on the domain.
|
|
|
|
=item B<update-device> I<domain-id> I<file> [I<--persistent>] [I<--force>]
|
|
|
|
Update the characteristics of a device associated with I<domain-id>, based on
|
|
the device definition in an XML I<file>. If the I<--persistent> option is
|
|
used, the changes will affect the next boot of the domain. The I<--force>
|
|
option can be used to force device update, e.g., to eject a CD-ROM even if it
|
|
is locked/mounted in the domain. See the documentation to learn about libvirt
|
|
XML format for a device.
|
|
|
|
=back
|
|
|
|
=head1 VIRTUAL NETWORK COMMANDS
|
|
|
|
The following commands manipulate networks. Libvirt has the capability to
|
|
define virtual networks which can then be used by domains and linked to
|
|
actual network devices. For more detailed information about this feature
|
|
see the documentation at L<http://libvirt.org/formatnetwork.html> . Many
|
|
of the commands for virtual networks are similar to the ones used for domains,
|
|
but the way to name a virtual network is either by its name or UUID.
|
|
|
|
=over 4
|
|
|
|
=item B<net-autostart> I<network> [I<--disable>]
|
|
|
|
Configure a virtual network to be automatically started at boot.
|
|
The I<--disable> option disable autostarting.
|
|
|
|
=item B<net-create> I<file>
|
|
|
|
Create a virtual network from an XML I<file>, see the documentation to get
|
|
a description of the XML network format used by libvirt.
|
|
|
|
=item B<net-define> I<file>
|
|
|
|
Define a virtual network from an XML I<file>, the network is just defined but
|
|
not instantiated.
|
|
|
|
=item B<net-destroy> I<network>
|
|
|
|
Destroy (stop) a given virtual network specified by its name or UUID. This
|
|
takes effect immediately.
|
|
|
|
=item B<net-dumpxml> I<network>
|
|
|
|
Output the virtual network information as an XML dump to stdout.
|
|
|
|
=item B<net-edit> I<network>
|
|
|
|
Edit the XML configuration file for a network.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh net-dumpxml network > network.xml
|
|
vi network.xml (or make changes with your other text editor)
|
|
virsh net-define network.xml
|
|
|
|
except that it does some error checking.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=item B<net-info> I<network>
|
|
|
|
Returns basic information about the I<network> object.
|
|
|
|
=item B<net-list> [I<--inactive> | I<--all>]
|
|
|
|
Returns the list of active networks, if I<--all> is specified this will also
|
|
include defined but inactive networks, if I<--inactive> is specified only the
|
|
inactive ones will be listed.
|
|
|
|
=item B<net-name> I<network-UUID>
|
|
|
|
Convert a network UUID to network name.
|
|
|
|
=item B<net-start> I<network>
|
|
|
|
Start a (previously defined) inactive network.
|
|
|
|
=item B<net-undefine> I<network>
|
|
|
|
Undefine the configuration for an inactive network.
|
|
|
|
=item B<net-uuid> I<network-name>
|
|
|
|
Convert a network name to network UUID.
|
|
|
|
=back
|
|
|
|
=head1 INTERFACE COMMANDS
|
|
|
|
The following commands manipulate host interfaces. Often, these host
|
|
interfaces can then be used by name within domain <interface> elements
|
|
(such as a system-created bridge interface), but there is no
|
|
requirement that host interfaces be tied to any particular guest
|
|
configuration XML at all.
|
|
|
|
Many of the commands for host interfaces are similar to the ones used
|
|
for domains, and the way to name an interface is either by its name or
|
|
its MAC address. However, using a MAC address for an I<iface>
|
|
argument only works when that address is unique (if an interface and a
|
|
bridge share the same MAC address, which is often the case, then using
|
|
that MAC address results in an error due to ambiguity, and you must
|
|
resort to a name instead).
|
|
|
|
=over 4
|
|
|
|
=item B<iface-define> I<file>
|
|
|
|
Define a host interface from an XML I<file>, the interface is just defined but
|
|
not started.
|
|
|
|
=item B<iface-destroy> I<interface>
|
|
|
|
Destroy (stop) a given host interface, such as by running "if-down" to
|
|
disable that interface from active use. This takes effect immediately.
|
|
|
|
=item B<iface-dumpxml> I<interface> [I<--inactive>]
|
|
|
|
Output the host interface information as an XML dump to stdout. If
|
|
I<--inactive> is specified, then the output reflects the persistent
|
|
state of the interface that will be used the next time it is started.
|
|
|
|
=item B<iface-edit> I<interface>
|
|
|
|
Edit the XML configuration file for a host interface.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh iface-dumpxml iface > iface.xml
|
|
vi iface.xml (or make changes with your other text editor)
|
|
virsh iface-define iface.xml
|
|
|
|
except that it does some error checking.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=item B<iface-list> [I<--inactive> | I<--all>]
|
|
|
|
Returns the list of active host interfaces. If I<--all> is specified
|
|
this will also include defined but inactive interfaces. If
|
|
I<--inactive> is specified only the inactive ones will be listed.
|
|
|
|
=item B<iface-name> I<interface>
|
|
|
|
Convert a host interface MAC to interface name, if the MAC address is unique
|
|
among the host's interfaces.
|
|
|
|
I<interface> specifies the interface MAC address.
|
|
|
|
=item B<iface-mac> I<interface>
|
|
|
|
Convert a host interface name to MAC address.
|
|
|
|
I<interface> specifies the interface name.
|
|
|
|
=item B<iface-start> I<interface>
|
|
|
|
Start a (previously defined) host interface, such as by running "if-up".
|
|
|
|
=item B<iface-undefine> I<interface>
|
|
|
|
Undefine the configuration for an inactive host interface.
|
|
|
|
=item B<iface-begin>
|
|
|
|
Create a snapshot of current host interface settings, which can later
|
|
be committed (I<iface-commit>) or restored (I<iface-rollback>). If a
|
|
snapshot already exists, then this command will fail until the
|
|
previous snapshot has been committed or restored. Undefined behavior
|
|
results if any external changes are made to host interfaces outside of
|
|
the libvirt API between the beginning of a snapshot and its eventual
|
|
commit or rollback.
|
|
|
|
=item B<iface-commit>
|
|
|
|
Declare all changes since the last I<iface-begin> as working, and
|
|
delete the rollback point. If no interface snapshot has already been
|
|
started, then this command will fail.
|
|
|
|
=item B<iface-rollback>
|
|
|
|
Revert all host interface settings back to the state recorded in the
|
|
last I<iface-begin>. If no interface snapshot has already been
|
|
started, then this command will fail. Rebooting the host also serves
|
|
as an implicit rollback point.
|
|
|
|
=back
|
|
|
|
=head1 STORAGE POOL COMMANDS
|
|
|
|
The following commands manipulate storage pools. Libvirt has the
|
|
capability to manage various storage solutions, including files, raw
|
|
partitions, and domain-specific formats, used to provide the storage
|
|
volumes visible as devices within virtual machines. For more detailed
|
|
information about this feature, see the documentation at
|
|
L<http://libvirt.org/formatstorage.html> . Many of the commands for
|
|
pools are similar to the ones used for domains.
|
|
|
|
=over 4
|
|
|
|
=item B<find-storage-pool-sources> I<type> [I<srcSpec>]
|
|
|
|
Returns XML describing all storage pools of a given I<type> that could
|
|
be found. If I<srcSpec> is provided, it is a file that contains XML
|
|
to further restrict the query for pools.
|
|
|
|
=item B<find-storage-pool-sources-as> I<type> [I<host>] [I<port>]
|
|
[I<initiator>]
|
|
|
|
Returns XML describing all storage pools of a given I<type> that could
|
|
be found. If I<host>, I<port>, or I<initiator> are provided, they control
|
|
where the query is performed.
|
|
|
|
=item B<pool-autostart> I<pool-or-uuid> [I<--disable>]
|
|
|
|
Configure whether I<pool> should automatically start at boot.
|
|
|
|
=item B<pool-build> I<pool-or-uuid> [I<--overwrite>] [I<--no-overwrite>]
|
|
|
|
Build a given pool.
|
|
|
|
Options I<--overwrite> and I<--no-overwrite> can only be used for
|
|
B<pool-build> a filesystem pool. If neither of them is specified,
|
|
B<pool-build> on a filesystem pool only makes the directory; If
|
|
I<--no-overwrite> is specified, it probes to determine if a
|
|
filesystem already exists on the target device, returning an error
|
|
if exists, or using mkfs to format the target device if not; If
|
|
I<--overwrite> is specified, mkfs is always executed, any existed
|
|
data on the target device is overwritten unconditionally.
|
|
|
|
=item B<pool-create> I<file>
|
|
|
|
Create and start a pool object from the XML I<file>.
|
|
|
|
=item B<pool-create-as> I<name> I<--print-xml> I<type> [I<source-host>]
|
|
[I<source-path>] [I<source-dev>] [I<source-name>] [<target>]
|
|
[I<--source-format format>]
|
|
|
|
Create and start a pool object I<name> from the raw parameters. If
|
|
I<--print-xml> is specified, then print the XML of the pool object
|
|
without creating the pool. Otherwise, the pool has the specified
|
|
I<type>.
|
|
|
|
=item B<pool-define> I<file>
|
|
|
|
Create, but do not start, a pool object from the XML I<file>.
|
|
|
|
=item B<pool-define-as> I<name> I<--print-xml> I<type> [I<source-host>]
|
|
[I<source-path>] [I<source-dev>] [I<source-name>] [<target>]
|
|
[I<--source-format format>]
|
|
|
|
Create, but do not start, a pool object I<name> from the raw parameters. If
|
|
I<--print-xml> is specified, then print the XML of the pool object
|
|
without defining the pool. Otherwise, the pool has the specified
|
|
I<type>.
|
|
|
|
=item B<pool-destroy> I<pool-or-uuid>
|
|
|
|
Destroy (stop) a given I<pool> object. Libvirt will no longer manage the
|
|
storage described by the pool object, but the raw data contained in
|
|
the pool is not changed, and can be later recovered with
|
|
B<pool-create>.
|
|
|
|
=item B<pool-delete> I<pool-or-uuid>
|
|
|
|
Destroy the resources used by a given I<pool> object. This operation
|
|
is non-recoverable. The I<pool> object will still exist after this
|
|
command, ready for the creation of new storage volumes.
|
|
|
|
=item B<pool-dumpxml> I<pool-or-uuid>
|
|
|
|
Returns the XML information about the I<pool> object.
|
|
|
|
=item B<pool-edit> I<pool-or-uuid>
|
|
|
|
Edit the XML configuration file for a storage pool.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh pool-dumpxml pool > pool.xml
|
|
vi pool.xml (or make changes with your other text editor)
|
|
virsh pool-define pool.xml
|
|
|
|
except that it does some error checking.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=item B<pool-info> I<pool-or-uuid>
|
|
|
|
Returns basic information about the I<pool> object.
|
|
|
|
=item B<pool-list> [I<--inactive> | I<--all>] [I<--details>]
|
|
|
|
List pool objects known to libvirt. By default, only pools in use by
|
|
active domains are listed; I<--inactive> lists just the inactive
|
|
pools, and I<--all> lists all pools. The I<--details> option instructs
|
|
virsh to additionally display pool persistence and capacity related
|
|
information where available.
|
|
|
|
=item B<pool-name> I<uuid>
|
|
|
|
Convert the I<uuid> to a pool name.
|
|
|
|
=item B<pool-refresh> I<pool-or-uuid>
|
|
|
|
Refresh the list of volumes contained in I<pool>.
|
|
|
|
=item B<pool-start> I<pool-or-uuid>
|
|
|
|
Start the storage I<pool>, which is previously defined but inactive.
|
|
|
|
=item B<pool-undefine> I<pool-or-uuid>
|
|
|
|
Undefine the configuration for an inactive I<pool>.
|
|
|
|
=item B<pool-uuid> I<pool>
|
|
|
|
Returns the UUID of the named I<pool>.
|
|
|
|
=back
|
|
|
|
=head1 VOLUME COMMANDS
|
|
|
|
=over 4
|
|
|
|
=item B<vol-create> I<pool-or-uuid> I<FILE>
|
|
|
|
Create a volume from an XML <file>.
|
|
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
|
|
I<FILE> is the XML <file> with the volume definition. An easy way to create the
|
|
XML <file> is to use the B<vol-dumpxml> command to obtain the definition of a
|
|
pre-existing volume.
|
|
|
|
B<Example>
|
|
|
|
virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
|
|
vi newvolume.xml (or make changes with your other text editor)
|
|
virsh vol-create differentstoragepool newvolume.xml
|
|
|
|
=item B<vol-create-from> I<pool-or-uuid> I<FILE> [I<--inputpool>
|
|
I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Create a volume, using another volume as input.
|
|
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
|
|
I<FILE> is the XML <file> with the volume definition.
|
|
I<--inputpool> I<pool-or-uuid> is the name or uuid of the storage pool the
|
|
source volume is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the source volume.
|
|
|
|
=item B<vol-create-as> I<pool-or-uuid> I<name> I<capacity>
|
|
[I<--allocation> I<size>] [I<--format> I<string>] [I<--backing-vol>
|
|
I<vol-name-or-key-or-path>] [I<--backing-vol-format> I<string>]
|
|
|
|
Create a volume from a set of arguments.
|
|
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume
|
|
in.
|
|
I<name> is the name of the new volume.
|
|
I<capacity> is the size of the volume to be created, with optional k, M, G, or
|
|
T suffix.
|
|
I<--allocation> I<size> is the initial size to be allocated in the volume, with
|
|
optional k, M, G, or T suffix.
|
|
I<--format> I<string> is used in file based storage pools to specify the volume
|
|
file format to use; raw, bochs, qcow, qcow2, vmdk.
|
|
I<--backing-vol> I<vol-name-or-key-or-path> is the source backing
|
|
volume to be used if taking a snapshot of an existing volume.
|
|
I<--backing-vol-format> I<string> is the format of the snapshot backing volume;
|
|
raw, bochs, qcow, qcow2, vmdk, host_device.
|
|
|
|
=item B<vol-clone> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
I<name>
|
|
|
|
Clone an existing volume. Less powerful, but easier to type, version of
|
|
B<vol-create-from>.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool to create
|
|
the volume in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the source volume.
|
|
I<name> is the name of the new volume.
|
|
|
|
=item B<vol-delete> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Delete a given volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to delete.
|
|
|
|
=item B<vol-upload> [I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>]
|
|
[I<--length> I<bytes>] I<vol-name-or-key-or-path> I<local-file>
|
|
|
|
Upload the contents of I<local-file> to a storage volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe.
|
|
I<--offset> is the position in the storage volume at which to start writing
|
|
the data. I<--length> is an upper bound of the amount of data to be uploaded.
|
|
An error will occurr if the I<local-file> is greater than the specified length.
|
|
|
|
=item B<vol-download> [I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>]
|
|
[I<--length> I<bytes>] I<vol-name-or-key-or-path> I<local-file>
|
|
|
|
Download the contents of I<local-file> from a storage volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe.
|
|
I<--offset> is the position in the storage volume at which to start reading
|
|
the data. I<--length> is an upper bound of the amount of data to be downloaded.
|
|
|
|
=item B<vol-wipe> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Wipe a volume, ensure data previously on the volume is not accessible to
|
|
future reads. I<--pool> I<pool-or-uuid> is the name or UUID of the storage
|
|
pool the volume is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe.
|
|
|
|
=item B<vol-dumpxml> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Output the volume information as an XML dump to stdout.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. I<vol-name-or-key-or-path> is the name or key or path of the volume
|
|
to output the XML of.
|
|
|
|
=item B<vol-info> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Returns basic information about the given storage volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. I<vol-name-or-key-or-path> is the name or key or path of the volume
|
|
to return information for.
|
|
|
|
=item B<vol-list> [I<--pool> I<pool-or-uuid>] [I<--details>]
|
|
|
|
Return the list of volumes in the given storage pool.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool.
|
|
The I<--details> option instructs virsh to additionally display volume
|
|
type and capacity related information where available.
|
|
|
|
=item B<vol-pool> [I<--uuid>] I<vol-key-or-path>
|
|
|
|
Return the pool name or UUID for a given volume. By default, the pool name is
|
|
returned. If the I<--uuid> option is given, the pool UUID is returned instead.
|
|
I<vol-key-or-path> is the key or path of the volume to return the pool
|
|
information for.
|
|
|
|
=item B<vol-path> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key>
|
|
|
|
Return the path for a given volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in.
|
|
I<vol-name-or-key> is the name or key of the volume to return the path for.
|
|
|
|
=item B<vol-name> I<vol-key-or-path>
|
|
|
|
Return the name for a given volume.
|
|
I<vol-key-or-path> is the key or path of the volume to return the name for.
|
|
|
|
=item B<vol-key> [I<--pool> I<pool-or-uuid>] I<vol-name-or-path>
|
|
|
|
Return the volume key for a given volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. I<vol-name-or-path> is the name or path of the volume to return the
|
|
volume key for.
|
|
|
|
=back
|
|
|
|
=head1 SECRET COMMMANDS
|
|
|
|
The following commands manipulate "secrets" (e.g. passwords, passphrases and
|
|
encryption keys). Libvirt can store secrets independently from their use, and
|
|
other objects (e.g. volumes or domains) can refer to the secrets for encryption
|
|
or possibly other uses. Secrets are identified using an UUID. See
|
|
L<http://libvirt.org/formatsecret.html> for documentation of the XML format
|
|
used to represent properties of secrets.
|
|
|
|
=over 4
|
|
|
|
=item B<secret-define> I<file>
|
|
|
|
Create a secret with the properties specified in I<file>, with no associated
|
|
secret value. If I<file> does not specify a UUID, choose one automatically.
|
|
If I<file> specifies an UUID of an existing secret, replace its properties by
|
|
properties defined in I<file>, without affecting the secret value.
|
|
|
|
=item B<secret-dumpxml> I<secret>
|
|
|
|
Output properties of I<secret> (specified by its UUID) as an XML dump to stdout.
|
|
|
|
=item B<secret-set-value> I<secret> I<base64>
|
|
|
|
Set the value associated with I<secret> (specified by its UUID) to the value
|
|
Base64-encoded value I<base64>.
|
|
|
|
=item B<secret-get-value> I<secret>
|
|
|
|
Output the value associated with I<secret> (specified by its UUID) to stdout,
|
|
encoded using Base64.
|
|
|
|
=item B<secret-undefine> I<secret>
|
|
|
|
Delete a I<secret> (specified by its UUID), including the associated value, if
|
|
any.
|
|
|
|
=item B<secret-list>
|
|
|
|
Output a list of UUIDs of known secrets to stdout.
|
|
|
|
=back
|
|
|
|
=head1 SNAPSHOT COMMMANDS
|
|
|
|
The following commands manipulate domain snapshots. Snapshots take the
|
|
disk, memory, and device state of a domain at a point-of-time, and save it
|
|
for future use. They have many uses, from saving a "clean" copy of an OS
|
|
image to saving a domain's state before a potentially destructive operation.
|
|
Snapshots are identified with a unique name. See
|
|
L<http://libvirt.org/formatsnapshot.html> for documentation of the XML format
|
|
used to represent properties of snapshots.
|
|
|
|
=over 4
|
|
|
|
=item B<snapshot-create> I<domain> [I<xmlfile>] {[I<--redefine> [I<--current>]]
|
|
| [I<--no-metadata>]}
|
|
|
|
Create a snapshot for domain I<domain> with the properties specified in
|
|
I<xmlfile>. Normally, the only properties settable for a domain snapshot
|
|
are the <name> and <description> elements; the rest of the fields are
|
|
ignored, and automatically filled in by libvirt. If I<xmlfile> is
|
|
completely omitted, then libvirt will choose a value for all fields.
|
|
The new snapshot will become current, as listed by B<snapshot-current>.
|
|
|
|
If I<--redefine> is specified, then all XML elements produced by
|
|
B<snapshot-dumpxml> are valid; this can be used to migrate snapshot
|
|
hierarchy from one machine to another, to recreate hierarchy for the
|
|
case of a transient domain that goes away and is later recreated with
|
|
the same name and UUID, or to make slight alterations in the snapshot
|
|
metadata (such as host-specific aspects of the domain XML embedded in
|
|
the snapshot). When this flag is supplied, the I<xmlfile> argument
|
|
is mandatory, and the domain's current snapshot will not be altered
|
|
unless the I<--current> flag is also given.
|
|
|
|
If I<--no-metadata> is specified, then the snapshot data is created,
|
|
but any metadata is immediately discarded (that is, libvirt does not
|
|
treat the snapshot as current, and cannot revert to the snapshot
|
|
unless I<--redefine> is later used to teach libvirt about the
|
|
metadata again).
|
|
|
|
Existence of snapshot metadata will prevent attempts to B<undefine>
|
|
a persistent domain. However, for transient domains, snapshot
|
|
metadata is silently lost when the domain quits running (whether
|
|
by command such as B<destroy> or by internal guest action).
|
|
|
|
=item B<snapshot-create-as> I<domain> {[I<--print-xml>] | [I<--no-metadata>]}
|
|
[I<name>] [I<description>]
|
|
|
|
Create a snapshot for domain I<domain> with the given <name> and
|
|
<description>; if either value is omitted, libvirt will choose a
|
|
value. If I<--print-xml> is specified, then XML appropriate for
|
|
I<snapshot-create> is output, rather than actually creating a snapshot.
|
|
|
|
If I<--no-metadata> is specified, then the snapshot data is created,
|
|
but any metadata is immediately discarded (that is, libvirt does not
|
|
treat the snapshot as current, and cannot revert to the snapshot
|
|
unless B<snapshot-create> is later used to teach libvirt about the
|
|
metadata again). This flag is incompatible with I<--print-xml>.
|
|
|
|
=item B<snapshot-current> I<domain> {[I<--name>] | [I<--security-info]
|
|
| [I<snapshotname>]}
|
|
|
|
Without I<snapshotname>, this will output the snapshot XML for the domain's
|
|
current snapshot (if any). If I<--name> is specified, just the
|
|
current snapshot name instead of the full xml. Otherwise, using
|
|
I<--security-info> will also include security sensitive information in
|
|
the XML.
|
|
|
|
With I<snapshotname>, this is a request to make the existing named
|
|
snapshot become the current snapshot, without reverting the domain.
|
|
|
|
=item B<snapshot-edit> I<domain> I<snapshotname> [I<--current>]
|
|
|
|
Edit the XML configuration file for I<snapshotname> of a domain. If
|
|
I<--current> is specified, also force the edited snapshot to become
|
|
the current snapshot.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh snapshot-dumpxml dom name > snapshot.xml
|
|
vi snapshot.xml (or make changes with your other text editor)
|
|
virsh snapshot-create dom snapshot.xml --redefine [--current]
|
|
|
|
except that it does some error checking.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=item B<snapshot-list> I<domain> [{I<--parent> | I<--roots>}] [I<--metadata>]
|
|
|
|
List all of the available snapshots for the given domain.
|
|
|
|
If I<--parent> is specified, add a column to the output table giving
|
|
the name of the parent of each snapshot.
|
|
|
|
If I<--roots> is specified, the list will be filtered to just snapshots
|
|
that have no parents; this option is not compatible with I<--parent>.
|
|
|
|
If I<--metadata> is specified, the list will be filtered to just
|
|
snapshots that involve libvirt metadata, and thus would prevent
|
|
B<undefine> of a persistent domain, or be lost on B<destroy> of
|
|
a transient domain.
|
|
|
|
=item B<snapshot-dumpxml> I<domain> I<snapshot> [I<--security-info>]
|
|
|
|
Output the snapshot XML for the domain's snapshot named I<snapshot>.
|
|
Using I<--security-info> will also include security sensitive information.
|
|
|
|
=item B<snapshot-parent> I<domain> I<snapshot>
|
|
|
|
Output the name of the parent snapshot for the given I<snapshot>, if any.
|
|
|
|
=item B<snapshot-revert> I<domain> I<snapshot> [{I<--running> | I<--paused>}]
|
|
|
|
Revert the given domain to the snapshot specified by I<snapshot>. Be aware
|
|
that this is a destructive action; any changes in the domain since the last
|
|
snapshot was taken will be lost. Also note that the state of the domain after
|
|
snapshot-revert is complete will be the state of the domain at the time
|
|
the original snapshot was taken.
|
|
|
|
Normally, reverting to a snapshot leaves the domain in the state it was
|
|
at the time the snapshot was created, except that a disk snapshot with
|
|
no vm state leaves the domain in an inactive state. Passing either the
|
|
I<--running> or I<--paused> flag will perform additional state changes
|
|
(such as booting an inactive domain, or pausing a running domain). Since
|
|
transient domains cannot be inactive, it is required to use one of these
|
|
flags when reverting to a disk snapshot of a transient domain.
|
|
|
|
=item B<snapshot-delete> I<domain> I<snapshot> I<--children>
|
|
|
|
Delete the snapshot for the domain named I<snapshot>. If this snapshot
|
|
has child snapshots, changes from this snapshot will be merged into the
|
|
children. If I<--children> is passed, then delete this snapshot and any
|
|
children of this snapshot.
|
|
|
|
=back
|
|
|
|
=head1 NWFILTER COMMMANDS
|
|
|
|
The following commands manipulate network filters. Network filters allow
|
|
filtering of the network traffic coming from and going to virtual machines.
|
|
Individual network traffic filters are written in XML and may contain
|
|
references to other network filters, describe traffic filtering rules,
|
|
or contain both. Network filters are referenced by virtual machines
|
|
from within their interface description. A network filter may be referenced
|
|
by multiple virtual machines' interfaces.
|
|
|
|
=over 4
|
|
|
|
=item B<nwfilter-define> I<xmlfile>
|
|
|
|
Make a new network filter known to libvirt. If a network filter with
|
|
the same name already exists, it will be replaced with the new XML.
|
|
Any running virtual machine referencing this network filter will have
|
|
its network traffic rules adapted. If for any reason the network traffic
|
|
filtering rules cannot be instantiated by any of the running virtual
|
|
machines, then the new XML will be rejected.
|
|
|
|
=item B<nwfilter-undefine> I<nwfilter-name>
|
|
|
|
Delete a network filter. The deletion will fail if any running virtual
|
|
machine is currently using this network filter.
|
|
|
|
=item B<nwfilter-list>
|
|
|
|
List all of the available network filters.
|
|
|
|
=item B<nwfilter-dumpxml> I<nwfilter-name>
|
|
|
|
Output the network filter XML.
|
|
|
|
=item B<nwfilter-edit> I<nwfilter-name>
|
|
|
|
Edit the XML of a network filter.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh nwfilter-dumpxml myfilter > myfilter.xml
|
|
vi myfilter.xml (or make changes with your other text editor)
|
|
virsh nwfilter-define myfilter.xml
|
|
|
|
except that it does some error checking.
|
|
The new network filter may be rejected due to the same reason as
|
|
mentioned in I<nwfilter-define>.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=back
|
|
|
|
=head1 QEMU-SPECIFIC COMMANDS
|
|
|
|
NOTE: Use of the following commands is B<strongly> discouraged. They
|
|
can cause libvirt to become confused and do the wrong thing on subsequent
|
|
operations. Once you have used this command, please do not report
|
|
problems to the libvirt developers; the reports will be ignored.
|
|
|
|
=over 4
|
|
|
|
=item B<qemu-attach> I<pid>
|
|
|
|
Attach an externally launched QEMU process to the libvirt QEMU driver.
|
|
The QEMU process must have been created with a monitor connection
|
|
using the UNIX driver. Ideally the process will also have had the
|
|
'-name' argument specified.
|
|
|
|
=over 4
|
|
|
|
$ qemu-kvm -cdrom ~/demo.iso \
|
|
-monitor unix:/tmp/demo,server,nowait \
|
|
-name foo \
|
|
-uuid cece4f9f-dff0-575d-0e8e-01fe380f12ea &
|
|
$ QEMUPID=$!
|
|
$ virsh qemu-attach $QEMUPID
|
|
|
|
=back
|
|
|
|
Not all functions of libvirt are expected to work reliably after
|
|
attaching to an externally launched QEMU process. There may be
|
|
issues with the guest ABI changing upon migration, and hotunplug
|
|
may not work.
|
|
|
|
=item B<qemu-monitor-command> I<domain> [I<--hmp>] I<command>...
|
|
|
|
Send an arbitrary monitor command I<command> to domain I<domain> through the
|
|
qemu monitor. The results of the command will be printed on stdout. If
|
|
I<--hmp> is passed, the command is considered to be a human monitor command
|
|
and libvirt will automatically convert it into QMP if needed. In that case
|
|
the result will also be converted back from QMP. If more than one argument
|
|
is provided for I<command>, they are concatenated with a space in between
|
|
before passing the single command to the monitor.
|
|
|
|
=back
|
|
|
|
=head1 ENVIRONMENT
|
|
|
|
The following environment variables can be set to alter the behaviour
|
|
of C<virsh>
|
|
|
|
=over 4
|
|
|
|
=item VIRSH_DEBUG=<0 to 4>
|
|
|
|
Turn on verbose debugging of virsh commands. Valid levels are
|
|
|
|
=item * VIRSH_DEBUG=0
|
|
|
|
DEBUG - Messages at ALL levels get logged
|
|
|
|
=item * VIRSH_DEBUG=1
|
|
|
|
INFO - Logs messages at levels INFO, NOTICE, WARNING and ERROR
|
|
|
|
=item * VIRSH_DEBUG=2
|
|
|
|
NOTICE - Logs messages at levels NOTICE, WARNING and ERROR
|
|
|
|
=item * VIRSH_DEBUG=3
|
|
|
|
WARNING - Logs messages at levels WARNING and ERROR
|
|
|
|
=item * VIRSH_DEBUG=4
|
|
|
|
ERROR - Messages at only ERROR level gets logged.
|
|
|
|
=item VIRSH_LOG_FILE=C<LOGFILE>
|
|
|
|
The file to log virsh debug messages.
|
|
|
|
=item VIRSH_DEFAULT_CONNECT_URI
|
|
|
|
The hypervisor to connect to by default. Set this to a URI, in the same
|
|
format as accepted by the B<connect> option.
|
|
|
|
=item VISUAL
|
|
|
|
The editor to use by the B<edit> and related options.
|
|
|
|
=item EDITOR
|
|
|
|
The editor to use by the B<edit> and related options, if C<VISUAL>
|
|
is not set.
|
|
|
|
=item LIBVIRT_DEBUG=LEVEL
|
|
|
|
Turn on verbose debugging of all libvirt API calls. Valid levels are
|
|
|
|
=over 4
|
|
|
|
=item * LIBVIRT_DEBUG=1
|
|
|
|
Messages at level DEBUG or above
|
|
|
|
=item * LIBVIRT_DEBUG=2
|
|
|
|
Messages at level INFO or above
|
|
|
|
=item * LIBVIRT_DEBUG=3
|
|
|
|
Messages at level WARNING or above
|
|
|
|
=item * LIBVIRT_DEBUG=4
|
|
|
|
Messages at level ERROR or above
|
|
|
|
=back
|
|
|
|
For further information about debugging options consult C<http://libvirt.org/logging.html>
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
Report any bugs discovered to the libvirt community via the mailing
|
|
list C<http://libvirt.org/contact.html> or bug tracker C<http://libvirt.org/bugs.html>.
|
|
Alternatively report bugs to your software distributor / vendor.
|
|
|
|
=head1 AUTHORS
|
|
|
|
Please refer to the AUTHORS file distributed with libvirt.
|
|
|
|
Based on the xm man page by:
|
|
Sean Dague <sean at dague dot net>
|
|
Daniel Stekloff <dsteklof at us dot ibm dot com>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (C) 2005, 2007-2010 Red Hat, Inc., and the authors listed in the
|
|
libvirt AUTHORS file.
|
|
|
|
=head1 LICENSE
|
|
|
|
virsh is distributed under the terms of the GNU LGPL v2+.
|
|
This is free software; see the source for copying conditions. There
|
|
is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
|
|
PURPOSE
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<virt-install(1)>, L<virt-xml-validate(1)>, L<virt-top(1)>, L<virt-df(1)>,
|
|
L<http://www.libvirt.org/>
|
|
|
|
=cut
|