Man pages for virt-image tool and XML format

Author: David Lutterkort

man/en/virt-image-xml.pod

@@ -0,0 +1,242 @@
+=pod
+
+=head1 NAME
+
+virt-image - Format of the virtual image XML descriptor
+
+=head1 DESCRIPTION
+
+L<virt-image(1)> relies on an XML descriptior to create virtual machines from
+virtual machine images. In general, a virtual machine image consists of the
+XML descriptor (usually in a file F<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 B<element>, whereas optional elements
+are marked as I<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.
+
+=head1 HOST MATCHING
+
+The image descriptor contains information on the requirements a guest has
+on the host platform through one or more the F</image/domain/boot>
+descriptors (see section L</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:
+
+=over 4
+
+=item *
+
+The CPU architecture of the boot descriptor, given by the
+F<boot/guest/arch> element, is supported by the host
+
+=item *
+
+The host supports a guest with the features requested in the
+F<boot/guest/features> element, such as providing an APIC, or having ACPI
+turned off
+
+=back
+
+If a suitable boot descriptor is found, the guest is created and booted
+according to the information about booting the OS from the F<boot/os>
+element and with the disks specified in the F<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.
+
+=head1 STRUCTURE
+
+The image descriptor consists of three sections, all contained in the
+toplevel B<image> element:
+
+=over 4
+
+=item General metadata about the image
+
+A number of elements like I<label>, B<name>, and I<description> that give
+some simple information about the image. The B<name> must be a string
+suitable as a name for the virtual machine, the I<label> is a short
+human-readable string suitable for display in graphical UI's, and the
+I<description> should be a longer, free-form description of the purpose of
+the image. The B<name> is mandatory.
+
+=item Virtual machine attributes
+
+The B<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 L</DOMAIN>)
+
+=item Storage layout
+
+The B<storage> element lists the files to back the virtual machine's disks
+and some information about their format and use. (see section L</STORAGE>)
+
+=back
+
+=head1 DOMAIN
+
+The B<domain> element contains one or more B<boot> descriptors (see section
+L</BOOT>) and a B<devices> element. The B<Devices> element lists the
+recommended number of virtual CPU's in the B<vcpu> element and the
+recommended amount of memory in kB in the B<memory> element. It also
+indicates whether the virtual machine should have a network interface
+through the I<interface> element and whether the virtual machine has a
+grphical interface through the I<graphics> element.
+
+=head2 BOOT
+
+Each B<boot> descriptor details how the virtual machine should be started
+on a certain hypervisor. The B<type> attribute of the B<boot> element,
+which can either be C<xen> or C<hvm>, dpeending on whether the boot
+descriptor is for a paravirtualized Xen(tm) guest or a fully-virtualized
+guest.
+
+The B<boot> element contains three subelements:
+
+=over 4
+
+=item The platform requirements of the guest
+
+The platform requirements, contained in the B<guest> element, consist of
+the B<arch> element and the I<features> element. The B<arch> element
+indicates the CPU architecture the guest expects, e.g. C<i686>, C<x86_64>,
+or C<ppc>.
+
+The I<features> element indicates whether certain platform features should
+be on or off. Currently, the platform features are I<pae>, I<acpi>, and
+I<apic>. They can be turned on or off by giving a I<state> attribute of
+either C<on> or C<off>. When a feature is mentioned in the I<features>
+element, it defaults to C<on>.
+
+=item The details of booting the image's operating system
+
+The B<os> element for fully-virtualized C<hvm> guests contains a B<loader>
+element whose B<dev> attribute indicates whether to boot off a hard disk
+(C<dev='hd'>) or off a CD-ROM (C<dev='cdrom'>)
+
+For paravirtualized guests, the B<os> element either contains a
+C<< <loader>pygrub</loader> >> element, indicating that the guest should be
+booted with F<pygrub>, or B<kernel>, I<initrd> and I<cmdline> elements. The
+contents of the B<kernel> and I<initrd> elements are the names of the
+kernel and initrd files, whereas the I<cmdline> element contains the
+command line that should be passed to the kernel on boot.
+
+=item The mapping of disk files as devices into the guest
+
+The mapping of disk files into the guest is performed by a list of B<drive>
+elements inside the B<boot> element. Each B<drive> element references the
+name of a disk file from the L</STORAGE> section through its B<disk>
+attribute and can optionally specify as what device that disk file should
+appear in the guest through its I<target> attribute. If the I<target> is
+omitted. device names are assigned in the order in which the B<drive>
+elements appear, skipping already assigned devices.
+
+=back
+
+=head1 STORAGE
+
+The B<storage> element lists the disk image files that are part ofthe
+virtual machine image in a list of one or more B<disk> elements. Each
+B<disk> element can contain the following attributes:
+
+=over 4
+
+=item *
+
+the B<file> attribute givingthe name of the disk file
+
+=item *
+
+the B<use> attribute indicating whether the disk file is a C<system>,
+C<user>, or C<scratch> disk. The B<use> attribute differentiates disk files
+so that an update based on replacing disk files can replace C<system>
+disks, but leave C<user> disks untouched.
+
+Generally, C<system> disks contain application code, C<user> disks contain
+the application's data, and C<scratch> disks contain temporary state that
+can be erased between runs of the guest.
+
+The virtual machine image must contain files for all C<system> disks, and
+may contain files for the C<user> and C<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 I<size> attribute.
+
+=item *
+
+the I<size> attribute giving the size of the disk in MB.
+
+=item *
+
+the I<format> attribute giving the format of the disk file. Currently, this
+can be either C<raw> for a raw disk image and C<iso> for an ISO image.
+
+=back
+
+=head1 EXAMPLE
+
+The image descriptor below can be used to create a virtual machine running
+the System Rescue CD (C<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="systemrescuecd.iso"/>
+        </boot>
+        <devices>
+          <vcpu>1</vcpu>
+          <memory>262144</memory>
+          <interface/>
+          <graphics/>
+        </devices>
+      </domain>
+      <storage>
+        <disk file="root.raw" use="scratch" size="100" format="raw"/>
+        <disk file="systemrescuecd.iso" use="system" format="iso"/>
+      </storage>
+    </image>
+
+To create a virtual machine, save the above XML in F<image.xml> and run:
+
+    # virt-image --vnc image.xml
+
+=head1 AUTHOR
+
+Writen by David Lutterkort. See the AUTHORS file in the source distribution for
+the complete list of credits.
+
+=head1 BUGS
+
+Report bugs to the mailing list C<http://www.redhat.com/mailman/listinfo/et-mgmt-tools>
+or directly to BugZilla C<http://bugzilla.redhat.com/bugzilla/> against the
+C<Fedora> product, and the C<python-virtinst> component.
+
+=head1 COPYRIGHT
+
+Copright (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 C<http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent 
+permitted by law.
+
+=head1 SEE ALSO
+
+L<virt-image(1)>, L<virt-install(1)>, the project website
+C<http://virt-manager.org>, the Relax-NG grammar for image XML C<image.rng>
+
+=cut
+