« back to all changes in this revision
Viewing changes to man/en/virt-image.5
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Soren Hansen
- Date: 2007-11-20 13:40:28 UTC
- Revision ID: james.westby@ubuntu.com-20071120134028-rg0pjby0jc4mycks
Tags: upstream-0.300.1+hg20071120
Import upstream version 0.300.1+hg20071120
- files added:
- doc
- man
- man/en
- po
- tests
- virtinst
added
removed
man/en/virt-image.5
1
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2
.\"
3
.\" Standard preamble:
4
.\" ========================================================================
5
.de Sh \" Subsection heading
6
.br
7
.if t .Sp
8
.ne 5
9
.PP
10
\fB\\$1\fR
11
.PP
12
..
13
.de Sp \" Vertical space (when we can't use .PP)
14
.if t .sp .5v
15
.if n .sp
16
..
17
.de Vb \" Begin verbatim text
18
.ft CW
19
.nf
20
.ne \\$1
21
..
22
.de Ve \" End verbatim text
23
.ft R
24
.fi
25
..
26
.\" Set up some character translations and predefined strings. \*(-- will
27
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28
.\" double quote, and \*(R" will give a right double quote. | will give a
29
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31
.\" expand to `' in nroff, nothing in troff, for use with C<>.
32
.tr \(*W-|\(bv\*(Tr
33
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34
.ie n \{\
35
. ds -- \(*W-
36
. ds PI pi
37
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39
. ds L" ""
40
. ds R" ""
41
. ds C` ""
42
. ds C' ""
43
'br\}
44
.el\{\
45
. ds -- \|\(em\|
46
. ds PI \(*p
47
. ds L" ``
48
. ds R" ''
49
'br\}
50
.\"
51
.\" If the F register is turned on, we'll generate index entries on stderr for
52
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53
.\" entries marked with X<> in POD. Of course, you'll have to process the
54
.\" output yourself in some meaningful fashion.
55
.if \nF \{\
56
. de IX
57
. tm Index:\\$1\t\\n%\t"\\$2"
58
..
59
. nr % 0
60
. rr F
61
.\}
62
.\"
63
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64
.\" way too many mistakes in technical documents.
65
.hy 0
66
.if n .na
67
.\"
68
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69
.\" Fear. Run. Save yourself. No user-serviceable parts.
70
. \" fudge factors for nroff and troff
71
.if n \{\
72
. ds #H 0
73
. ds #V .8m
74
. ds #F .3m
75
. ds #[ \f1
76
. ds #] \fP
77
.\}
78
.if t \{\
79
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80
. ds #V .6m
81
. ds #F 0
82
. ds #[ \&
83
. ds #] \&
84
.\}
85
. \" simple accents for nroff and troff
86
.if n \{\
87
. ds ' \&
88
. ds ` \&
89
. ds ^ \&
90
. ds , \&
91
. ds ~ ~
92
. ds /
93
.\}
94
.if t \{\
95
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101
.\}
102
. \" troff and (daisy-wheel) nroff accents
103
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110
.ds ae a\h'-(\w'a'u*4/10)'e
111
.ds Ae A\h'-(\w'A'u*4/10)'E
112
. \" corrections for vroff
113
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115
. \" for low resolution devices (crt and lpr)
116
.if \n(.H>23 .if \n(.V>19 \
117
\{\
118
. ds : e
119
. ds 8 ss
120
. ds o a
121
. ds d- d\h'-1'\(ga
122
. ds D- D\h'-1'\(hy
123
. ds th \o'bp'
124
. ds Th \o'LP'
125
. ds ae ae
126
. ds Ae AE
127
.\}
128
.rm #[ #] #H #V #F C
129
.\" ========================================================================
130
.\"
131
.IX Title "virt-image 5"
132
.TH virt-image 5 "2007-08-24" "perl v5.8.8" "Virtual Machine Install Tools"
133
.SH "NAME"
134
virt\-image \- Format of the virtual image XML descriptor
135
.SH "DESCRIPTION"
136
.IX Header "DESCRIPTION"
137
\&\fIvirt\-image\fR\|(1) relies on an \s-1XML\s0 descriptor to create virtual machines from
138
virtual machine images. In general, a virtual machine image consists of the
139
\&\s-1XML\s0 descriptor (usually in a file \fIimage.xml\fR) and a number of files for
140
the virtual machine's disks.
141
.PP
142
In the following explanation of the structure of the image descriptor,
143
mandatory \s-1XML\s0 elements are marked as \fBelement\fR, whereas optional elements
144
are marked as \fIelement\fR.
145
.PP
146
All file names in the image descriptor are relative to the location of the
147
descriptor itself. Generally, disk files are either kept in the same
148
directory as the image descriptor, or in a subdirectory.
149
.SH "HOST MATCHING"
150
.IX Header "HOST MATCHING"
151
The image descriptor contains information on the requirements a guest has
152
on the host platform through one or more the \fI/image/domain/boot\fR
153
descriptors (see section \*(L"\s-1BOOT\s0\*(R"). The image can only be used if at least
154
one of the boot descriptors is suitable for the host platform; a boot
155
descriptor is suitable if:
156
.IP "\(bu" 4
157
The \s-1CPU\s0 architecture of the boot descriptor, given by the
158
\&\fIboot/guest/arch\fR element, is supported by the host
159
.IP "\(bu" 4
160
The host supports a guest with the features requested in the
161
\&\fIboot/guest/features\fR element, such as providing an \s-1APIC\s0, or having \s-1ACPI\s0
162
turned off
163
.PP
164
If a suitable boot descriptor is found, the guest is created and booted
165
according to the information about booting the \s-1OS\s0 from the \fIboot/os\fR
166
element and with the disks specified in the \fIboot/drive\fR element. If more
167
than one suitable boot descriptor is found, one of them is chosen based on
168
a heuristic, generally preferring paravirtualized guests over full
169
virtualized ones, though this is an implementation detail of the tool
170
creating the virtual machine.
171
.SH "STRUCTURE"
172
.IX Header "STRUCTURE"
173
The image descriptor consists of three sections, all contained in the
174
toplevel \fBimage\fR element:
175
.IP "General metadata about the image" 4
176
.IX Item "General metadata about the image"
177
A number of elements like \fIlabel\fR, \fBname\fR, and \fIdescription\fR that give
178
some simple information about the image. The \fBname\fR must be a string
179
suitable as a name for the virtual machine, the \fIlabel\fR is a short
180
human-readable string suitable for display in graphical \s-1UI\s0's, and the
181
\&\fIdescription\fR should be a longer, free-form description of the purpose of
182
the image. The \fBname\fR is mandatory.
183
.IP "Virtual machine attributes" 4
184
.IX Item "Virtual machine attributes"
185
The \fBdomain\fR element contains instructions on how to boot the image, and
186
device attributes such as the number of virtual \s-1CPU\s0's and the size of the
187
memory. (see section \*(L"\s-1DOMAIN\s0\*(R")
188
.IP "Storage layout" 4
189
.IX Item "Storage layout"
190
The \fBstorage\fR element lists the files to back the virtual machine's disks
191
and some information about their format and use. (see section \*(L"\s-1STORAGE\s0\*(R")
192
.SH "DOMAIN"
193
.IX Header "DOMAIN"
194
The \fBdomain\fR element contains one or more \fBboot\fR descriptors (see section
195
\&\*(L"\s-1BOOT\s0\*(R") and a \fBdevices\fR element. The \fBDevices\fR element lists the
196
recommended number of virtual \s-1CPU\s0's in the \fBvcpu\fR element and the
197
recommended amount of memory in kB in the \fBmemory\fR element. It also
198
indicates whether the virtual machine should have a network interface
199
through the \fIinterface\fR element and whether the virtual machine has a
200
graphical interface through the \fIgraphics\fR element.
201
.Sh "\s-1BOOT\s0"
202
.IX Subsection "BOOT"
203
Each \fBboot\fR descriptor details how the virtual machine should be started
204
on a certain hypervisor. The \fBtype\fR attribute of the \fBboot\fR element,
205
which can either be \f(CW\*(C`xen\*(C'\fR or \f(CW\*(C`hvm\*(C'\fR, depending on whether the boot
206
descriptor is for a paravirtualized Xen(tm) guest or a fully-virtualized
207
guest.
208
.PP
209
The \fBboot\fR element contains three subelements:
210
.IP "The platform requirements of the guest" 4
211
.IX Item "The platform requirements of the guest"
212
The platform requirements, contained in the \fBguest\fR element, consist of
213
the \fBarch\fR element and the \fIfeatures\fR element. The \fBarch\fR element
214
indicates the \s-1CPU\s0 architecture the guest expects, e.g. \f(CW\*(C`i686\*(C'\fR, \f(CW\*(C`x86_64\*(C'\fR,
215
or \f(CW\*(C`ppc\*(C'\fR.
216
.Sp
217
The \fIfeatures\fR element indicates whether certain platform features should
218
be on or off. Currently, the platform features are \fIpae\fR, \fIacpi\fR, and
219
\&\fIapic\fR. They can be turned on or off by giving a \fIstate\fR attribute of
220
either \f(CW\*(C`on\*(C'\fR or \f(CW\*(C`off\*(C'\fR. When a feature is mentioned in the \fIfeatures\fR
221
element, it defaults to \f(CW\*(C`on\*(C'\fR.
222
.IP "The details of booting the image's operating system" 4
223
.IX Item "The details of booting the image's operating system"
224
The \fBos\fR element for fully-virtualized \f(CW\*(C`hvm\*(C'\fR guests contains a \fBloader\fR
225
element whose \fBdev\fR attribute indicates whether to boot off a hard disk
226
(\f(CW\*(C`dev='hd'\*(C'\fR) or off a CD-ROM (\f(CW\*(C`dev='cdrom'\*(C'\fR)
227
.Sp
228
For paravirtualized guests, the \fBos\fR element either contains a
229
\&\f(CW\*(C`<loader>pygrub</loader>\*(C'\fR element, indicating that the guest should be
230
booted with \fIpygrub\fR, or \fBkernel\fR, \fIinitrd\fR and \fIcmdline\fR elements. The
231
contents of the \fBkernel\fR and \fIinitrd\fR elements are the names of the
232
kernel and initrd files, whereas the \fIcmdline\fR element contains the
233
command line that should be passed to the kernel on boot.
234
.IP "The mapping of disk files as devices into the guest" 4
235
.IX Item "The mapping of disk files as devices into the guest"
236
The mapping of disk files into the guest is performed by a list of \fBdrive\fR
237
elements inside the \fBboot\fR element. Each \fBdrive\fR element references the
238
name of a disk file from the \*(L"\s-1STORAGE\s0\*(R" section through its \fBdisk\fR
239
attribute and can optionally specify as what device that disk file should
240
appear in the guest through its \fItarget\fR attribute. If the \fItarget\fR is
241
omitted. device names are assigned in the order in which the \fBdrive\fR
242
elements appear, skipping already assigned devices.
243
.SH "STORAGE"
244
.IX Header "STORAGE"
245
The \fBstorage\fR element lists the disk image files that are part of the
246
virtual machine image in a list of one or more \fBdisk\fR elements. Each
247
\&\fBdisk\fR element can contain the following attributes:
248
.IP "\(bu" 4
249
the \fBfile\fR attribute giving the name of the disk file
250
.IP "\(bu" 4
251
the \fBuse\fR attribute indicating whether the disk file is a \f(CW\*(C`system\*(C'\fR,
252
\&\f(CW\*(C`user\*(C'\fR, or \f(CW\*(C`scratch\*(C'\fR disk. The \fBuse\fR attribute differentiates disk files
253
so that an update based on replacing disk files can replace \f(CW\*(C`system\*(C'\fR
254
disks, but leave \f(CW\*(C`user\*(C'\fR disks untouched.
255
.Sp
256
Generally, \f(CW\*(C`system\*(C'\fR disks contain application code, \f(CW\*(C`user\*(C'\fR disks contain
257
the application's data, and \f(CW\*(C`scratch\*(C'\fR disks contain temporary state that
258
can be erased between runs of the guest.
259
.Sp
260
The virtual machine image must contain files for all \f(CW\*(C`system\*(C'\fR disks, and
261
may contain files for the \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`scratch\*(C'\fR disks. If the latter are
262
not part of the image, they are initialized as empty files when a guest is
263
created, with the size given by the \fIsize\fR attribute.
264
.IP "\(bu" 4
265
the \fIsize\fR attribute giving the size of the disk in \s-1MB\s0.
266
.IP "\(bu" 4
267
the \fIformat\fR attribute giving the format of the disk file. Currently, this
268
can be either \f(CW\*(C`raw\*(C'\fR for a raw disk image and \f(CW\*(C`iso\*(C'\fR for an \s-1ISO\s0 image.
269
.SH "EXAMPLE"
270
.IX Header "EXAMPLE"
271
The image descriptor below can be used to create a virtual machine running
272
the System Rescue \s-1CD\s0 (\f(CW\*(C`http://www.sysresccd.org/\*(C'\fR) Besides the descriptor,
273
you only need the \s-1ISO\s0 image from the System Rescue \s-1CD\s0 website.
274
.PP
275
.Vb 26
276
\& <?xml version="1.0" encoding="UTF-8"?>
277
\& <image>
278
\& <name>sysresccd</name>
279
\& <domain>
280
\& <boot type="hvm">
281
\& <guest>
282
\& <arch>i686</arch>
283
\& </guest>
284
\& <os>
285
\& <loader dev="cdrom"/>
286
\& </os>
287
\& <drive disk="root.raw" target="hda"/>
288
\& <drive disk="systemrescuecd.iso"/>
289
\& </boot>
290
\& <devices>
291
\& <vcpu>1</vcpu>
292
\& <memory>262144</memory>
293
\& <interface/>
294
\& <graphics/>
295
\& </devices>
296
\& </domain>
297
\& <storage>
298
\& <disk file="root.raw" use="scratch" size="100" format="raw"/>
299
\& <disk file="systemrescuecd.iso" use="system" format="iso"/>
300
\& </storage>
301
\& </image>
302
.Ve
303
.PP
304
To create a virtual machine, save the above \s-1XML\s0 in \fIimage.xml\fR and run:
305
.PP
306
.Vb 1
307
\& # virt-image --vnc image.xml
308
.Ve
309
.SH "AUTHOR"
310
.IX Header "AUTHOR"
311
Written by David Lutterkort. See the \s-1AUTHORS\s0 file in the source distribution for
312
the complete list of credits.
313
.SH "BUGS"
314
.IX Header "BUGS"
315
Report bugs to the mailing list \f(CW\*(C`http://www.redhat.com/mailman/listinfo/et\-mgmt\-tools\*(C'\fR
316
or directly to BugZilla \f(CW\*(C`http://bugzilla.redhat.com/bugzilla/\*(C'\fR against the
317
\&\f(CW\*(C`Fedora\*(C'\fR product, and the \f(CW\*(C`python\-virtinst\*(C'\fR component.
318
.SH "COPYRIGHT"
319
.IX Header "COPYRIGHT"
320
Copyright (C) 2006\-2007 Red Hat, Inc, and various contributors.
321
This is free software. You may redistribute copies of it under the terms of the \s-1GNU\s0 General
322
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
323
permitted by law.
324
.SH "SEE ALSO"
325
.IX Header "SEE ALSO"
326
\&\fIvirt\-image\fR\|(1), \fIvirt\-install\fR\|(1), the project website
327
\&\f(CW\*(C`http://virt\-manager.org\*(C'\fR, the Relax-NG grammar for image \s-1XML\s0 \f(CW\*(C`image.rng\*(C'\fR
Loggerhead is a web-based interface for Breezy
Version: 2.0.1