1virt-image(5) Virtual Machine Install Tools virt-image(5)
2
6 virt-image - Format of the virtual image XML descriptor
7
9 virt-image(1) relies on an XML descriptor to create virtual machines
10 from virtual machine images. In general, a virtual machine image con‐
11 sists of the XML descriptor (usually in a file image.xml) and a number
12 of files for the virtual machine's disks.
13 In the following explanation of the structure of the image descriptor,
15 mandatory XML elements are marked as element, whereas optional elements
16 are marked as element.
17 All file names in the image descriptor are relative to the location of
19 the descriptor itself. Generally, disk files are either kept in the
20 same directory as the image descriptor, or in a subdirectory.
21
23 The image descriptor contains information on the requirements a guest
24 has on the host platform through one or more the /image/domain/boot
25 descriptors (see section "BOOT"). The image can only be used if at
26 least one of the boot descriptors is suitable for the host platform; a
27 boot descriptor is suitable if:
28 · The CPU architecture of the boot descriptor, given by the
30 boot/guest/arch element, is supported by the host
31 · The host supports a guest with the features requested in the
33 boot/guest/features element, such as providing an APIC, or having
34 ACPI turned off
35 If a suitable boot descriptor is found, the guest is created and booted
37 according to the information about booting the OS from the boot/os ele‐
38 ment and with the disks specified in the boot/drive element. If more
39 than one suitable boot descriptor is found, one of them is chosen based
40 on a heuristic, generally preferring paravirtualized guests over full
41 virtualized ones, though this is an implementation detail of the tool
42 creating the virtual machine.
43
45 The image descriptor consists of three sections, all contained in the
46 toplevel image element:
47 General metadata about the image
49 A number of elements like label, name, and description that give
50 some simple information about the image. The name must be a string
51 suitable as a name for the virtual machine, the label is a short
52 human-readable string suitable for display in graphical UI's, and
53 the description should be a longer, free-form description of the
54 purpose of the image. The name is mandatory.
55 Virtual machine attributes
57 The domain element contains instructions on how to boot the image,
58 and device attributes such as the number of virtual CPU's and the
59 size of the memory. (see section "DOMAIN")
60 Storage layout
62 The storage element lists the files to back the virtual machine's
63 disks and some information about their format and use. (see section
64 "STORAGE")
65
67 The domain element contains one or more boot descriptors (see section
68 "BOOT") and a devices element. The Devices element lists the recom‐
69 mended number of virtual CPU's in the vcpu element and the recommended
70 amount of memory in kB in the memory element. It also indicates whether
71 the virtual machine should have a network interface through the inter‐
72 face element and whether the virtual machine has a graphical interface
73 through the graphics element.
74 BOOT
76 Each boot descriptor details how the virtual machine should be started
78 on a certain hypervisor. The type attribute of the boot element, which
79 can either be "xen" or "hvm", depending on whether the boot descriptor
80 is for a paravirtualized Xen(tm) guest or a fully-virtualized guest.
81 The boot element contains three subelements:
83 The platform requirements of the guest
85 The platform requirements, contained in the guest element, consist
86 of the arch element and the features element. The arch element
87 indicates the CPU architecture the guest expects, e.g. "i686",
88 "x86_64", or "ppc".
89 The features element indicates whether certain platform features
91 should be on or off. Currently, the platform features are pae,
92 acpi, and apic. They can be turned on or off by giving a state
93 attribute of either "on" or "off". When a feature is mentioned in
94 the features element, it defaults to "on".
95 The details of booting the image's operating system
97 The os element for fully-virtualized "hvm" guests contains a loader
98 element whose dev attribute indicates whether to boot off a hard
99 disk ("dev='hd'") or off a CD-ROM ("dev='cdrom'")
100 For paravirtualized guests, the os element either contains a
102 "<loader>pygrub</loader>" element, indicating that the guest should
103 be booted with pygrub, or kernel, initrd and cmdline elements. The
104 contents of the kernel and initrd elements are the names of the
105 kernel and initrd files, whereas the cmdline element contains the
106 command line that should be passed to the kernel on boot.
107 The mapping of disk files as devices into the guest
109 The mapping of disk files into the guest is performed by a list of
110 drive elements inside the boot element. Each drive element refer‐
111 ences the name of a disk file from the "STORAGE" section through
112 its disk attribute and can optionally specify as what device that
113 disk file should appear in the guest through its target attribute.
114 If the target is omitted, device names are assigned in the order in
115 which the drive elements appear, skipping already assigned devices.
116
118 The storage element lists the disk image files that are part of the
119 virtual machine image in a list of one or more disk elements. Each disk
120 element can contain the following attributes:
121 · the file attribute giving the name of the disk file
123 · an optional id attribute. The name given with that attribute is
125 used to reference the disk from the drive element of a boot
126 descriptor. If the id attribute is missing, it defaults to the file
127 attribute.
128 · the use attribute indicating whether the disk file is a "system",
130 "user", or "scratch" disk. The use attribute differentiates disk
131 files so that an update based on replacing disk files can replace
132 "system" disks, but leave "user" disks untouched.
133 Generally, "system" disks contain application code, "user" disks
135 contain the application's data, and "scratch" disks contain tempo‐
136 rary state that can be erased between runs of the guest.
137 The virtual machine image must contain files for all "system"
139 disks, and may contain files for the "user" and "scratch" disks. If
140 the latter are not part of the image, they are initialized as empty
141 files when a guest is created, with the size given by the size
142 attribute.
143 · the size attribute giving the size of the disk in MB.
145 · the format attribute giving the format of the disk file. Currently,
147 this can be either "raw" for a raw disk image and "iso" for an ISO
148 image.
149
151 The image descriptor below can be used to create a virtual machine run‐
152 ning the System Rescue CD ("http://www.sysresccd.org/") Besides the
153 descriptor, you only need the ISO image from the System Rescue CD web‐
154 site.
155 <?xml version="1.0" encoding="UTF-8"?>
157 <image>
158 <name>sysresccd</name>
159 <domain>
160 <boot type="hvm">
161 <guest>
162 <arch>i686</arch>
163 </guest>
164 <os>
165 <loader dev="cdrom"/>
166 </os>
167 <drive disk="root.raw" target="hda"/>
168 <drive disk="sysresc"/>
169 </boot>
170 <devices>
171 <vcpu>1</vcpu>
172 <memory>262144</memory>
173 <interface/>
174 <graphics/>
175 </devices>
176 </domain>
177 <storage>
178 <disk file="root.raw" use="scratch" size="100" format="raw"/>
179 <disk id="sysresc" file="isos/systemrescuecd.iso"
180 use="system" format="iso"/>
181 </storage>
182 </image>
183 To create a virtual machine, save the above XML in image.xml and run:
185 # virt-image --vnc image.xml
187
189 Written by David Lutterkort. See the AUTHORS file in the source distri‐
190 bution for the complete list of credits.
191
193 Report bugs to the mailing list "http://www.redhat.com/mail‐
194 man/listinfo/et-mgmt-tools" or directly to BugZilla
195 "http://bugzilla.redhat.com/bugzilla/" against the "Fedora" product,
196 and the "python-virtinst" component.
197
199 Copyright (C) 2006-2007 Red Hat, Inc, and various contributors. This
200 is free software. You may redistribute copies of it under the terms of
201 the GNU General Public License "http://www.gnu.org/licenses/gpl.html".
202 There is NO WARRANTY, to the extent permitted by law.
203
205 virt-image(1), virt-install(1), the project website "http://virt-man‐
206 ager.org", the Relax-NG grammar for image XML "image.rng"
207perl v5.8.8 2007-12-04 virt-image(5)