Provided by: virtinst_0.600.1-1ubuntu3_all bug

NAME

       virt-image - Format of the virtual image XML descriptor

DESCRIPTION

       virt-image(1) relies on an XML descriptor to create virtual machines
       from virtual machine images. In general, a virtual machine image
       consists of the XML descriptor (usually in a file image.xml) and a
       number of files for the virtual machine's disks.

       In the following explanation of the structure of the image descriptor,
       mandatory XML elements are marked as element, whereas optional elements
       are marked as element.

       All file names in the image descriptor are relative to the location of
       the descriptor itself. Generally, disk files are either kept in the
       same directory as the image descriptor, or in a subdirectory.

HOST MATCHING

       The image descriptor contains information on the requirements a guest
       has on the host platform through one or more the /image/domain/boot
       descriptors (see section "BOOT"). The image can only be used if at
       least one of the boot descriptors is suitable for the host platform; a
       boot descriptor is suitable if:

       o   The CPU architecture of the boot descriptor, given by the
           boot/guest/arch element, is supported by the host

       o   The host supports a guest with the features requested in the
           boot/guest/features element, such as providing an APIC, or having
           ACPI turned off

       If a suitable boot descriptor is found, the guest is created and booted
       according to the information about booting the OS from the boot/os
       element and with the disks specified in the boot/drive element. If more
       than one suitable boot descriptor is found, one of them is chosen based
       on a heuristic, generally preferring paravirtualized guests over full
       virtualized ones, though this is an implementation detail of the tool
       creating the virtual machine.

STRUCTURE

       The image descriptor consists of three sections, all contained in the
       toplevel image element:

       General metadata about the image
           A number of elements like label, name, and description that give
           some simple information about the image. The name must be a string
           suitable as a name for the virtual machine, the label is a short
           human-readable string suitable for display in graphical UI's, and
           the description should be a longer, free-form description of the
           purpose of the image. The name is mandatory.

       Virtual machine attributes
           The domain element contains instructions on how to boot the image,
           and device attributes such as the number of virtual CPU's and the
           size of the memory. (see section "DOMAIN")

       Storage layout
           The storage element lists the files to back the virtual machine's
           disks and some information about their format and use. (see section
           "STORAGE")

DOMAIN

       The domain element contains one or more boot descriptors (see section
       "BOOT") and a devices element. The Devices element lists the
       recommended number of virtual CPU's in the vcpu element and the
       recommended amount of memory in kB in the memory element. It also
       indicates whether the virtual machine should have a network interface
       through the interface element and whether the virtual machine has a
       graphical interface through the graphics element.

   BOOT
       Each boot descriptor details how the virtual machine should be started
       on a certain hypervisor. The type attribute of the boot element, which
       can either be "xen" or "hvm", depending on whether the boot descriptor
       is for a paravirtualized Xen(tm) guest or a fully-virtualized guest.

       The boot element contains three subelements:

       The platform requirements of the guest
           The platform requirements, contained in the guest element, consist
           of the arch element and the features element. The arch element
           indicates the CPU architecture the guest expects, e.g. "i686",
           "x86_64", or "ppc".

           The features element indicates whether certain platform features
           should be on or off. Currently, the platform features are pae,
           acpi, and apic. They can be turned on or off by giving a state
           attribute of either "on" or "off". When a feature is mentioned in
           the features element, it defaults to "on".

       The details of booting the image's operating system
           The os element for fully-virtualized "hvm" guests contains a loader
           element whose dev attribute indicates whether to boot off a hard
           disk ("dev='hd'") or off a CD-ROM ("dev='cdrom'")

           For paravirtualized guests, the os element either contains a
           "<loader>pygrub</loader>" element, indicating that the guest should
           be booted with pygrub, or kernel, initrd and cmdline elements. The
           contents of the kernel and initrd elements are the names of the
           kernel and initrd files, whereas the cmdline element contains the
           command line that should be passed to the kernel on boot.

       The mapping of disk files as devices into the guest
           The mapping of disk files into the guest is performed by a list of
           drive elements inside the boot element. Each drive element
           references the name of a disk file from the "STORAGE" section
           through its disk attribute and can optionally specify as what
           device that disk file should appear in the guest through its target
           attribute. If the target is omitted, device names are assigned in
           the order in which the drive elements appear, skipping already
           assigned devices.

STORAGE

       The storage element lists the disk image files that are part of the
       virtual machine image in a list of one or more disk elements. Each disk
       element can contain the following attributes:

       o   the file attribute giving the name of the disk file

       o   an optional id attribute. The name given with that attribute is
           used to reference the disk from the drive element of a boot
           descriptor. If the id attribute is missing, it defaults to the file
           attribute.

       o   the use attribute indicating whether the disk file is a "system",
           "user", or "scratch" disk. The use attribute differentiates disk
           files so that an update based on replacing disk files can replace
           "system" disks, but leave "user" disks untouched.

           Generally, "system" disks contain application code, "user" disks
           contain the application's data, and "scratch" disks contain
           temporary state that can be erased between runs of the guest.

           The virtual machine image must contain files for all "system"
           disks, and may contain files for the "user" and "scratch" disks. If
           the latter are not part of the image, they are initialized as empty
           files when a guest is created, with the size given by the size
           attribute.

       o   the size attribute giving the size of the disk in MB.

       o   the format attribute giving the format of the disk file. Currently,
           this can be one of: "raw" "iso", "qcow", "qcow2", or "vmdk".

EXAMPLE

       The image descriptor below can be used to create a virtual machine
       running the System Rescue CD ("http://www.sysresccd.org/") Besides the
       descriptor, you only need the ISO image from the System Rescue CD
       website.

           <?xml version="1.0" encoding="UTF-8"?>
           <image>
             <name>sysresccd</name>
             <domain>
               <boot type="hvm">
                 <guest>
                   <arch>i686</arch>
                 </guest>
                 <os>
                   <loader dev="cdrom"/>
                 </os>
                 <drive disk="root.raw" target="hda"/>
                 <drive disk="sysresc"/>
               </boot>
               <devices>
                 <vcpu>1</vcpu>
                 <memory>262144</memory>
                 <interface/>
                 <graphics/>
               </devices>
             </domain>
             <storage>
               <disk file="root.raw" use="scratch" size="100" format="raw"/>
               <disk id="sysresc" file="isos/systemrescuecd.iso"
                     use="system" format="iso"/>
             </storage>
           </image>

       To create a virtual machine, save the above XML in image.xml and run:

           # virt-image --vnc image.xml

AUTHOR

       Written by David Lutterkort. See the AUTHORS file in the source
       distribution for the complete list of credits.

BUGS

       Please see "http://virt-manager.org/page/BugReporting"

COPYRIGHT

       Copyright (C) 2006-2007 Red Hat, Inc, and various contributors.  This
       is free software. You may redistribute copies of it under the terms of
       the GNU General Public License "http://www.gnu.org/licenses/gpl.html".
       There is NO WARRANTY, to the extent permitted by law.

SEE ALSO

       virt-image(1), virt-install(1), the project website
       "http://virt-manager.org", the Relax-NG grammar for image XML
       "image.rng"

                                  2011-04-15                     virt-image(5)