5
virt-image - Format of the virtual image XML descriptor
9
L<virt-image(1)> relies on an XML descriptor to create virtual machines from
10
virtual machine images. In general, a virtual machine image consists of the
11
XML descriptor (usually in a file F<image.xml>) and a number of files for
12
the virtual machine's disks.
14
In the following explanation of the structure of the image descriptor,
15
mandatory XML elements are marked as B<element>, whereas optional elements
16
are marked as I<element>.
18
All file names in the image descriptor are relative to the location of the
19
descriptor itself. Generally, disk files are either kept in the same
20
directory as the image descriptor, or in a subdirectory.
24
The image descriptor contains information on the requirements a guest has
25
on the host platform through one or more the F</image/domain/boot>
26
descriptors (see section L</BOOT>). The image can only be used if at least
27
one of the boot descriptors is suitable for the host platform; a boot
28
descriptor is suitable if:
34
The CPU architecture of the boot descriptor, given by the
35
F<boot/guest/arch> element, is supported by the host
39
The host supports a guest with the features requested in the
40
F<boot/guest/features> element, such as providing an APIC, or having ACPI
45
If a suitable boot descriptor is found, the guest is created and booted
46
according to the information about booting the OS from the F<boot/os>
47
element and with the disks specified in the F<boot/drive> element. If more
48
than one suitable boot descriptor is found, one of them is chosen based on
49
a heuristic, generally preferring paravirtualized guests over full
50
virtualized ones, though this is an implementation detail of the tool
51
creating the virtual machine.
55
The image descriptor consists of three sections, all contained in the
56
toplevel B<image> element:
60
=item General metadata about the image
62
A number of elements like I<label>, B<name>, and I<description> that give
63
some simple information about the image. The B<name> must be a string
64
suitable as a name for the virtual machine, the I<label> is a short
65
human-readable string suitable for display in graphical UI's, and the
66
I<description> should be a longer, free-form description of the purpose of
67
the image. The B<name> is mandatory.
69
=item Virtual machine attributes
71
The B<domain> element contains instructions on how to boot the image, and
72
device attributes such as the number of virtual CPU's and the size of the
73
memory. (see section L</DOMAIN>)
77
The B<storage> element lists the files to back the virtual machine's disks
78
and some information about their format and use. (see section L</STORAGE>)
84
The B<domain> element contains one or more B<boot> descriptors (see section
85
L</BOOT>) and a B<devices> element. The B<Devices> element lists the
86
recommended number of virtual CPU's in the B<vcpu> element and the
87
recommended amount of memory in kB in the B<memory> element. It also
88
indicates whether the virtual machine should have a network interface
89
through the I<interface> element and whether the virtual machine has a
90
graphical interface through the I<graphics> element.
94
Each B<boot> descriptor details how the virtual machine should be started
95
on a certain hypervisor. The B<type> attribute of the B<boot> element,
96
which can either be C<xen> or C<hvm>, depending on whether the boot
97
descriptor is for a paravirtualized Xen(tm) guest or a fully-virtualized
100
The B<boot> element contains three subelements:
104
=item The platform requirements of the guest
106
The platform requirements, contained in the B<guest> element, consist of
107
the B<arch> element and the I<features> element. The B<arch> element
108
indicates the CPU architecture the guest expects, e.g. C<i686>, C<x86_64>,
111
The I<features> element indicates whether certain platform features should
112
be on or off. Currently, the platform features are I<pae>, I<acpi>, and
113
I<apic>. They can be turned on or off by giving a I<state> attribute of
114
either C<on> or C<off>. When a feature is mentioned in the I<features>
115
element, it defaults to C<on>.
117
=item The details of booting the image's operating system
119
The B<os> element for fully-virtualized C<hvm> guests contains a B<loader>
120
element whose B<dev> attribute indicates whether to boot off a hard disk
121
(C<dev='hd'>) or off a CD-ROM (C<dev='cdrom'>)
123
For paravirtualized guests, the B<os> element either contains a
124
C<< <loader>pygrub</loader> >> element, indicating that the guest should be
125
booted with F<pygrub>, or B<kernel>, I<initrd> and I<cmdline> elements. The
126
contents of the B<kernel> and I<initrd> elements are the names of the
127
kernel and initrd files, whereas the I<cmdline> element contains the
128
command line that should be passed to the kernel on boot.
130
=item The mapping of disk files as devices into the guest
132
The mapping of disk files into the guest is performed by a list of B<drive>
133
elements inside the B<boot> element. Each B<drive> element references the
134
name of a disk file from the L</STORAGE> section through its B<disk>
135
attribute and can optionally specify as what device that disk file should
136
appear in the guest through its I<target> attribute. If the I<target> is
137
omitted. device names are assigned in the order in which the B<drive>
138
elements appear, skipping already assigned devices.
144
The B<storage> element lists the disk image files that are part of the
145
virtual machine image in a list of one or more B<disk> elements. Each
146
B<disk> element can contain the following attributes:
152
the B<file> attribute giving the name of the disk file
156
the B<use> attribute indicating whether the disk file is a C<system>,
157
C<user>, or C<scratch> disk. The B<use> attribute differentiates disk files
158
so that an update based on replacing disk files can replace C<system>
159
disks, but leave C<user> disks untouched.
161
Generally, C<system> disks contain application code, C<user> disks contain
162
the application's data, and C<scratch> disks contain temporary state that
163
can be erased between runs of the guest.
165
The virtual machine image must contain files for all C<system> disks, and
166
may contain files for the C<user> and C<scratch> disks. If the latter are
167
not part of the image, they are initialized as empty files when a guest is
168
created, with the size given by the I<size> attribute.
172
the I<size> attribute giving the size of the disk in MB.
176
the I<format> attribute giving the format of the disk file. Currently, this
177
can be either C<raw> for a raw disk image and C<iso> for an ISO image.
183
The image descriptor below can be used to create a virtual machine running
184
the System Rescue CD (C<http://www.sysresccd.org/>) Besides the descriptor,
185
you only need the ISO image from the System Rescue CD website.
187
<?xml version="1.0" encoding="UTF-8"?>
189
<name>sysresccd</name>
196
<loader dev="cdrom"/>
198
<drive disk="root.raw" target="hda"/>
199
<drive disk="systemrescuecd.iso"/>
203
<memory>262144</memory>
209
<disk file="root.raw" use="scratch" size="100" format="raw"/>
210
<disk file="systemrescuecd.iso" use="system" format="iso"/>
214
To create a virtual machine, save the above XML in F<image.xml> and run:
216
# virt-image --vnc image.xml
220
Written by David Lutterkort. See the AUTHORS file in the source distribution for
221
the complete list of credits.
225
Report bugs to the mailing list C<http://www.redhat.com/mailman/listinfo/et-mgmt-tools>
226
or directly to BugZilla C<http://bugzilla.redhat.com/bugzilla/> against the
227
C<Fedora> product, and the C<python-virtinst> component.
231
Copyright (C) 2006-2007 Red Hat, Inc, and various contributors.
232
This is free software. You may redistribute copies of it under the terms of the GNU General
233
Public License C<http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent
238
L<virt-image(1)>, L<virt-install(1)>, the project website
239
C<http://virt-manager.org>, the Relax-NG grammar for image XML C<image.rng>
added
removed
man/en/virt-image-xml.pod
