~ubuntu-branches/ubuntu/maverick/libvirt/maverick

.\"

.\" Standard preamble:

.\" ========================================================================

..

.\" Set up some character translations and predefined strings.  \*(-- will

.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left

.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

.ie n \{\

.    ds -- \(*W-

.    ds R" ''

'br\}

.\"

.\" If the F register is turned on, we'll generate index entries on stderr for

.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index

.\" entries marked with X<> in POD.  Of course, you'll have to process the

.\" output yourself in some meaningful fashion.

.    de IX

.    tm Index:\\$1\t\\n%\t"\\$2"

..

.    nr % 0

.    rr F

.\}

.\"

.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).

.\" Fear.  Run.  Save yourself.  No user-serviceable parts.

.\" ========================================================================

.\"

.IX Title "VIRSH 1"

.SH "NAME"

virsh \- management user interface

.SH "SYNOPSIS"

The basic structure of most virsh usage is:

.PP

.Vb 1

.Ve

.PP

Where \fIcommand\fR is one of the commands listed below, \fIdomain-id\fR

.IX Header "NOTES"

All \fBvirsh\fR operations rely upon the libvirt library.

For any virsh commands to run xend/qemu, or what ever virtual library that libvirt supports.  For this reason you should start xend/qemu as a service when your system first boots using xen/qemu. This can usually be done using the command

.PP

Most \fBvirsh\fR commands require root privileges to run due to the

communications channels used to talk to the hypervisor.  Running as

allow to connect locally as root to the daemon supervising QEmu and \s-1KVM\s0 domains

.IP "qemu:///session" 4

.IX Item "qemu:///session"

.RE

.RS 4

.Sp

\&\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-

.Sp

.Vb 2

\&  2 fedora               paused

.Ve

.Sp

Name is the name of the domain.  \s-1ID\s0 the domain numeric id.

.Sp

\&\fB\s-1STATES\s0\fR

.Sp

The domain is currently running on a \s-1CPU\s0

because the domain is waiting on \s-1IO\s0 (a traditional wait state) or has

gone to sleep because there was nothing else for it to do.

The domain has been paused, usually occurring through the administrator

consume allocated resources like memory, but will not be eligible for

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.

The domain has crashed, which is always a violent ending.  Usually

this state can only occur if the domain has been configured not to

The domain is in process of dying, but hasn't completely shutdown or

crashed.

.RE

.RS 4

.SH "DOMAIN COMMANDS"

.IX Header "DOMAIN COMMANDS"

The following commands manipulate domains directly, as stated

Connect the virtual serial console for the guest.

.IP "\fBcreate\fR \fI\s-1FILE\s0\fR" 4

.IX Item "create FILE"

.Sp

\&\fBExample\fR

.Sp

but not started.

.IP "\fBdestroy\fR \fIdomain-id\fR" 4

.IX Item "destroy domain-id"

\&\s-1OS\s0 any chance to react, and it the equivalent of ripping the power

cord out on a physical machine.  In most cases you will want to use

the \fBshutdown\fR command instead.

.IP "\fBdumpxml\fR \fIdomain-id\fR" 4

.IX Item "dumpxml domain-id"

Output the domain information as an \s-1XML\s0 dump to stdout, this format can be used by the \fBcreate\fR command.

.IP "\fBmigrate\fR optional \fI\-\-live\fR \fIdomain-id\fR \fIdesturi\fR \fImigrateuri\fR" 4

.IX Item "migrate optional --live domain-id desturi migrateuri"

Migrate domain to another host.  Add \-\-live for live migration. The \fIdesturi\fR

executed the reboot action, which may be significantly before the

domain actually reboots.

.Sp

.IP "\fBrestore\fR \fIstate-file\fR" 4

.IX Item "restore state-file"

Restores a domain from an \fBvirsh save\fR state file.  See \fIsave\fR for more info.

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 \s-1TCP\s0 timeouts may have expired.

.IP "\fBschedinfo\fR optional \fI\-\-weight\fR \fBnumber\fR optional \fI\-\-cap\fR \fBnumber\fR \fIdomain-id\fR" 4

.IX Item "schedinfo optional --weight number optional --cap number domain-id"

.IP "\fBsetmem\fR \fIdomain-id\fR \fBkilobytes\fR" 4

.IX Item "setmem domain-id kilobytes"

Change the current memory allocation in the guest domain. This should take

succeed, and may take a variable length of time depending on what

services must be shutdown in the domain.

.Sp

.IP "\fBstart\fR \fIdomain-name\fR" 4

.IX Item "start domain-name"

Start a (previously defined) inactive domain.

.IX Item "vncdisplay domain-id"

Output the \s-1IP\s0 address and port number for the \s-1VNC\s0 display. If the information

is not available the processes will provide an exit code of 1.

The following commands manipulate devices associated to domains.

The domain-id can be specified as an short integer, a name or a full \s-1UUID\s0.

To better understand the values allowed as options for the command

\&\fItype\fR can be either \fInetwork\fR to indicate a physical network device or \fIbridge\fR to indicate a bridge to a device.

It is recommended to use the \fImac\fR option to distinguish between the interfaces

if more than one are present on the domain.

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

.IP "\fBnet-dumpxml\fR \fInetwork\fR" 4

.IX Item "net-dumpxml network"

Output the virtual network information as an \s-1XML\s0 dump to stdout.

.IP "\fBnet-list\fR optional \fI\-\-inactive\fR or \fI\-\-all\fR" 4

.IX Item "net-list optional --inactive or --all"

Returns the list of active networks, if \fI\-\-all\fR is specified this will also

.IP "\fBnet-uuid\fR \fInetwork-name\fR" 4

.IX Item "net-uuid network-name"

Convert a network name to network \s-1UUID\s0.

.SH "ENVIRONMENT"

.IX Header "ENVIRONMENT"

.IP "\s-1VIRSH_DEFAULT_CONNECT_URI\s0" 4

.IX Item "VIRSH_DEFAULT_CONNECT_URI"

The hypervisor to connect to by default. Set this to a \s-1URI\s0, in the same

format as accepted by the \fBconnect\fR option.

.Vb 2

\&  Andrew Puch <apuch @ redhat.com>

\&  Daniel Veillard <veillard @ redhat.com>

\&  Sean Dague <sean at dague dot net>

\&  Daniel Stekloff <dsteklof at us dot ibm dot com>

.Ve