mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-05 04:41:20 +00:00
0ddc8d0aeb
Based on a smaller patch developed by Moritoshi Oshiro: https://bugzilla.redhat.com/show_bug.cgi?id=693963 * tools/virsh.pod (freecell): Mention all, and clarify that optional cellno requires --cellno.
1417 lines
48 KiB
Plaintext
1417 lines
48 KiB
Plaintext
=head1 NAME
|
|
|
|
virsh - management user interface
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<virsh> [I<OPTION>]... [I<COMMAND_STRING>]
|
|
|
|
B<virsh> [I<OPTION>]... I<COMMAND> [I<ARG>]...
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<virsh> program is the main interface for managing virsh guest
|
|
domains. The program can be used to create, pause, and shutdown
|
|
domains. It can also be used to list current domains. Libvirt is a C
|
|
toolkit to interact with the virtualization capabilities of recent
|
|
versions of Linux (and other OSes). It is free software available
|
|
under the GNU Lesser General Public License. Virtualization of the
|
|
Linux Operating System means the ability to run multiple instances of
|
|
Operating Systems concurrently on a single hardware system where the
|
|
basic resources are driven by a Linux instance. The library aims at
|
|
providing a long term stable C API. It currently supports Xen, QEmu,
|
|
KVM, LXC, OpenVZ, VirtualBox and VMware ESX.
|
|
|
|
The basic structure of most virsh usage is:
|
|
|
|
virsh [OPTION]... <command> <domain-id> [ARG]...
|
|
|
|
Where I<command> is one of the commands listed below, I<domain-id>
|
|
is the numeric domain id, or the domain name (which will be internally
|
|
translated to domain id), and I<ARGS> are command specific
|
|
options. There are a few exceptions to this rule in the cases where
|
|
the command in question acts on all domains, the entire machine,
|
|
or directly on the xen hypervisor. Those exceptions will be clear for
|
|
each of those commands.
|
|
|
|
The B<virsh> program can be used either to run one I<COMMAND> by giving the
|
|
command and its arguments on the shell command line, or a I<COMMAND_STRING>
|
|
which is a single shell argument consisting of multiple I<COMMAND> actions
|
|
and their arguments joined with whitespace, and separated by semicolons
|
|
between commands. Within I<COMMAND_STRING>, virsh understands the
|
|
same single, double, and backslash escapes as the shell, although you must
|
|
add another layer of shell escaping in creating the single shell argument.
|
|
If no command is given in the command line, B<virsh> will then start a minimal
|
|
interpreter waiting for your commands, and the B<quit> command will then exit
|
|
the program.
|
|
|
|
The B<virsh> program understands the following I<OPTIONS>.
|
|
|
|
=over 4
|
|
|
|
=item B<-h>, B<--help>
|
|
|
|
Ignore all other arguments, and behave as if the B<help> command were
|
|
given instead.
|
|
|
|
=item B<-v>, B<--version[=short]>
|
|
|
|
Ignore all other arguments, and prints the version of the libvirt library
|
|
virsh is coming from
|
|
|
|
=item B<-V>, B<--version=long>
|
|
|
|
Ignore all other arguments, and prints the version of the libvirt library
|
|
virsh is coming from and which options and driver are compiled in.
|
|
|
|
=item B<-c>, B<--connect> I<URI>
|
|
|
|
Connect to the specified I<URI>, as if by the B<connect> command,
|
|
instead of the default connection.
|
|
|
|
=item B<-d>, B<--debug> I<LEVEL>
|
|
|
|
Enable debug messages at integer I<LEVEL> and above. I<LEVEL> can
|
|
range from 0 (default) to 5.
|
|
|
|
=item B<-l>, B<--log> I<FILE>
|
|
|
|
Output logging details to I<FILE>.
|
|
|
|
=item B<-q>, B<--quiet>
|
|
|
|
Avoid extra informational messages.
|
|
|
|
=item B<-r>, B<--readonly>
|
|
|
|
Make the initial connection read-only, as if by the I<--readonly>
|
|
option of the B<connect> command.
|
|
|
|
=item B<-t>, B<--timing>
|
|
|
|
Output elapsed time information for each command.
|
|
|
|
=back
|
|
|
|
=head1 NOTES
|
|
|
|
Most B<virsh> operations rely upon the libvirt library being able to
|
|
connect to an already running libvirtd service. This can usually be
|
|
done using the command B<service libvirtd start>.
|
|
|
|
Most B<virsh> commands require root privileges to run due to the
|
|
communications channels used to talk to the hypervisor. Running as
|
|
non root will return an error.
|
|
|
|
Most B<virsh> commands act synchronously, except maybe shutdown,
|
|
setvcpus and setmem. In those cases the fact that the B<virsh>
|
|
program returned, may not mean the action is complete and you
|
|
must poll periodically to detect that the guest completed the
|
|
operation.
|
|
|
|
=head1 GENERIC COMMANDS
|
|
|
|
The following commands are generic i.e. not specific to a domain.
|
|
|
|
=over 4
|
|
|
|
=item B<help> optional I<command-or-group>
|
|
|
|
This lists each of the virsh commands. When used without options, all
|
|
commands are listed, one per line, grouped into related categories,
|
|
displaying the keyword for each group.
|
|
|
|
To display only commands for a specific group, give the keyword for that
|
|
group as an option. For example:
|
|
|
|
virsh # help host
|
|
|
|
Host and Hypervisor (help keyword 'host'):
|
|
capabilities capabilities
|
|
connect (re)connect to hypervisor
|
|
freecell NUMA free memory
|
|
hostname print the hypervisor hostname
|
|
qemu-monitor-command Qemu Monitor Command
|
|
sysinfo print the hypervisor sysinfo
|
|
uri print the hypervisor canonical URI
|
|
|
|
To display detailed information for a specific command, give its name as the
|
|
option instead. For example:
|
|
|
|
virsh # help list
|
|
NAME
|
|
list - list domains
|
|
|
|
SYNOPSIS
|
|
list [--inactive] [--all]
|
|
|
|
DESCRIPTION
|
|
Returns list of domains.
|
|
|
|
OPTIONS
|
|
--inactive list inactive domains
|
|
--all list inactive & active domains
|
|
|
|
=item B<quit>, B<exit>
|
|
|
|
quit this interactive terminal
|
|
|
|
=item B<version>
|
|
|
|
Will print out the major version info about what this built from.
|
|
|
|
=over 4
|
|
|
|
B<Example>
|
|
|
|
B<virsh> version
|
|
|
|
Compiled against library: libvir 0.0.6
|
|
|
|
Using library: libvir 0.0.6
|
|
|
|
Using API: Xen 3.0.0
|
|
|
|
Running hypervisor: Xen 3.0.0
|
|
|
|
=back
|
|
|
|
=item B<cd> optional 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> optional I<--readonly>
|
|
|
|
(Re)-Connect to the hypervisor. When the shell is first started, this
|
|
is automatically run with the I<URI> parameter requested by the C<-c>
|
|
option on the command line. The I<URI> parameter specifies how to
|
|
connect to the hypervisor. The documentation page at
|
|
L<http://libvirt.org/uri.html> list the values supported, but the most
|
|
common are:
|
|
|
|
=over 4
|
|
|
|
=item xen:///
|
|
|
|
this is used to connect to the local Xen hypervisor, this is the default
|
|
|
|
=item qemu:///system
|
|
|
|
connect locally as root to the daemon supervising QEmu and KVM domains
|
|
|
|
=item qemu:///session
|
|
|
|
connect locally as a normal user to his own set of QEmu and KVM domains
|
|
|
|
=item lxc:///
|
|
|
|
connect to a local linux container
|
|
|
|
=back
|
|
|
|
For remote access see the documentation page on how to make URIs.
|
|
The I<--readonly> option allows for read-only connection
|
|
|
|
=item B<uri>
|
|
|
|
Prints the hypervisor canonical URI, can be useful in shell mode.
|
|
|
|
=item B<hostname>
|
|
|
|
Print the hypervisor hostname.
|
|
|
|
=item B<sysinfo>
|
|
|
|
Print the XML representation of the hypervisor sysinfo, if available.
|
|
|
|
=item B<nodeinfo>
|
|
|
|
Returns basic information about the node, like number and type of CPU,
|
|
and size of the physical memory.
|
|
|
|
=item B<capabilities>
|
|
|
|
Print an XML document describing the capabilities of the hypervisor
|
|
we are currently connected to. This includes a section on the host
|
|
capabilities in terms of CPU and features, and a set of description
|
|
for each kind of guest which can be virtualized. For a more complete
|
|
description see:
|
|
L<http://libvirt.org/formatcaps.html>
|
|
The XML also show the NUMA topology information if available.
|
|
|
|
=item B<list> optional I<--inactive> I<--all>
|
|
|
|
Prints information about one or more domains. If no domains are
|
|
specified it prints out information about running domains.
|
|
|
|
An example format for the list is as follows:
|
|
|
|
B<virsh> list
|
|
Id Name State
|
|
|
|
----------------------------------
|
|
|
|
0 Domain-0 running
|
|
2 fedora paused
|
|
|
|
|
|
Name is the name of the domain. ID the domain numeric id.
|
|
State is the run state (see below).
|
|
|
|
B<STATES>
|
|
|
|
The State field lists 7 states for a domain, and which ones the
|
|
current domain is in.
|
|
|
|
=over 4
|
|
|
|
=item B<running>
|
|
|
|
The domain is currently running on a CPU
|
|
|
|
=item B<idle>
|
|
|
|
The domain is idle, and not running or runnable. This can be caused
|
|
because the domain is waiting on IO (a traditional wait state) or has
|
|
gone to sleep because there was nothing else for it to do.
|
|
|
|
=item B<paused>
|
|
|
|
The domain has been paused, usually occurring through the administrator
|
|
running B<virsh suspend>. When in a paused state the domain will still
|
|
consume allocated resources like memory, but will not be eligible for
|
|
scheduling by the hypervisor.
|
|
|
|
=item B<shutdown>
|
|
|
|
The domain is in the process of shutting down, i.e. the guest operating system
|
|
has been notified and should be in the process of stopping its operations
|
|
gracefully.
|
|
|
|
=item B<shut off>
|
|
|
|
The domain is not running. Usually this indicates the domain has been
|
|
shut down completely, or has not been started.
|
|
|
|
=item B<crashed>
|
|
|
|
The domain has crashed, which is always a violent ending. Usually
|
|
this state can only occur if the domain has been configured not to
|
|
restart on crash.
|
|
|
|
=item B<dying>
|
|
|
|
The domain is in process of dying, but hasn't completely shutdown or
|
|
crashed.
|
|
|
|
=back
|
|
|
|
=item B<freecell> optional { I<--cellno> B<cellno> | I<--all> }
|
|
|
|
Prints the available amount of memory on the machine or within a
|
|
NUMA cell if I<cellno> is provided. If I<--all> is provided instead
|
|
of I<--cellno>, then show the information on all NUMA cells.
|
|
|
|
=item B<cpu-baseline> I<FILE>
|
|
|
|
Compute baseline CPU which will be supported by all host CPUs given in <file>.
|
|
The list of host CPUs is built by extracting all <cpu> elements from the
|
|
<file>. Thus, the <file> can contain either a set of <cpu> elements separated
|
|
by new lines or even a set of complete <capabilities> elements printed by
|
|
B<capabilities> command.
|
|
|
|
=item B<cpu-compare> I<FILE>
|
|
|
|
Compare CPU definition from XML <file> with host CPU. The XML <file> may
|
|
contain either host or guest CPU definition. The host CPU definition is the
|
|
<cpu> element and its contents as printed by B<capabilities> command. The
|
|
guest CPU definition is the <cpu> element and its contents from domain XML
|
|
definition. For more information on guest CPU definition see:
|
|
L<http://libvirt.org/formatdomain.html#elementsCPU>
|
|
|
|
=back
|
|
|
|
=head1 DOMAIN COMMANDS
|
|
|
|
The following commands manipulate domains directly, as stated
|
|
previously most commands take domain-id as the first parameter. The
|
|
I<domain-id> can be specified as a short integer, a name or a full UUID.
|
|
|
|
=over 4
|
|
|
|
=item B<autostart> optional I<--disable> I<domain-id>
|
|
|
|
Configure a domain to be automatically started at boot.
|
|
|
|
The option I<--disable> disables autostarting.
|
|
|
|
=item B<console> I<domain-id> [I<devname>]
|
|
|
|
Connect the virtual serial console for the guest. The optional
|
|
I<devname> parameter refers to the device alias of an alternate
|
|
console, serial or parallel device configured for the guest.
|
|
If omitted, the primary console will be opened.
|
|
|
|
=item B<create> I<FILE> optional I<--console> I<--paused>
|
|
|
|
Create a domain from an XML <file>. An easy way to create the XML
|
|
<file> is to use the B<dumpxml> command to obtain the definition of a
|
|
pre-existing guest. The domain will be paused if the I<--paused> option
|
|
is used and supported by the driver; otherwise it will be running.
|
|
If I<--console> is requested, attach to the console after creation.
|
|
|
|
B<Example>
|
|
|
|
virsh dumpxml <domain-id> > domain.xml
|
|
vi domain.xml (or make changes with your other text editor)
|
|
virsh create < domain.xml
|
|
|
|
=item B<define> I<FILE>
|
|
|
|
Define a domain from an XML <file>. The domain definition is registered
|
|
but not started.
|
|
|
|
=item B<destroy> I<domain-id>
|
|
|
|
Immediately terminate the domain domain-id. This doesn't give the domain
|
|
OS any chance to react, and it's the equivalent of ripping the power
|
|
cord out on a physical machine. In most cases you will want to use
|
|
the B<shutdown> command instead.
|
|
|
|
=item B<domblkstat> I<domain> I<block-device>
|
|
|
|
Get device block stats for a running domain.
|
|
|
|
=item B<domifstat> I<domain> I<interface-device>
|
|
|
|
Get network interface stats for a running domain.
|
|
|
|
=item B<dommemstat> I<domain>
|
|
|
|
Get memory stats for a running domain.
|
|
|
|
=item B<domblkinfo> I<domain> I<block-device>
|
|
|
|
Get block device size info for a domain.
|
|
|
|
=item B<dominfo> I<domain-id>
|
|
|
|
Returns basic information about the domain.
|
|
|
|
=item B<domuuid> I<domain-name-or-id>
|
|
|
|
Convert a domain name or id to domain UUID
|
|
|
|
=item B<domid> I<domain-name-or-uuid>
|
|
|
|
Convert a domain name (or UUID) to a domain id
|
|
|
|
=item B<domjobabort> I<domain-id-or-uuid>
|
|
|
|
Abort the currently running domain job.
|
|
|
|
=item B<domjobinfo> I<domain-id-or-uuid>
|
|
|
|
Returns information about jobs running on a domain.
|
|
|
|
=item B<domname> I<domain-id-or-uuid>
|
|
|
|
Convert a domain Id (or UUID) to domain name
|
|
|
|
=item B<domstate> I<domain-id>
|
|
|
|
Returns state about a running domain.
|
|
|
|
=item B<domxml-from-native> I<format> I<config>
|
|
|
|
Convert the file I<config> in the native guest configuration format
|
|
named by I<format> to a domain XML format.
|
|
|
|
=item B<domxml-to-native> I<format> I<xml>
|
|
|
|
Convert the file I<xml> in domain XML format to the native guest
|
|
configuration format named by I<format>.
|
|
|
|
=item B<dump> I<domain-id> I<corefilepath>
|
|
|
|
Dumps the core of a domain to a file for analysis.
|
|
|
|
=item B<dumpxml> I<domain-id> optional I<--inactive> I<--security-info> I<--update-cpu>
|
|
|
|
Output the domain information as an XML dump to stdout, this format can be used
|
|
by the B<create> command. Additional options affecting the XML dump may be
|
|
used. I<--inactive> tells virsh to dump domain configuration that will be used
|
|
on next start of the domain as opposed to the current domain configuration.
|
|
Using I<--security-info> security sensitive information will also be included
|
|
in the XML dump. I<--update-cpu> updates domain CPU requirements according to
|
|
host CPU.
|
|
|
|
=item B<echo> optional I<--shell> I<--xml> I<arg>...
|
|
|
|
Echo back each I<arg>, separated by space. If I<--shell> is
|
|
specified, then the output will be single-quoted where needed, so that
|
|
it is suitable for reuse in a shell context. If I<--xml> is
|
|
specified, then the output will be escaped for use in XML.
|
|
|
|
=item B<edit> I<domain-id>
|
|
|
|
Edit the XML configuration file for a domain.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh dumpxml domain > domain.xml
|
|
vi domain.xml (or make changes with your other text editor)
|
|
virsh define domain.xml
|
|
|
|
except that it does some error checking.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=item B<managedsave> I<domain-id>
|
|
|
|
Save and destroy 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.
|
|
|
|
=item B<managedsave-remove> I<domain-id>
|
|
|
|
Remove the B<managedsave> state file for a domain, if it exists. This
|
|
ensures the domain will do a full boot the next time it is started.
|
|
|
|
=item B<maxvcpus> optional I<type>
|
|
|
|
Provide the maximum number of virtual CPUs supported for a guest VM on
|
|
this connection. If provided, the I<type> parameter must be a valid
|
|
type attribute for the <domain> element of XML.
|
|
|
|
=item B<migrate> optional I<--live> I<--p2p> I<--direct> I<--tunnelled>
|
|
I<--persistent> I<--undefinesource> I<--suspend> I<--copy-storage-all>
|
|
I<--copy-storage-inc> I<--verbose> I<domain-id> I<desturi> I<migrateuri>
|
|
I<dname> I<--timeout>
|
|
|
|
Migrate domain to another host. Add I<--live> for live migration; I<--p2p>
|
|
for peer-2-peer migration; I<--direct> for direct migration; or I<--tunnelled>
|
|
for tunnelled migration. I<--persistent> leaves the domain persistent on
|
|
destination host, I<--undefinesource> undefines the domain on the source host,
|
|
and I<--suspend> leaves the domain paused on the destination host.
|
|
I<--copy-storage-all> indicates migration with non-shared storage with full
|
|
disk copy, I<--copy-storage-inc> indicates migration with non-shared storage
|
|
with incremental copy (same base image shared between source and destination).
|
|
I<--verbose> displays the progress of migration.
|
|
|
|
The I<desturi> is the connection URI of the destination host, and
|
|
I<migrateuri> is the migration URI, which usually can be omitted.
|
|
I<dname> is used for renaming the domain to new name during migration, which
|
|
also usually can be omitted.
|
|
|
|
I<--timeout> forces guest to suspend when live migration exceeds timeout, and
|
|
then the migration will complete offline. It can only be used with I<--live>.
|
|
|
|
B<Note>: The I<desturi> parameter for normal migration and peer2peer migration
|
|
has different semantics:
|
|
|
|
=over 4
|
|
|
|
=item * normal migration: the I<desturi> is an address of the target host as
|
|
seen from the client machine.
|
|
|
|
=item * peer2peer migration: the I<desturi> is an address of the target host as
|
|
seen from the source machine.
|
|
|
|
=back
|
|
|
|
=item B<migrate-setmaxdowntime> I<domain-id> I<downtime>
|
|
|
|
Set maximum tolerable downtime for a domain which is being live-migrated to
|
|
another host. The I<downtime> is a number of milliseconds the guest is allowed
|
|
to be down at the end of live migration.
|
|
|
|
=item B<reboot> I<domain-id>
|
|
|
|
Reboot a domain. This acts just as if the domain had the B<reboot>
|
|
command run from the console. The command returns as soon as it has
|
|
executed the reboot action, which may be significantly before the
|
|
domain actually reboots.
|
|
|
|
The exact behavior of a domain when it reboots is set by the
|
|
I<on_reboot> parameter in the domain's XML definition.
|
|
|
|
=item B<restore> I<state-file>
|
|
|
|
Restores a domain from a B<virsh save> state file. See I<save> for more info.
|
|
|
|
B<Note>: To avoid corrupting file system contents within the domain, you
|
|
should not reuse the saved state file for a second B<restore> unless you
|
|
have also reverted all storage volumes back to the same contents as when
|
|
the state file was created.
|
|
|
|
=item B<save> I<domain-id> I<state-file>
|
|
|
|
Saves a running domain 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.
|
|
|
|
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.
|
|
|
|
=item B<schedinfo> optional I<--set> B<parameter=value> I<domain-id>
|
|
|
|
=item B<schedinfo> optional I<--weight> B<number> optional I<--cap> B<number> I<domain-id>
|
|
|
|
Allows you to show (and set) the domain scheduler parameters. The parameters available for each hypervisor are:
|
|
|
|
LXC, QEMU/KVM (posix scheduler): cpu_shares
|
|
|
|
Xen (credit scheduler): weight, cap
|
|
|
|
ESX (allocation scheduler): reservation, limit, shares
|
|
|
|
B<Note>: The cpu_shares parameter has a valid value range of 0-262144; Negative
|
|
values are wrapped to positive, and larger values are capped at the maximum.
|
|
Therefore, -1 is a useful shorthand for 262144.
|
|
|
|
B<Note>: The weight and cap parameters are defined only for the
|
|
XEN_CREDIT scheduler and are now I<DEPRECATED>.
|
|
|
|
=item B<setmem> I<domain-id> B<kilobytes> optional I<--config> I<--live>
|
|
I<--current>
|
|
|
|
Change the memory allocation for a guest domain.
|
|
If I<--live> is specified, perform a memory balloon of a running guest.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified, affect the current guest state.
|
|
Both I<--live> and I<--config> flags may be given, but I<--current> is
|
|
exclusive. If no flag is specified, behavior is different depending
|
|
on hypervisor.
|
|
|
|
Some hypervisors require a larger granularity than kilobytes, and requests
|
|
that are not an even multiple will be rounded up. For example, vSphere/ESX
|
|
rounds the parameter up unless the kB argument is evenly divisible by 1024
|
|
(that is, the kB argument happens to represent megabytes).
|
|
|
|
For Xen, you can only adjust the memory of a running domain if the domain is
|
|
paravirtualized or running the PV balloon driver.
|
|
|
|
=item B<setmaxmem> I<domain-id> B<kilobytes> optional I<--config> I<--live>
|
|
I<--current>
|
|
|
|
Change the maximum memory allocation limit for a guest domain.
|
|
If I<--live> is specified, affect a running guest.
|
|
If I<--config> is specified, affect the next boot of a persistent guest.
|
|
If I<--current> is specified, affect the current guest state.
|
|
Both I<--live> and I<--current> flags may be given, but I<--current> is
|
|
exclusive. If no flag is specified, behavior is different depending
|
|
on hypervisor.
|
|
|
|
This command works for at least the Xen, QEMU/KVM and vSphere/ESX hypervisors.
|
|
|
|
Some hypervisors require a larger granularity than kilobytes, rounding up
|
|
requests that are not an even multiple of the desired amount. vSphere/ESX
|
|
is one of these, requiring the parameter to be evenly divisible by 4MB. For
|
|
vSphere/ESX, 263168 (257MB) would be rounded up because it's not a multiple
|
|
of 4MB, while 266240 (260MB) is valid without rounding.
|
|
|
|
|
|
=item B<memtune> I<domain-id> optional I<--hard-limit> B<kilobytes>
|
|
optional I<--soft-limit> B<kilobytes> optional I<--swap-hard-limit>
|
|
B<kilobytes> optional I<--min-guarantee> B<kilobytes>
|
|
|
|
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>.
|
|
|
|
For QEMU/KVM, the parameters are applied to the QEMU process as a whole.
|
|
Thus, when counting them, one needs to add up guest RAM, guest video RAM, and
|
|
some memory overhead of QEMU itself. The last piece is hard to determine so
|
|
one needs guess and try.
|
|
|
|
=over 4
|
|
|
|
=item I<--hard-limit>
|
|
|
|
The maximum memory the guest can use. The units for this value are kilobytes
|
|
(i.e. blocks of 1024 bytes).
|
|
|
|
=item I<--soft-limit>
|
|
|
|
The memory limit to enforce during memory contention. The units for this
|
|
value are kilobytes (i.e. blocks of 1024 bytes).
|
|
|
|
=item I<--swap-hard-limit>
|
|
|
|
The maximum memory plus swap the guest can use. The units for this value are
|
|
kilobytes (i.e. blocks of 1024 bytes). This has to be more than hard-limit
|
|
value provided.
|
|
|
|
=item I<--min-guarantee>
|
|
|
|
The guaranteed minimum memory allocation for the guest. The units for this
|
|
value are kilobytes (i.e. blocks of 1024 bytes).
|
|
|
|
=back
|
|
|
|
=item B<blkiotune> I<domain-id> optional I<--weight> B<weight>
|
|
|
|
Display or set the blkio parameters. QEMU/KVM supports I<--weight>.
|
|
I<--weight> is in range [100, 1000].
|
|
|
|
=item B<setvcpus> I<domain-id> I<count> optional I<--maximum> I<--config>
|
|
I<--live>
|
|
|
|
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.
|
|
|
|
When neither the I<--config> nor I<--live> flags are given, the I<--live>
|
|
flag is assumed and the guest domain must be active. In this situation it
|
|
is up to the hypervisor whether the I<--config> flag is also assumed, and
|
|
therefore whether the XML configuration is adjusted to make the change
|
|
persistent.
|
|
|
|
The I<--maximum> flag controls the maximum number of virtual cpus that can
|
|
be hot-plugged the next time the domain is booted. As such, it must only be
|
|
used with the I<--config> flag, and not with the I<--live> flag.
|
|
|
|
=item B<shutdown> I<domain-id>
|
|
|
|
Gracefully shuts down a domain. This coordinates with the domain OS
|
|
to perform graceful shutdown, so there is no guarantee that it will
|
|
succeed, and may take a variable length of time depending on what
|
|
services must be shutdown in the domain.
|
|
|
|
The exact behavior of a domain when it shuts down is set by the
|
|
I<on_shutdown> parameter in the domain's XML definition.
|
|
|
|
=item B<start> I<domain-name> optional I<--console> I<--paused>
|
|
|
|
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.
|
|
|
|
=item B<suspend> I<domain-id>
|
|
|
|
Suspend a running domain. It is kept in memory but won't be scheduled
|
|
anymore.
|
|
|
|
=item B<resume> I<domain-id>
|
|
|
|
Moves a domain out of the suspended state. This will allow a previously
|
|
suspended domain to now be eligible for scheduling by the underlying
|
|
hypervisor.
|
|
|
|
=item B<ttyconsole> I<domain-id>
|
|
|
|
Output the device used for the TTY console of the domain. If the information
|
|
is not available the processes will provide an exit code of 1.
|
|
|
|
=item B<undefine> I<domain-id>
|
|
|
|
Undefine the configuration for an inactive domain. Since it's not running
|
|
the domain name or UUID must be used as the I<domain-id>.
|
|
|
|
=item B<vcpucount> I<domain-id> optional I<--maximum> I<--current>
|
|
I<--config> I<--live>
|
|
|
|
Print information about the virtual cpu counts of the given
|
|
I<domain-id>. If no flags are specified, all possible counts are
|
|
listed in a table; otherwise, the output is limited to just the
|
|
numeric value requested.
|
|
|
|
I<--maximum> requests information on the maximum cap of vcpus that a
|
|
domain can add via B<setvcpus>, while I<--current> shows the current
|
|
usage; these two flags cannot both be specified. I<--config>
|
|
requests information regarding the next time the domain will be
|
|
booted, while I<--live> requires a running domain and lists current
|
|
values; these two flags cannot both be specified.
|
|
|
|
=item B<vcpuinfo> I<domain-id>
|
|
|
|
Returns basic information about the domain virtual CPUs, like the number of
|
|
vCPUs, the running time, the affinity to physical processors.
|
|
|
|
=item B<vcpupin> I<domain-id> I<vcpu> I<cpulist>
|
|
|
|
Pin domain VCPUs to host physical CPUs. The I<vcpu> number must be provided
|
|
and I<cpulist> is a comma separated list of physical CPU numbers.
|
|
|
|
=item B<vncdisplay> I<domain-id>
|
|
|
|
Output the IP address and port number for the VNC display. If the information
|
|
is not available the processes will provide an exit code of 1.
|
|
|
|
=back
|
|
|
|
=head1 DEVICE COMMANDS
|
|
|
|
The following commands manipulate devices associated to domains.
|
|
The domain-id can be specified as a short integer, a name or a full UUID.
|
|
To better understand the values allowed as options for the command
|
|
reading the documentation at L<http://libvirt.org/formatdomain.html> on the
|
|
format of the device sections to get the most accurate set of accepted values.
|
|
|
|
=over 4
|
|
|
|
=item B<attach-device> I<domain-id> I<FILE>
|
|
|
|
Attach a device to the domain, using a device definition in an XML file.
|
|
See the documentation to learn about libvirt XML format for a device.
|
|
For cdrom and floppy devices, this command only replaces the media within
|
|
the single existing device; consider using B<update-device> for this usage.
|
|
|
|
=item B<attach-disk> I<domain-id> I<source> I<target> optional
|
|
I<--driver driver> I<--subdriver subdriver> I<--type type>
|
|
I<--mode mode> I<--persistent> I<--sourcetype soucetype>
|
|
|
|
Attach a new disk device to the domain.
|
|
I<source> and I<target> are paths for the files and devices.
|
|
I<driver> can be I<file>, I<tap> or I<phy> depending on the kind of access.
|
|
I<type> can indicate I<cdrom> or I<floppy> as alternative to the disk default,
|
|
although this use only replaces the media within the existing virtual cdrom or
|
|
floppy device; consider using B<update-device> for this usage instead.
|
|
I<mode> can specify the two specific mode I<readonly> or I<shareable>.
|
|
I<persistent> indicates the changes will affect the next boot of the domain.
|
|
I<sourcetype> can indicate the type of source (block|file)
|
|
|
|
=item B<attach-interface> I<domain-id> I<type> I<source> optional
|
|
I<--target target> I<--mac mac> I<--script script> I<--model model>
|
|
I<--persistent>
|
|
|
|
Attach a new network interface to the domain.
|
|
I<type> can be either I<network> to indicate a physical network device or I<bridge> to indicate a bridge to a device.
|
|
I<source> indicates the source device.
|
|
I<target> allows to indicate the target device in the guest.
|
|
I<mac> allows to specify the MAC address of the network interface.
|
|
I<script> allows to specify a path to a script handling a bridge instead of
|
|
the default one.
|
|
I<model> allows to specify the model type.
|
|
I<persistent> indicates the changes will affect the next boot of the domain.
|
|
|
|
=item B<detach-device> I<domain-id> I<FILE>
|
|
|
|
Detach a device from the domain, takes the same kind of XML descriptions
|
|
as command B<attach-device>.
|
|
|
|
=item B<detach-disk> I<domain-id> I<target>
|
|
|
|
Detach a disk device from a domain. The I<target> is the device as seen
|
|
from the domain.
|
|
|
|
=item B<detach-interface> I<domain-id> I<type> optional I<--mac mac>
|
|
|
|
Detach a network interface from a domain.
|
|
I<type> can be either I<network> to indicate a physical network device or I<bridge> to indicate a bridge to a device.
|
|
It is recommended to use the I<mac> option to distinguish between the interfaces
|
|
if more than one are present on the domain.
|
|
|
|
=item B<update-device> I<domain-id> I<file> optional I<--persistent> I<--force>
|
|
|
|
Update the characteristics of a device associated with I<domain-id>, based on
|
|
the device definition in an XML I<file>. If the I<--persistent> option is
|
|
used, the changes will affect the next boot of the domain. The I<--force>
|
|
option can be used to force device update, e.g., to eject a CD-ROM even if it
|
|
is locked/mounted in the domain. See the documentation to learn about libvirt
|
|
XML format for a device.
|
|
|
|
=back
|
|
|
|
=head1 VIRTUAL NETWORK COMMANDS
|
|
|
|
The following commands manipulate networks. Libvirt has the capability to
|
|
define virtual networks which can then be used by domains and linked to
|
|
actual network devices. For more detailed information about this feature
|
|
see the documentation at L<http://libvirt.org/formatnetwork.html> . A lot
|
|
of the command for virtual networks are similar to the one 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> optional I<--disable>
|
|
|
|
Configure a virtual network to be automatically started at boot.
|
|
The I<--disable> option disable autostarting.
|
|
|
|
=item B<net-create> I<file>
|
|
|
|
Create a virtual network from an XML I<file>, see the documentation to get
|
|
a description of the XML network format used by libvirt.
|
|
|
|
=item B<net-define> I<file>
|
|
|
|
Define a virtual network from an XML I<file>, the network is just defined but
|
|
not instantiated.
|
|
|
|
=item B<net-destroy> I<network>
|
|
|
|
Destroy a given virtual network specified by its name or UUID. This takes
|
|
effect immediately.
|
|
|
|
=item B<net-dumpxml> I<network>
|
|
|
|
Output the virtual network information as an XML dump to stdout.
|
|
|
|
=item B<net-edit> I<network>
|
|
|
|
Edit the XML configuration file for a network.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh net-dumpxml network > network.xml
|
|
vi network.xml (or make changes with your other text editor)
|
|
virsh net-define network.xml
|
|
|
|
except that it does some error checking.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=item B<net-info> I<network>
|
|
|
|
Returns basic information about the I<network> object.
|
|
|
|
=item B<net-list> optional I<--inactive> or I<--all>
|
|
|
|
Returns the list of active networks, if I<--all> is specified this will also
|
|
include defined but inactive networks, if I<--inactive> is specified only the
|
|
inactive ones will be listed.
|
|
|
|
=item B<net-name> I<network-UUID>
|
|
|
|
Convert a network UUID to network name.
|
|
|
|
=item B<net-start> I<network>
|
|
|
|
Start a (previously defined) inactive network.
|
|
|
|
=item B<net-undefine> I<network>
|
|
|
|
Undefine the configuration for an inactive network.
|
|
|
|
=item B<net-uuid> I<network-name>
|
|
|
|
Convert a network name to network UUID.
|
|
|
|
=back
|
|
|
|
=head1 STORAGE POOL COMMANDS
|
|
|
|
The following commands manipulate storage pools. Libvirt has the
|
|
capability to manage various storage solutions, including files, raw
|
|
partitions, and domain-specific formats, used to provide the storage
|
|
volumes visible as devices within virtual machines. For more detailed
|
|
information about this feature, see the documentation at
|
|
L<http://libvirt.org/formatstorage.html> . A lot of the commands for
|
|
pools are similar to the ones used for domains.
|
|
|
|
=over 4
|
|
|
|
=item B<find-storage-pool-sources> I<type> optional I<srcSpec>
|
|
|
|
Returns XML describing all storage pools of a given I<type> that could
|
|
be found. If I<srcSpec> is provided, it is a file that contains XML
|
|
to further restrict the query for pools.
|
|
|
|
=item B<find-storage-pool-sources> I<type> optional I<host> I<port>
|
|
|
|
Returns XML describing all storage pools of a given I<type> that could
|
|
be found. If I<host> and I<port> are provided, they control where the
|
|
query is performed.
|
|
|
|
=item B<pool-autostart> I<pool-or-uuid> optional I<--disable>
|
|
|
|
Configure whether I<pool> should automatically start at boot.
|
|
|
|
=item B<pool-build> I<pool-or-uuid>
|
|
|
|
Build a given pool.
|
|
|
|
=item B<pool-create> I<file>
|
|
|
|
Create and start a pool object from the XML I<file>.
|
|
|
|
=item B<pool-create-as> I<name> I<--print-xml> I<type> optional I<source-host>
|
|
I<source-path> I<source-dev> I<source-name> <target> I<--source-format format>
|
|
|
|
Create and start a pool object I<name> from the raw parameters. If
|
|
I<--print-xml> is specified, then print the XML of the pool object
|
|
without creating the pool. Otherwise, the pool has the specified
|
|
I<type>.
|
|
|
|
=item B<pool-define> I<file>
|
|
|
|
Create, but do not start, a pool object from the XML I<file>.
|
|
|
|
=item B<pool-define-as> I<name> I<--print-xml> I<type> optional I<source-host>
|
|
I<source-path> I<source-dev> I<source-name> <target> I<--source-format format>
|
|
|
|
Create, but do not start, a pool object I<name> from the raw parameters. If
|
|
I<--print-xml> is specified, then print the XML of the pool object
|
|
without defining the pool. Otherwise, the pool has the specified
|
|
I<type>.
|
|
|
|
=item B<pool-destroy> I<pool-or-uuid>
|
|
|
|
Destroy 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.
|
|
|
|
=item B<pool-dumpxml> I<pool-or-uuid>
|
|
|
|
Returns the XML information about the I<pool> object.
|
|
|
|
=item B<pool-edit> I<pool-or-uuid>
|
|
|
|
Edit the XML configuration file for a storage pool.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh pool-dumpxml pool > pool.xml
|
|
vi pool.xml (or make changes with your other text editor)
|
|
virsh pool-define pool.xml
|
|
|
|
except that it does some error checking.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=item B<pool-info> I<pool-or-uuid>
|
|
|
|
Returns basic information about the I<pool> object.
|
|
|
|
=item B<pool-list> optional I<--inactive> I<--all> I<--details>
|
|
|
|
List pool objects known to libvirt. By default, only pools in use by
|
|
active domains are listed; I<--inactive> lists just the inactive
|
|
pools, and I<--all> lists all pools. The I<--details> option instructs
|
|
virsh to additionally display pool persistence and capacity related
|
|
information where available.
|
|
|
|
=item B<pool-name> I<uuid>
|
|
|
|
Convert the I<uuid> to a pool name.
|
|
|
|
=item B<pool-refresh> I<pool-or-uuid>
|
|
|
|
Refresh the list of volumes contained in I<pool>.
|
|
|
|
=item B<pool-start> I<pool-or-uuid>
|
|
|
|
Start the storage I<pool>, which is previously defined but inactive.
|
|
|
|
=item B<pool-undefine> I<pool-or-uuid>
|
|
|
|
Undefine the configuration for an inactive I<pool>.
|
|
|
|
=item B<pool-uuid> I<pool>
|
|
|
|
Returns the UUID of the named I<pool>.
|
|
|
|
=back
|
|
|
|
=head1 VOLUME COMMANDS
|
|
|
|
=over 4
|
|
|
|
=item B<vol-create> I<pool-or-uuid> I<FILE>
|
|
|
|
Create a volume from an XML <file>.
|
|
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
|
|
I<FILE> is the XML <file> with the volume definition. An easy way to create the
|
|
XML <file> is to use the B<vol-dumpxml> command to obtain the definition of a
|
|
pre-existing volume.
|
|
|
|
B<Example>
|
|
|
|
virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
|
|
vi newvolume.xml (or make changes with your other text editor)
|
|
virsh vol-create differentstoragepool newvolume.xml
|
|
|
|
=item B<vol-create-from> I<pool-or-uuid> I<FILE> [optional I<--inputpool>
|
|
I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Create a volume, using another volume as input.
|
|
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
|
|
I<FILE> is the XML <file> with the volume definition.
|
|
I<--inputpool> I<pool-or-uuid> is the name or uuid of the storage pool the
|
|
source volume is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the source volume.
|
|
|
|
=item B<vol-create-as> I<pool-or-uuid> I<name> I<capacity> optional
|
|
I<--allocation> I<size> I<--format> I<string> I<--backing-vol>
|
|
I<vol-name-or-key-or-path> I<--backing-vol-format> I<string>
|
|
|
|
Create a volume from a set of arguments.
|
|
I<pool-or-uuid> is the name or UUID of the storage pool to create the volume
|
|
in.
|
|
I<name> is the name of the new volume.
|
|
I<capacity> is the size of the volume to be created, with optional k, M, G, or
|
|
T suffix.
|
|
I<--allocation> I<size> is the initial size to be allocated in the volume, with
|
|
optional k, M, G, or T suffix.
|
|
I<--format> I<string> is used in file based storage pools to specify the volume
|
|
file format to use; raw, bochs, qcow, qcow2, vmdk.
|
|
I<--backing-vol> I<vol-name-or-key-or-path> is the source backing
|
|
volume to be used if taking a snapshot of an existing volume.
|
|
I<--backing-vol-format> I<string> is the format of the snapshot backing volume;
|
|
raw, bochs, qcow, qcow2, vmdk, host_device.
|
|
|
|
=item B<vol-clone> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path> I<name>
|
|
|
|
Clone an existing volume. Less powerful, but easier to type, version of
|
|
B<vol-create-from>.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the source volume.
|
|
I<name> is the name of the new volume.
|
|
|
|
=item B<vol-delete> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Delete a given volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to delete.
|
|
|
|
=item B<vol-upload> [optional I<--pool> I<pool-or-uuid> I<--offset> I<bytes> I<--length> I<bytes>] I<vol-name-or-key-or-path> I<local-file>
|
|
|
|
Upload the contents of I<local-file> to a storage volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe.
|
|
I<--offset> is the position in the storage volume at which to start writing
|
|
the data. I<--length> is an upper bound of the amount of data to be uploaded.
|
|
An error will occurr if the I<local-file> is greater than the specified length.
|
|
|
|
=item B<vol-download> [optional I<--pool> I<pool-or-uuid> I<--offset> I<bytes> I<--length> I<bytes>] I<vol-name-or-key-or-path> I<local-file>
|
|
|
|
Download the contents of I<local-file> from a storage volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe.
|
|
I<--offset> is the position in the storage volume at which to start reading
|
|
the data. I<--length> is an upper bound of the amount of data to be downloaded.
|
|
|
|
=item B<vol-wipe> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Wipe a volume, ensure data previously on the volume is not accessible to future reads.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to wipe.
|
|
|
|
=item B<vol-dumpxml> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Output the volume information as an XML dump to stdout.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to output the XML of.
|
|
|
|
=item B<vol-info> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path>
|
|
|
|
Returns basic information about the given storage volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
|
|
I<vol-name-or-key-or-path> is the name or key or path of the volume to return information for.
|
|
|
|
=item B<vol-list> [optional I<--pool>] I<pool-or-uuid> optional 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> [optional I<--uuid>] I<vol-key-or-path>
|
|
|
|
Return the pool name or UUID for a given volume. By default, the pool name is
|
|
returned. If the I<--uuid> option is given, the pool UUID is returned instead.
|
|
I<vol-key-or-path> is the key or path of the volume to return the pool
|
|
information for.
|
|
|
|
=item B<vol-path> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-key>
|
|
|
|
Return the path for a given volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
|
|
I<vol-name-or-key> is the name or key of the volume to return the path for.
|
|
|
|
=item B<vol-name> I<vol-key-or-path>
|
|
|
|
Return the name for a given volume.
|
|
I<vol-key-or-path> is the key or path of the volume to return the name for.
|
|
|
|
=item B<vol-key> [optional I<--pool> I<pool-or-uuid>] I<vol-name-or-path>
|
|
|
|
Return the volume key for a given volume.
|
|
I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume is in.
|
|
I<vol-name-or-path> is the name or path of the volume to return the volume key for.
|
|
|
|
=back
|
|
|
|
=head1 SECRET COMMMANDS
|
|
|
|
The following commands manipulate "secrets" (e.g. passwords, passphrases and
|
|
encryption keys). Libvirt can store secrets independently from their use, and
|
|
other objects (e.g. volumes or domains) can refer to the secrets for encryption
|
|
or possibly other uses. Secrets are identified using an UUID. See
|
|
L<http://libvirt.org/formatsecret.html> for documentation of the XML format
|
|
used to represent properties of secrets.
|
|
|
|
=over 4
|
|
|
|
=item B<secret-define> I<file>
|
|
|
|
Create a secret with the properties specified in I<file>, with no associated
|
|
secret value. If I<file> does not specify a UUID, choose one automatically.
|
|
If I<file> specifies an UUID of an existing secret, replace its properties by
|
|
properties defined in I<file>, without affecting the secret value.
|
|
|
|
=item B<secret-dumpxml> I<secret>
|
|
|
|
Output properties of I<secret> (specified by its UUID) as an XML dump to stdout.
|
|
|
|
=item B<secret-set-value> I<secret> I<base64>
|
|
|
|
Set the value associated with I<secret> (specified by its UUID) to the value
|
|
Base64-encoded value I<base64>.
|
|
|
|
=item B<secret-get-value> I<secret>
|
|
|
|
Output the value associated with I<secret> (specified by its UUID) to stdout,
|
|
encoded using Base64.
|
|
|
|
=item B<secret-undefine> I<secret>
|
|
|
|
Delete a I<secret> (specified by its UUID), including the associated value, if
|
|
any.
|
|
|
|
=item B<secret-list>
|
|
|
|
Output a list of UUIDs of known secrets to stdout.
|
|
|
|
=back
|
|
|
|
=head1 SNAPSHOT COMMMANDS
|
|
|
|
The following commands manipulate domain snapshots. Snapshots take the
|
|
disk, memory, and device state of a domain at a point-of-time, and save it
|
|
for future use. They have many uses, from saving a "clean" copy of an OS
|
|
image to saving a domain's state before a potentially destructive operation.
|
|
Snapshots are identified with a unique name. See
|
|
L<http://libvirt.org/formatsnapshot.html> for documentation of the XML format
|
|
used to represent properties of snapshots.
|
|
|
|
=over 4
|
|
|
|
=item B<snapshot-create> I<domain> I<xmlfile>
|
|
|
|
Create a snapshot for domain I<domain> with the properties specified in
|
|
I<xmlfile>. The only properties settable for a domain snapshot are the
|
|
<name> and <description>; 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.
|
|
|
|
=item B<snapshot-current> I<domain>
|
|
|
|
Output the snapshot XML for the domain's current snapshot (if any).
|
|
|
|
=item B<snapshot-list> I<domain>
|
|
|
|
List all of the available snapshots for the given domain.
|
|
|
|
=item B<snapshot-dumpxml> I<domain> I<snapshot>
|
|
|
|
Output the snapshot XML for the domain's snapshot named I<snapshot>.
|
|
|
|
=item B<snapshot-revert> I<domain> I<snapshot>
|
|
|
|
Revert the given domain to the snapshot specified by I<snapshot>. Be aware
|
|
that this is a destructive action; any changes in the domain since the
|
|
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.
|
|
|
|
=item B<snapshot-delete> I<domain> I<snapshot> I<--children>
|
|
|
|
Delete the snapshot for the domain named I<snapshot>. If this snapshot
|
|
has child snapshots, changes from this snapshot will be merged into the
|
|
children. If I<--children> is passed, then delete this snapshot and any
|
|
children of this snapshot.
|
|
|
|
=back
|
|
|
|
=head1 NWFILTER COMMMANDS
|
|
|
|
The following commands manipulate network filters. Network filters allow
|
|
filtering of the network traffic coming from and going to virtual machines.
|
|
Individual network traffic filters are written in XML and may contain
|
|
references to other network filters, describe traffic filtering rules,
|
|
or contain both. Network filters are referenced by virtual machines
|
|
from within their interface description. A network filter may be referenced
|
|
by multiple virtual machines' interfaces.
|
|
|
|
=over 4
|
|
|
|
=item B<nwfilter-define> I<xmlfile>
|
|
|
|
Make a new network filter known to libvirt. If a network filter with
|
|
the same name already exists, it will be replaced with the new XML.
|
|
Any running virtual machine referencing this network filter will have
|
|
its network traffic rules adapted. If for any reason the network traffic
|
|
filtering rules cannot be instantiated by any of the running virtual
|
|
machines, then the new XML will be rejected.
|
|
|
|
=item B<nwfilter-undefine> I<nwfilter-name>
|
|
|
|
Delete a network filter. The deletion will fail if any running virtual
|
|
machine is currently using this network filter.
|
|
|
|
=item B<nwfilter-list>
|
|
|
|
List all of the available network filters.
|
|
|
|
=item B<nwfilter-dumpxml> I<nwfilter-name>
|
|
|
|
Output the network filter XML.
|
|
|
|
=item B<nwfilter-edit> I<nwfilter-name>
|
|
|
|
Edit the XML of a network filter.
|
|
|
|
This is equivalent to:
|
|
|
|
virsh nwfilter-dumpxml myfilter > myfilter.xml
|
|
vi myfilter.xml (or make changes with your other text editor)
|
|
virsh nwfilter-define myfilter.xml
|
|
|
|
except that it does some error checking.
|
|
The new network filter may be rejected due to the same reason as
|
|
mentioned in I<nwfilter-define>.
|
|
|
|
The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
|
|
variables, and defaults to C<vi>.
|
|
|
|
=back
|
|
|
|
=head1 QEMU-SPECIFIC COMMANDS
|
|
|
|
NOTE: Use of the following commands is B<strongly> discouraged. They
|
|
can cause libvirt to become confused and do the wrong thing on subsequent
|
|
operations. Once you have used this command, please do not report
|
|
problems to the libvirt developers; the reports will be ignored.
|
|
|
|
=over 4
|
|
|
|
=item B<qemu-monitor-command> I<domain> I<command> optional I<--hmp>
|
|
|
|
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.
|
|
|
|
=back
|
|
|
|
=head1 ENVIRONMENT
|
|
|
|
The following environment variables can be set to alter the behaviour
|
|
of C<virsh>
|
|
|
|
=over 4
|
|
|
|
=item VIRSH_DEFAULT_CONNECT_URI
|
|
|
|
The hypervisor to connect to by default. Set this to a URI, in the same
|
|
format as accepted by the B<connect> option.
|
|
|
|
=item VISUAL
|
|
|
|
The editor to use by the B<edit> and related options.
|
|
|
|
=item EDITOR
|
|
|
|
The editor to use by the B<edit> and related options, if C<VISUAL>
|
|
is not set.
|
|
|
|
=item LIBVIRT_DEBUG=LEVEL
|
|
|
|
Turn on verbose debugging of all libvirt API calls. Valid levels are
|
|
|
|
=over 4
|
|
|
|
=item * LIBVIRT_DEBUG=1
|
|
|
|
Messages at level DEBUG or above
|
|
|
|
=item * LIBVIRT_DEBUG=2
|
|
|
|
Messages at level INFO or above
|
|
|
|
=item * LIBVIRT_DEBUG=3
|
|
|
|
Messages at level WARNING or above
|
|
|
|
=item * LIBVIRT_DEBUG=4
|
|
|
|
Messages at level ERROR or above
|
|
|
|
=back
|
|
|
|
For further information about debugging options consult C<http://libvirt.org/logging.html>
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
Report any bugs discovered to the libvirt community via the mailing
|
|
list C<http://libvirt.org/contact.html> or bug tracker C<http://libvirt.org/bugs.html>.
|
|
Alternatively report bugs to your software distributor / vendor.
|
|
|
|
=head1 AUTHORS
|
|
|
|
Please refer to the AUTHORS file distributed with libvirt.
|
|
|
|
Based on the xm man page by:
|
|
Sean Dague <sean at dague dot net>
|
|
Daniel Stekloff <dsteklof at us dot ibm dot com>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (C) 2005, 2007-2010 Red Hat, Inc., and the authors listed in the
|
|
libvirt AUTHORS file.
|
|
|
|
=head1 LICENSE
|
|
|
|
virsh is distributed under the terms of the GNU LGPL v2+.
|
|
This is free software; see the source for copying conditions. There
|
|
is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
|
|
PURPOSE
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<virt-install(1)>, L<virt-xml-validate(1)>, L<virt-top(1)>, L<virt-df(1)>,
|
|
L<http://www.libvirt.org/>
|
|
|
|
=cut
|