mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-26 23:55:23 +00:00
6d27148ae1
This command is a virsh wrapper for virConnectBaselineHypervisorCPU. Signed-off-by: Jiri Denemark <jdenemar@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
5028 lines
219 KiB
Plaintext
5028 lines
219 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> [I<--daemon>]
|
|
|
|
Will print out the major version info about what this built from.
|
|
If I<--daemon> is specified then the version of the libvirt daemon
|
|
is included in the output.
|
|
|
|
=over 4
|
|
|
|
B<Example>
|
|
|
|
$ virsh version
|
|
Compiled against library: libvirt 1.2.3
|
|
Using library: libvirt 1.2.3
|
|
Using API: QEMU 1.2.3
|
|
Running hypervisor: QEMU 2.0.50
|
|
|
|
$ virsh version --daemon
|
|
Compiled against library: libvirt 1.2.3
|
|
Using library: libvirt 1.2.3
|
|
Using API: QEMU 1.2.3
|
|
Running hypervisor: QEMU 2.0.50
|
|
Running against daemon: 1.2.6
|
|
|
|
=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<https://libvirt.org/uri.html> list the values supported, but the most
|
|
common are:
|
|
|
|
=over 4
|
|
|
|
=item xen:///system
|
|
|
|
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:///system
|
|
|
|
connect to a local linux container
|
|
|
|
=back
|
|
|
|
To find the currently used URI, check the I<uri> command documented below.
|
|
|
|
For remote access see the documentation page at
|
|
L<https://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. The information libvirt displays is dependent
|
|
upon what each architecture may provide.
|
|
|
|
=item B<nodecpumap> [I<--pretty>]
|
|
|
|
Displays the node's total number of CPUs, the number of online CPUs
|
|
and the list of online CPUs.
|
|
|
|
With I<--pretty> the online CPUs are printed as a range instead of a list.
|
|
|
|
=item B<nodecpustats> [I<cpu>] [I<--percent>]
|
|
|
|
Returns cpu stats of the node.
|
|
If I<cpu> is specified, this will print the specified cpu statistics only.
|
|
If I<--percent> is specified, this will print the 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 print the 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<https://libvirt.org/formatcaps.html>
|
|
The XML also show the NUMA topology information if available.
|
|
|
|
=item B<domcapabilities> [I<virttype>] [I<emulatorbin>]
|
|
[I<arch>] [I<machine>]
|
|
|
|
Print an XML document describing the domain capabilities for the
|
|
hypervisor we are connected to using information either sourced from an
|
|
existing domain or taken from the B<virsh capabilities> output. This may
|
|
be useful if you intend to create a new domain and are curious if for
|
|
instance it could make use of VFIO by creating a domain for the
|
|
hypervisor with a specific emulator and architecture.
|
|
|
|
Each hypervisor will have different requirements regarding which options
|
|
are required and which are optional. A hypervisor can support providing
|
|
a default value for any of the options.
|
|
|
|
The I<virttype> option specifies the virtualization type used. The value
|
|
to be used is either from the 'type' attribute of the <domain/> top
|
|
level element from the domain XML or the 'type' attribute found within
|
|
each <guest/> element from the B<virsh capabilities> output. The
|
|
I<emulatorbin> option specifies the path to the emulator. The value to
|
|
be used is either the <emulator> element in the domain XML or the
|
|
B<virsh capabilities> output. The I<arch> option specifies the
|
|
architecture to be used for the domain. The value to be used is either
|
|
the "arch" attribute from the domain's XML <os/> element and <type/>
|
|
subelement or the "name" attribute of an <arch/> element from the
|
|
B<virsh capabililites> output. The I<machine> specifies the machine type
|
|
for the emulator. The value to be used is either the "machine" attribute
|
|
from the domain's XML <os/> element and <type/> subelement or one from a
|
|
list of machines from the B<virsh capabilities> output for a specific
|
|
architecture and domain type.
|
|
|
|
For the qemu hypervisor, a I<virttype> of either 'qemu' or 'kvm' must be
|
|
supplied along with either the I<emulatorbin> or I<arch> in order to
|
|
generate output for the default I<machine>. Supplying a I<machine>
|
|
value will generate output for the specific machine.
|
|
|
|
=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 what state each domain is currently in. A domain
|
|
can be in one of the following possible states:
|
|
|
|
|
|
=over 4
|
|
|
|
=item B<running>
|
|
|
|
The domain is currently running on a CPU
|
|
|
|
=item B<idle>
|
|
|
|
The domain is idle, and not running or runnable. This can be caused
|
|
because the domain is waiting on IO (a traditional wait state) or has
|
|
gone to sleep because there was nothing else for it to do.
|
|
|
|
=item B<paused>
|
|
|
|
The domain has been paused, usually occurring through the administrator
|
|
running B<virsh suspend>. When in a paused state the domain will still
|
|
consume allocated resources like memory, but will not be eligible for
|
|
scheduling by the hypervisor.
|
|
|
|
=item B<in 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<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.
|
|
|
|
If both I<--name> and I<--uuid> are specified, domain UUID's and names
|
|
are printed side by side without any header. Flag I<--table> specifies
|
|
that the legacy table-formatted output should be used. This is the
|
|
default if neither I<--name> nor I<--uuid> are specified. Option
|
|
I<--table> is mutually exclusive with options I<--uuid> and I<--name>.
|
|
|
|
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<freepages> [{ [I<--cellno>] I<cellno> [I<--pagesize>] I<pagesize> |
|
|
I<--all> }]
|
|
|
|
Prints the available amount of pages within a NUMA cell. I<cellno> refers
|
|
to the NUMA cell you're interested in. I<pagesize> is a scaled integer (see
|
|
B<NOTES> above). Alternatively, if I<--all> is used, info on each possible
|
|
combination of NUMA cell and page size is printed out.
|
|
|
|
=item B<allocpages> [I<--pagesize>] I<pagesize> [I<--pagecount>] I<pagecount>
|
|
[[I<--cellno>] I<cellno>] [I<--add>] [I<--all>]
|
|
|
|
Change the size of pages pool of I<pagesize> on the host. If
|
|
I<--add> is specified, then I<pagecount> pages are added into the
|
|
pool. However, if I<--add> wasn't specified, then the
|
|
I<pagecount> is taken as the new absolute size of the pool (this
|
|
may be used to free some pages and size the pool down). The
|
|
I<cellno> modifier can be used to narrow the modification down to
|
|
a single host NUMA cell. On the other end of spectrum lies
|
|
I<--all> which executes the modification on all NUMA cells.
|
|
|
|
=item B<cpu-baseline> I<FILE> [I<--features>] [I<--migratable>]
|
|
|
|
Compute baseline CPU which will be supported by all host CPUs given in <file>.
|
|
(See B<hypervisor-cpu-baseline> command to get a CPU which can be provided by a
|
|
specific hypervisor.) 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. If I<--migratable> is specified,
|
|
features that block migration will not be included in the resulting CPU.
|
|
|
|
=item B<cpu-compare> I<FILE> [I<--error>]
|
|
|
|
Compare CPU definition from XML <file> with host CPU. (See
|
|
B<hypervisor-cpu-compare> command for comparing the CPU definition with the CPU
|
|
which a specific hypervisor is able to provide on the host.) 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 or the CPU definition created from the host CPU model found in
|
|
domain capabilities XML (printed by B<domcapabilities> command). In
|
|
addition to the <cpu> element itself, this command accepts
|
|
full domain XML, capabilities XML, or domain capabilities XML containing
|
|
the CPU definition. For more information on guest CPU definition see:
|
|
L<https://libvirt.org/formatdomain.html#elementsCPU>. If I<--error> is
|
|
specified, the command will return an error when the given CPU is
|
|
incompatible with host CPU and a message providing more details about the
|
|
incompatibility will be printed out.
|
|
|
|
=item B<cpu-models> I<arch>
|
|
|
|
Print the list of CPU models known by libvirt for the specified architecture.
|
|
Whether a specific hypervisor is able to create a domain which uses any of
|
|
the printed CPU models is a separate question which can be answered by
|
|
looking at the domain capabilities XML returned by B<domcapabilities> command.
|
|
Moreover, for some architectures libvirt does not know any CPU models and
|
|
the usable CPU models are only limited by the hypervisor. This command will
|
|
print that all CPU models are accepted for these architectures and the actual
|
|
list of supported CPU models can be checked in the domain capabilities XML.
|
|
|
|
=item B<echo> [I<--shell>] [I<--xml>] [I<arg>...]
|
|
|
|
Echo back each I<arg>, separated by space. If I<--shell> is
|
|
specified, then the output will be single-quoted where needed, so that
|
|
it is suitable for reuse in a shell context. If I<--xml> is
|
|
specified, then the output will be escaped for use in XML.
|
|
|
|
=item B<hypervisor-cpu-compare> I<FILE> [I<virttype>] [I<emulator>] [I<arch>]
|
|
[I<machine>] [I<--error>]
|
|
|
|
Compare CPU definition from XML <file> with the CPU the hypervisor is able to
|
|
provide on the host. (This is different from B<cpu-compare> which compares the
|
|
CPU definition with the host CPU without considering any specific hypervisor
|
|
and its abilities.)
|
|
|
|
The XML I<FILE> may contain either a host or guest CPU definition. The host CPU
|
|
definition is the <cpu> element and its contents as printed by the
|
|
B<capabilities> command. The guest CPU definition is the <cpu> element and its
|
|
contents from the domain XML definition or the CPU definition created from the
|
|
host CPU model found in the domain capabilities XML (printed by the
|
|
B<domcapabilities> command). In addition to the <cpu> element itself, this
|
|
command accepts full domain XML, capabilities XML, or domain capabilities XML
|
|
containing the CPU definition. For more information on guest CPU definition
|
|
see: L<https://libvirt.org/formatdomain.html#elementsCPU>.
|
|
|
|
The I<virttype> option specifies the virtualization type (usable in the 'type'
|
|
attribute of the <domain> top level element from the domain XML). I<emulator>
|
|
specifies the path to the emulator, I<arch> specifies the CPU architecture, and
|
|
I<machine> specifies the machine type. If I<--error> is specified, the command
|
|
will return an error when the given CPU is incompatible with the host CPU and a
|
|
message providing more details about the incompatibility will be printed out.
|
|
|
|
=item B<hypervisor-cpu-baseline> I<FILE> [I<virttype>] [I<emulator>] [I<arch>]
|
|
[I<machine>] [I<--features>] [I<--migratable>]
|
|
|
|
Compute a baseline CPU which will be compatible with all CPUs defined in an XML
|
|
I<file> and with the CPU the hypervisor is able to provide on the host. (This
|
|
is different from B<cpu-baseline> which does not consider any hypervisor
|
|
abilities when computing the baseline CPU.)
|
|
|
|
The XML I<FILE> may contain either host or guest CPU definitions describing the
|
|
host CPU model. The host CPU definition is the <cpu> element and its contents
|
|
as printed by B<capabilities> command. The guest CPU definition may be created
|
|
from the host CPU model found in domain capabilities XML (printed by
|
|
B<domcapabilities> command). In addition to the <cpu> elements, this command
|
|
accepts full capabilities XMLs, or domain capabilities XMLs containing the CPU
|
|
definitions. For best results, use only the CPU definitions from domain
|
|
capabilities.
|
|
|
|
When I<FILE> contains only a single CPU definition, the command will print the
|
|
same CPU with restrictions imposed by the capabilities of the hypervisor.
|
|
Specifically, running th B<virsh hypervisor-cpu-baseline> command with no
|
|
additional options on the result of B<virsh domcapabilities> will transform the
|
|
host CPU model from domain capabilities XML to a form directly usable in domain
|
|
XML.
|
|
|
|
The I<virttype> option specifies the virtualization type (usable in the 'type'
|
|
attribute of the <domain> top level element from the domain XML). I<emulator>
|
|
specifies the path to the emulator, I<arch> specifies the CPU architecture, and
|
|
I<machine> specifies the machine type. 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. If I<--migratable> is specified, features that
|
|
block migration will not be included in the resulting CPU.
|
|
|
|
|
|
=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,...>] [I<--validate>]
|
|
|
|
Create a domain from an XML <file>. Optionally, I<--validate> option can be
|
|
passed to validate the format of the input XML file against an internal RNG
|
|
schema (identical to using L<virt-xml-validate(1)> tool). Domains created using
|
|
this command are going to be either transient (temporary ones that will vanish
|
|
once destroyed) or existing persistent domains that will run with one-time use
|
|
configuration, leaving the persistent XML untouched (this can come handy during
|
|
an automated testing of various configurations all based on the original XML).
|
|
See the B<Example> section for usage demonstration.
|
|
|
|
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>
|
|
|
|
1) prepare a template from an existing domain (skip directly to 3a if writing
|
|
one from scratch)
|
|
|
|
# virsh dumpxml <domain> > domain.xml
|
|
|
|
2) edit the template using an editor of your choice and:
|
|
a) DO CHANGE! <name> and <uuid> (<uuid> can also be removed), or
|
|
b) DON'T CHANGE! either <name> or <uuid>
|
|
|
|
# $EDITOR domain.xml
|
|
|
|
3) create a domain from domain.xml, depending on whether following 2a or 2b
|
|
respectively:
|
|
a) the domain is going to be transient
|
|
b) an existing persistent domain will run with a modified one-time
|
|
configuration
|
|
|
|
# virsh create domain.xml
|
|
|
|
=item B<define> I<FILE> [I<--validate>]
|
|
|
|
Define a domain from an XML <file>. Optionally, the format of the input XML
|
|
file can be validated against an internal RNG schema with I<--validate>
|
|
(identical to using L<virt-xml-validate(1)> tool). 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.
|
|
(See also B<metadata> that works with XML based domain metadata.)
|
|
|
|
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 or qemu 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<domifaddr> I<domain> [I<interface>] [I<--full>]
|
|
[I<--source lease|agent|arp>]
|
|
|
|
Get a list of interfaces of a running domain along with their IP and MAC
|
|
addresses, or limited output just for one interface if I<interface> is
|
|
specified. Note that I<interface> can be driver dependent, it can be the name
|
|
within guest OS or the name you would see in domain XML. Moreover, the whole
|
|
command may require a guest agent to be configured for the queried domain under
|
|
some hypervisors, notably QEMU.
|
|
|
|
If I<--full> is specified, the interface name and MAC address is always
|
|
displayed when the interface has multiple IP addresses or aliases; otherwise,
|
|
only the interface name and MAC address is displayed for the first name and
|
|
MAC address with "-" for the others using the same name and MAC address.
|
|
|
|
The I<--source> argument specifies what data source to use for the
|
|
addresses, currently 'lease' to read DHCP leases, 'agent' to query
|
|
the guest OS via an agent, or 'arp' to get IP from host's arp tables.
|
|
If unspecified, 'lease' is the default.
|
|
|
|
=item B<domifstat> I<domain> I<interface-device>
|
|
|
|
Get network interface stats for a running domain. The network
|
|
interface stats are only available for interfaces that have a
|
|
physical source interface. This does not include, for example, a
|
|
'user' interface type since it is a virtual LAN with NAT to the
|
|
outside world. I<interface-device> can be the interface target by
|
|
name or MAC address.
|
|
|
|
=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,floor>]
|
|
[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,floor> is the same as
|
|
in command I<attach-interface>. Values for I<average>, I<peak> and I<floor>
|
|
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<https://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<--config> 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.
|
|
|
|
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>:
|
|
swap_in - The amount of data read from swap space (in KiB)
|
|
swap_out - The amount of memory written out to swap space (in KiB)
|
|
major_fault - The number of page faults where disk IO was required
|
|
minor_fault - The number of other page faults
|
|
unused - The amount of memory left unused by the system (in KiB)
|
|
available - The amount of usable memory as seen by the domain (in KiB)
|
|
actual - Current balloon value (in KiB)
|
|
rss - Resident Set Size of the running domain's process (in KiB)
|
|
usable - The amount of memory which can be reclaimed by balloon
|
|
without causing host swapping (in KiB)
|
|
last-update - Timestamp of the last update of statistics (in seconds)
|
|
|
|
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> [I<--human>]
|
|
|
|
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). If I<--human> is set, the
|
|
output will have a human readable output.
|
|
|
|
=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<domstats> [I<--raw>] [I<--enforce>] [I<--backing>] [I<--state>]
|
|
[I<--cpu-total>] [I<--balloon>] [I<--vcpu>] [I<--interface>] [I<--block>]
|
|
[I<--perf>] [[I<--list-active>] [I<--list-inactive>] [I<--list-persistent>]
|
|
[I<--list-transient>] [I<--list-running>] [I<--list-paused>]
|
|
[I<--list-shutoff>] [I<--list-other>]] | [I<domain> ...]
|
|
|
|
Get statistics for multiple or all domains. Without any argument this
|
|
command prints all available statistics for all domains.
|
|
|
|
The list of domains to gather stats for can be either limited by listing
|
|
the domains as a space separated list, or by specifying one of the
|
|
filtering flags I<--list-*>. (The approaches can't be combined.)
|
|
|
|
By default some of the returned fields may be converted to more
|
|
human friendly values by a set of pretty-printers. To suppress this
|
|
behavior use the I<--raw> flag.
|
|
|
|
The individual statistics groups are selectable via specific flags. By
|
|
default all supported statistics groups are returned. Supported
|
|
statistics groups flags are: I<--state>, I<--cpu-total>, I<--balloon>,
|
|
I<--vcpu>, I<--interface>, I<--block>, I<--perf>.
|
|
|
|
Note that - depending on the hypervisor type and version or the domain state
|
|
- not all of the following statistics may be returned.
|
|
|
|
When selecting the I<--state> group the following fields are returned:
|
|
|
|
"state.state" - state of the VM, returned as number from
|
|
virDomainState enum
|
|
"state.reason" - reason for entering given state, returned
|
|
as int from virDomain*Reason enum corresponding
|
|
to given state
|
|
|
|
I<--cpu-total> returns:
|
|
|
|
"cpu.time" - total cpu time spent for this domain in nanoseconds
|
|
"cpu.user" - user cpu time spent in nanoseconds
|
|
"cpu.system" - system cpu time spent in nanoseconds
|
|
|
|
I<--balloon> returns:
|
|
|
|
"balloon.current" - the memory in KiB currently used
|
|
"balloon.maximum" - the maximum memory in KiB allowed
|
|
"balloon.swap_in" - the amount of data read from swap space (in KiB)
|
|
"balloon.swap_out" - the amount of memory written out to swap
|
|
space (in KiB)
|
|
"balloon.major_fault" - the number of page faults then disk IO
|
|
was required
|
|
"balloon.minor_fault" - the number of other page faults
|
|
"balloon.unused" - the amount of memory left unused by the
|
|
system (in KiB)
|
|
"balloon.available" - the amount of usable memory as seen by
|
|
the domain (in KiB)
|
|
"balloon.rss" - Resident Set Size of running domain's process
|
|
(in KiB)
|
|
"balloon.usable" - the amount of memory which can be reclaimed by
|
|
balloon without causing host swapping (in KiB)
|
|
"balloon.last-update" - timestamp of the last update of statistics
|
|
(in seconds)
|
|
|
|
I<--vcpu> returns:
|
|
|
|
"vcpu.current" - current number of online virtual CPUs
|
|
"vcpu.maximum" - maximum number of online virtual CPUs
|
|
"vcpu.<num>.state" - state of the virtual CPU <num>, as
|
|
number from virVcpuState enum
|
|
"vcpu.<num>.time" - virtual cpu time spent by virtual
|
|
CPU <num> (in microseconds)
|
|
"vcpu.<num>.wait" - virtual cpu time spent by virtual
|
|
CPU <num> waiting on I/O (in microseconds)
|
|
"vcpu.<num>.halted" - virtual CPU <num> is halted: yes or
|
|
no (may indicate the processor is idle
|
|
or even disabled, depending on the
|
|
architecture)
|
|
|
|
I<--interface> returns:
|
|
|
|
"net.count" - number of network interfaces on this domain
|
|
"net.<num>.name" - name of the interface <num>
|
|
"net.<num>.rx.bytes" - number of bytes received
|
|
"net.<num>.rx.pkts" - number of packets received
|
|
"net.<num>.rx.errs" - number of receive errors
|
|
"net.<num>.rx.drop" - number of receive packets dropped
|
|
"net.<num>.tx.bytes" - number of bytes transmitted
|
|
"net.<num>.tx.pkts" - number of packets transmitted
|
|
"net.<num>.tx.errs" - number of transmission errors
|
|
"net.<num>.tx.drop" - number of transmit packets dropped
|
|
|
|
I<--perf> returns the statistics of all enabled perf events:
|
|
|
|
"perf.cmt" - the cache usage in Byte currently used
|
|
"perf.mbmt" - total system bandwidth from one level of cache
|
|
"perf.mbml" - bandwidth of memory traffic for a memory controller
|
|
"perf.cpu_cycles" - the count of cpu cycles (total/elapsed)
|
|
"perf.instructions" - the count of instructions
|
|
"perf.cache_references" - the count of cache hits
|
|
"perf.cache_misses" - the count of caches misses
|
|
"perf.branch_instructions" - the count of branch instructions
|
|
"perf.branch_misses" - the count of branch misses
|
|
"perf.bus_cycles" - the count of bus cycles
|
|
"perf.stalled_cycles_frontend" - the count of stalled frontend
|
|
cpu cycles
|
|
"perf.stalled_cycles_backend" - the count of stalled backend
|
|
cpu cycles
|
|
"perf.ref_cpu_cycles" - the count of ref cpu cycles
|
|
"perf.cpu_clock" - the count of cpu clock time
|
|
"perf.task_clock" - the count of task clock time
|
|
"perf.page_faults" - the count of page faults
|
|
"perf.context_switches" - the count of context switches
|
|
"perf.cpu_migrations" - the count of cpu migrations
|
|
"perf.page_faults_min" - the count of minor page faults
|
|
"perf.page_faults_maj" - the count of major page faults
|
|
"perf.alignment_faults" - the count of alignment faults
|
|
"perf.emulation_faults" - the count of emulation faults
|
|
|
|
See the B<perf> command for more details about each event.
|
|
|
|
I<--block> returns information about disks associated with each
|
|
domain. Using the I<--backing> flag extends this information to
|
|
cover all resources in the backing chain, rather than the default
|
|
of limiting information to the active layer for each guest disk.
|
|
Information listed includes:
|
|
|
|
"block.count" - number of block devices being listed
|
|
"block.<num>.name" - name of the target of the block
|
|
device <num> (the same name for
|
|
multiple entries if I<--backing>
|
|
is present)
|
|
"block.<num>.backingIndex" - when I<--backing> is present,
|
|
matches up with the <backingStore>
|
|
index listed in domain XML for
|
|
backing files
|
|
"block.<num>.path" - file source of block device <num>, if
|
|
it is a local file or block device
|
|
"block.<num>.rd.reqs" - number of read requests
|
|
"block.<num>.rd.bytes" - number of read bytes
|
|
"block.<num>.rd.times" - total time (ns) spent on reads
|
|
"block.<num>.wr.reqs" - number of write requests
|
|
"block.<num>.wr.bytes" - number of written bytes
|
|
"block.<num>.wr.times" - total time (ns) spent on writes
|
|
"block.<num>.fl.reqs" - total flush requests
|
|
"block.<num>.fl.times" - total time (ns) spent on cache flushing
|
|
"block.<num>.errors" - Xen only: the 'oo_req' value
|
|
"block.<num>.allocation" - offset of highest written sector in bytes
|
|
"block.<num>.capacity" - logical size of source file in bytes
|
|
"block.<num>.physical" - physical size of source file in bytes
|
|
"block.<num>.threshold" - threshold (in bytes) for delivering the
|
|
VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event
|
|
See domblkthreshold.
|
|
|
|
Selecting a specific statistics groups doesn't guarantee that the
|
|
daemon supports the selected group of stats. Flag I<--enforce>
|
|
forces the command to fail if the daemon doesn't support the
|
|
selected group.
|
|
|
|
=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<--bytes>]
|
|
[I<base>] [I<--shallow>] [I<top>] [I<--delete>] [I<--keep-relative>]
|
|
[I<--wait> [I<--async>] [I<--verbose>]] [I<--timeout> B<seconds>]
|
|
[I<--active>] [{I<--pivot> | I<--keep-overlay>}]
|
|
|
|
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 attempt to remove these invalidated
|
|
files at the successful completion of the commit operation. When the
|
|
I<--keep-relative> flag is used, the backing file paths will be kept relative.
|
|
|
|
When I<top> is omitted or specified as the active image, it is also
|
|
possible to specify I<--active> to trigger a two-phase active commit. In
|
|
the first phase, I<top> is copied into I<base> and the job can only be
|
|
canceled, with top still containing data not yet in base. In the second
|
|
phase, I<top> and I<base> remain identical until a call to B<blockjob>
|
|
with the I<--abort> flag (keeping top as the active image that tracks
|
|
changes from that point in time) or the I<--pivot> flag (making base
|
|
the new active image and invalidating top).
|
|
|
|
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 for I<--active>, enters the second phase), or until the operation
|
|
is canceled because 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. Using I<--pivot> is shorthand
|
|
for combining I<--active> I<--wait> with an automatic B<blockjob>
|
|
I<--pivot>; and using I<--keep-overlay> is shorthand for combining
|
|
I<--active> I<--wait> with an automatic B<blockjob> 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).
|
|
I<bandwidth> specifies copying bandwidth limit in MiB/s, although for
|
|
qemu, it may be non-zero only for an online domain. For further information
|
|
on the I<bandwidth> argument see the corresponding section for the B<blockjob>
|
|
command.
|
|
|
|
=item B<blockcopy> I<domain> I<path> { I<dest> [I<format>] [I<--blockdev>]
|
|
| I<--xml> B<file> } [I<--shallow>] [I<--reuse-external>] [I<bandwidth>]
|
|
[I<--wait> [I<--async>] [I<--verbose>]] [{I<--pivot> | I<--finish>}]
|
|
[I<--timeout> B<seconds>] [I<granularity>] [I<buf-size>] [I<--bytes>]
|
|
[I<--transient-job>]
|
|
|
|
Copy a disk backing image chain to a destination. Either I<dest> as
|
|
the destination file name, or I<--xml> with the name of an XML file containing
|
|
a top-level <disk> element describing the destination, must be present.
|
|
Additionally, if I<dest> is given, I<format> should be specified to declare
|
|
the format of the destination (if I<format> is omitted, then libvirt
|
|
will reuse the format of the source, or with I<--reuse-external> will
|
|
be forced to probe the destination format, which could be a potential
|
|
security hole). The command supports I<--raw> as a boolean flag synonym for
|
|
I<--format=raw>. When using I<dest>, the destination is treated as a regular
|
|
file unless I<--blockdev> is used to signal that it is a block device. 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 the destination must exist and have
|
|
sufficient space to hold the copy. If I<--shallow> is used in
|
|
conjunction with I<--reuse-external> then the pre-created image must have
|
|
guest visible contents identical to guest visible contents of the backing
|
|
file of the original image. This may be used to modify the backing file
|
|
names on the destination.
|
|
|
|
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> (similar to
|
|
B<blockjob> I<--pivot>) or I<--finish> (similar to B<blockjob> I<--abort>)
|
|
implies I<--wait>, and will additionally end the job cleanly rather than
|
|
leaving things in the mirroring phase. If job cancellation is triggered
|
|
by timeout or by I<--finish>, 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 has actually cancelled.
|
|
|
|
I<path> specifies fully-qualified path of the disk.
|
|
I<bandwidth> specifies copying bandwidth limit in MiB/s. Specifying a negative
|
|
value is interpreted as an unsigned long long value that might be essentially
|
|
unlimited, but more likely would overflow; it is safer to use 0 for that
|
|
purpose. For further information on the I<bandwidth> argument see the
|
|
corresponding section for the B<blockjob> command.
|
|
Specifying I<granularity> allows fine-tuning of the granularity that will be
|
|
copied when a dirty region is detected; larger values trigger less
|
|
I/O overhead but may end up copying more data overall (the default value is
|
|
usually correct); hypervisors may restrict this to be a power of two or fall
|
|
within a certain range. Specifying I<buf-size> will control how much data can
|
|
be simultaneously in-flight during the copy; larger values use more memory but
|
|
may allow faster completion (the default value is usually correct).
|
|
|
|
I<--transient-job> allows to specify that the user does not require the job to
|
|
be recovered if the VM crashes or is turned off before the job completes. This
|
|
flag removes the restriction of copy jobs to transient domains if that
|
|
restriction is applied by the hypervisor.
|
|
|
|
=item B<blockpull> I<domain> I<path> [I<bandwidth>] [I<--bytes>] [I<base>]
|
|
[I<--wait> [I<--verbose>] [I<--timeout> B<seconds>] [I<--async>]]
|
|
[I<--keep-relative>]
|
|
|
|
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.
|
|
|
|
Using the I<--keep-relative> flag will keep the backing chain names
|
|
relative.
|
|
|
|
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. For further information
|
|
on the I<bandwidth> argument see the corresponding section for the B<blockjob>
|
|
command.
|
|
|
|
=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>]]
|
|
[[I<total-bytes-sec-max>] | [I<read-bytes-sec-max>] [I<write-bytes-sec-max>]]
|
|
[[I<total-iops-sec-max>] | [I<read-iops-sec-max>] [I<write-iops-sec-max>]]
|
|
[[I<total-bytes-sec-max-length>] |
|
|
[I<read-bytes-sec-max-length>] [I<write-bytes-sec-max-length>]]
|
|
[[I<total-iops-sec-max-length>] |
|
|
[I<read-iops-sec-max-length>] [I<write-iops-sec-max-length>]]
|
|
[I<size-iops-sec>] [I<group-name>]
|
|
|
|
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 as a scaled integer, the
|
|
default being bytes per second if no suffix is specified.
|
|
I<--read-bytes-sec> specifies read throughput limit as a scaled integer, the
|
|
default being bytes per second if no suffix is specified.
|
|
I<--write-bytes-sec> specifies write throughput limit as a scaled integer, the
|
|
default being bytes per second if no suffix is specified.
|
|
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.
|
|
I<--total-bytes-sec-max> specifies maximum total throughput limit as a scaled
|
|
integer, the default being bytes per second if no suffix is specified
|
|
I<--read-bytes-sec-max> specifies maximum read throughput limit as a scaled
|
|
integer, the default being bytes per second if no suffix is specified.
|
|
I<--write-bytes-sec-max> specifies maximum write throughput limit as a scaled
|
|
integer, the default being bytes per second if no suffix is specified.
|
|
I<--total-iops-sec-max> specifies maximum total I/O operations limit per second.
|
|
I<--read-iops-sec-max> specifies maximum read I/O operations limit per second.
|
|
I<--write-iops-sec-max> specifies maximum write I/O operations limit per second.
|
|
I<--total-bytes-sec-max-length> specifies duration in seconds to allow maximum
|
|
total throughput limit.
|
|
I<--read-bytes-sec-max-length> specifies duration in seconds to allow maximum
|
|
read throughput limit.
|
|
I<--write-bytes-sec-max-length> specifies duration in seconds to allow maximum
|
|
write throughput limit.
|
|
I<--total-iops-sec-max-length> specifies duration in seconds to allow maximum
|
|
total I/O operations limit.
|
|
I<--read-iops-sec-max-length> specifies duration in seconds to allow maximum
|
|
read I/O operations limit.
|
|
I<--write-iops-sec-max-length> specifies duration in seconds to allow maximum
|
|
write I/O operations limit.
|
|
I<--size-iops-sec> specifies size I/O operations limit per second.
|
|
I<--group-name> specifies group name to share I/O quota between multiple drives.
|
|
For a qemu domain, if no name is provided, then the default is to have a single
|
|
group for each I<device>.
|
|
|
|
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.
|
|
|
|
It is up to the hypervisor to determine how to handle the length values.
|
|
For the qemu hypervisor, if an I/O limit value or maximum value is set,
|
|
then the default value of 1 second will be displayed. Supplying a 0 will
|
|
reset the value back to the default.
|
|
|
|
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.
|
|
When setting the disk io parameters both I<--live> and I<--config> flags may be
|
|
given, but I<--current> is exclusive. For querying only one of I<--live>,
|
|
I<--config> or I<--current> can be specified. 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<--raw>] [I<--bytes>] | [I<bandwidth>] }
|
|
|
|
Manage active block operations. There are three mutually-exclusive modes:
|
|
I<--info>, I<bandwidth>, and I<--abort>. I<--async> and I<--pivot> imply
|
|
abort mode; I<--raw> implies info mode; and if no mode was given, I<--info>
|
|
mode is assumed.
|
|
|
|
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).
|
|
|
|
In I<--abort> mode, 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 or active
|
|
commit job be pivoted over to the new image.
|
|
|
|
In I<--info> mode, the active job information on the specified
|
|
disk will be printed. By default, the output is a single human-readable
|
|
summary line; this format may change in future versions. Adding
|
|
I<--raw> lists each field of the struct, in a stable format. If the
|
|
I<--bytes> flag is set, then the command errors out if the server could
|
|
not supply bytes/s resolution; when omitting the flag, raw output is
|
|
listed in MiB/s and human-readable output automatically selects the
|
|
best resolution supported by the server.
|
|
|
|
I<bandwidth> can be used to set bandwidth limit for the active job in MiB/s.
|
|
If I<--bytes> is specified then the bandwidth value is interpreted in
|
|
bytes/s. Specifying a negative value is interpreted as an unsigned long
|
|
value or essentially unlimited. The hypervisor can choose whether to
|
|
reject the value or convert it to the maximum value allowed. Optionally a
|
|
scaled positive number may be used as bandwidth (see B<NOTES> above). Using
|
|
I<--bytes> with a scaled value allows to use finer granularity. A scaled value
|
|
used without I<--bytes> will be rounded down to MiB/s. Note that the
|
|
I<--bytes> may be unsupported by the hypervisor.
|
|
|
|
|
|
=item B<domblkthreshold> I<domain> I<dev> I<threshold>
|
|
|
|
Set the threshold value for delivering the block-threshold event. I<dev>
|
|
specifies the disk device target or backing chain element of given device using
|
|
the 'target[1]' syntax. I<threshold> is a scaled value of the offset. If the
|
|
block device should write beyond that offset the event will be delivered.
|
|
|
|
=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>]
|
|
[[I<--type>] B<type>] [I<--all>]
|
|
|
|
Output a URI which can be used to connect to the graphical display of the
|
|
domain via VNC, SPICE or RDP. The particular graphical display type can
|
|
be selected using the B<type> parameter (e.g. "vnc", "spice", "rdp"). If
|
|
I<--include-password> is specified, the SPICE channel password will be
|
|
included in the URI. If I<--all> is specified, then all show all possible
|
|
graphical displays, for a VM could have more than one graphical displays.
|
|
|
|
=item B<domfsinfo> I<domain>
|
|
|
|
Show a list of mounted filesystems within the running domain. The list contains
|
|
mountpoints, names of a mounted device in the guest, filesystem types, and
|
|
unique target names used in the domain XML (<target dev='name'/>).
|
|
|
|
Note that this command requires a guest agent configured and running in the
|
|
domain's guest OS.
|
|
|
|
=item B<domfsfreeze> I<domain> [[I<--mountpoint>] B<mountpoint>...]
|
|
|
|
Freeze mounted filesystems within a running domain to prepare for consistent
|
|
snapshots.
|
|
|
|
The I<--mountpoint> option takes a parameter B<mountpoint>, which is a
|
|
mount point path of the filesystem to be frozen. This option can occur
|
|
multiple times. If this is not specified, every mounted filesystem is frozen.
|
|
|
|
Note: B<snapshot-create> command has a I<--quiesce> option to freeze
|
|
and thaw the filesystems automatically to keep snapshots consistent.
|
|
B<domfsfreeze> command is only needed when a user wants to utilize the
|
|
native snapshot features of storage devices not supported by libvirt.
|
|
|
|
=item B<domfsthaw> I<domain> [[I<--mountpoint>] B<mountpoint>...]
|
|
|
|
Thaw mounted filesystems within a running domain, which have been frozen by
|
|
domfsfreeze command.
|
|
|
|
The I<--mountpoint> option takes a parameter B<mountpoint>, which is a
|
|
mount point path of the filesystem to be thawed. This option can occur
|
|
multiple times. If this is not specified, every mounted filesystem is thawed.
|
|
|
|
=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, if a 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> [I<--completed>]
|
|
|
|
Returns information about jobs running on a domain. I<--completed> tells
|
|
virsh to return information about a recently finished job. Statistics of
|
|
a completed job are automatically destroyed once read or when libvirtd
|
|
is restarted. Note that time information returned for completed
|
|
migrations may be completely irrelevant unless both source and
|
|
destination hosts have synchronized time (i.e., NTP daemon is running
|
|
on both of them).
|
|
|
|
=item B<domname> I<domain-id-or-uuid>
|
|
|
|
Convert a domain Id (or UUID) to domain name
|
|
|
|
=item B<domrename> I<domain> I<new-name>
|
|
|
|
Rename a domain. This command changes current domain name to the new name
|
|
specified in the second argument.
|
|
|
|
B<Note>: Domain must be inactive and without snapshots.
|
|
|
|
=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<domtime> I<domain> { [I<--now>] [I<--pretty>] [I<--sync>]
|
|
[I<--time> B<time>] }
|
|
|
|
Gets or sets the domain's system time. When run without any arguments
|
|
(but I<domain>), the current domain's system time is printed out. The
|
|
I<--pretty> modifier can be used to print the time in more human
|
|
readable form.
|
|
|
|
When I<--time> B<time> is specified, the domain's time is
|
|
not gotten but set instead. The I<--now> modifier acts like if it was
|
|
an alias for I<--time> B<$now>, which means it sets the time that is
|
|
currently on the host virsh is running at. In both cases (setting and
|
|
getting), time is in seconds relative to Epoch of 1970-01-01 in UTC.
|
|
The I<--sync> modifies the set behavior a bit: The time passed is
|
|
ignored, but the time to set is read from domain's RTC instead. Please
|
|
note, that some hypervisors may require a guest agent to be configured
|
|
in order to get or set the guest time.
|
|
|
|
=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>, B<xen-xl>, or B<xen-sxpr>. For
|
|
LXC hypervisor, the I<format> argument must be B<lxc-tools>.
|
|
|
|
=item B<domxml-to-native> I<format>
|
|
{ [I<--xml>] I<xml> | I<--domain> I<domain-name-or-id-or-uuid> }
|
|
|
|
Convert the file I<xml> into domain XML format or convert an existing
|
|
I<--domain> to the native guest configuration format named by I<format>.
|
|
The I<xml> and I<--domain> arguments are mutually exclusive.
|
|
|
|
For the QEMU/KVM hypervisor, the I<format> argument must be B<qemu-argv>.
|
|
|
|
For the Xen hypervisor, the I<format> argument may be B<xen-xm>, B<xen-xl>,
|
|
or B<xen-sxpr>.
|
|
|
|
For the LXC hypervisor, the I<format> argument must be B<lxc-tools>.
|
|
|
|
=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>.
|
|
|
|
NOTE: Crash dump in a old kvmdump format is being obsolete and cannot be loaded
|
|
and processed by crash utility since its version 6.1.0. A --memory-only option
|
|
is required in order to produce valid ELF file which can be later processed by
|
|
the crash utility.
|
|
|
|
=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<--timestamp>] | 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.
|
|
|
|
When I<--timestamp> is used, a human-readable timestamp will be printed
|
|
before the event.
|
|
|
|
=item B<iothreadinfo> I<domain> [[I<--live>] [I<--config>] | [I<--current>]]
|
|
|
|
Display basic domain IOThreads information including the IOThread ID and
|
|
the CPU Affinity for each IOThread.
|
|
|
|
If I<--live> is specified, get the IOThreads data from the running guest. If
|
|
the guest is not running, an error is returned.
|
|
If I<--config> is specified, get the IOThreads data from the next boot of
|
|
a persistent guest.
|
|
If I<--current> is specified or I<--live> and I<--config> are not specified,
|
|
then get the IOThread data based on the current guest state.
|
|
|
|
=item B<iothreadpin> I<domain> I<iothread> I<cpulist>
|
|
[[I<--live>] [I<--config>] | [I<--current>]]
|
|
|
|
Change the pinning of a domain IOThread to host physical CPUs. In order
|
|
to retrieve a list of all IOThreads, use B<iothreadinfo>. To pin an
|
|
I<iothread> specify the I<cpulist> desired for the IOThread ID as listed
|
|
in the B<iothreadinfo> output.
|
|
|
|
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 iothreadpin setting, that is, to pin an I<iothread>
|
|
to all physical cpus, simply specify 'r' as a I<cpulist>.
|
|
|
|
If I<--live> is specified, affect a running guest. If the guest is not running,
|
|
an error is returned.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified or I<--live> and I<--config> are not 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<iothreadadd> I<domain> I<iothread_id>
|
|
[[I<--config>] [I<--live>] | [I<--current>]]
|
|
|
|
Add a new IOThread to the domain using the specified I<iothread_id>.
|
|
If the I<iothread_id> already exists, the command will fail. The
|
|
I<iothread_id> must be greater than zero.
|
|
|
|
If I<--live> is specified, affect a running guest. If the guest is not
|
|
running an error is returned.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified or I<--live> and I<--config> are not specified,
|
|
affect the current guest state.
|
|
|
|
=item B<iothreaddel> I<domain> I<iothread_id>
|
|
[[I<--config>] [I<--live>] | [I<--current>]]
|
|
|
|
Delete an IOThread from the domain using the specified I<iothread_id>.
|
|
If an IOThread is currently assigned to a disk resource such as via the
|
|
B<attach-disk> command, then the attempt to remove the IOThread will fail.
|
|
If the I<iothread_id> does not exist an error will occur.
|
|
|
|
If I<--live> is specified, affect a running guest. If the guest is not
|
|
running an error is returned.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified or I<--live> and I<--config> are not specified,
|
|
affect the current guest state.
|
|
|
|
=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<managedsave-define> I<domain> I<xml> [{I<--running> | I<--paused>}]
|
|
|
|
Update the domain XML that will be used when I<domain> is later
|
|
started. 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 change disk file paths.
|
|
|
|
The managed save image records whether the domain should be started 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<start> should use.
|
|
|
|
=item B<managedsave-dumpxml> I<domain> [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<managedsave> command. Using
|
|
I<--security-info> will also include security sensitive information.
|
|
|
|
=item B<managedsave-edit> I<domain> [{I<--running> | I<--paused>}]
|
|
|
|
Edit the XML configuration associated with a saved state file of a
|
|
I<domain> was created by the B<managedsave> command.
|
|
|
|
The managed save image records whether the domain should be started 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 managedsave-dumpxml domain-name > state-file.xml
|
|
vi state-file.xml (or make changes with your other text editor)
|
|
virsh managedsave-define domain-name 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<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<metadata> I<domain> [[I<--live>] [I<--config>] | [I<--current>]]
|
|
[I<--edit>] [I<uri>] [I<key>] [I<set>] [I<--remove>]
|
|
|
|
Show or modify custom XML metadata of a domain. The metadata is a user
|
|
defined XML that allows to store arbitrary XML data in the domain definition.
|
|
Multiple separate custom metadata pieces can be stored in the domain XML.
|
|
The pieces are identified by a private XML namespace provided via the
|
|
I<uri> argument. (See also B<desc> that works with textual metadata of
|
|
a domain.)
|
|
|
|
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<--remove> specifies that the metadata element specified by the I<uri>
|
|
argument should be removed rather than updated.
|
|
|
|
Flag I<--edit> specifies that an editor with the metadata identified by the
|
|
I<uri> argument should be opened and the contents saved back afterwards.
|
|
Otherwise the new contents can be provided via the I<set> argument.
|
|
|
|
When setting metadata via I<--edit> or I<set> the I<key> argument must be
|
|
specified and is used to prefix the custom elements to bind them
|
|
to the private namespace.
|
|
|
|
If neither of I<--edit> and I<set> are specified the XML metadata corresponding
|
|
to the I<uri> namespace is displayed instead of being modified.
|
|
|
|
=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<--rdma-pin-all>] [I<--abort-on-error>] [I<--postcopy>] [I<--postcopy-after-precopy>]
|
|
I<domain> I<desturi> [I<migrateuri>] [I<graphicsuri>] [I<listen-address>] [I<dname>]
|
|
[I<--timeout> B<seconds> [I<--timeout-suspend> | I<--timeout-postcopy>]]
|
|
[I<--xml> B<file>] [I<--migrate-disks> B<disk-list>] [I<--disks-port> B<port>]
|
|
[I<--compressed>] [I<--comp-methods> B<method-list>]
|
|
[I<--comp-mt-level>] [I<--comp-mt-threads>] [I<--comp-mt-dthreads>]
|
|
[I<--comp-xbzrle-cache>] [I<--auto-converge>] [I<auto-converge-initial>]
|
|
[I<auto-converge-increment>] [I<--persistent-xml> B<file>] [I<--tls>]
|
|
|
|
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. By default only non-shared non-readonly images are transferred. Use
|
|
I<--migrate-disks> to explicitly specify a list of disk targets to
|
|
transfer via the comma separated B<disk-list> argument. 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<--abort-on-error> cancels
|
|
the migration if a soft error (for example I/O error) happens during the
|
|
migration. I<--postcopy> enables post-copy logic in migration, but does not
|
|
actually start post-copy, i.e., migration is started in pre-copy mode.
|
|
Once migration is running, the user may switch to post-copy using the
|
|
B<migrate-postcopy> command sent from another virsh instance or use
|
|
I<--postcopy-after-precopy> along with I<--postcopy> to let libvirt
|
|
automatically switch to post-copy after the first pass of pre-copy is finished.
|
|
|
|
I<--auto-converge> forces convergence during live migration. The initial
|
|
guest CPU throttling rate can be set with I<auto-converge-initial>. If the
|
|
initial throttling rate is not enough to ensure convergence, the rate is
|
|
periodically increased by I<auto-converge-increment>.
|
|
|
|
I<--rdma-pin-all> can be used with RDMA migration (i.e., when I<migrateuri>
|
|
starts with rdma://) to tell the hypervisor to pin all domain's memory at once
|
|
before migration starts rather than letting it pin memory pages as needed. For
|
|
QEMU/KVM this requires hard_limit memory tuning element (in the domain XML) to
|
|
be used and set to the maximum memory configured for the domain plus any memory
|
|
consumed by the QEMU process itself. Beware of setting the memory limit too
|
|
high (and thus allowing the domain to lock most of the host's memory). Doing so
|
|
may be dangerous to both the domain and the host itself since the host's kernel
|
|
may run out of memory.
|
|
|
|
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.
|
|
|
|
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.
|
|
If I<--persistent> is enabled, I<--persistent-xml> B<file> can be used to
|
|
supply an alternative XML file which will be used as the persistent domain
|
|
definition on the destination host.
|
|
|
|
I<--timeout> B<seconds> tells virsh to run a specified action when live
|
|
migration exceeds that many seconds. It can only be used with I<--live>.
|
|
If I<--timeout-suspend> is specified, the domain will be suspended after
|
|
the timeout and the migration will complete offline; this is the default
|
|
if no I<--timeout-*> option is specified on the command line. When
|
|
I<--timeout-postcopy> is used, virsh will switch migration from pre-copy
|
|
to post-copy upon timeout; migration has to be started with I<--postcopy>
|
|
option for this to work.
|
|
|
|
I<--compressed> activates compression, the compression method is chosen
|
|
with I<--comp-methods>. Supported methods are "mt" and "xbzrle" and
|
|
can be used in any combination. When no methods are specified, a hypervisor
|
|
default methods will be used. QEMU defaults to "xbzrle". Compression methods
|
|
can be tuned further. I<--comp-mt-level> sets compression level.
|
|
Values are in range from 0 to 9, where 1 is maximum speed and 9 is maximum
|
|
compression. I<--comp-mt-threads> and I<--comp-mt-dthreads> set the number
|
|
of compress threads on source and the number of decompress threads on target
|
|
respectively. I<--comp-xbzrle-cache> sets size of page cache in bytes.
|
|
|
|
Providing I<--tls> causes the migration to use the host configured TLS setup
|
|
(see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in order to perform
|
|
the migration of the domain. Usage requires proper TLS setup for both source
|
|
and target.
|
|
|
|
Running migration can be canceled by interrupting virsh (usually using
|
|
C<Ctrl-C>) or by B<domjobabort> command sent from another virsh instance.
|
|
|
|
The I<desturi> and I<migrateuri> parameters can be used to control which
|
|
destination the migration uses. I<desturi> is important for managed
|
|
migration, but unused for direct migration; I<migrateuri> is required
|
|
for direct migration, but can usually be automatically determined for
|
|
managed migration.
|
|
|
|
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. Some hypervisors, including QEMU, have an optional
|
|
"migration_host" configuration parameter (useful when the host has multiple
|
|
network interfaces). If this is unspecified, libvirt determines a name
|
|
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
|
|
|
|
See L<https://libvirt.org/migration.html#uris> for more details on
|
|
migration URIs.
|
|
|
|
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.
|
|
|
|
Optional I<disks-port> sets the port that hypervisor on destination side should
|
|
bind to for incoming disks traffic. Currently it is supported only by qemu.
|
|
|
|
=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-getmaxdowntime> I<domain>
|
|
|
|
Get the maximum tolerable downtime for a domain which is being live-migrated to
|
|
another host. This is the 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. I<bandwidth> is interpreted as an unsigned long
|
|
long value. Specifying a negative value results in an essentially unlimited
|
|
value being provided to the hypervisor. The hypervisor can choose whether to
|
|
reject the value or convert it to the maximum value allowed.
|
|
|
|
=item B<migrate-getspeed> I<domain>
|
|
|
|
Get the maximum migration bandwidth (in MiB/s) for a domain.
|
|
|
|
=item B<migrate-postcopy> I<domain>
|
|
|
|
Switch the current migration from pre-copy to post-copy. This is only
|
|
supported for a migration started with I<--postcopy> option.
|
|
|
|
=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' or any
|
|
valid number from the virDomainNumatuneMemMode enum in case the daemon
|
|
supports it. 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>, C<signal> and C<paravirt>. 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, vcpu_period, vcpu_quota
|
|
|
|
QEMU/KVM (posix scheduler): cpu_shares, vcpu_period, vcpu_quota,
|
|
emulator_period, emulator_quota, iothread_quota, iothread_period
|
|
|
|
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.
|
|
|
|
B<Note>: The vcpu_period, emulator_period, and iothread_period parameters
|
|
have a valid value range of 1000-1000000 or 0, and the vcpu_quota,
|
|
emulator_quota, and iothread_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.
|
|
|
|
See L<virkeycode-linux(7)> and L<virkeyname-linux(7)>
|
|
|
|
=item B<xt>
|
|
|
|
The numeric values are those defined by the original XT keyboard
|
|
controller. No symbolic names are provided
|
|
|
|
See L<virkeycode-xt(7)>
|
|
|
|
=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
|
|
|
|
See L<virkeycode-atset1(7)>
|
|
|
|
=item B<atset2>
|
|
|
|
The numeric values are those defined by the AT keyboard controller,
|
|
set 2. No symbolic names are provided
|
|
|
|
See L<virkeycode-atset2(7)>
|
|
|
|
=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
|
|
|
|
See L<virkeycode-atset3(7)>
|
|
|
|
=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
|
|
|
|
See L<virkeycode-osx(7)> and L<virkeyname-osx(7)>
|
|
|
|
=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.
|
|
|
|
See L<virkeycode-xtkbd(7)>
|
|
|
|
=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
|
|
|
|
See L<virkeycode-win32(7)> and L<virkeyname-win32(7)>
|
|
|
|
=item B<usb>
|
|
|
|
The numeric values are those defined by the USB HID specification
|
|
for keyboard input. No symbolic names are provided
|
|
|
|
See L<virkeycode-usb(7)>
|
|
|
|
=item B<qnum>
|
|
|
|
The numeric values are those defined by the QNUM 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.
|
|
|
|
See L<virkeycode-qnum(7)>
|
|
|
|
=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.
|
|
|
|
For LXC, the value being set is the cgroups value for limit_in_bytes or the
|
|
maximum amount of user memory (including file cache). When viewing memory
|
|
inside the container, this is the /proc/meminfo "MemTotal" value. When viewing
|
|
the value from the host, use the B<virsh memtune> command. In order to view
|
|
the current memory in use and the maximum value allowed to set memory, use
|
|
the B<virsh dominfo> command.
|
|
|
|
=item B<set-lifecycle-action> I<domain> I<type> I<action>
|
|
[[I<--config>] [I<--live>] | [I<--current>]]
|
|
|
|
Set the lifecycle I<action> for specified lifecycle I<type>. For the list of
|
|
lifecycle types and actions and possible combinations see the documentation at
|
|
L<https://libvirt.org/formatdomain.html#elementsEvents>.
|
|
|
|
=item B<set-user-password> I<domain> I<user> I<password> [I<--encrypted>]
|
|
|
|
Set the password for the I<user> account in the guest domain.
|
|
|
|
If I<--encrypted> is specified, the password is assumed to be already
|
|
encrypted by the method required by the guest OS.
|
|
|
|
For QEMU/KVM, this requires the guest agent to be configured
|
|
and running.
|
|
|
|
=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. Even persistent configuration changes
|
|
might not be performed with some hypervisors/configuration (e.g. on NUMA enabled
|
|
domains on QEMU). For complex configuration changes use command B<edit>
|
|
instead).
|
|
|
|
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.
|
|
|
|
For LXC, the displayed hard_limit value is the current memory setting
|
|
from the XML or the results from a B<virsh setmem> command.
|
|
|
|
=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<perf> I<domain> [I<--enable> B<eventSpec>]
|
|
[I<--disable> B<eventSpec>]
|
|
[[I<--config>] [I<--live>] | [I<--current>]]
|
|
|
|
Get the current perf events setting or enable/disable specific perf
|
|
events for a guest domain.
|
|
|
|
Perf is a performance analyzing tool in Linux, and it can instrument
|
|
CPU performance counters, tracepoints, kprobes, and uprobes (dynamic
|
|
tracing). Perf supports a list of measurable events, and can measure
|
|
events coming from different sources. For instance, some event are
|
|
pure kernel counters, in this case they are called software events,
|
|
including context-switches, minor-faults, etc.. Now dozens of events
|
|
from different sources can be supported by perf.
|
|
|
|
Currently only QEMU/KVM supports this command. The I<--enable> and I<--disable>
|
|
option combined with B<eventSpec> can be used to enable or disable specific
|
|
performance event. B<eventSpec> is a string list of one or more events
|
|
separated by commas. Valid event names are as follows:
|
|
|
|
B<Valid perf event names>
|
|
cmt - A PQos (Platform Qos) feature to monitor the
|
|
usage of cache by applications running on the
|
|
platform.
|
|
mbmt - Provides a way to monitor the total system
|
|
memory bandwidth between one level of cache
|
|
and another.
|
|
mbml - Provides a way to limit the amount of data
|
|
(bytes/s) send through the memory controller
|
|
on the socket.
|
|
cache_misses - Provides the count of cache misses by
|
|
applications running on the platform.
|
|
cache_references - Provides the count of cache hits by
|
|
applications running on th e platform.
|
|
instructions - Provides the count of instructions executed
|
|
by applications running on the platform.
|
|
cpu_cycles - Provides the count of cpu cycles
|
|
(total/elapsed). May be used with
|
|
instructions in order to get a cycles
|
|
per instruction.
|
|
branch_instructions - Provides the count of branch instructions
|
|
executed by applications running on the
|
|
platform.
|
|
branch_misses - Provides the count of branch misses executed
|
|
by applications running on the platform.
|
|
bus_cycles - Provides the count of bus cycles executed
|
|
by applications running on the platform.
|
|
stalled_cycles_frontend - Provides the count of stalled cpu
|
|
cycles in the frontend of the
|
|
instruction processor pipeline by
|
|
applications running on the platform.
|
|
stalled_cycles_backend - Provides the count of stalled cpu
|
|
cycles in the backend of the
|
|
instruction processor pipeline by
|
|
applications running on the platform.
|
|
ref_cpu_cycles - Provides the count of total cpu cycles
|
|
not affected by CPU frequency scaling by
|
|
applications running on the platform.
|
|
cpu_clock - Provides the cpu clock time consumed by
|
|
applications running on the platform.
|
|
task_clock - Provides the task clock time consumed by
|
|
applications running on the platform.
|
|
page_faults - Provides the count of page faults by
|
|
applications running on the platform.
|
|
context_switches - Provides the count of context switches
|
|
by applications running on the platform.
|
|
cpu_migrations - Provides the count cpu migrations by
|
|
applications running on the platform.
|
|
page_faults_min - Provides the count minor page faults
|
|
by applications running on the platform.
|
|
page_faults_maj - Provides the count major page faults
|
|
by applications running on the platform.
|
|
alignment_faults - Provides the count alignment faults
|
|
by applications running on the platform.
|
|
emulation_faults - Provides the count emulation faults
|
|
by applications running on the platform.
|
|
|
|
B<Note>: The statistics can be retrieved using the B<domstats> command using
|
|
the I<--perf> flag.
|
|
|
|
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<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-device 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-device 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-device 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-device 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>] [I<--hotpluggable>]
|
|
|
|
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.
|
|
|
|
To allow adding vcpus to persistent definitions that can be later hotunplugged
|
|
after the domain is booted it is necessary to specify the I<--hotpluggable>
|
|
flag. Vcpus added to live domains supporting vcpu unplug are automatically
|
|
marked as hotpluggable.
|
|
|
|
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> or the I<--current>
|
|
flag. Note that it may not be possible to change the maximum vcpu count if
|
|
the processor topology is specified for the guest.
|
|
|
|
=item B<setvcpu> I<domain> I<vcpulist> [I<--enable>] | [I<--disable>]
|
|
[[I<--live>] [I<--config>] | [I<--current>]]
|
|
|
|
Change state of individual vCPUs using hot(un)plug mechanism.
|
|
|
|
See B<vcpupin> for information on format of I<vcpulist>. Hypervisor drivers may
|
|
require that I<vcpulist> contains exactly vCPUs belonging to one hotpluggable
|
|
entity. This is usually just a single vCPU but certain architectures such as
|
|
ppc64 require a full core to be specified at once.
|
|
|
|
Note that hypervisors may refuse to disable certain vcpus such as vcpu 0 or
|
|
others.
|
|
|
|
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. This is the
|
|
default. Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive.
|
|
|
|
=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_poweroff> 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>, C<signal> and C<paravirt>. 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-numbered 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<--nvram>] [I<--keep-nvram>]
|
|
[ {I<--storage> B<volumes> | I<--remove-all-storage> [I<--delete-snapshots>]}
|
|
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.
|
|
|
|
I<--nvram> and I<--keep-nvram> specify accordingly to delete or keep nvram
|
|
(/domain/os/nvram/) file. If the domain has an nvram file and the flags are
|
|
omitted, the undefine will fail.
|
|
|
|
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 I<--delete-snapshots> flag specifies that any snapshots associated with
|
|
the storage volume should be deleted as well. Requires the
|
|
I<--remove-all-storage> flag to be provided. Not all storage drivers
|
|
support this option, presently only rbd.
|
|
|
|
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> [I<--pretty>]
|
|
|
|
Returns basic information about the domain virtual CPUs, like the number of
|
|
vCPUs, the running time, the affinity to physical processors.
|
|
|
|
With I<--pretty>, cpu affinities are shown as ranges.
|
|
|
|
An example output is
|
|
|
|
$ virsh vcpuinfo fedora
|
|
VCPU: 0
|
|
CPU: 0
|
|
State: running
|
|
CPU time: 7,0s
|
|
CPU Affinity: yyyy
|
|
|
|
VCPU: 1
|
|
CPU: 1
|
|
State: running
|
|
CPU time: 0,7s
|
|
CPU Affinity: yyyy
|
|
|
|
B<STATES>
|
|
|
|
The State field displays the current operating state of a virtual CPU
|
|
|
|
=over 4
|
|
|
|
=item B<offline>
|
|
|
|
The virtual CPU is offline and not usable by the domain.
|
|
This state is not supported by all hypervisors.
|
|
|
|
=item B<running>
|
|
|
|
The virtual CPU is available to the domain and is operating.
|
|
|
|
=item B<blocked>
|
|
|
|
The virtual CPU is available to the domain but is waiting for a resource.
|
|
This state is not supported by all hypervisors, in which case I<running>
|
|
may be reported instead.
|
|
|
|
=item B<no state>
|
|
|
|
The virtual CPU state could not be determined. This could happen if
|
|
the hypervisor is newer than virsh.
|
|
|
|
=item B<N/A>
|
|
|
|
There's no information about the virtual CPU state available. This can
|
|
be the case if the domain is not running or the hypervisor does
|
|
not report the virtual CPU state.
|
|
|
|
=back
|
|
|
|
=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.
|
|
For pinning the I<vcpu> to all physical cpus specify 'r' as a 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.
|
|
|
|
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<guestvcpus> I<domain> [[I<--enable>] | [I<--disable>]] [I<cpulist>]
|
|
|
|
Query or change state of vCPUs from guest's point of view using the guest agent.
|
|
When invoked without I<cpulist> the guest is queried for available guest vCPUs,
|
|
their state and possibility to be offlined.
|
|
|
|
If I<cpulist> is provided then one of I<--enable> or I<--disable> must be
|
|
provided too. The desired operation is then executed on the domain.
|
|
|
|
See B<vcpupin> for information on I<cpulist>.
|
|
|
|
=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<https://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<https://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 PCI 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<--targetbus bus>] [I<--driver
|
|
driver>] [I<--subdriver subdriver>] [I<--iothread iothread>]
|
|
[I<--cache cache>] [I<--io io>] [I<--type type>]
|
|
[I<--mode mode>] [I<--sourcetype sourcetype>] [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; the optional I<targetbus> attribute specifies the type
|
|
of disk device to emulate; possible values are driver specific, with typical
|
|
values being I<ide>, I<scsi>, I<virtio>, I<xen>, I<usb>, I<sata>, or I<sd>, if
|
|
omitted, the bus type is inferred from the style of the device name (e.g. a
|
|
device named 'sda' will typically be exported using a SCSI bus). 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<io> controls specific policies on I/O; QEMU guests support "threads" and "native".
|
|
I<iothread> is the number within the range of domain IOThreads to which
|
|
this disk may be attached (QEMU only).
|
|
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, ide:controller.bus.unit or ccw:cssid.ssid.devno.
|
|
Virtio-ccw devices must have their cssid set to 0xfe.
|
|
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<--inbound average,peak,burst,floor>] [I<--outbound average,peak,burst>]
|
|
[I<--managed>] [I<--print-xml>]
|
|
|
|
Attach a new network interface to the domain.
|
|
|
|
B<type> can be one of the:
|
|
|
|
=over 4
|
|
|
|
I<network> to indicate connection via a libvirt virtual network,
|
|
|
|
I<bridge> to indicate connection via a bridge device on the host,
|
|
|
|
I<direct> to indicate connection directly to one of the host's network
|
|
interfaces or bridges,
|
|
|
|
I<hostdev> to indicate connection using a passthrough of PCI device
|
|
on the host.
|
|
|
|
=back
|
|
|
|
B<source> indicates the source of the connection. The source depends
|
|
on the type of the interface:
|
|
|
|
=over 4
|
|
|
|
I<network> name of the virtual network,
|
|
|
|
I<bridge> the name of the bridge device,
|
|
|
|
I<direct> the name of the host's interface or bridge,
|
|
|
|
I<hostdev> the PCI address of the host's interface formatted
|
|
as domain:bus:slot.function.
|
|
|
|
=back
|
|
|
|
B<--target> is used to specify the tap/macvtap device to be used to
|
|
connect the domain to the source. Names starting with 'vnet' are
|
|
considered as auto-generated and are blanked out/regenerated each
|
|
time the interface is attached.
|
|
|
|
B<--mac> specifies the MAC address of the network interface; if a MAC
|
|
address is not given, a new address will be automatically generated
|
|
(and stored in the persistent configuration if "--config" is given on
|
|
the command line).
|
|
|
|
B<--script> is used to specify a path to a custom script to be called
|
|
while attaching to a bridge - this will be called instead of the default
|
|
script not in addition to it. This is valid only for interfaces of
|
|
I<bridge> type and only for Xen domains.
|
|
|
|
B<--model> specifies the network device model to be presented to the
|
|
domain.
|
|
|
|
B<--inbound> and B<--outbound> control the bandwidth of the
|
|
interface. At least one from the I<average>, I<floor> pair must be
|
|
specified. The other two I<peak> and I<burst> are optional, so
|
|
"average,peak", "average,,burst", "average,,,floor", "average" and
|
|
",,,floor" are also legal. Values for I<average>, I<floor> 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<https://libvirt.org/formatnetwork.html#elementQoS>.
|
|
|
|
B<--managed> is usable only for I<hostdev> type and tells libvirt
|
|
that the interface should be managed, which means detached and reattached
|
|
from/to the host by libvirt.
|
|
|
|
If B<--print-xml> is specified, then the XML of the interface that would be
|
|
attached is printed instead.
|
|
|
|
If B<--live> is specified, affect a running domain.
|
|
If B<--config> is specified, affect the next startup of a persistent domain.
|
|
If B<--current> is specified, affect the current domain state.
|
|
Both B<--live> and B<--config> flags may be given, but B<--current> is
|
|
exclusive. When no flag is specified legacy API is used whose behavior
|
|
depends on the hypervisor driver.
|
|
|
|
For compatibility purposes, B<--persistent> behaves like B<--config> for
|
|
an offline domain, and like B<--live> B<--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>: The supplied XML description of the device should be as specific
|
|
as its definition in the domain XML. The set of attributes used
|
|
to match the device are internal to the drivers. Using a partial definition,
|
|
or attempting to detach a device that is not present in the domain XML,
|
|
but shares some specific attributes with one that is present,
|
|
may lead to unexpected results.
|
|
|
|
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-device-alias> I<domain> I<alias>
|
|
[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]]
|
|
|
|
Detach a device with given I<alias> from the I<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.
|
|
|
|
=item B<detach-disk> I<domain> I<target>
|
|
[[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]]
|
|
[I<--print-xml>]
|
|
|
|
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>.
|
|
|
|
If B<--print-xml> is specified, then the XML which would be used to detach the
|
|
disk is printed instead.
|
|
|
|
=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<https://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>]]
|
|
[I<--print-xml>] [I<--block>]
|
|
|
|
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. Flag I<--block>
|
|
allows to set the backing type in case a block device is used as media for the
|
|
CDROM or floppy drive instead of a file.
|
|
|
|
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.
|
|
If I<--print-xml> is specified, the XML that would be used to change media is
|
|
printed instead of changing the media.
|
|
|
|
=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<https://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 of a PCI device 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. If a PCI 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.
|
|
|
|
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', 'drm', 'mdev',
|
|
'mdev_types', 'ccw'.
|
|
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 PCI devices in managed mode and USB devices, 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.
|
|
|
|
=item B<nodedev-event> {[I<nodedev>] I<event> [I<--loop>] [I<--timeout>
|
|
I<seconds>] [I<--timestamp>] | I<--list>}
|
|
|
|
Wait for a class of node device events to occur, and print appropriate
|
|
details of events as they happen. The events can optionally be filtered
|
|
by I<nodedev>. 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.
|
|
|
|
When I<--timestamp> is used, a human-readable timestamp will be printed
|
|
before the event.
|
|
|
|
=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<https://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<https://libvirt.org/formatnetwork.html>
|
|
to get a description of the XML network format used by libvirt.
|
|
|
|
=item B<net-define> I<file>
|
|
|
|
Define an inactive persistent virtual network or modify an existing persistent
|
|
one from the XML I<file>.
|
|
|
|
=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<--timestamp>] | 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.
|
|
|
|
When I<--timestamp> is used, a human-readable timestamp will be printed
|
|
before the event.
|
|
|
|
=item B<net-info> I<network>
|
|
|
|
Returns basic information about the I<network> object.
|
|
|
|
=item B<net-list> [I<--inactive> | I<--all>]
|
|
{ [I<--table>] | I<--name> | I<--uuid> }
|
|
[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.
|
|
|
|
If I<--name> is specified, network names are printed instead of the table
|
|
formatted one per line. If I<--uuid> is specified network'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.
|
|
|
|
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 a persistent network. If the network is active,
|
|
make it transient.
|
|
|
|
=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>.
|
|
|
|
=item B<net-dhcp-leases> I<network> [I<mac>]
|
|
|
|
Get a list of dhcp leases for all network interfaces connected to the given
|
|
virtual I<network> or limited output just for one interface if I<mac> is
|
|
specified.
|
|
|
|
=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 an inactive persistent physical host interface or modify an existing
|
|
persistent one from the XML I<file>.
|
|
|
|
=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<https://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 possible available storage pool sources that
|
|
could be used to create or define a storage pool of a given I<type>. If
|
|
I<srcSpec> is provided, it is a file that contains XML to further restrict
|
|
the query for pools.
|
|
|
|
Not all storage pools support discovery in this manner. Furthermore, for
|
|
those that do support discovery, only specific XML elements are required
|
|
in order to return valid data, while other elements and even attributes
|
|
of some elements are ignored since they are not necessary to find the pool
|
|
based on the search criteria. The following lists the supported I<type>
|
|
options and the expected minimal XML elements used to perform the search.
|
|
|
|
For a "netfs" or "gluster" pool, the minimal expected XML required is the
|
|
<host> element with a "name" attribute describing the IP address or hostname
|
|
to be used to find the pool. The "port" attribute will be ignored as will
|
|
any other provided XML elements in I<srcSpec>.
|
|
|
|
For a "logical" pool, the contents of the I<srcSpec> file are ignored,
|
|
although if provided the file must at least exist.
|
|
|
|
For an "iscsi" pool, the minimal expect XML required is the <host> element
|
|
with a "name" attribute describing the IP address or hostname to be used to
|
|
find the pool (the iSCSI server address). Optionally, the "port" attribute
|
|
may be provided, although it will default to 3260. Optionally, an <initiator>
|
|
XML element with a "name" attribute may be provided to further restrict the
|
|
iSCSI target search to a specific initiator for multi-iqn iSCSI storage pools.
|
|
|
|
=item B<find-storage-pool-sources-as> I<type> [I<host>] [I<port>]
|
|
[I<initiator>]
|
|
|
|
Rather than providing I<srcSpec> XML file for B<find-storage-pool-sources>
|
|
use this command option in order to have virsh generate the query XML file
|
|
using the optional arguments. The command will return the same output
|
|
XML as B<find-storage-pool-sources>.
|
|
|
|
Use I<host> to describe a specific host to use for networked storage, such
|
|
as netfs, gluster, and iscsi I<type> pools.
|
|
|
|
Use I<port> to further restrict which networked port to utilize for the
|
|
connection if required by the specific storage backend, such as iscsi.
|
|
|
|
Use I<initiator> to further restrict the iscsi I<type> pool searches to
|
|
specific target initiators.
|
|
|
|
=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, disk, or logical pool.
|
|
|
|
For a file system pool if neither flag is specified, then B<pool-build>
|
|
just makes the target path directory and no attempt to run mkfs on the
|
|
target volume device. If I<--no-overwrite> is specified, it probes to
|
|
determine if a filesystem already exists on the target device, returning
|
|
an error if one exists or using mkfs to format the target device if not.
|
|
If I<--overwrite> is specified, mkfs is always executed and any existing
|
|
data on the target device is overwritten unconditionally.
|
|
|
|
For a disk pool, if neither of them is specified or I<--no-overwrite>
|
|
is specified, B<pool-build> will check the target volume device for
|
|
existing filesystems or partitions before attempting to write a new
|
|
label on the target volume device. If the target volume device already
|
|
has a label, the command will fail. If I<--overwrite> is specified,
|
|
then no check will be made on the target volume device prior to writing
|
|
a new label. Writing of the label uses the pool source format type
|
|
or "dos" if not specified.
|
|
|
|
For a logical pool, if neither of them is specified or I<--no-overwrite>
|
|
is specified, B<pool-build> will check the target volume devices for
|
|
existing filesystems or partitions before attempting to initialize
|
|
and format each device for usage by the logical pool. If any target
|
|
volume device already has a label, the command will fail. If
|
|
I<--overwrite> is specified, then no check will be made on the target
|
|
volume devices prior to initializing and formatting each device. Once
|
|
all the target volume devices are properly formatted via pvcreate,
|
|
the volume group will be created using all the devices.
|
|
|
|
=item B<pool-create> I<file>
|
|
[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]]
|
|
|
|
Create and start a pool object from the XML I<file>.
|
|
|
|
[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] perform a
|
|
B<pool-build> after creation in order to remove the need for a
|
|
follow-up command to build the pool. The I<--overwrite> and
|
|
I<--no-overwrite> flags follow the same rules as B<pool-build>. If
|
|
just I<--build> is provided, then B<pool-build> is called with no flags.
|
|
|
|
=item B<pool-create-as> I<name> I<type>
|
|
[I<--source-host hostname>] [I<--source-path path>] [I<--source-dev path>]
|
|
[I<--source-name name>] [I<--target path>] [I<--source-format format>]
|
|
[I<--auth-type authtype> I<--auth-username username>
|
|
[I<--secret-usage usage> | I<--secret-uuid uuid>]]
|
|
[[I<--adapter-name name>] | [I<--adapter-wwnn> wwnn I<--adapter-wwpn> wwpn]
|
|
[I<--adapter-parent parent>]]
|
|
[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] [I<--print-xml>]
|
|
|
|
|
|
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>. When using B<pool-create-as> for a pool of I<type> "disk",
|
|
the existing partitions found on the I<--source-dev path> will be used
|
|
to populate the disk pool. Therefore, it is suggested to use
|
|
B<pool-define-as> and B<pool-build> with the I<--overwrite> in order
|
|
to properly initialize the disk pool.
|
|
|
|
[I<--source-host hostname>] provides the source hostname for pools backed
|
|
by storage from a remote server (pool types netfs, iscsi, rbd, sheepdog,
|
|
gluster).
|
|
|
|
[I<--source-path path>] provides the source directory path for pools backed
|
|
by directories (pool type dir).
|
|
|
|
[I<--source-dev path>] provides the source path for pools backed by physical
|
|
devices (pool types fs, logical, disk, iscsi, zfs).
|
|
|
|
[I<--source-name name>] provides the source name for pools backed by storage
|
|
from a named element (pool types logical, rbd, sheepdog, gluster).
|
|
|
|
[I<--target path>] is the path for the mapping of the storage pool into
|
|
the host file system.
|
|
|
|
[I<--source-format format>] provides information about the format of the
|
|
pool (pool types fs, netfs, disk, logical).
|
|
|
|
[I<--auth-type authtype> I<--auth-username username>
|
|
[I<--secret-usage usage> | I<--secret-uuid uuid>]]
|
|
provides the elements required to generate authentication credentials for
|
|
the storage pool. The I<authtype> is either chap for iscsi I<type> pools or
|
|
ceph for rbd I<type> pools. Either the secret I<usage> or I<uuid> value may
|
|
be provided, but not both.
|
|
|
|
[I<--adapter-name name>] defines the scsi_hostN adapter name to be used for
|
|
the scsi_host adapter type pool.
|
|
|
|
[I<--adapter-wwnn wwnn> I<--adapter-wwpn wwpn> [I<--adapter-parent parent> |
|
|
I<--adapter-parent-wwnn parent_wwnn> I<adapter-parent-wwpn parent_wwpn> |
|
|
I<--adapter-parent-fabric-wwn parent_fabric_wwn>]]
|
|
defines the wwnn and wwpn to be used for the fc_host adapter type pool.
|
|
Optionally provide the parent scsi_hostN node device to be used for the
|
|
vHBA either by parent name, parent_wwnn and parent_wwpn, or parent_fabric_wwn.
|
|
The parent name could change between reboots if the hardware environment
|
|
changes, so providing the parent_wwnn and parent_wwpn ensure usage of the
|
|
same physical HBA even if the scsi_hostN node device changes. Usage of the
|
|
parent_fabric_wwn allows a bit more flexibility to choose an HBA on the
|
|
same storage fabric in order to define the pool.
|
|
|
|
[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] perform a
|
|
B<pool-build> after creation in order to remove the need for a
|
|
follow-up command to build the pool. The I<--overwrite> and
|
|
I<--no-overwrite> flags follow the same rules as B<pool-build>. If
|
|
just I<--build> is provided, then B<pool-build> is called with no flags.
|
|
|
|
For a "logical" pool only [I<--name>] needs to be provided. The
|
|
[I<--source-name>] if provided must match the Volume Group name.
|
|
If not provided, one will be generated using the [I<--name>]. If
|
|
provided the [I<--target>] is ignored and a target source is generated
|
|
using the [I<--source-name>] (or as generated from the [I<--name>]).
|
|
|
|
=item B<pool-define> I<file>
|
|
|
|
Define an inactive persistent storage pool or modify an existing persistent one
|
|
from the XML I<file>.
|
|
|
|
=item B<pool-define-as> I<name> I<type>
|
|
[I<--source-host hostname>] [I<--source-path path>] [I<--source-dev path>]
|
|
[I<--source-name name>] [I<--target path>] [I<--source-format format>]
|
|
[I<--auth-type authtype> I<--auth-username username>
|
|
[I<--secret-usage usage> | I<--secret-uuid uuid>]]
|
|
[[I<--adapter-name name>] | [I<--adapter-wwnn> I<--adapter-wwpn>]
|
|
[I<--adapter-parent parent>]] [I<--print-xml>]
|
|
|
|
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>.
|
|
|
|
Use the same arguments as B<pool-create-as>, except for the I<--build>,
|
|
I<--overwrite>, and I<--no-overwrite> options.
|
|
|
|
=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<--bytes>] I<pool-or-uuid>
|
|
|
|
Returns basic information about the I<pool> object. If I<--bytes> is specified the sizes
|
|
of basic info are not converted to human friendly units.
|
|
|
|
=item B<pool-list> [I<--inactive>] [I<--all>]
|
|
[I<--persistent>] [I<--transient>]
|
|
[I<--autostart>] [I<--no-autostart>]
|
|
[[I<--details>] [I<--uuid>]
|
|
[I<--name>] [<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. If I<--uuid> is specified only pool's UUIDs are printed.
|
|
If I<--name> is specified only pool's names are printed. If both I<--name>
|
|
and I<--uuid> are specified, pool's UUID and names are printed side by side
|
|
without any header. Option I<--details> is mutually exclusive with options
|
|
I<--uuid> and I<--name>.
|
|
|
|
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>
|
|
[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]]
|
|
|
|
Start the storage I<pool>, which is previously defined but inactive.
|
|
|
|
[I<--build>] [[I<--overwrite>] | [I<--no-overwrite>]] perform a
|
|
B<pool-build> prior to B<pool-start> to ensure the pool environment is
|
|
in an expected state rather than needing to run the build command prior
|
|
to startup. The I<--overwrite> and I<--no-overwrite> flags follow the
|
|
same rules as B<pool-build>. If just I<--build> is provided, then
|
|
B<pool-build> is called with no flags.
|
|
|
|
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 dependent 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>.
|
|
|
|
=item B<pool-event> {[I<pool>] I<event> [I<--loop>] [I<--timeout>
|
|
I<seconds>] [I<--timestamp>] | I<--list>}
|
|
|
|
Wait for a class of storage pool events to occur, and print appropriate
|
|
details of events as they happen. The events can optionally be filtered
|
|
by I<pool>. 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.
|
|
|
|
When I<--timestamp> is used, a human-readable timestamp will be printed
|
|
before the event.
|
|
|
|
=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<vol-name-or-key-or-path>
|
|
[I<--inputpool> I<pool-or-uuid>] [I<--prealloc-metadata>] [I<--reflink>]
|
|
|
|
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<vol-name-or-key-or-path> is the name or key or path of the source volume.
|
|
|
|
I<--inputpool> I<pool-or-uuid> is the name or uuid of the storage pool the
|
|
source volume is in.
|
|
|
|
[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.
|
|
|
|
When I<--reflink> is specified, perform a COW lightweight copy,
|
|
where the data blocks are copied only when modified.
|
|
If this is not possible, the copy fails.
|
|
|
|
=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>] [I<--print-xml>]
|
|
|
|
Create a volume from a set of arguments unless I<--print-xml> is specified, in
|
|
which case just the XML of the volume object is printed out without any actual
|
|
object creation.
|
|
|
|
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. For a disk pool, this must match the
|
|
partition name as determined from the pool's source device path and the next
|
|
available partition. For example, a source device path of /dev/sdb and there
|
|
are no partitions on the disk, then the name must be sdb1 with the next
|
|
name being sdb2 and so on.
|
|
|
|
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. Use extended for disk
|
|
storage pools in order to create an extended partition (other values are
|
|
validity checked but not preserved when libvirtd is restarted or the pool
|
|
is refreshed).
|
|
|
|
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<vol-name-or-key-or-path> I<name>
|
|
[I<--pool> I<pool-or-uuid>] [I<--prealloc-metadata>] [I<--reflink>]
|
|
|
|
Clone an existing volume within the parent pool. Less powerful,
|
|
but easier to type, version of B<vol-create-from>.
|
|
|
|
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<--pool> I<pool-or-uuid> is the name or UUID of the storage pool
|
|
that contains the source volume and will contain the new volume.
|
|
If the source volume name is provided instead of the key or path, then
|
|
providing the pool is necessary to find the volume to be cloned; otherwise,
|
|
the first volume found by the key or path will be used.
|
|
|
|
[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.
|
|
|
|
When I<--reflink> is specified, perform a COW lightweight copy,
|
|
where the data blocks are copied only when modified.
|
|
If this is not possible, the copy fails.
|
|
|
|
=item B<vol-delete> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>]
|
|
[I<--delete-snapshots>]
|
|
|
|
Delete a given volume.
|
|
|
|
I<vol-name-or-key-or-path> is the volume name or key or path of the volume
|
|
to delete.
|
|
|
|
[I<--pool> I<pool-or-uuid>] is the name or UUID of the storage pool the volume
|
|
is in. If the volume name is provided instead of the key or path, then
|
|
providing the pool is necessary to find the volume to be deleted; otherwise,
|
|
the first volume found by the key or path will be used.
|
|
|
|
The I<--delete-snapshots> flag specifies that any snapshots associated with
|
|
the storage volume should be deleted as well. Not all storage drivers
|
|
support this option, presently only rbd.
|
|
|
|
=item B<vol-upload> I<vol-name-or-key-or-path> I<local-file>
|
|
[I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>]
|
|
[I<--length> I<bytes>] [I<--sparse>]
|
|
|
|
Upload the contents of I<local-file> to a storage volume.
|
|
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume where the
|
|
I<local-file> will be uploaded.
|
|
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. If the volume name is provided instead of the key or path, then
|
|
providing the pool is necessary to find the volume to be uploaded into;
|
|
otherwise, the first volume found by the key or path will be used.
|
|
|
|
I<--offset> is the position in the storage volume at which to start writing
|
|
the data. The value must be 0 or larger.
|
|
|
|
I<--length> is an upper bound of the amount of data to be uploaded.
|
|
A negative value is interpreted as an unsigned long long value to
|
|
essentially include everything from the offset to the end of the volume.
|
|
|
|
If I<--sparse> is specified, this command will preserve volume sparseness.
|
|
|
|
An error will occur if the I<local-file> is greater than the specified
|
|
I<length>.
|
|
|
|
See the description for the libvirt virStorageVolUpload API for details
|
|
regarding possible target volume and pool changes as a result of the
|
|
pool refresh when the upload is attempted.
|
|
|
|
=item B<vol-download> I<vol-name-or-key-or-path> I<local-file>
|
|
[I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>] [I<--length> I<bytes>]
|
|
[I<--sparse>]
|
|
|
|
Download the contents of a storage volume to I<local-file>.
|
|
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to
|
|
download into I<local-file>.
|
|
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. If the volume name is provided instead of the key or path, then
|
|
providing the pool is necessary to find the volume to be uploaded into;
|
|
otherwise, the first volume found by the key or path will be used.
|
|
|
|
I<--offset> is the position in the storage volume at which to start reading
|
|
the data. The value must be 0 or larger.
|
|
|
|
I<--length> is an upper bound of the amount of data to be downloaded.
|
|
A negative value is interpreted as an unsigned long long value to
|
|
essentially include everything from the offset to the end of the volume.
|
|
|
|
If I<--sparse> is specified, this command will preserve volume sparseness.
|
|
|
|
=item B<vol-wipe> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>]
|
|
[I<--algorithm> I<algorithm>]
|
|
|
|
Wipe a volume, ensure data previously on the volume is not accessible to
|
|
future reads.
|
|
|
|
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.
|
|
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the
|
|
volume is in. If the volume name is provided instead of the key or path,
|
|
then providing the pool is necessary to find the volume to be wiped;
|
|
otherwise, the first volume found by the key or path will be used.
|
|
|
|
Use the I<--algorithm> switch choosing from the list of the following
|
|
algorithms in order to define which algorithm to use for the wipe.
|
|
|
|
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.
|
|
trim - 1-pass trimming the volume using TRIM or DISCARD
|
|
|
|
B<Note>: The C<scrub> binary will be used to handle the 'nnsa', 'dod',
|
|
'bsi', 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33' algorithms.
|
|
The availability of the algorithms may be limited by the version of
|
|
the C<scrub> binary installed on the host. The 'zero' algorithm will
|
|
write zeroes to the entire volume. For some volumes, such as sparse
|
|
or rbd volumes, this may result in completely filling the volume with
|
|
zeroes making it appear to be completely full. As an alternative, the
|
|
'trim' algorithm does not overwrite all the data in a volume, rather
|
|
it expects the storage driver to be able to discard all bytes in a
|
|
volume. It is up to the storage driver to handle how the discarding
|
|
occurs. Not all storage drivers or volume types can support 'trim'.
|
|
|
|
=item B<vol-dumpxml> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>]
|
|
|
|
Output the volume information as an XML dump to stdout.
|
|
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume
|
|
to output the XML.
|
|
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. If the volume name is provided instead of the key or path, then
|
|
providing the pool is necessary to find the volume to be uploaded into;
|
|
otherwise, the first volume found by the key or path will be used.
|
|
|
|
=item B<vol-info> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>]
|
|
[I<--bytes>] [I<--physical>]
|
|
|
|
Returns basic information about the given storage volume.
|
|
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume
|
|
to return information for.
|
|
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. If the volume name is provided instead of the key or path, then
|
|
providing the pool is necessary to find the volume to be uploaded into;
|
|
otherwise, the first volume found by the key or path will be used.
|
|
|
|
If I<--bytes> is specified the sizes are not converted to human friendly
|
|
units.
|
|
|
|
If I<--physical> is specified, then the host physical size is returned
|
|
and displayed instead of the allocation value. The physical value for
|
|
some file types, such as qcow2 may have a different (larger) physical
|
|
value than is shown for allocation. Additionally sparse files will
|
|
have different physical and allocation values.
|
|
|
|
=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<vol-key-or-path> [I<--uuid>]
|
|
|
|
Return the pool name or UUID for a given volume. By default, the pool name is
|
|
returned.
|
|
|
|
I<vol-key-or-path> is the key or path of the volume to return the pool
|
|
information.
|
|
|
|
If the I<--uuid> option is given, the pool UUID is returned instead.
|
|
|
|
=item B<vol-path> I<vol-name-or-key> [I<--pool> I<pool-or-uuid>]
|
|
|
|
Return the path for a given volume.
|
|
|
|
I<vol-name-or-key> is the name or key of the volume to return the path.
|
|
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. If the volume name is provided instead of the key, then providing
|
|
the pool is necessary to find the volume to be uploaded into; otherwise,
|
|
the first volume found by the key will be used.
|
|
|
|
=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.
|
|
|
|
=item B<vol-key> I<vol-name-or-path> [I<--pool> I<pool-or-uuid>]
|
|
|
|
Return the volume key for a given volume.
|
|
|
|
I<vol-name-or-path> is the name or path of the volume to return the
|
|
volume key.
|
|
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. If the volume name is provided instead of the path, then providing
|
|
the pool is necessary to find the volume to be uploaded into; otherwise,
|
|
the first volume found by the path will be used.
|
|
|
|
=item B<vol-resize> I<vol-name-or-path> I<capacity> [I<--pool> I<pool-or-uuid>]
|
|
[I<--allocate>] [I<--delta>] [I<--shrink>]
|
|
|
|
Resize the capacity of the given volume, in bytes.
|
|
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume
|
|
to resize.
|
|
|
|
I<capacity> is a scaled integer (see B<NOTES> above) for the volume,
|
|
which defaults to bytes if there is no suffix.
|
|
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume
|
|
is in. If the volume name is provided instead of the key or path, then
|
|
providing the pool is necessary to find the volume to be uploaded into;
|
|
otherwise, the first volume found by the key or path will be used.
|
|
|
|
The new I<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.
|
|
The I<capacity> cannot be negative unless I<--shrink> is provided, but
|
|
a negative sign is not necessary.
|
|
|
|
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<https://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-event> {[I<secret>] I<event> [I<--loop>] [I<--timeout>
|
|
I<seconds>] [I<--timestamp>] | I<--list>}
|
|
|
|
Wait for a class of secret events to occur, and print appropriate details
|
|
of events as they happen. The events can optionally be filtered by
|
|
I<secret>. 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.
|
|
|
|
When I<--timestamp> is used, a human-readable timestamp will be printed
|
|
before the event.
|
|
|
|
=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<https://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 be pre-created with correct format and
|
|
metadata. The file is then 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 (checkpoint) while
|
|
the guest is running. Both disk snapshot and domain memory snapshot are
|
|
taken. 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]>. A I<diskspec>
|
|
must be provided for disks backed by block devices as libvirt doesn't
|
|
auto-generate file names for those. 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 be pre-created with correct
|
|
format and metadata. The file is then 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 device hotplug
|
|
or hotunplug may not work. The attached environment should be considered
|
|
primarily read-only.
|
|
|
|
=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>]
|
|
[I<--timestamp>]
|
|
|
|
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.
|
|
|
|
When I<--timestamp> is used, a human-readable timestamp will be printed
|
|
before the event, and the timing information provided by QEMU will be
|
|
omitted.
|
|
|
|
=item B<lxc-enter-namespace> I<domain> [I<--noseclabel>] -- /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. The command will be run
|
|
with the same sVirt context and cgroups placement as processes within the
|
|
container. This command only works when connected to the LXC hypervisor
|
|
driver. This command succeeds only if C</path/to/binary> has 0 exit status.
|
|
|
|
By default the new process will run with the security label of the new
|
|
parent container. Use the I<--noseclabel> option to instead have the
|
|
process keep the same security label as C<virsh>.
|
|
|
|
=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
|
|
|
|
=back
|
|
|
|
For further information about debugging options consult
|
|
L<https://libvirt.org/logging.html>
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
Report any bugs discovered to the libvirt community via the mailing
|
|
list L<https://libvirt.org/contact.html> or bug tracker
|
|
L<https://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-2015 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<https://libvirt.org/>
|
|
|
|
=cut
|