~ubuntu-branches/ubuntu/quantal/virtinst/quantal-proposed

.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "VIRT-IMAGE 1"
.TH VIRT-IMAGE 1 "2012-07-09" "" "Virtual Machine Install Tools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
virt\-image \- create virtual machines from an image descriptor
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBvirt-image\fR [\s-1OPTION\s0]... \s-1IMAGE\s0.XML
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBvirt-image\fR is a command line tool for creating virtual machines from an
\&\s-1XML\s0 image descriptor \f(CW\*(C`IMAGE.XML\*(C'\fR (\fIvirt\-image\fR\|(5)). Most attributes of
the virtual machine are taken from the \s-1XML\s0 descriptor (e.g., where the
files to back the virtual machine's disks are and how to map them into the
guest), though certain information must be added on the command line, such
as the name of the guest.
.PP
The \s-1XML\s0 descriptor defines most attributes of the guest, making it possible
to bundle and distribute it together with the files backing the guest's
disks.
.SH "OPTIONS"
.IX Header "OPTIONS"
Most options can be omitted, in which case \fBvirt-image\fR will use defaults
from the \s-1XML\s0 descriptor. When defaults are taken from the \s-1XML\s0 descriptor,
they are indicated below as a path. \-\-name is the only required command
line option.
.IP "\-h, \-\-help" 4
.IX Item "-h, --help"
Show the help message and exit
.IP "\-\-connect=URI" 4
.IX Item "--connect=URI"
Connect to a non-default hypervisor. See \fIvirt\-install\fR\|(1) for details
.SS "General Options"
.IX Subsection "General Options"
General configuration parameters that apply to all types of guest installs.
.IP "\-n \s-1NAME\s0, \-\-name=NAME" 2
.IX Item "-n NAME, --name=NAME"
Name of the guest instance
.IP "\-r \s-1MEMORY\s0, \-\-ram=MEMORY" 2
.IX Item "-r MEMORY, --ram=MEMORY"
Memory to allocate for guest instance in megabytes. Defaults to
\&\f(CW\*(C`/image/devices/memory\*(C'\fR in the \s-1XML\s0 descriptor.
.IP "\-u \s-1UUID\s0, \-\-uuid=UUID" 2
.IX Item "-u UUID, --uuid=UUID"
\&\s-1UUID\s0 for the guest; if none is given a random \s-1UUID\s0 will be generated. If
you specify \s-1UUID\s0, you should use a 32\-digit hexadecimal number.
.IP "\-\-vcpus=VCPUS" 2
.IX Item "--vcpus=VCPUS"
Number of vcpus to configure for your guest. Defaults to
\&\f(CW\*(C`/image/devices/vcpu\*(C'\fR in the \s-1XML\s0 descriptor. This option can also be
used to set \s-1CPU\s0 topology, please see \fIvirt\-install\fR\|(1) for more info.
.IP "\-\-cpuset" 2
.IX Item "--cpuset"
Set which physical cpus the guest can use. Please see \fIvirt\-install\fR\|(1) for
more info.
.IP "\-\-cpu" 2
.IX Item "--cpu"
Configure the \s-1CPU\s0 and \s-1CPU\s0 features exposed to the guest. Please see
\&\fIvirt\-install\fR\|(1) for more info.
.IP "\-\-check\-cpu" 2
.IX Item "--check-cpu"
Check that vcpus do not exceed physical CPUs and warn if they do.
.IP "\-\-os\-type=OS_TYPE" 2
.IX Item "--os-type=OS_TYPE"
Optimize the guest configuration for a type of operating system (ex. 'linux',
\&'windows'). This will attempt to pick the most suitable \s-1ACPI\s0 & \s-1APIC\s0 settings,
optimally supported mouse drivers, virtio, and generally accommodate other
operating system quirks.  See \fIvirt\-install\fR\|(1) for valid values.
.IP "\-\-os\-variant=OS_VARIANT" 2
.IX Item "--os-variant=OS_VARIANT"
Further optimize the guest configuration for a specific operating system
variant (ex. 'fedora8', 'winxp'). This parameter is optional, and does not
require an \f(CW\*(C`\-\-os\-type\*(C'\fR to be specified. See \fIvirt\-install\fR\|(1) for valid
values.
.SS "Full Virtualization specific options"
.IX Subsection "Full Virtualization specific options"
Parameters specific only to fully virtualized guest installs.
.IP "\-\-noapic" 2
.IX Item "--noapic"
Force disable \s-1APIC\s0 for the guest.
.IP "\-\-noacpi" 2
.IX Item "--noacpi"
Force disable \s-1ACPI\s0 for the guest.
.SS "Networking Configuration"
.IX Subsection "Networking Configuration"
.IP "\-w \s-1NETWORK\s0, \-\-network=NETWORK" 2
.IX Item "-w NETWORK, --network=NETWORK"
Connect the guest to the host network. See \fIvirt\-install\fR\|(1) for details
.IP "\-m \s-1MAC\s0, \-\-mac=MAC" 2
.IX Item "-m MAC, --mac=MAC"
This is deprecated in favor of \f(CW\*(C`\-\-network ...,mac=MAC,...\*(C'\fR
.IP "\-b \s-1BRIDGE\s0, \-\-bridge=BRIDGE" 2
.IX Item "-b BRIDGE, --bridge=BRIDGE"
This is deprecated in favor of \f(CW\*(C`\-\-network bridge=BRIDGE\*(C'\fR
.SS "Graphics Configuration"
.IX Subsection "Graphics Configuration"
If no graphics option is specified, \f(CW\*(C`virt\-image\*(C'\fR will default to
\&'\-\-graphics vnc' if the \s-1DISPLAY\s0 environment variable is set, otherwise
\&'\-\-graphics none' is used.
.IP "\-\-graphics \s-1TYPE\s0,opt1=arg1,opt2=arg2,..." 2
.IX Item "--graphics TYPE,opt1=arg1,opt2=arg2,..."
Specifies the graphical display configuration. This does not configure any
virtual hardware, just how the guest's graphical display can be accessed.
See \fIvirt\-install\fR\|(1) for details usage info.
.IP "\-\-vnc" 2
.IX Item "--vnc"
This option is deprecated in favor of \f(CW\*(C`\-\-graphics vnc,...\*(C'\fR
.IP "\-\-vncport=VNCPORT" 2
.IX Item "--vncport=VNCPORT"
This option is deprecated in favor of \f(CW\*(C`\-\-graphics vnc,port=PORT,...\*(C'\fR
.IP "\-\-vnclisten=VNCLISTEN" 2
.IX Item "--vnclisten=VNCLISTEN"
This option is deprecated in favor of \f(CW\*(C`\-\-graphics vnc,listen=LISTEN,...\*(C'\fR
.IP "\-k \s-1KEYMAP\s0, \-\-keymap=KEYMAP" 2
.IX Item "-k KEYMAP, --keymap=KEYMAP"
This option is deprecated in favor of \f(CW\*(C`\-\-graphics vnc,keymap=KEYMAP,...\*(C'\fR
.IP "\-\-sdl" 2
.IX Item "--sdl"
This option is deprecated in favor of \f(CW\*(C`\-\-graphics sdl,...\*(C'\fR
.IP "\-\-nographics" 2
.IX Item "--nographics"
This option is deprecated in favor of \f(CW\*(C`\-\-graphics none\*(C'\fR
.SS "Miscellaneous Options"
.IX Subsection "Miscellaneous Options"
.IP "\-p, \-\-print" 2
.IX Item "-p, --print"
Print the libvirt \s-1XML\s0, but do not start the guest.
.IP "\-\-boot=BOOT" 2
.IX Item "--boot=BOOT"
The zero-based index of the boot record to use. The \s-1XML\s0 descriptor can
contain multiple \f(CW\*(C`/image/domain/boot\*(C'\fR elements for use on different
hypervisors. By default, the one that is most appropriate for the current
hypervisor is selected.
.IP "\-\-replace" 2
.IX Item "--replace"
Shutdown and remove any existing guest with the passed \f(CW\*(C`\-\-name\*(C'\fR before
installing from the image.
.IP "\-\-noreboot" 2
.IX Item "--noreboot"
Prevent the domain automatatically booting after importing the image.
.IP "\-\-skip\-checksum" 2
.IX Item "--skip-checksum"
Do not check disk images against checksums (if they are listed in the
image xml).
.IP "\-d, \-\-debug" 2
.IX Item "-d, --debug"
Print debugging information.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Create and start a guest called \f(CW\*(C`example\*(C'\fR with a \s-1VNC\s0 console from
\&\f(CW\*(C`image.xml\*(C'\fR:
.PP
.Vb 1
\&  # virt\-image \-\-name example \-\-vnc image.xml
.Ve
.PP
Print the libvirt \s-1XML\s0 for a guest called \f(CW\*(C`example\*(C'\fR without graphics, but
do not create or start a virtual machine:
.PP
.Vb 1
\&  # virt\-image \-\-print \-\-name example \-\-nographics image.xml
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Written by David Lutterkort and Cole Robinson. See the \s-1AUTHORS\s0 file in
the source distribution for the complete list of credits.
.SH "BUGS"
.IX Header "BUGS"
Please see http://virt\-manager.org/page/BugReporting
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2006\-2012 Red Hat, Inc, and various contributors.
This is free software. You may redistribute copies of it under the terms
of the \s-1GNU\s0 General Public License \f(CW\*(C`http://www.gnu.org/licenses/gpl.html\*(C'\fR.
There is \s-1NO\s0 \s-1WARRANTY\s0, to the extent permitted by law.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIvirt\-image\fR\|(5), \fIvirt\-install\fR\|(1), the project website
\&\f(CW\*(C`http://virt\-manager.org\*(C'\fR