mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-03 11:51:11 +00:00
22a92eb0a7
Fixes https://bugzilla.redhat.com/show_bug.cgi?id=1088748 The hotplugged vcpus could fail to show up in the guest if they were added during boot, see: https://bugzilla.redhat.com/show_bug.cgi?id=807508 Also change arbitrary to arbitrarily.
3550 lines
149 KiB
Plaintext
3550 lines
149 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> [ARG]...
|
|
|
|
Where I<command> is one of the commands listed below; I<domain> is the
|
|
numeric domain id, or the domain name, or the domain UUID; 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. Note: it is permissible to
|
|
give numeric names to domains, however, doing so will result in a
|
|
domain that can only be identified by domain id. In other words, if a
|
|
numeric value is supplied it will be interpreted as a domain id, not
|
|
as a name.
|
|
|
|
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<-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 below for the description of each I<LEVEL>.
|
|
|
|
=item B<-e>, B<--escape> I<string>
|
|
|
|
Set alternative escape sequence for I<console> command. By default,
|
|
telnet's B<^]> is used. Allowed characters when using hat notation are:
|
|
alphabetic character, @, [, ], \, ^, _.
|
|
|
|
=item B<-h>, B<--help>
|
|
|
|
Ignore all other arguments, and behave as if the B<help> command were
|
|
given instead.
|
|
|
|
=item B<-k>, B<--keepalive-interval> I<INTERVAL>
|
|
|
|
Set an I<INTERVAL> (in seconds) for sending keepalive messages to
|
|
check whether connection to the server is still alive. Setting the
|
|
interval to 0 disables client keepalive mechanism.
|
|
|
|
=item B<-K>, B<--keepalive-count> I<COUNT>
|
|
|
|
Set a number of times keepalive message can be sent without getting an
|
|
answer from the server without marking the connection dead. There is
|
|
no effect to this setting in case the I<INTERVAL> is set to 0.
|
|
|
|
=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.
|
|
|
|
=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.
|
|
|
|
=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.
|
|
|
|
B<virsh> strives for backward compatibility. Although the B<help>
|
|
command only lists the preferred usage of a command, if an older
|
|
version of B<virsh> supported an alternate spelling of a command or
|
|
option (such as I<--tunnelled> instead of I<--tunneled>), then
|
|
scripts using that older spelling will continue to work.
|
|
|
|
Several B<virsh> commands take an optionally scaled integer; if no
|
|
scale is provided, then the default is listed in the command (for
|
|
historical reasons, some commands default to bytes, while other
|
|
commands default to kibibytes). The following case-insensitive
|
|
suffixes can be used to select a specific scale:
|
|
b, byte byte 1
|
|
KB kilobyte 1,000
|
|
k, KiB kibibyte 1,024
|
|
MB megabyte 1,000,000
|
|
M, MiB mebibyte 1,048,576
|
|
GB gigabyte 1,000,000,000
|
|
G, GiB gibibyte 1,073,741,824
|
|
TB terabyte 1,000,000,000,000
|
|
T, TiB tebibyte 1,099,511,627,776
|
|
PB petabyte 1,000,000,000,000,000
|
|
P, PiB pebibyte 1,125,899,906,842,624
|
|
EB exabyte 1,000,000,000,000,000,000
|
|
E, EiB exbibyte 1,152,921,504,606,846,976
|
|
|
|
=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
|
|
cpu-models show the CPU models for an architecture
|
|
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
|
|
qemu-agent-command QEMU Guest Agent 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
|
|
|
|
=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 at
|
|
L<http://libvirt.org/uri.html> 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<nodecpumap>
|
|
|
|
Displays the node's total number of CPUs, the number of online CPUs
|
|
and the list of online CPUs.
|
|
|
|
=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<nodesuspend> [I<target>] [I<duration>]
|
|
|
|
Puts the node (host machine) into a system-wide sleep state and schedule
|
|
the node's Real-Time-Clock interrupt to resume the node after the time
|
|
duration specified by I<duration> is out.
|
|
I<target> specifies the state to which the host will be suspended to, it
|
|
can be "mem" (suspend to RAM), "disk" (suspend to disk), or "hybrid"
|
|
(suspend to both RAM and disk). I<duration> specifies the time duration
|
|
in seconds for which the host has to be suspended, it should be at least
|
|
60 seconds.
|
|
|
|
=item B<node-memory-tune> [I<shm-pages-to-scan>] [I<shm-sleep-millisecs>]
|
|
[I<shm-merge-across-nodes>]
|
|
|
|
Allows you to display or set the node memory parameters.
|
|
I<shm-pages-to-scan> can be used to set the number of pages to scan
|
|
before the shared memory service goes to sleep; I<shm-sleep-millisecs>
|
|
can be used to set the number of millisecs the shared memory service should
|
|
sleep before next scan; I<shm-merge-across-nodes> specifies if pages from
|
|
different numa nodes can be merged. When set to 0, only pages which physically
|
|
reside in the memory area of same NUMA node can be merged. When set to 1,
|
|
pages from all nodes can be merged. Default to 1.
|
|
|
|
B<Note>: Currently the "shared memory service" only means KSM (Kernel Samepage
|
|
Merging).
|
|
|
|
=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>
|
|
|
|
Inject NMI to the guest.
|
|
|
|
=item B<list> [I<--inactive> | I<--all>]
|
|
[I<--managed-save>] [I<--title>]
|
|
{ [I<--table>] | I<--name> | I<--uuid> }
|
|
[I<--persistent>] [I<--transient>]
|
|
[I<--with-managed-save>] [I<--without-managed-save>]
|
|
[I<--autostart>] [I<--no-autostart>]
|
|
[I<--with-snapshot>] [I<--without-snapshot>]
|
|
[I<--state-running>] [I<--state-paused>]
|
|
[I<--state-shutoff>] [I<--state-other>]
|
|
|
|
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 8 states for a domain, and which ones the
|
|
current domain is in.
|
|
|
|
=over 4
|
|
|
|
=item B<cpu-models> I<arch>
|
|
|
|
Print the list of CPU models known for the specified architecture.
|
|
|
|
=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<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.
|
|
|
|
=item B<pmsuspended>
|
|
|
|
The domain has been suspended by guest power management, e.g. entered
|
|
into s3 state.
|
|
|
|
=back
|
|
|
|
Normally only active domains are listed. To list inactive domains specify
|
|
I<--inactive> or I<--all> to list both active and inactive domains.
|
|
|
|
To further filter the list of domains you may specify one or more of filtering
|
|
flags supported by the B<list> command. These flags are grouped by function.
|
|
Specifying one or more flags from a group enables the filter group. Note that
|
|
some combinations of flags may yield no results. Supported filtering flags and
|
|
groups:
|
|
|
|
=over 4
|
|
|
|
=item B<Persistence>
|
|
|
|
Flag I<--persistent> is used to include persistent domains in the returned
|
|
list. To include transient domains specify I<--transient>.
|
|
|
|
=item B<Existence of managed save image>
|
|
|
|
To list domains having a managed save image specify flag
|
|
I<--with-managed-save>. For domains that don't have a managed save image
|
|
specify I<--without-managed-save>.
|
|
|
|
=item B<Domain state>
|
|
|
|
The following filter flags select a domain by its state:
|
|
I<--state-running> for running domains, I<--state-paused> for paused domains,
|
|
I<--state-shutoff> for turned off domains and I<--state-other> for all
|
|
other states as a fallback.
|
|
|
|
=item B<Autostarting domains>
|
|
|
|
To list autostarting domains use the flag I<--autostart>. To list domains with
|
|
this feature disabled use I<--no-autostart>.
|
|
|
|
=item B<Snapshot existence>
|
|
|
|
Domains that have snapshot images can be listed using flag I<--with-snapshot>,
|
|
domains without a snapshot I<--without-snapshot>.
|
|
|
|
=back
|
|
|
|
When talking to older servers, this command is forced to use a series of API
|
|
calls with an inherent race, where a domain might not be listed or might appear
|
|
more than once if it changed state between calls while the list was being
|
|
collected. Newer servers do not have this problem.
|
|
|
|
If I<--managed-save> is specified, then domains that have managed save state
|
|
(only possible if they are in the B<shut off> state, so you need to specify
|
|
I<--inactive> or I<--all> to actually list them) will instead show as B<saved>
|
|
in the listing. This flag is usable only with the default I<--table> output.
|
|
Note that this flag does not filter the list of domains.
|
|
|
|
If I<--name> is specified, domain names are printed instead of the table
|
|
formatted one per line. If I<--uuid> is specified domain's UUID's are printed
|
|
instead of names. Flag I<--table> specifies that the legacy table-formatted
|
|
output should be used. This is the default. All of these are mutually
|
|
exclusive.
|
|
|
|
If I<--title> is specified, then the short domain description (title) is
|
|
printed in an extra column. This flag is usable only with the default
|
|
I<--table> output.
|
|
|
|
Example:
|
|
|
|
B<virsh> list --title
|
|
Id Name State Title
|
|
--------------------------------------------------------------------------
|
|
0 Domain-0 running Mailserver 1
|
|
2 fedora paused
|
|
|
|
=item B<freecell> [{ [I<--cellno>] B<cellno> | I<--all> }]
|
|
|
|
Prints the available amount of memory on the machine or within a NUMA
|
|
cell. The freecell command can provide one of three different
|
|
displays of available memory on the machine depending on the options
|
|
specified. With no options, it displays the total free memory on the
|
|
machine. With the --all option, it displays the free memory in each
|
|
cell and the total free memory on the machine. Finally, with a
|
|
numeric argument or with --cellno plus a cell number it will display
|
|
the free memory for the specified cell only.
|
|
|
|
=item B<cpu-baseline> I<FILE> [I<--features>]
|
|
|
|
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. If I<--features> is specified then the
|
|
resulting XML description will explicitly include all features that make
|
|
up the CPU, without this option features that are part of the CPU model
|
|
will not be listed in the XML description.
|
|
|
|
=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>
|
|
|
|
=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.
|
|
|
|
=back
|
|
|
|
=head1 DOMAIN COMMANDS
|
|
|
|
The following commands manipulate domains directly, as stated
|
|
previously most commands take domain as the first parameter. The
|
|
I<domain> can be specified as a short integer, a name or a full UUID.
|
|
|
|
=over 4
|
|
|
|
=item B<autostart> [I<--disable>] I<domain>
|
|
|
|
Configure a domain to be automatically started at boot.
|
|
|
|
The option I<--disable> disables autostarting.
|
|
|
|
=item B<console> I<domain> [I<devname>] [I<--safe>] [I<--force>]
|
|
|
|
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.
|
|
|
|
If the flag I<--safe> is specified, the connection is only attempted
|
|
if the driver supports safe console handling. This flag specifies that
|
|
the server has to ensure exclusive access to console devices. Optionally
|
|
the I<--force> flag may be specified, requesting to disconnect any existing
|
|
sessions, such as in a case of a broken connection.
|
|
|
|
=item B<create> I<FILE> [I<--console>] [I<--paused>] [I<--autodestroy>]
|
|
[I<--pass-fds N,M,...>]
|
|
|
|
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.
|
|
|
|
If I<--pass-fds> is specified, the argument is a comma separated list
|
|
of open file descriptors which should be pass on into the guest. The
|
|
file descriptors will be re-numbered in the guest, starting from 3. This
|
|
is only supported with container based virtualization.
|
|
|
|
B<Example>
|
|
|
|
virsh dumpxml <domain> > 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. If domain is already running, the changes will take
|
|
effect on the next boot.
|
|
|
|
=item B<desc> I<domain> [[I<--live>] [I<--config>] |
|
|
[I<--current>]] [I<--title>] [I<--edit>] [I<--new-desc>
|
|
New description or title message]
|
|
|
|
Show or modify description and title of a domain. These values are user
|
|
fields that allow to store arbitrary textual data to allow easy
|
|
identification of domains. Title should be short, although it's not enforced.
|
|
|
|
Flags I<--live> or I<--config> select whether this command works on live
|
|
or persistent definitions of the domain. If both I<--live> and I<--config>
|
|
are specified, the I<--config> option takes precedence on getting the current
|
|
description and both live configuration and config are updated while setting
|
|
the description. I<--current> is exclusive and implied if none of these was
|
|
specified.
|
|
|
|
Flag I<--edit> specifies that an editor with the contents of current
|
|
description or title should be opened and the contents saved back afterwards.
|
|
|
|
Flag I<--title> selects operation on the title field instead of description.
|
|
|
|
If neither of I<--edit> and I<--new-desc> are specified the note or description
|
|
is displayed instead of being modified.
|
|
|
|
=item B<destroy> I<domain> [I<--graceful>]
|
|
|
|
Immediately terminate the domain I<domain>. 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> 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>.
|
|
|
|
If I<--graceful> is specified, don't resort to extreme measures
|
|
(e.g. SIGKILL) when the guest doesn't stop after a reasonable timeout;
|
|
return an error instead.
|
|
|
|
=item B<domblkstat> I<domain> [I<block-device>] [I<--human>]
|
|
|
|
Get device block stats for a running domain. A I<block-device> corresponds
|
|
to a unique target name (<target dev='name'/>) or source file (<source
|
|
file='name'/>) for one of the disk devices attached to I<domain> (see
|
|
also B<domblklist> for listing these names). On a lxc domain, omitting the
|
|
I<block-device> yields device block stats summarily for the entire domain.
|
|
|
|
Use I<--human> for a more human readable output.
|
|
|
|
Availability of these fields depends on hypervisor. Unsupported fields are
|
|
missing from the output. Other fields may appear if communicating with a newer
|
|
version of libvirtd.
|
|
|
|
B<Explanation of fields> (fields appear in the following order):
|
|
rd_req - count of read operations
|
|
rd_bytes - count of read bytes
|
|
wr_req - count of write operations
|
|
wr_bytes - count of written bytes
|
|
errs - error count
|
|
flush_operations - count of flush operations
|
|
rd_total_times - total time read operations took (ns)
|
|
wr_total_times - total time write operations took (ns)
|
|
flush_total_times - total time flush operations took (ns)
|
|
<-- other fields provided by hypervisor -->
|
|
|
|
=item B<domifstat> I<domain> I<interface-device>
|
|
|
|
Get network interface stats for a running domain.
|
|
|
|
=item B<domif-setlink> I<domain> I<interface-device> I<state> [I<--config>]
|
|
|
|
Modify link state of the domain's virtual interface. Possible values for
|
|
state are "up" and "down. If I<--config> is specified, only the persistent
|
|
configuration of the domain is modified, for compatibility purposes,
|
|
I<--persistent> is alias of I<--config>.
|
|
I<interface-device> can be the interface's target name or the MAC address.
|
|
|
|
=item B<domif-getlink> I<domain> I<interface-device> [I<--config>]
|
|
|
|
Query link state of the domain's virtual interface. If I<--config>
|
|
is specified, query the persistent configuration, for compatibility
|
|
purposes, I<--persistent> is alias of I<--config>.
|
|
|
|
I<interface-device> can be the interface's target name or the MAC address.
|
|
|
|
=item B<domiftune> I<domain> I<interface-device>
|
|
[[I<--config>] [I<--live>] | [I<--current>]]
|
|
[I<--inbound average,peak,burst>]
|
|
[I<--outbound average,peak,burst>]
|
|
|
|
Set or query the domain's network interface's bandwidth parameters.
|
|
I<interface-device> can be the interface's target name (<target dev='name'/>),
|
|
or the MAC address.
|
|
|
|
If no I<--inbound> or I<--outbound> is specified, this command will
|
|
query and show the bandwidth settings. Otherwise, it will set the
|
|
inbound or outbound bandwidth. I<average,peak,burst> is the same as
|
|
in command I<attach-interface>. Values for I<average> and I<peak> are
|
|
expressed in kilobytes per second, while I<burst> is expressed in kilobytes
|
|
in a single burst at -I<peak> speed as described in the Network XML
|
|
documentation at L<http://libvirt.org/formatnetwork.html#elementQoS>.
|
|
|
|
To clear inbound or outbound settings, use I<--inbound> or I<--outbound>
|
|
respectfully with average value of zero.
|
|
|
|
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<dommemstat> I<domain> [I<--period> B<seconds>]
|
|
[[I<--config>] [I<--live>] | [I<--current>]]
|
|
|
|
Get memory stats for a running domain.
|
|
|
|
Depending on the hypervisor a variety of statistics can be returned
|
|
|
|
For QEMU/KVM with a memory balloon, setting the optional I<--period> to a
|
|
value larger than 0 in seconds will allow the balloon driver to return
|
|
additional statistics which will be displayed by subsequent B<dommemstat>
|
|
commands. Setting the I<--period> to 0 will stop the balloon driver collection,
|
|
but does not clear the statistics in the balloon driver. Requires at least
|
|
QEMU/KVM 1.5 to be running on the host.
|
|
|
|
The I<--live>, I<--config>, and I<--current> flags are only valid when using
|
|
the I<--period> option in order to set the collection period for the balloon
|
|
driver. If I<--live> is specified, only the running guest collection period
|
|
is affected. 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 the guest state.
|
|
|
|
=item B<domblkerror> I<domain>
|
|
|
|
Show errors on block devices. This command usually comes handy when
|
|
B<domstate> command says that a domain was paused due to I/O error.
|
|
The B<domblkerror> command lists all block devices in error state and
|
|
the error seen on each of them.
|
|
|
|
=item B<domblkinfo> I<domain> I<block-device>
|
|
|
|
Get block device size info for a domain. A I<block-device> corresponds
|
|
to a unique target name (<target dev='name'/>) or source file (<source
|
|
file='name'/>) for one of the disk devices attached to I<domain> (see
|
|
also B<domblklist> for listing these names).
|
|
|
|
=item B<domblklist> I<domain> [I<--inactive>] [I<--details>]
|
|
|
|
Print a table showing the brief information of all block devices
|
|
associated with I<domain>. If I<--inactive> is specified, query the
|
|
block devices that will be used on the next boot, rather than those
|
|
currently in use by a running domain. If I<--details> is specified,
|
|
disk type and device value will also be printed. Other contexts
|
|
that require a block device name (such as I<domblkinfo> or
|
|
I<snapshot-create> for disk snapshots) will accept either target
|
|
or unique source names printed by this command.
|
|
|
|
=item B<domiflist> I<domain> [I<--inactive>]
|
|
|
|
Print a table showing the brief information of all virtual interfaces
|
|
associated with I<domain>. If I<--inactive> is specified, query the
|
|
virtual interfaces that will be used on the next boot, rather than those
|
|
currently in use by a running domain. Other contexts that require a MAC
|
|
address of virtual interface (such as I<detach-interface> or
|
|
I<domif-setlink>) will accept the MAC address printed by this command.
|
|
|
|
=item B<blockcommit> I<domain> I<path> [I<bandwidth>]
|
|
{[I<base>] | [I<--shallow>]} [I<top>] [I<--delete>]
|
|
[I<--wait> [I<--verbose>] [I<--timeout> B<seconds>] [I<--async>]]
|
|
|
|
Reduce the length of a backing image chain, by committing changes at the
|
|
top of the chain (snapshot or delta files) into backing images. By
|
|
default, this command attempts to flatten the entire chain. If I<base>
|
|
and/or I<top> are specified as files within the backing chain, then the
|
|
operation is constrained to committing just that portion of the chain;
|
|
I<--shallow> can be used instead of I<base> to specify the immediate
|
|
backing file of the resulting top image to be committed. The files
|
|
being committed are rendered invalid, possibly as soon as the operation
|
|
starts; using the I<--delete> flag will remove these files at the successful
|
|
completion of the commit operation.
|
|
|
|
By default, this command returns as soon as possible, and data for
|
|
the entire disk is committed in the background; the progress of the
|
|
operation can be checked with B<blockjob>. However, if I<--wait> is
|
|
specified, then this command will block until the operation completes,
|
|
or cancel the operation if the optional I<timeout> in seconds elapses
|
|
or SIGINT is sent (usually with C<Ctrl-C>). Using I<--verbose> along
|
|
with I<--wait> will produce periodic status updates. If job cancellation
|
|
is triggered, I<--async> will return control to the user as fast as
|
|
possible, otherwise the command may continue to block a little while
|
|
longer until the job is done cleaning up.
|
|
|
|
I<path> specifies fully-qualified path of the disk; it corresponds
|
|
to a unique target name (<target dev='name'/>) or source file (<source
|
|
file='name'/>) for one of the disk devices attached to I<domain> (see
|
|
also B<domblklist> for listing these names).
|
|
I<bandwidth> specifies copying bandwidth limit in MiB/s, although for
|
|
qemu, it may be non-zero only for an online domain.
|
|
|
|
=item B<blockcopy> I<domain> I<path> I<dest> [I<bandwidth>] [I<--shallow>]
|
|
[I<--reuse-external>] [I<--raw>] [I<--wait> [I<--verbose>]
|
|
[{I<--pivot> | I<--finish>}] [I<--timeout> B<seconds>] [I<--async>]]
|
|
|
|
Copy a disk backing image chain to I<dest>. By default, this command
|
|
flattens the entire chain; but if I<--shallow> is specified, the copy
|
|
shares the backing chain.
|
|
|
|
If I<--reuse-external> is specified, then I<dest> must exist and have
|
|
contents identical to the resulting backing file (that is, it must
|
|
start with contents matching the backing file I<disk> if I<--shallow>
|
|
is used, otherwise it must start empty); this option is typically used
|
|
to set up a relative backing file name in the destination.
|
|
|
|
The format of the destination is determined by the first match in the
|
|
following list: if I<--raw> is specified, it will be raw; if
|
|
I<--reuse-external> is specified, the existing destination is probed
|
|
for a format; and in all other cases, the destination format will
|
|
match the source format.
|
|
|
|
By default, the copy job runs in the background, and consists of two
|
|
phases. Initially, the job must copy all data from the source, and
|
|
during this phase, the job can only be canceled to revert back to the
|
|
source disk, with no guarantees about the destination. After this phase
|
|
completes, both the source and the destination remain mirrored until a
|
|
call to B<blockjob> with the I<--abort> and I<--pivot> flags pivots over
|
|
to the copy, or a call without I<--pivot> leaves the destination as a
|
|
faithful copy of that point in time. However, if I<--wait> is specified,
|
|
then this command will block until the mirroring phase begins, or cancel
|
|
the operation if the optional I<timeout> in seconds elapses or SIGINT is
|
|
sent (usually with C<Ctrl-C>). Using I<--verbose> along with I<--wait>
|
|
will produce periodic status updates. Using I<--pivot> or I<--finish>
|
|
along with I<--wait> will additionally end the job cleanly rather than
|
|
leaving things in the mirroring phase. If job cancellation is triggered,
|
|
I<--async> will return control to the user as fast as possible, otherwise
|
|
the command may continue to block a little while longer until the job
|
|
is done cleaning up.
|
|
|
|
I<path> specifies fully-qualified path of the disk.
|
|
I<bandwidth> specifies copying bandwidth limit in MiB/s.
|
|
|
|
=item B<blockpull> I<domain> I<path> [I<bandwidth>] [I<base>]
|
|
[I<--wait> [I<--verbose>] [I<--timeout> B<seconds>] [I<--async>]]
|
|
|
|
Populate a disk from its backing image chain. By default, this command
|
|
flattens the entire chain; but if I<base> is specified, containing the
|
|
name of one of the backing files in the chain, then that file becomes
|
|
the new backing file and only the intermediate portion of the chain is
|
|
pulled. Once all requested data from the backing image chain has been
|
|
pulled, the disk no longer depends on that portion of the backing chain.
|
|
|
|
By default, this command returns as soon as possible, and data for
|
|
the entire disk is pulled in the background; the progress of the
|
|
operation can be checked with B<blockjob>. However, if I<--wait> is
|
|
specified, then this command will block until the operation completes,
|
|
or cancel the operation if the optional I<timeout> in seconds elapses
|
|
or SIGINT is sent (usually with C<Ctrl-C>). Using I<--verbose> along
|
|
with I<--wait> will produce periodic status updates. If job cancellation
|
|
is triggered, I<--async> will return control to the user as fast as
|
|
possible, otherwise the command may continue to block a little while
|
|
longer until the job is done cleaning up.
|
|
|
|
I<path> specifies fully-qualified path of the disk; it corresponds
|
|
to a unique target name (<target dev='name'/>) or source file (<source
|
|
file='name'/>) for one of the disk devices attached to I<domain> (see
|
|
also B<domblklist> for listing these names).
|
|
I<bandwidth> specifies copying bandwidth limit in MiB/s.
|
|
|
|
=item B<blkdeviotune> I<domain> I<device>
|
|
[[I<--config>] [I<--live>] | [I<--current>]]
|
|
[[I<total-bytes-sec>] | [I<read-bytes-sec>] [I<write-bytes-sec>]]
|
|
[[I<total-iops-sec>] | [I<read-iops-sec>] [I<write-iops-sec>]]
|
|
|
|
Set or query the block disk io parameters for a block device of I<domain>.
|
|
I<device> specifies a unique target name (<target dev='name'/>) or source
|
|
file (<source file='name'/>) for one of the disk devices attached to
|
|
I<domain> (see also B<domblklist> for listing these names).
|
|
|
|
If no limit is specified, it will query current I/O limits setting.
|
|
Otherwise, alter the limits with these flags:
|
|
I<--total-bytes-sec> specifies total throughput limit in bytes per second.
|
|
I<--read-bytes-sec> specifies read throughput limit in bytes per second.
|
|
I<--write-bytes-sec> specifies write throughput limit in bytes per second.
|
|
I<--total-iops-sec> specifies total I/O operations limit per second.
|
|
I<--read-iops-sec> specifies read I/O operations limit per second.
|
|
I<--write-iops-sec> specifies write I/O operations limit per second.
|
|
|
|
Older versions of virsh only accepted these options with underscore
|
|
instead of dash, as in I<--total_bytes_sec>.
|
|
|
|
Bytes and iops values are independent, but setting only one value (such
|
|
as --read-bytes-sec) resets the other two in that category to unlimited.
|
|
An explicit 0 also clears any limit. A non-zero value for a given total
|
|
cannot be mixed with non-zero values for read or write.
|
|
|
|
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<blockjob> I<domain> I<path> { [I<--abort>] [I<--async>] [I<--pivot>] |
|
|
[I<--info>] | [I<bandwidth>] }
|
|
|
|
Manage active block operations. There are three modes: I<--info>,
|
|
I<bandwidth>, and I<--abort>; I<--info> is default except that I<--async>
|
|
or I<--pivot> implies I<--abort>.
|
|
|
|
I<path> specifies fully-qualified path of the disk; it corresponds
|
|
to a unique target name (<target dev='name'/>) or source file (<source
|
|
file='name'/>) for one of the disk devices attached to I<domain> (see
|
|
also B<domblklist> for listing these names).
|
|
|
|
If I<--abort> is specified, the active job on the specified disk will
|
|
be aborted. If I<--async> is also specified, this command will return
|
|
immediately, rather than waiting for the cancellation to complete. If
|
|
I<--pivot> is specified, this requests that an active copy job
|
|
be pivoted over to the new copy.
|
|
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<blockresize> I<domain> I<path> I<size>
|
|
|
|
Resize a block device of domain while the domain is running, I<path>
|
|
specifies the absolute path of the block device; it corresponds
|
|
to a unique target name (<target dev='name'/>) or source file (<source
|
|
file='name'/>) for one of the disk devices attached to I<domain> (see
|
|
also B<domblklist> for listing these names).
|
|
|
|
I<size> is a scaled integer (see B<NOTES> above) which defaults to KiB
|
|
(blocks of 1024 bytes) if there is no suffix. You must use a suffix of
|
|
"B" to get bytes (note that for historical reasons, this differs from
|
|
B<vol-resize> which defaults to bytes without a suffix).
|
|
|
|
=item B<domdisplay> I<domain> [I<--include-password>]
|
|
|
|
Output a URI which can be used to connect to the graphical display of the
|
|
domain via VNC, SPICE or RDP. If I<--include-password> is specified, the
|
|
SPICE channel password will be included in the URI.
|
|
|
|
=item B<domfstrim> I<domain> [I<--minimum> B<bytes>]
|
|
[I<--mountpoint mountPoint>]
|
|
|
|
Issue a fstrim command on all mounted filesystems within a running
|
|
domain. It discards blocks which are not in use by the filesystem.
|
|
If I<--minimum> B<bytes> is specified, it tells guest kernel length
|
|
of contiguous free range. Smaller than this may be ignored (this is
|
|
a hint and the guest may not respect it). By increasing this value,
|
|
the fstrim operation will complete more quickly for filesystems
|
|
with badly fragmented free space, although not all blocks will
|
|
be discarded. The default value is zero, meaning "discard
|
|
every free block". Moreover, a if user wants to trim only one mount
|
|
point, it can be specified via optional I<--mountpoint> parameter.
|
|
|
|
=item B<domhostname> I<domain>
|
|
|
|
Returns the hostname of a domain, if the hypervisor makes it available.
|
|
|
|
=item B<dominfo> I<domain>
|
|
|
|
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>
|
|
|
|
Abort the currently running domain job.
|
|
|
|
=item B<domjobinfo> I<domain>
|
|
|
|
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> [I<--reason>]
|
|
|
|
Returns state about a domain. I<--reason> tells virsh to also print
|
|
reason for the state.
|
|
|
|
=item B<domcontrol> I<domain>
|
|
|
|
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. For QEMU/KVM hypervisor,
|
|
the I<format> argument must be B<qemu-argv>. For Xen hypervisor, the
|
|
I<format> argument may be B<xen-xm> or B<xen-sxpr>.
|
|
|
|
=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>. For QEMU/KVM hypervisor,
|
|
the I<format> argument must be B<qemu-argv>. For Xen hypervisor, the
|
|
I<format> argument may be B<xen-xm> or B<xen-sxpr>.
|
|
|
|
=item B<dump> I<domain> I<corefilepath> [I<--bypass-cache>]
|
|
{ [I<--live>] | [I<--crash>] | [I<--reset>] } [I<--verbose>] [I<--memory-only>]
|
|
[I<--format> I<string>]
|
|
|
|
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<--reset> is specified, the domain is reset after successful dump.
|
|
Note, these three switches are mutually exclusive.
|
|
If I<--bypass-cache> is specified, the save will avoid the file system
|
|
cache, although this may slow down the operation.
|
|
If I<--memory-only> is specified, the file is elf file, and will only
|
|
include domain's memory and cpu common register value. It is very
|
|
useful if the domain uses host devices directly.
|
|
I<--format> I<string> is used to specify the format of 'memory-only'
|
|
dump, and I<string> can be one of them: elf, kdump-zlib(kdump-compressed
|
|
format with zlib-compressed), kdump-lzo(kdump-compressed format with
|
|
lzo-compressed), kdump-snappy(kdump-compressed format with snappy-compressed).
|
|
|
|
The progress may be monitored using B<domjobinfo> virsh command and canceled
|
|
with B<domjobabort> command (sent by another virsh instance). Another option
|
|
is to send SIGINT (usually with C<Ctrl-C>) to the virsh process running
|
|
B<dump> command. I<--verbose> displays the progress of dump.
|
|
|
|
NOTE: Some hypervisors may require the user to manually ensure proper
|
|
permissions on file and path specified by argument I<corefilepath>.
|
|
|
|
=item B<dumpxml> I<domain> [I<--inactive>] [I<--security-info>]
|
|
[I<--update-cpu>] [I<--migratable>]
|
|
|
|
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. With I<--migratable> one can request an XML that is suitable for
|
|
migrations, i.e., compatible with older libvirt releases and possibly amended
|
|
with internal run-time options. This option may automatically enable other
|
|
options (I<--update-cpu>, I<--security-info>, ...) as necessary.
|
|
|
|
=item B<edit> I<domain>
|
|
|
|
Edit the XML configuration file for a domain, which will affect the
|
|
next boot of the guest.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh dumpxml --inactive --security-info 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<event> {[I<domain>] { I<event> | I<--all> } [I<--loop>]
|
|
[I<--timeout> I<seconds>] | I<--list>}
|
|
|
|
Wait for a class of domain events to occur, and print appropriate details
|
|
of events as they happen. The events can optionally be filtered by
|
|
I<domain>. Using I<--list> as the only argument will provide a list
|
|
of possible I<event> values known by this client, although the connection
|
|
might not allow registering for all these events. It is also possible
|
|
to use I<--all> instead of I<event> to register for all possible event
|
|
types at once.
|
|
|
|
By default, this command is one-shot, and returns success once an event
|
|
occurs; you can send SIGINT (usually via C<Ctrl-C>) to quit immediately.
|
|
If I<--timeout> is specified, the command gives up waiting for events
|
|
after I<seconds> have elapsed. With I<--loop>, the command prints all
|
|
events until a timeout or interrupt key.
|
|
|
|
=item B<managedsave> I<domain> [I<--bypass-cache>]
|
|
[{I<--running> | I<--paused>}] [I<--verbose>]
|
|
|
|
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.
|
|
|
|
The progress may be monitored using B<domjobinfo> virsh command and canceled
|
|
with B<domjobabort> command (sent by another virsh instance). Another option
|
|
is to send SIGINT (usually with C<Ctrl-C>) to the virsh process running
|
|
B<managedsave> command. I<--verbose> displays the progress of save.
|
|
|
|
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>
|
|
|
|
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<cpu-stats> I<domain> [I<--total>] [I<start>] [I<count>]
|
|
|
|
Provide cpu statistics information of a domain. The domain should
|
|
be running. Default it shows stats for all CPUs, and a total. Use
|
|
I<--total> for only the total stats, I<start> for only the per-cpu
|
|
stats of the CPUs from I<start>, I<count> for only I<count> CPUs'
|
|
stats.
|
|
|
|
=item B<migrate> [I<--live>] [I<--offline>] [I<--direct>] [I<--p2p> [I<--tunnelled>]]
|
|
[I<--persistent>] [I<--undefinesource>] [I<--suspend>] [I<--copy-storage-all>]
|
|
[I<--copy-storage-inc>] [I<--change-protection>] [I<--unsafe>] [I<--verbose>]
|
|
[I<--compressed>] [I<--abort-on-error>]
|
|
I<domain> I<desturi> [I<migrateuri>] [I<graphicsuri>] [I<listen-address>]
|
|
[I<dname>] [I<--timeout> B<seconds>] [I<--xml> B<file>]
|
|
|
|
Migrate domain to another host. Add I<--live> for live migration; <--p2p>
|
|
for peer-2-peer migration; I<--direct> for direct migration; or I<--tunnelled>
|
|
for tunnelled migration. I<--offline> migrates domain definition without
|
|
starting the domain on destination and without stopping it on source host.
|
|
Offline migration may be used with inactive domains and it must be used with
|
|
I<--persistent> option. 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).
|
|
In both cases the disk images have to exist on destination host, the
|
|
I<--copy-storage-...> options only tell libvirt to transfer data from the
|
|
images on source host to the images found at the same place on the destination
|
|
host. 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. I<--compressed>
|
|
activates compression of memory pages that have to be transferred repeatedly
|
|
during live migration. I<--abort-on-error> cancels the migration if a soft
|
|
error (for example I/O error) happens during the migration.
|
|
|
|
B<Note>: Individual hypervisors usually do not support all possible types of
|
|
migration. For example, QEMU does not support direct migration.
|
|
|
|
In some cases libvirt may refuse to migrate the domain because doing so may
|
|
lead to potential problems such as data corruption, and thus the migration is
|
|
considered unsafe. For QEMU domain, this may happen if the domain uses disks
|
|
without explicitly setting cache mode to "none". Migrating such domains is
|
|
unsafe unless the disk images are stored on coherent clustered filesystem,
|
|
such as GFS2 or GPFS. If you are sure the migration is safe or you just do not
|
|
care, use I<--unsafe> to force the migration.
|
|
|
|
The I<desturi> is the connection URI of the destination host, and
|
|
I<migrateuri> is the migration URI, which usually can be omitted (see below).
|
|
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>.
|
|
|
|
Running migration can be canceled by interrupting virsh (usually using
|
|
C<Ctrl-C>) or by B<domjobabort> command sent from another virsh instance.
|
|
|
|
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
|
|
|
|
When I<migrateuri> is not specified, libvirt will automatically determine the
|
|
hypervisor specific URI, by looking up the target host's configured hostname.
|
|
There are a few scenarios where specifying I<migrateuri> may help:
|
|
|
|
=over 4
|
|
|
|
=item * The configured hostname is incorrect, or DNS is broken. If a host has a
|
|
hostname which will not resolve to match one of its public IP addresses, then
|
|
libvirt will generate an incorrect URI. In this case I<migrateuri> should be
|
|
explicitly specified, using an IP address, or a correct hostname.
|
|
|
|
=item * The host has multiple network interfaces. If a host has multiple network
|
|
interfaces, it might be desirable for the migration data stream to be sent over
|
|
a specific interface for either security or performance reasons. In this case
|
|
I<migrateuri> should be explicitly specified, using an IP address associated
|
|
with the network to be used.
|
|
|
|
=item * The firewall restricts what ports are available. When libvirt generates
|
|
a migration URI, it will pick a port number using hypervisor specific rules.
|
|
Some hypervisors only require a single port to be open in the firewalls, while
|
|
others require a whole range of port numbers. In the latter case I<migrateuri>
|
|
might be specified to choose a specific port number outside the default range in
|
|
order to comply with local firewall policies.
|
|
|
|
=back
|
|
|
|
Optional I<graphicsuri> overrides connection parameters used for automatically
|
|
reconnecting a graphical clients at the end of migration. If omitted, libvirt
|
|
will compute the parameters based on target host IP address. In case the
|
|
client does not have a direct access to the network virtualization hosts are
|
|
connected to and needs to connect through a proxy, I<graphicsuri> may be used
|
|
to specify the address the client should connect to. The URI is formed as
|
|
follows:
|
|
|
|
protocol://hostname[:port]/[?parameters]
|
|
|
|
where protocol is either "spice" or "vnc" and parameters is a list of protocol
|
|
specific parameters separated by '&'. Currently recognized parameters are
|
|
"tlsPort" and "tlsSubject". For example,
|
|
|
|
spice://target.host.com:1234/?tlsPort=4567
|
|
|
|
Optional I<listen-address> sets the listen address that hypervisor on the
|
|
destination side should bind to for incoming migration. Both IPv4 and IPv6
|
|
addresses are accepted as well as hostnames (the resolving is done on
|
|
destination). Some hypervisors do not support this feature and will return an
|
|
error if this parameter is used.
|
|
|
|
=item B<migrate-setmaxdowntime> I<domain> 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-compcache> I<domain> [I<--size> B<bytes>]
|
|
|
|
Sets and/or gets size of the cache (in bytes) used for compressing repeatedly
|
|
transferred memory pages during live migration. When called without I<size>,
|
|
the command just prints current size of the compression cache. When I<size>
|
|
is specified, the hypervisor is asked to change compression cache to I<size>
|
|
bytes and then the current size is printed (the result may differ from the
|
|
requested size due to rounding done by the hypervisor). The I<size> option
|
|
is supposed to be used while the domain is being live-migrated as a reaction
|
|
to migration progress and increasing number of compression cache misses
|
|
obtained from domjobinfo.
|
|
|
|
=item B<migrate-setspeed> I<domain> I<bandwidth>
|
|
|
|
Set the maximum migration bandwidth (in MiB/s) for a domain which is being
|
|
migrated to another host.
|
|
|
|
=item B<migrate-getspeed> I<domain>
|
|
|
|
Get the maximum migration bandwidth (in MiB/s) for a domain.
|
|
|
|
=item B<numatune> I<domain> [I<--mode> B<mode>] [I<--nodeset> B<nodeset>]
|
|
[[I<--config>] [I<--live>] | [I<--current>]]
|
|
|
|
Set or get a domain's numa parameters, corresponding to the <numatune>
|
|
element of domain XML. Without flags, the current settings are
|
|
displayed.
|
|
|
|
I<mode> can be one of `strict', `interleave' and `preferred'. For a
|
|
running domain, the mode can't be changed, and the nodeset can be
|
|
changed only if the domain was started with a mode of `strict'.
|
|
|
|
I<nodeset> is a list of numa nodes used by the host for running the domain.
|
|
Its syntax is a comma separated list, with '-' for ranges and '^' for
|
|
excluding a node.
|
|
|
|
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.
|
|
|
|
=item B<reboot> I<domain> [I<--mode MODE-LIST>]
|
|
|
|
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.
|
|
|
|
By default the hypervisor will try to pick a suitable shutdown
|
|
method. To specify an alternative method, the I<--mode> parameter
|
|
can specify a comma separated list which includes C<acpi>, C<agent>,
|
|
C<initctl> and C<signal>. The order in which drivers will try each
|
|
mode is undefined, and not related to the order specified to virsh.
|
|
For strict control over ordering, use a single mode at a time and
|
|
repeat the command.
|
|
|
|
=item B<reset> I<domain>
|
|
|
|
Reset a domain immediately without any guest shutdown. B<reset>
|
|
emulates the power reset button on a machine, where all guest
|
|
hardware sees the RST line set and reinitializes internal state.
|
|
|
|
B<Note>: Reset without any guest OS shutdown risks data loss.
|
|
|
|
=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> I<state-file> [I<--bypass-cache>] [I<--xml> B<file>]
|
|
[{I<--running> | I<--paused>}] [I<--verbose>]
|
|
|
|
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.
|
|
|
|
The progress may be monitored using B<domjobinfo> virsh command and canceled
|
|
with B<domjobabort> command (sent by another virsh instance). Another option
|
|
is to send SIGINT (usually with C<Ctrl-C>) to the virsh process running
|
|
B<save> command. I<--verbose> displays the progress of save.
|
|
|
|
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<domain> [[I<--config>] [I<--live>] | [I<--current>]]
|
|
[[I<--set>] B<parameter=value>]...
|
|
|
|
=item B<schedinfo> [I<--weight> B<number>] [I<--cap> B<number>]
|
|
I<domain>
|
|
|
|
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,
|
|
emulator_period, emulator_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. On the Linux kernel, the
|
|
values 0 and 1 are automatically converted to a minimal value of 2.
|
|
|
|
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/emulator_period parameters have a valid value range
|
|
of 1000-1000000 or 0, and the vcpu_quota/emulator_quota parameters have 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> [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<send-key> I<domain> [I<--codeset> B<codeset>]
|
|
[I<--holdtime> B<holdtime>] I<keycode>...
|
|
|
|
Parse the I<keycode> sequence as keystrokes to send to I<domain>.
|
|
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.
|
|
|
|
If multiple keycodes are specified, they are all sent simultaneously
|
|
to the guest, and they may be received in random order. If you need
|
|
distinct keypresses, you must use multiple send-key invocations.
|
|
|
|
=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<xt_kbd>
|
|
|
|
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. these
|
|
# are all pressed simultaneously and may be received by the guest
|
|
# in random order
|
|
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<send-process-signal> I<domain-id> I<pid> I<signame>
|
|
|
|
Send a signal I<signame> to the process identified by I<pid> running in
|
|
the virtual domain I<domain-id>. The I<pid> is a process ID in the virtual
|
|
domain namespace.
|
|
|
|
The I<signame> argument may be either an integer signal constant number,
|
|
or one of the symbolic names:
|
|
|
|
"nop", "hup", "int", "quit", "ill",
|
|
"trap", "abrt", "bus", "fpe", "kill",
|
|
"usr1", "segv", "usr2", "pipe", "alrm",
|
|
"term", "stkflt", "chld", "cont", "stop",
|
|
"tstp", "ttin", "ttou", "urg", "xcpu",
|
|
"xfsz", "vtalrm", "prof", "winch", "poll",
|
|
"pwr", "sys", "rt0", "rt1", "rt2", "rt3",
|
|
"rt4", "rt5", "rt6", "rt7", "rt8", "rt9",
|
|
"rt10", "rt11", "rt12", "rt13", "rt14", "rt15",
|
|
"rt16", "rt17", "rt18", "rt19", "rt20", "rt21",
|
|
"rt22", "rt23", "rt24", "rt25", "rt26", "rt27",
|
|
"rt28", "rt29", "rt30", "rt31", "rt32"
|
|
|
|
The symbol name may optionally be prefixed with 'sig' or 'sig_' and
|
|
may be in uppercase or lowercase.
|
|
|
|
B<Examples>
|
|
virsh send-process-signal myguest 1 15
|
|
virsh send-process-signal myguest 1 term
|
|
virsh send-process-signal myguest 1 sigterm
|
|
virsh send-process-signal myguest 1 SIG_HUP
|
|
|
|
=item B<setmem> I<domain> B<size> [[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.
|
|
|
|
I<size> is a scaled integer (see B<NOTES> above); it defaults to kibibytes
|
|
(blocks of 1024 bytes) unless you provide a suffix (and the older option
|
|
name I<--kilobytes> is available as a deprecated synonym) . Libvirt rounds
|
|
up to the nearest kibibyte. Some hypervisors require a larger granularity
|
|
than KiB, and requests that are not an even multiple will be rounded up.
|
|
For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
|
|
|
|
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> B<size> [[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<--config> flags may be given, but I<--current> is
|
|
exclusive. If no flag is specified, behavior is different depending
|
|
on hypervisor.
|
|
|
|
Some hypervisors such as QEMU/KVM don't support live changes (especially
|
|
increasing) of the maximum memory limit.
|
|
|
|
I<size> is a scaled integer (see B<NOTES> above); it defaults to kibibytes
|
|
(blocks of 1024 bytes) unless you provide a suffix (and the older option
|
|
name I<--kilobytes> is available as a deprecated synonym) . Libvirt rounds
|
|
up to the nearest kibibyte. Some hypervisors require a larger granularity
|
|
than KiB, and requests that are not an even multiple will be rounded up.
|
|
For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
|
|
|
|
=item B<memtune> I<domain> [I<--hard-limit> B<size>]
|
|
[I<--soft-limit> B<size>] [I<--swap-hard-limit> B<size>]
|
|
[I<--min-guarantee> B<size>] [[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>.
|
|
I<--min-guarantee> is supported only by ESX hypervisor. Each of these
|
|
limits are scaled integers (see B<NOTES> above), with a default of
|
|
kibibytes (blocks of 1024 bytes) if no suffix is present. Libvirt rounds
|
|
up to the nearest kibibyte. Some hypervisors require a larger granularity
|
|
than KiB, and requests that are not an even multiple will be rounded up.
|
|
For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
|
|
|
|
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, 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.
|
|
|
|
=item I<--soft-limit>
|
|
|
|
The memory limit to enforce during memory contention.
|
|
|
|
=item I<--swap-hard-limit>
|
|
|
|
The maximum memory plus swap the guest can use. This has to be more
|
|
than hard-limit value provided.
|
|
|
|
=item I<--min-guarantee>
|
|
|
|
The guaranteed minimum memory allocation for the guest.
|
|
|
|
=back
|
|
|
|
Specifying -1 as a value for these limits is interpreted as unlimited.
|
|
|
|
=item B<blkiotune> I<domain> [I<--weight> B<weight>]
|
|
[I<--device-weights> B<device-weights>]
|
|
[I<--device-read-iops-sec> B<device-read-iops-sec>]
|
|
[I<--device-write-iops-sec> B<device-write-iops-sec>]
|
|
[I<--device-read-bytes-sec> B<device-read-bytes-sec>]
|
|
[I<--device-write-bytes-sec> B<device-write-bytes-sec>]
|
|
[[I<--config>] [I<--live>] | [I<--current>]]
|
|
|
|
Display or set the blkio parameters. QEMU/KVM supports I<--weight>.
|
|
I<--weight> is in range [100, 1000]. After kernel 2.6.39, the value
|
|
could be in the range [10, 1000].
|
|
|
|
B<device-weights> is a single string listing one or more device/weight
|
|
pairs, in the format of /path/to/device,weight,/path/to/device,weight.
|
|
Each weight is in the range [100, 1000], [10, 1000] after kernel 2.6.39,
|
|
or the value 0 to remove that device from per-device listings.
|
|
Only the devices listed in the string are modified;
|
|
any existing per-device weights for other devices remain unchanged.
|
|
|
|
B<device-read-iops-sec> is a single string listing one or more device/read_iops_sec
|
|
pairs, int the format of /path/to/device,read_iops_sec,/path/to/device,read_iops_sec.
|
|
Each read_iops_sec is a number which type is unsigned int, value 0 to remove that
|
|
device from per-decice listing.
|
|
Only the devices listed in the string are modified;
|
|
any existing per-device read_iops_sec for other devices remain unchanged.
|
|
|
|
B<device-write-iops-sec> is a single string listing one or more device/write_iops_sec
|
|
pairs, int the format of /path/to/device,write_iops_sec,/path/to/device,write_iops_sec.
|
|
Each write_iops_sec is a number which type is unsigned int, value 0 to remove that
|
|
device from per-decice listing.
|
|
Only the devices listed in the string are modified;
|
|
any existing per-device write_iops_sec for other devices remain unchanged.
|
|
|
|
B<device-read-bytes-sec> is a single string listing one or more device/read_bytes_sec
|
|
pairs, int the format of /path/to/device,read_bytes_sec,/path/to/device,read_bytes_sec.
|
|
Each read_bytes_sec is a number which type is unsigned long long, value 0 to remove
|
|
that device from per-decice listing.
|
|
Only the devices listed in the string are modified;
|
|
any existing per-device read_bytes_sec for other devices remain unchanged.
|
|
|
|
B<device-write-bytes-sec> is a single string listing one or more device/write_bytes_sec
|
|
pairs, int the format of /path/to/device,write_bytes_sec,/path/to/device,write_bytes_sec.
|
|
Each write_bytes_sec is a number which type is unsigned long long, value 0 to remove
|
|
that device from per-decice listing.
|
|
Only the devices listed in the string are modified;
|
|
any existing per-device write_bytes_sec for other devices remain unchanged.
|
|
|
|
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, but I<--current> is
|
|
exclusive. If no flag is specified, behavior is different depending
|
|
on hypervisor.
|
|
|
|
=item B<setvcpus> I<domain> I<count> [I<--maximum>] [[I<--config>]
|
|
[I<--live>] | [I<--current>]] [I<--guest>]
|
|
|
|
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 this command is run
|
|
before the guest has finished booting, the guest may fail to process
|
|
the change.
|
|
|
|
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.
|
|
|
|
If I<--guest> is specified, then the count of cpus is modified in the guest
|
|
instead of the hypervisor. This flag is usable only for live domains
|
|
and may require guest agent to be configured in the guest.
|
|
|
|
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> [I<--mode MODE-LIST>]
|
|
|
|
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> 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>.
|
|
|
|
By default the hypervisor will try to pick a suitable shutdown
|
|
method. To specify an alternative method, the I<--mode> parameter
|
|
can specify a comma separated list which includes C<acpi>, C<agent>,
|
|
C<initctl> and C<signal>. The order in which drivers will try each
|
|
mode is undefined, and not related to the order specified to virsh.
|
|
For strict control over ordering, use a single mode at a time and
|
|
repeat the command.
|
|
|
|
=item B<start> I<domain-name-or-uuid> [I<--console>] [I<--paused>]
|
|
[I<--autodestroy>] [I<--bypass-cache>] [I<--force-boot>] [I<--pass-fds N,M,...>]
|
|
|
|
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.
|
|
|
|
If I<--pass-fds> is specified, the argument is a comma separated list
|
|
of open file descriptors which should be pass on into the guest. The
|
|
file descriptors will be re-numered in the guest, starting from 3. This
|
|
is only supported with container based virtualization.
|
|
|
|
=item B<suspend> I<domain>
|
|
|
|
Suspend a running domain. It is kept in memory but won't be scheduled
|
|
anymore.
|
|
|
|
=item B<resume> I<domain>
|
|
|
|
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<dompmsuspend> I<domain> I<target> [I<--duration>]
|
|
|
|
Suspend a running domain into one of these states (possible I<target>
|
|
values):
|
|
mem equivalent of S3 ACPI state
|
|
disk equivalent of S4 ACPI state
|
|
hybrid RAM is saved to disk but not powered off
|
|
|
|
The I<--duration> argument specifies number of seconds before the domain is
|
|
woken up after it was suspended (see also B<dompmwakeup>). Default is 0 for
|
|
unlimited suspend time. (This feature isn't currently supported by any
|
|
hypervisor driver and 0 should be used.).
|
|
|
|
Note that this command requires a guest agent configured and running in the
|
|
domain's guest OS.
|
|
|
|
Beware that at least for QEMU, the domain's process will be terminated when
|
|
target disk is used and a new process will be launched when libvirt is asked
|
|
to wake up the domain. As a result of this, any runtime changes, such as
|
|
device hotplug or memory settings, are lost unless such changes were made
|
|
with I<--config> flag.
|
|
|
|
|
|
=item B<dompmwakeup> I<domain>
|
|
|
|
Wakeup a domain from pmsuspended state (either suspended by dompmsuspend or
|
|
from the guest itself). Injects a wakeup into the guest that is in pmsuspended
|
|
state, rather than waiting for the previously requested duration (if any) to
|
|
elapse. This operation doesn't not necessarily fail if the domain is running.
|
|
|
|
=item B<ttyconsole> I<domain>
|
|
|
|
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> [I<--managed-save>] [I<--snapshots-metadata>]
|
|
[ {I<--storage> B<volumes> | I<--remove-all-storage>} I<--wipe-storage>]
|
|
|
|
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.
|
|
|
|
The I<--storage> flag takes a parameter B<volumes>, which is a comma separated
|
|
list of volume target names or source paths of storage volumes to be removed
|
|
along with the undefined domain. Volumes can be undefined and thus removed only
|
|
on inactive domains. Volume deletion is only attempted after the domain is
|
|
undefined; if not all of the requested volumes could be deleted, the
|
|
error message indicates what still remains behind. If a volume path is not
|
|
found in the domain definition, it's treated as if the volume was successfully
|
|
deleted. Only volumes managed by libvirt in storage pools can be removed this
|
|
way.
|
|
(See B<domblklist> for list of target names associated to a domain).
|
|
Example: --storage vda,/path/to/storage.img
|
|
|
|
The I<--remove-all-storage> flag specifies that all of the domain's storage
|
|
volumes should be deleted.
|
|
|
|
The flag I<--wipe-storage> specifies that the storage volumes should be
|
|
wiped before removal.
|
|
|
|
NOTE: For an inactive domain, the domain name or UUID must be used as the
|
|
I<domain>.
|
|
|
|
=item B<vcpucount> I<domain> [{I<--maximum> | I<--active>}
|
|
{I<--config> | I<--live> | I<--current>}] [I<--guest>]
|
|
|
|
Print information about the virtual cpu counts of the given
|
|
I<domain>. 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.
|
|
|
|
If I<--guest> is specified, then the count of cpus is reported from
|
|
the perspective of the guest. This flag is usable only for live domains
|
|
and may require guest agent to be configured in the guest.
|
|
|
|
=item B<vcpuinfo> I<domain>
|
|
|
|
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> [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<emulatorpin> I<domain> [I<cpulist>] [[I<--live>] [I<--config>]
|
|
| [I<--current>]]
|
|
|
|
Query or change the pinning of domain's emulator threads to host physical
|
|
CPUs.
|
|
|
|
See B<vcpupin> for I<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.
|
|
|
|
|
|
=item B<vncdisplay> I<domain>
|
|
|
|
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 I<domain> 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> I<FILE>
|
|
[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]]
|
|
|
|
Attach a device to the domain, using a device definition in an XML
|
|
file using a device definition element such as <disk> or <interface>
|
|
as the top-level element. See the documentation at
|
|
L<http://libvirt.org/formatdomain.html#elementsDevices> to learn about
|
|
libvirt XML format for a device. If I<--config> is specified the
|
|
command alters the persistent domain configuration with the device
|
|
attach taking effect the next time libvirt starts the domain.
|
|
For cdrom and floppy devices, this command only replaces the media
|
|
within an existing device; consider using B<update-device> for this
|
|
usage. For passthrough host devices, see also B<nodedev-detach>,
|
|
needed if the device does not use managed mode.
|
|
|
|
If I<--live> is specified, affect a running domain.
|
|
If I<--config> is specified, affect the next startup of a persistent domain.
|
|
If I<--current> is specified, affect the current domain state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. When no flag is specified legacy API is used whose behavior depends
|
|
on the hypervisor driver.
|
|
|
|
For compatibility purposes, I<--persistent> behaves like I<--config> for
|
|
an offline domain, and like I<--live> I<--config> for a running domain.
|
|
|
|
B<Note>: using of partial device definition XML files may lead to unexpected
|
|
results as some fields may be autogenerated and thus match devices other than
|
|
expected.
|
|
|
|
=item B<attach-disk> I<domain> I<source> I<target>
|
|
[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]]
|
|
[I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>]
|
|
[I<--type type>] [I<--mode mode>] [I<--config>] [I<--sourcetype soucetype>]
|
|
[I<--serial serial>] [I<--wwn wwn>] [I<--rawio>]
|
|
[I<--address address>] [I<--multifunction>] [I<--print-xml>]
|
|
|
|
Attach a new disk device to the domain.
|
|
I<source> is path for the files and devices. I<target> controls the bus or
|
|
device under which the disk is exposed to the guest OS. It indicates the
|
|
"logical" device name. I<driver> can be I<file>, I<tap> or I<phy> for the Xen
|
|
hypervisor depending on the kind of access; or I<qemu> for the QEMU emulator.
|
|
Further details to the driver can be passed using I<subdriver>. For Xen
|
|
I<subdriver> can be I<aio>, while for QEMU subdriver should match the format
|
|
of the disk source, such as I<raw> or I<qcow2>. Hypervisor default will be
|
|
used if I<subdriver> is not specified. However, the default may not be
|
|
correct, esp. for QEMU as for security reasons it is configured not to detect
|
|
disk formats. I<type> can indicate I<lun>, 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<sourcetype> can indicate the type of source (block|file)
|
|
I<cache> can be one of "default", "none", "writethrough", "writeback",
|
|
"directsync" or "unsafe".
|
|
I<serial> is the serial of disk device. I<wwn> is the wwn of disk device.
|
|
I<rawio> indicates the disk needs rawio capability.
|
|
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.
|
|
I<multifunction> indicates specified pci address is a multifunction pci device
|
|
address.
|
|
|
|
If I<--print-xml> is specified, then the XML of the disk that would be attached
|
|
is printed instead.
|
|
|
|
If I<--live> is specified, affect a running domain.
|
|
If I<--config> is specified, affect the next startup of a persistent domain.
|
|
If I<--current> is specified, affect the current domain state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. When no flag is specified legacy API is used whose behavior depends
|
|
on the hypervisor driver.
|
|
|
|
For compatibility purposes, I<--persistent> behaves like I<--config> for
|
|
an offline domain, and like I<--live> I<--config> for a running domain.
|
|
Likewise, I<--shareable> is an alias for I<--mode shareable>.
|
|
|
|
=item B<attach-interface> I<domain> I<type> I<source>
|
|
[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]]
|
|
[I<--target target>] [I<--mac mac>] [I<--script script>] [I<--model model>]
|
|
[I<--config>] [I<--inbound average,peak,burst>] [I<--outbound average,peak,burst>]
|
|
|
|
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. Names starting with 'vnet' are considered as
|
|
auto-generated an hence blanked out. 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<inbound> and I<outbound> control the bandwidth of the interface.
|
|
I<peak> and I<burst> are optional, so "average,peak", "average,,burst" and
|
|
"average" are also legal. Values for I<average> and I<peak> are
|
|
expressed in kilobytes per second, while I<burst> is expressed in kilobytes
|
|
in a single burst at -I<peak> speed as described in the Network XML
|
|
documentation at L<http://libvirt.org/formatnetwork.html#elementQoS>.
|
|
|
|
If I<--live> is specified, affect a running domain.
|
|
If I<--config> is specified, affect the next startup of a persistent domain.
|
|
If I<--current> is specified, affect the current domain state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. When no flag is specified legacy API is used whose behavior depends
|
|
on the hypervisor driver.
|
|
|
|
For compatibility purposes, I<--persistent> behaves like I<--config> for
|
|
an offline domain, and like I<--live> I<--config> for a running domain.
|
|
|
|
B<Note>: the optional target value is the name of a device to be created
|
|
as the back-end on the node. If not provided a device named "vnetN" or "vifN"
|
|
will be created automatically.
|
|
|
|
=item B<detach-device> I<domain> I<FILE>
|
|
[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]]
|
|
|
|
Detach a device from the domain, takes the same kind of XML descriptions
|
|
as command B<attach-device>.
|
|
For passthrough host devices, see also B<nodedev-reattach>, needed if
|
|
the device does not use managed mode.
|
|
|
|
B<Note>: using of partial device definition XML files may lead to unexpected
|
|
results as some fields may be autogenerated and thus match devices other than
|
|
expected.
|
|
|
|
If I<--live> is specified, affect a running domain.
|
|
If I<--config> is specified, affect the next startup of a persistent domain.
|
|
If I<--current> is specified, affect the current domain state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. When no flag is specified legacy API is used whose behavior depends
|
|
on the hypervisor driver.
|
|
|
|
For compatibility purposes, I<--persistent> behaves like I<--config> for
|
|
an offline domain, and like I<--live> I<--config> for a running domain.
|
|
|
|
Note that older versions of virsh used I<--config> as an alias for
|
|
I<--persistent>.
|
|
|
|
=item B<detach-disk> I<domain> I<target>
|
|
[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]]
|
|
|
|
Detach a disk device from a domain. The I<target> is the device as seen
|
|
from the domain.
|
|
|
|
If I<--live> is specified, affect a running domain.
|
|
If I<--config> is specified, affect the next startup of a persistent domain.
|
|
If I<--current> is specified, affect the current domain state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. When no flag is specified legacy API is used whose behavior depends
|
|
on the hypervisor driver.
|
|
|
|
For compatibility purposes, I<--persistent> behaves like I<--config> for
|
|
an offline domain, and like I<--live> I<--config> for a running domain.
|
|
|
|
Note that older versions of virsh used I<--config> as an alias for
|
|
I<--persistent>.
|
|
|
|
=item B<detach-interface> I<domain> I<type> [I<--mac mac>]
|
|
[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]]
|
|
|
|
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.
|
|
|
|
If I<--live> is specified, affect a running domain.
|
|
If I<--config> is specified, affect the next startup of a persistent domain.
|
|
If I<--current> is specified, affect the current domain state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. When no flag is specified legacy API is used whose behavior depends
|
|
on the hypervisor driver.
|
|
|
|
For compatibility purposes, I<--persistent> behaves like I<--config> for
|
|
an offline domain, and like I<--live> I<--config> for a running domain.
|
|
|
|
Note that older versions of virsh used I<--config> as an alias for
|
|
I<--persistent>.
|
|
|
|
=item B<update-device> I<domain> I<file> [I<--force>]
|
|
[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]]
|
|
|
|
Update the characteristics of a device associated with I<domain>,
|
|
based on the device definition in an XML I<file>. 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 at
|
|
L<http://libvirt.org/formatdomain.html#elementsDevices> to learn about
|
|
libvirt XML format for a device.
|
|
|
|
If I<--live> is specified, affect a running domain.
|
|
If I<--config> is specified, affect the next startup of a persistent domain.
|
|
If I<--current> is specified, affect the current domain state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. Not specifying any flag is the same as specifying I<--current>.
|
|
|
|
For compatibility purposes, I<--persistent> behaves like I<--config> for
|
|
an offline domain, and like I<--live> I<--config> for a running domain.
|
|
|
|
Note that older versions of virsh used I<--config> as an alias for
|
|
I<--persistent>.
|
|
|
|
B<Note>: using of partial device definition XML files may lead to unexpected
|
|
results as some fields may be autogenerated and thus match devices other than
|
|
expected.
|
|
|
|
=item B<change-media> I<domain> I<path> [I<--eject>] [I<--insert>]
|
|
[I<--update>] [I<source>] [I<--force>] [[I<--live>] [I<--config>] | [I<--current>]]
|
|
|
|
Change media of CDROM or floppy drive. I<path> can be the fully-qualified path
|
|
or the unique target name (<target dev='hdc'>) of the disk device. I<source>
|
|
specifies the path of the media to be inserted or updated.
|
|
|
|
I<--eject> indicates the media will be ejected.
|
|
I<--insert> indicates the media will be inserted. I<source> must be specified.
|
|
If the device has source (e.g. <source file='media'>), and I<source> is not
|
|
specified, I<--update> is equal to I<--eject>. If the device has no source,
|
|
and I<source> is specified, I<--update> is equal to I<--insert>. If the device
|
|
has source, and I<source> is specified, I<--update> behaves like combination
|
|
of I<--eject> and I<--insert>.
|
|
If none of I<--eject>, I<--insert>, and I<--update> is specified, I<--update>
|
|
is used by default.
|
|
The I<--force> option can be used to force media changing.
|
|
If I<--live> is specified, alter live configuration of running guest.
|
|
If I<--config> is specified, alter persistent configuration, effect observed
|
|
on next boot.
|
|
I<--current> can be either or both of I<live> and I<config>, depends on
|
|
the hypervisor's implementation.
|
|
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.
|
|
|
|
=back
|
|
|
|
=head1 NODEDEV COMMANDS
|
|
|
|
The following commands manipulate host devices that are intended to be
|
|
passed through to guest domains via <hostdev> elements in a domain's
|
|
<devices> section. A node device key is generally specified by the bus
|
|
name followed by its address, using underscores between all components,
|
|
such as pci_0000_00_02_1, usb_1_5_3, or net_eth1_00_27_13_6a_fe_00.
|
|
The B<nodedev-list> gives the full list of host devices that are known
|
|
to libvirt, although this includes devices that cannot be assigned to
|
|
a guest (for example, attempting to detach the PCI device that controls
|
|
the host's hard disk controller where the guest's disk images live could
|
|
cause the host system to lock up or reboot).
|
|
|
|
For more information on node device definition see:
|
|
L<http://libvirt.org/formatnode.html>.
|
|
|
|
Passthrough devices cannot be simultaneously used by the host and its
|
|
guest domains, nor by multiple active guests at once. If the
|
|
<hostdev> description includes the attribute B<managed='yes'>, and the
|
|
hypervisor driver supports it, then the device is in managed mode, and
|
|
attempts to use that passthrough device in an active guest will
|
|
automatically behave as if B<nodedev-detach> (guest start, device
|
|
hot-plug) and B<nodedev-reattach> (guest stop, device hot-unplug) were
|
|
called at the right points (currently, qemu does this for PCI devices,
|
|
but not USB). If a device is not marked as managed, then it must
|
|
manually be detached before guests can use it, and manually reattached
|
|
to be returned to the host. Also, if a device is manually detached,
|
|
then the host does not regain control of the device without a matching
|
|
reattach, even if the guests use the device in managed mode.
|
|
|
|
=over 4
|
|
|
|
=item B<nodedev-create> I<FILE>
|
|
|
|
Create a device on the host node that can then be assigned to virtual
|
|
machines. Normally, libvirt is able to automatically determine which
|
|
host nodes are available for use, but this allows registration of
|
|
host hardware that libvirt did not automatically detect. I<file>
|
|
contains xml for a top-level <device> description of a node device.
|
|
|
|
=item B<nodedev-destroy> I<device>
|
|
|
|
Destroy (stop) a device on the host. I<device> can be either device
|
|
name or wwn pair in "wwnn,wwpn" format (only works for vHBA currently).
|
|
Note that this makes libvirt quit managing a host device, and may even
|
|
make that device unusable by the rest of the physical host until a reboot.
|
|
|
|
=item B<nodedev-detach> I<nodedev> [I<--driver backend_driver>]
|
|
|
|
Detach I<nodedev> from the host, so that it can safely be used by
|
|
guests via <hostdev> passthrough. This is reversed with
|
|
B<nodedev-reattach>, and is done automatically for managed devices.
|
|
For compatibility purposes, this command can also be spelled
|
|
B<nodedev-dettach>.
|
|
|
|
Different backend drivers expect the device to be bound to different
|
|
dummy devices. For example, QEMU's "kvm" backend driver (the default)
|
|
expects the device to be bound to pci-stub, but its "vfio" backend
|
|
driver expects the device to be bound to vfio-pci. The I<--driver>
|
|
parameter can be used to specify the desired backend driver.
|
|
|
|
=item B<nodedev-dumpxml> I<device>
|
|
|
|
Dump a <device> XML representation for the given node device, including
|
|
such information as the device name, which bus owns the device, the
|
|
vendor and product id, and any capabilities of the device usable by
|
|
libvirt (such as whether device reset is supported). I<device> can
|
|
be either device name or wwn pair in "wwnn,wwpn" format (only works
|
|
for HBA).
|
|
|
|
=item B<nodedev-list> I<cap> I<--tree>
|
|
|
|
List all of the devices available on the node that are known by libvirt.
|
|
I<cap> is used to filter the list by capability types, the types must be
|
|
separated by comma, e.g. --cap pci,scsi, valid capability types include
|
|
'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host', 'scsi_target',
|
|
'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic'. If I<--tree> is
|
|
used, the output is formatted in a tree representing parents of each node.
|
|
I<cap> and I<--tree> are mutually exclusive.
|
|
|
|
=item B<nodedev-reattach> I<nodedev>
|
|
|
|
Declare that I<nodedev> is no longer in use by any guests, and that
|
|
the host can resume normal use of the device. This is done
|
|
automatically for devices in managed mode, but must be done explicitly
|
|
to match any explicit B<nodedev-detach>.
|
|
|
|
=item B<nodedev-reset> I<nodedev>
|
|
|
|
Trigger a device reset for I<nodedev>, useful prior to transferring
|
|
a node device between guest passthrough or the host. Libvirt will
|
|
often do this action implicitly when required, but this command
|
|
allows an explicit reset when needed.
|
|
|
|
=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 transient (temporary) virtual network from an
|
|
XML I<file> and instantiate (start) the network.
|
|
See the documentation at L<http://libvirt.org/formatnetwork.html>
|
|
to get a description of the XML network format used by libvirt.
|
|
|
|
=item B<net-define> I<file>
|
|
|
|
Define a persistent virtual network from an XML I<file>, the network is just
|
|
defined but not instantiated (started).
|
|
|
|
=item B<net-destroy> I<network>
|
|
|
|
Destroy (stop) a given transient or persistent virtual network
|
|
specified by its name or UUID. This takes effect immediately.
|
|
|
|
=item B<net-dumpxml> I<network> [I<--inactive>]
|
|
|
|
Output the virtual network information as an XML dump to stdout.
|
|
If I<--inactive> is specified, then physical functions are not
|
|
expanded into their associated virtual functions.
|
|
|
|
=item B<net-edit> I<network>
|
|
|
|
Edit the XML configuration file for a network.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh net-dumpxml --inactive 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-event> {[I<network>] I<event> [I<--loop>] [I<--timeout>
|
|
I<seconds>] | I<--list>}
|
|
|
|
Wait for a class of network events to occur, and print appropriate details
|
|
of events as they happen. The events can optionally be filtered by
|
|
I<network>. Using I<--list> as the only argument will provide a list
|
|
of possible I<event> values known by this client, although the connection
|
|
might not allow registering for all these events.
|
|
|
|
By default, this command is one-shot, and returns success once an event
|
|
occurs; you can send SIGINT (usually via C<Ctrl-C>) to quit immediately.
|
|
If I<--timeout> is specified, the command gives up waiting for events
|
|
after I<seconds> have elapsed. With I<--loop>, the command prints all
|
|
events until a timeout or interrupt key.
|
|
|
|
=item B<net-info> I<network>
|
|
|
|
Returns basic information about the I<network> object.
|
|
|
|
=item B<net-list> [I<--inactive> | I<--all>]
|
|
[I<--persistent>] [<--transient>]
|
|
[I<--autostart>] [<--no-autostart>]
|
|
|
|
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. You may also want to filter the returned networks
|
|
by I<--persistent> to list the persistent ones, I<--transient> to list the
|
|
transient ones, I<--autostart> to list the ones with autostart enabled, and
|
|
I<--no-autostart> to list the ones with autostart disabled.
|
|
|
|
NOTE: When talking to older servers, this command is forced to use a series of
|
|
API calls with an inherent race, where a pool might not be listed or might appear
|
|
more than once if it changed state between calls while the list was being
|
|
collected. Newer servers do not have this problem.
|
|
|
|
=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.
|
|
|
|
=item B<net-update> I<network> I<command> I<section> I<xml>
|
|
[I<--parent-index> I<index>] [[I<--live>] [I<--config>] | [I<--current>]]
|
|
|
|
Update the given section of an existing network definition, with the
|
|
changes optionally taking effect immediately, without needing to
|
|
destroy and re-start the network.
|
|
|
|
I<command> is one of "add-first", "add-last", "add" (a synonym for
|
|
add-last), "delete", or "modify".
|
|
|
|
I<section> is one of "bridge", "domain", "ip", "ip-dhcp-host",
|
|
"ip-dhcp-range", "forward", "forward-interface", "forward-pf",
|
|
"portgroup", "dns-host", "dns-txt", or "dns-srv", each section being
|
|
named by a concatenation of the xml element hierarchy leading to the
|
|
element being changed. For example, "ip-dhcp-host" will change a
|
|
<host> element that is contained inside a <dhcp> element inside an
|
|
<ip> element of the network.
|
|
|
|
I<xml> is either the text of a complete xml element of the type being
|
|
changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the
|
|
name of a file that contains a complete xml element. Disambiguation is
|
|
done by looking at the first character of the provided text - if the
|
|
first character is "<", it is xml text, if the first character is not
|
|
"<", it is the name of a file that contains the xml text to be used.
|
|
|
|
The I<--parent-index> option is used to specify which of several
|
|
parent elements the requested element is in (0-based). For example, a
|
|
dhcp <host> element could be in any one of multiple <ip> elements in
|
|
the network; if a parent-index isn't provided, the "most appropriate"
|
|
<ip> element will be selected (usually the only one that already has a
|
|
<dhcp> element), but if I<--parent-index> is given, that particular
|
|
instance of <ip> will get the modification.
|
|
|
|
If I<--live> is specified, affect a running network.
|
|
If I<--config> is specified, affect the next startup of a persistent network.
|
|
If I<--current> is specified, affect the current network state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. Not specifying any flag is the same as specifying I<--current>.
|
|
|
|
=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-bridge> I<interface> I<bridge> [I<--no-stp>] [I<delay>]
|
|
[I<--no-start>]
|
|
|
|
Create a bridge device named I<bridge>, and attach the existing
|
|
network device I<interface> to the new bridge. The new bridge
|
|
defaults to starting immediately, with STP enabled and a delay of 0;
|
|
these settings can be altered with I<--no-stp>, I<--no-start>, and an
|
|
integer number of seconds for I<delay>. All IP address configuration
|
|
of I<interface> will be moved to the new bridge device.
|
|
|
|
See also B<iface-unbridge> for undoing this operation.
|
|
|
|
=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-unbridge> I<bridge> [I<--no-start>]
|
|
|
|
Tear down a bridge device named I<bridge>, releasing its underlying
|
|
interface back to normal usage, and moving all IP address
|
|
configuration from the bridge device to the underlying device. The
|
|
underlying interface is restarted unless I<--no-start> is present;
|
|
this flag is present for symmetry, but generally not recommended.
|
|
|
|
See also B<iface-bridge> for creating a bridge.
|
|
|
|
=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<--inactive>] I<pool-or-uuid>
|
|
|
|
Returns the XML information about the I<pool> object.
|
|
I<--inactive> tells virsh to dump pool configuration that will be used
|
|
on next start of the pool as opposed to the current pool configuration.
|
|
|
|
=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<--persistent>] [I<--transient>]
|
|
[I<--autostart>] [I<--no-autostart>]
|
|
[[I<--details>] [<type>]
|
|
|
|
List pool objects known to libvirt. By default, only active pools
|
|
are listed; I<--inactive> lists just the inactive pools, and I<--all>
|
|
lists all pools.
|
|
|
|
In addition, there are several sets of filtering flags. I<--persistent> is to
|
|
list the persistent pools, I<--transient> is to list the transient pools.
|
|
I<--autostart> lists the autostarting pools, I<--no-autostart> lists the pools
|
|
with autostarting disabled.
|
|
|
|
You may also want to list pools with specified types using I<type>, the
|
|
pool types must be separated by comma, e.g. --type dir,disk. The valid pool
|
|
types include 'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi', 'scsi',
|
|
'mpath', 'rbd', 'sheepdog' and 'gluster'.
|
|
|
|
The I<--details> option instructs virsh to additionally
|
|
display pool persistence and capacity related information where available.
|
|
|
|
NOTE: When talking to older servers, this command is forced to use a series of
|
|
API calls with an inherent race, where a pool might not be listed or might appear
|
|
more than once if it changed state between calls while the list was being
|
|
collected. Newer servers do not have this problem.
|
|
|
|
=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.
|
|
|
|
B<Note>: A storage pool that relies on remote resources such as an
|
|
"iscsi" or a (v)HBA backed "scsi" pool may need to be refreshed multiple
|
|
times in order to have all the volumes detected (see B<pool-refresh>).
|
|
This is because the corresponding volume devices may not be present in
|
|
the host's filesystem during the initial pool startup or the current
|
|
refresh attempt. The number of refresh retries is dependant upon the
|
|
network connection and the time the host takes to export the
|
|
corresponding devices.
|
|
|
|
=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> [I<--prealloc-metadata>]
|
|
|
|
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.
|
|
[I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't
|
|
support full allocation). This option creates a sparse image file with metadata,
|
|
resulting in higher performance compared to images with no preallocation and
|
|
only slightly higher initial disk space usage.
|
|
|
|
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> [I<--prealloc-metadata>]
|
|
|
|
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.
|
|
[I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't
|
|
support full allocation). This option creates a sparse image file with metadata,
|
|
resulting in higher performance compared to images with no preallocation and
|
|
only slightly higher initial disk space usage.
|
|
|
|
=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>]
|
|
[I<--prealloc-metadata>]
|
|
|
|
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, as a scaled integer
|
|
(see B<NOTES> above), defaulting to bytes if there is no suffix.
|
|
I<--allocation> I<size> is the initial size to be allocated in the volume,
|
|
also as a scaled integer defaulting to bytes.
|
|
I<--format> I<string> is used in file based storage pools to specify the volume
|
|
file format to use; raw, bochs, qcow, qcow2, vmdk, qed.
|
|
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, qed, vmdk, host_device. These are, however, meant for
|
|
file based storage pools.
|
|
[I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't
|
|
support full allocation). This option creates a sparse image file with metadata,
|
|
resulting in higher performance compared to images with no preallocation and
|
|
only slightly higher initial disk space usage.
|
|
|
|
=item B<vol-clone> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
I<name> [I<--prealloc-metadata>]
|
|
|
|
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.
|
|
[I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't
|
|
support full allocation). This option creates a sparse image file with metadata,
|
|
resulting in higher performance compared to images with no preallocation and
|
|
only slightly higher initial disk space usage.
|
|
|
|
=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 where the
|
|
file will be uploaded.
|
|
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 occur 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 a storage volume to I<local-file>.
|
|
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 download.
|
|
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<--algorithm> I<algorithm>]
|
|
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.
|
|
It is possible to choose different wiping algorithms instead of re-writing
|
|
volume with zeroes. This can be done via I<--algorithm> switch.
|
|
|
|
B<Supported algorithms>
|
|
zero - 1-pass all zeroes
|
|
nnsa - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for
|
|
sanitizing removable and non-removable hard disks:
|
|
random x2, 0x00, verify.
|
|
dod - 4-pass DoD 5220.22-M section 8-306 procedure for
|
|
sanitizing removable and non-removable rigid
|
|
disks: random, 0x00, 0xff, verify.
|
|
bsi - 9-pass method recommended by the German Center of
|
|
Security in Information Technologies
|
|
(http://www.bsi.bund.de): 0xff, 0xfe, 0xfd, 0xfb,
|
|
0xf7, 0xef, 0xdf, 0xbf, 0x7f.
|
|
gutmann - The canonical 35-pass sequence described in
|
|
Gutmann's paper.
|
|
schneier - 7-pass method described by Bruce Schneier in
|
|
"Applied Cryptography" (1996): 0x00, 0xff,
|
|
random x5.
|
|
pfitzner7 - Roy Pfitzner's 7-random-pass method: random x7.
|
|
pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
|
|
random - 1-pass pattern: random.
|
|
|
|
B<Note>: The availability of algorithms may be limited by the version
|
|
of the C<scrub> binary installed on the host.
|
|
|
|
=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.
|
|
|
|
=item B<vol-resize> [I<--pool> I<pool-or-uuid>] I<vol-name-or-path>
|
|
I<pool-or-uuid> I<capacity> [I<--allocate>] [I<--delta>] [I<--shrink>]
|
|
|
|
Resize the capacity of the given volume, in bytes.
|
|
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 resize. The new capacity might be sparse unless I<--allocate> is
|
|
specified. Normally, I<capacity> is the new size, but if I<--delta>
|
|
is present, then it is added to the existing size. Attempts to shrink
|
|
the volume will fail unless I<--shrink> is present; I<capacity> cannot
|
|
be negative unless I<--shrink> is provided, but a negative sign is not
|
|
necessary. I<capacity> is a scaled integer (see B<NOTES> above), which
|
|
defaults to bytes if there is no suffix. This command is only safe
|
|
for storage volumes not in use by an active guest; see also
|
|
B<blockresize> for live resizing.
|
|
|
|
=back
|
|
|
|
=head1 SECRET COMMANDS
|
|
|
|
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 a 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 a 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> [I<--ephemeral>] [I<--no-ephemeral>]
|
|
[I<--private>] [I<--no-private>]
|
|
|
|
Returns the list of secrets. You may also want to filter the returned secrets
|
|
by I<--ephemeral> to list the ephemeral ones, I<--no-ephemeral> to list the
|
|
non-ephemeral ones, I<--private> to list the private ones, and
|
|
I<--no-private> to list the non-private ones.
|
|
|
|
=back
|
|
|
|
=head1 SNAPSHOT COMMANDS
|
|
|
|
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>] [I<--halt>] [I<--disk-only>] [I<--reuse-external>]
|
|
[I<--quiesce>] [I<--atomic>] [I<--live>]}
|
|
|
|
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, as well as <disks> if
|
|
I<--disk-only> is given; 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<--halt> is specified, the domain will be left in an inactive state
|
|
after the snapshot is created.
|
|
|
|
If I<--disk-only> is specified, the snapshot will only include disk
|
|
state rather than the usual system checkpoint with vm state. Disk
|
|
snapshots are faster than full system checkpoints, but reverting to a
|
|
disk snapshot may require fsck or journal replays, since it is like
|
|
the disk state at the point when the power cord is abruptly pulled;
|
|
and mixing I<--halt> and I<--disk-only> loses any data that was not
|
|
flushed to disk at the time.
|
|
|
|
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).
|
|
|
|
If I<--reuse-external> is specified, and the snapshot XML requests an
|
|
external snapshot with a destination of an existing file, then the
|
|
destination must exist, and is reused; otherwise, a snapshot is refused
|
|
to avoid losing contents of the existing files.
|
|
|
|
If I<--quiesce> is specified, libvirt will try to use guest agent
|
|
to freeze and unfreeze domain's mounted file systems. However,
|
|
if domain has no guest agent, snapshot creation will fail.
|
|
Currently, this requires I<--disk-only> to be passed as well.
|
|
|
|
If I<--atomic> is specified, libvirt will guarantee that the snapshot
|
|
either succeeds, or fails with no changes; not all hypervisors support
|
|
this. If this flag is not specified, then some hypervisors may fail
|
|
after partially performing the action, and B<dumpxml> must be used to
|
|
see whether any partial changes occurred.
|
|
|
|
If I<--live> is specified, libvirt takes the snapshot while the guest is
|
|
running. This increases the size of the memory image of the external
|
|
checkpoint. This is currently supported only for external checkpoints.
|
|
|
|
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<--halt>] [I<--reuse-external>]} [I<name>]
|
|
[I<description>] [I<--disk-only> [I<--quiesce>]] [I<--atomic>]
|
|
[[I<--live>] [I<--memspec> B<memspec>]] [I<--diskspec>] B<diskspec>]...
|
|
|
|
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.
|
|
Otherwise, if I<--halt> is specified, the domain will be left in an
|
|
inactive state after the snapshot is created, and if I<--disk-only>
|
|
is specified, the snapshot will not include vm state.
|
|
|
|
The I<--memspec> option can be used to control whether a checkpoint
|
|
is internal or external. The I<--memspec> flag is mandatory, followed
|
|
by a B<memspec> of the form B<[file=]name[,snapshot=type]>, where
|
|
type can be B<no>, B<internal>, or B<external>. To include a literal
|
|
comma in B<file=name>, escape it with a second comma. I<--memspec> cannot
|
|
be used together with I<--disk-only>.
|
|
|
|
The I<--diskspec> option can be used to control how I<--disk-only> and
|
|
external checkpoints create external files. This option can occur
|
|
multiple times, according to the number of <disk> elements in the domain
|
|
xml. Each <diskspec> is in the
|
|
form B<disk[,snapshot=type][,driver=type][,file=name]>. To include a
|
|
literal comma in B<disk> or in B<file=name>, escape it with a second
|
|
comma. A literal I<--diskspec> must precede each B<diskspec> unless
|
|
all three of I<domain>, I<name>, and I<description> are also present.
|
|
For example, a diskspec of "vda,snapshot=external,file=/path/to,,new"
|
|
results in the following XML:
|
|
<disk name='vda' snapshot='external'>
|
|
<source file='/path/to,new'/>
|
|
</disk>
|
|
|
|
If I<--reuse-external> is specified, and the domain XML or I<diskspec>
|
|
option requests an external snapshot with a destination of an existing
|
|
file, then the destination must exist, and is reused; otherwise, a
|
|
snapshot is refused to avoid losing contents of the existing files.
|
|
|
|
If I<--quiesce> is specified, libvirt will try to use guest agent
|
|
to freeze and unfreeze domain's mounted file systems. However,
|
|
if domain has no guest agent, snapshot creation will fail.
|
|
Currently, this requires I<--disk-only> to be passed as well.
|
|
|
|
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>.
|
|
|
|
If I<--atomic> is specified, libvirt will guarantee that the snapshot
|
|
either succeeds, or fails with no changes; not all hypervisors support
|
|
this. If this flag is not specified, then some hypervisors may fail
|
|
after partially performing the action, and B<dumpxml> must be used to
|
|
see whether any partial changes occurred.
|
|
|
|
If I<--live> is specified, libvirt takes the snapshot while the guest is
|
|
running. This increases the size of the memory image of the external
|
|
checkpoint. This is currently supported only for external checkpoints.
|
|
|
|
=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>]
|
|
{[I<--rename>] | [I<--clone>]}
|
|
|
|
Edit the XML configuration file for I<snapshotname> of a domain. If
|
|
both I<snapshotname> and I<--current> are specified, also force the
|
|
edited snapshot to become the current snapshot. If I<snapshotname>
|
|
is omitted, then I<--current> must be supplied, to edit 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>.
|
|
|
|
If I<--rename> is specified, then the edits can change the snapshot
|
|
name. If I<--clone> is specified, then changing the snapshot name
|
|
will create a clone of the snapshot metadata. If neither is specified,
|
|
then the edits must not change the snapshot name. Note that changing
|
|
a snapshot name must be done with care, since the contents of some
|
|
snapshots, such as internal snapshots within a single qcow2 file, are
|
|
accessible only from the original name.
|
|
|
|
=item B<snapshot-info> I<domain> {I<snapshot> | I<--current>}
|
|
|
|
Output basic information about a named <snapshot>, or the current snapshot
|
|
with I<--current>.
|
|
|
|
=item B<snapshot-list> I<domain> [I<--metadata>] [I<--no-metadata>]
|
|
[{I<--parent> | I<--roots> | [{I<--tree> | I<--name>}]}]
|
|
[{[I<--from>] B<snapshot> | I<--current>} [I<--descendants>]]
|
|
[I<--leaves>] [I<--no-leaves>] [I<--inactive>] [I<--active>]
|
|
[I<--disk-only>] [I<--internal>] [I<--external>]
|
|
|
|
List all of the available snapshots for the given domain, defaulting
|
|
to show columns for the snapshot name, creation time, and domain state.
|
|
|
|
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.
|
|
If I<--tree> is specified, the output will be in a tree format, listing
|
|
just snapshot names. These three options are mutually exclusive. If
|
|
I<--name> is specified only the snapshot name is printed. This option is
|
|
mutually exclusive with I<--tree>.
|
|
|
|
If I<--from> is provided, filter the list to snapshots which are
|
|
children of the given B<snapshot>; or if I<--current> is provided,
|
|
start at the current snapshot. When used in isolation or with
|
|
I<--parent>, the list is limited to direct children unless
|
|
I<--descendants> is also present. When used with I<--tree>, the
|
|
use of I<--descendants> is implied. This option is not compatible
|
|
with I<--roots>. Note that the starting point of I<--from> or
|
|
I<--current> is not included in the list unless the I<--tree>
|
|
option is also present.
|
|
|
|
If I<--leaves> is specified, the list will be filtered to just
|
|
snapshots that have no children. Likewise, if I<--no-leaves> is
|
|
specified, the list will be filtered to just snapshots with
|
|
children. (Note that omitting both options does no filtering,
|
|
while providing both options will either produce the same list
|
|
or error out depending on whether the server recognizes the flags).
|
|
Filtering options are not compatible with I<--tree>.
|
|
|
|
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. Likewise, if I<--no-metadata> is specified,
|
|
the list will be filtered to just snapshots that exist without
|
|
the need for libvirt metadata.
|
|
|
|
If I<--inactive> is specified, the list will be filtered to snapshots
|
|
that were taken when the domain was shut off. If I<--active> is
|
|
specified, the list will be filtered to snapshots that were taken
|
|
when the domain was running, and where the snapshot includes the
|
|
memory state to revert to that running state. If I<--disk-only> is
|
|
specified, the list will be filtered to snapshots that were taken
|
|
when the domain was running, but where the snapshot includes only
|
|
disk state.
|
|
|
|
If I<--internal> is specified, the list will be filtered to snapshots
|
|
that use internal storage of existing disk images. If I<--external>
|
|
is specified, the list will be filtered to snapshots that use external
|
|
files for disk images or memory state.
|
|
|
|
=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.
|
|
Use B<snapshot-current> to easily access the XML of the current snapshot.
|
|
|
|
=item B<snapshot-parent> I<domain> {I<snapshot> | I<--current>}
|
|
|
|
Output the name of the parent snapshot, if any, for the given
|
|
I<snapshot>, or for the current snapshot with I<--current>.
|
|
|
|
=item B<snapshot-revert> I<domain> {I<snapshot> | I<--current>}
|
|
[{I<--running> | I<--paused>}] [I<--force>]
|
|
|
|
Revert the given domain to the snapshot specified by I<snapshot>, or to
|
|
the current snapshot with I<--current>. 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.
|
|
|
|
There are two cases where a snapshot revert involves extra risk, which
|
|
requires the use of I<--force> to proceed. One is the case of a
|
|
snapshot that lacks full domain information for reverting
|
|
configuration (such as snapshots created prior to libvirt 0.9.5);
|
|
since libvirt cannot prove that the current configuration matches what
|
|
was in use at the time of the snapshot, supplying I<--force> assures
|
|
libvirt that the snapshot is compatible with the current configuration
|
|
(and if it is not, the domain will likely fail to run). The other is
|
|
the case of reverting from a running domain to an active state where a
|
|
new hypervisor has to be created rather than reusing the existing
|
|
hypervisor, because it implies drawbacks such as breaking any existing
|
|
VNC or Spice connections; this condition happens with an active
|
|
snapshot that uses a provably incompatible configuration, as well as
|
|
with an inactive snapshot that is combined with the I<--start> or
|
|
I<--pause> flag.
|
|
|
|
=item B<snapshot-delete> I<domain> {I<snapshot> | I<--current>} [I<--metadata>]
|
|
[{I<--children> | I<--children-only>}]
|
|
|
|
Delete the snapshot for the domain named I<snapshot>, or the current
|
|
snapshot with I<--current>. 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. If I<--children-only> is passed, then delete
|
|
any children of this snapshot, but leave this snapshot intact. These
|
|
two flags are mutually exclusive.
|
|
|
|
If I<--metadata> is specified, then only delete the snapshot metadata
|
|
maintained by libvirt, while leaving the snapshot contents intact for
|
|
access by external tools; otherwise deleting a snapshot also removes
|
|
the data contents from that point in time.
|
|
|
|
=back
|
|
|
|
=head1 NWFILTER COMMANDS
|
|
|
|
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 HYPERVISOR-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 these commands, please do not report
|
|
problems to the libvirt developers; the reports will be ignored. If
|
|
you find that these commands are the only way to accomplish something,
|
|
then it is better to request that the feature be added as a first-class
|
|
citizen in the regular libvirt library.
|
|
|
|
=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<--pretty>] }
|
|
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 I<--pretty> is given,
|
|
and the monitor uses QMP, then the output will be pretty-printed. 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.
|
|
|
|
=item B<qemu-agent-command> I<domain> [I<--timeout> I<seconds> | I<--async> |
|
|
I<--block>] I<command>...
|
|
|
|
Send an arbitrary guest agent command I<command> to domain I<domain> through
|
|
qemu agent.
|
|
I<--timeout>, I<--async> and I<--block> options are exclusive.
|
|
I<--timeout> requires timeout seconds I<seconds> and it must be positive.
|
|
When I<--aysnc> is given, the command waits for timeout whether success or
|
|
failed. And when I<--block> is given, the command waits forever with blocking
|
|
timeout.
|
|
|
|
=item B<qemu-monitor-event> [I<domain>] [I<--event> I<event-name>] [I<--loop>]
|
|
[I<--timeout> I<seconds>] [I<--pretty>] [I<--regex>] [I<--no-case>]
|
|
|
|
Wait for arbitrary QEMU monitor events to occur, and print out the
|
|
details of events as they happen. The events can optionally be filtered
|
|
by I<domain> or I<event-name>. The 'query-events' QMP command can be
|
|
used via I<qemu-monitor-command> to learn what events are supported.
|
|
If I<--regex> is used, I<event-name> is a basic regular expression
|
|
instead of a literal string. If I<--no-case> is used, I<event-name>
|
|
will match case-insensitively.
|
|
|
|
By default, this command is one-shot, and returns success once an event
|
|
occurs; you can send SIGINT (usually via C<Ctrl-C>) to quit immediately.
|
|
If I<--timeout> is specified, the command gives up waiting for events
|
|
after I<seconds> have elapsed. With I<--loop>, the command prints all
|
|
events until a timeout or interrupt key. If I<--pretty> is specified,
|
|
any JSON event details are pretty-printed for better legibility.
|
|
|
|
=item B<lxc-enter-namespace> I<domain> -- /path/to/binary [arg1, [arg2, ...]]
|
|
|
|
Enter the namespace of I<domain> and execute the command C</path/to/binary>
|
|
passing the requested args. The binary path is relative to the container
|
|
root filesystem, not the host root filesystem. The binary will inherit the
|
|
environment variables / console visible to virsh. This command only works
|
|
when connected to the LXC hypervisor driver. This command succeeds only
|
|
if C</path/to/binary> has 0 exit status.
|
|
|
|
=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
|
|
|
|
=over 4
|
|
|
|
=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.
|
|
|
|
=back
|
|
|
|
=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. This environment variable
|
|
is deprecated in favour of the global B<LIBVIRT_DEFAULT_URI> variable
|
|
which serves the same purpose.
|
|
|
|
=item LIBVIRT_DEFAULT_URI
|
|
|
|
The hypervisor to connect to by default. Set this to a URI, in the
|
|
same format as accepted by the B<connect> option. This overrides
|
|
the default URI set in any client config file and prevents libvirt
|
|
from probing for drivers.
|
|
|
|
=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 VIRSH_HISTSIZE
|
|
|
|
The number of commands to remember in the command history. The
|
|
default value is 500.
|
|
|
|
=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-2014 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
|