libvirt/docs/format.html
Daniel Veillard 635ae38979 * include/libvirt/libvirt.h[.in] include/libvirt/virterror.h
proxy/libvirt_proxy.c qemud/Makefile.am qemud/conf.c qemud/conf.h
  qemud/dispatch.c qemud/internal.h qemud/protocol.h
  src/driver.h src/internal.h src/libvirt.c src/libvirt_sym.version
  src/proxy_internal.c src/proxy_internal.h src/qemu_internal.c
  src/test.c src/virsh.c src/virterror.c src/xen_internal.c
  src/xen_internal.h src/xend_internal.c src/xm_internal.c
  src/xml.h src/xs_internal.c: applied patch from Richard Jones
  adding virConnectGetCapabilities(), plus various small little
  fixes
* docs/*: fixed the api extractor script and regenerated
Daniel
2007-03-15 17:24:56 +00:00

215 lines
15 KiB
HTML

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="libvirt.css" /><link rel="SHORTCUT ICON" href="/32favicon.png" /><title>XML Format</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">XML Format</h1><p>This section describes the XML format used to represent domains, there
arevariations on the format based on the kind of domains run and the
optionsused to launch them:</p><ul><li><a href="#Normal1">Normal paravirtualized Xen domains</a></li>
<li><a href="#Fully1">Fully virtualized Xen domains</a></li>
<li><a href="#KVM1">KVM domains</a></li>
<li><a href="#QEmu1">QEmu domains</a></li>
</ul><p>The formats try as much as possible to follow the same structure and
reuseelements and attributes where it makes sense.</p><h3 id="Normal"><a name="Normal1" id="Normal1">Normal paravirtualized
Xendomains</a>:</h3><p>The library use an XML format to describe domains, as input to <a href="html/libvirt-libvirt.html#virDomainCreateLinux">virDomainCreateLinux()</a>and
as the output of <a href="html/libvirt-libvirt.html#virDomainGetXMLDesc">virDomainGetXMLDesc()</a>,the
following is an example of the format as returned by the shell
command<code>virsh xmldump fc4</code>, where fc4 was one of the running
domains:</p><pre>&lt;domain type='xen' <span style="color: #0071FF; background-color: #FFFFFF">id='18'</span>&gt;
&lt;name&gt;fc4&lt;/name&gt;
<span style="color: #00B200; background-color: #FFFFFF">&lt;os&gt;
&lt;type&gt;linux&lt;/type&gt;
&lt;kernel&gt;/boot/vmlinuz-2.6.15-1.43_FC5guest&lt;/kernel&gt;
&lt;initrd&gt;/boot/initrd-2.6.15-1.43_FC5guest.img&lt;/initrd&gt;
&lt;root&gt;/dev/sda1&lt;/root&gt;
&lt;cmdline&gt; ro selinux=0 3&lt;/cmdline&gt;
&lt;/os&gt;</span>
&lt;memory&gt;131072&lt;/memory&gt;
&lt;vcpu&gt;1&lt;/vcpu&gt;
&lt;devices&gt;
<span style="color: #FF0080; background-color: #FFFFFF">&lt;disk type='file'&gt;
&lt;source file='/u/fc4.img'/&gt;
&lt;target dev='sda1'/&gt;
&lt;/disk&gt;</span>
<span style="color: #0000FF; background-color: #FFFFFF">&lt;interface type='bridge'&gt;
&lt;source bridge='xenbr0'/&gt;
&lt;mac address='</span><span style="color: #0000FF; background-color: #FFFFFF"></span><span style="color: #0000FF; background-color: #FFFFFF">aa:00:00:00:00:11'/&gt;
&lt;script path='/etc/xen/scripts/vif-bridge'/&gt;
&lt;/interface&gt;</span>
<span style="color: #FF8000; background-color: #FFFFFF">&lt;console tty='/dev/pts/5'/&gt;</span>
&lt;/devices&gt;
&lt;/domain&gt;</pre><p>The root element must be called <code>domain</code>with no namespace,
the<code>type</code>attribute indicates the kind of hypervisor used, 'xen'
isthe default value. The <code>id</code>attribute gives the domain id
atruntime (not however that this may change, for example if the domain is
savedto disk and restored). The domain has a few children whose order is
notsignificant:</p><ul><li>name: the domain name, preferably ASCII based</li>
<li>memory: the maximum memory allocated to the domain in kilobytes</li>
<li>vcpu: the number of virtual cpu configured for the domain</li>
<li>os: a block describing the Operating System, its content will
bedependant on the OS type
<ul><li>type: indicate the OS type, always linux at this point</li>
<li>kernel: path to the kernel on the Domain 0 filesystem</li>
<li>initrd: an optional path for the init ramdisk on the Domain
0filesystem</li>
<li>cmdline: optional command line to the kernel</li>
<li>root: the root filesystem from the guest viewpoint, it may bepassed
as part of the cmdline content too</li>
</ul></li>
<li>devices: a list of <code>disk</code>,
<code>interface</code>and<code>console</code>descriptions in no special
order</li>
</ul><p>The format of the devices and their type may grow over time, but
thefollowing should be sufficient for basic use:</p><p>A <code>disk</code>device indicates a block device, it can have twovalues
for the type attribute either 'file' or 'block' corresponding to the 2options
availble at the Xen layer. It has two mandatory children, and oneoptional one
in no specific order:</p><ul><li>source with a file attribute containing the path in Domain 0 to thefile
or a dev attribute if using a block device, containing the devicename
('hda5' or '/dev/hda5')</li>
<li>target indicates in a dev attribute the device where it is mapped inthe
guest</li>
<li>readonly an optional empty element indicating the device
isread-only</li>
</ul><p>An <code>interface</code>element describes a network device mapped on
theguest, it also has a type whose value is currently 'bridge', it also have
anumber of children in no specific order:</p><ul><li>source: indicating the bridge name</li>
<li>mac: the optional mac address provided in the address attribute</li>
<li>ip: the optional IP address provided in the address attribute</li>
<li>script: the script used to bridge the interfcae in the Domain 0</li>
<li>target: and optional target indicating the device name.</li>
</ul><p>A <code>console</code>element describes a serial console connection tothe
guest. It has no children, and a single attribute
<code>tty</code>whichprovides the path to the Pseudo TTY on which the guest
console can beaccessed</p><p>Life cycle actions for the domain can also be expressed in the XML
format,they drive what should be happening if the domain crashes, is rebooted
or ispoweroff. There is various actions possible when this happen:</p><ul><li>destroy: The domain is cleaned up (that's the default normal
processingin Xen)</li>
<li>restart: A new domain is started in place of the old one with the
sameconfiguration parameters</li>
<li>preserve: The domain will remain in memory until it is
destroyedmanually, it won't be running but allows for post-mortem
debugging</li>
<li>rename-restart: a variant of the previous one but where the old
domainis renamed before being saved to allow a restart</li>
</ul><p>The following could be used for a Xen production system:</p><pre>&lt;domain&gt;
...
&lt;on_reboot&gt;restart&lt;/on_reboot&gt;
&lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
&lt;on_crash&gt;rename-restart&lt;/on_crash&gt;
...
&lt;/domain&gt;</pre><p>While the format may be extended in various ways as support for
morehypervisor types and features are added, it is expected that this core
subsetwill remain functional in spite of the evolution of the library.</p><h3 id="Fully"><a name="Fully1" id="Fully1">Fully virtualized
guests</a>(added in 0.1.3):</h3><p>Here is an example of a domain description used to start a
fullyvirtualized (a.k.a. HVM) Xen domain. This requires hardware
virtualizationsupport at the processor level but allows to run unmodified
operatingsystems:</p><pre>&lt;domain type='xen' id='3'&gt;
&lt;name&gt;fv0&lt;/name&gt;
&lt;uuid&gt;4dea22b31d52d8f32516782e98ab3fa0&lt;/uuid&gt;
&lt;os&gt;
<span style="color: #0000E5; background-color: #FFFFFF">&lt;type&gt;hvm&lt;/type&gt;</span>
<span style="color: #0000E5; background-color: #FFFFFF">&lt;loader&gt;/usr/lib/xen/boot/hvmloader&lt;/loader&gt;</span>
<span style="color: #0000E5; background-color: #FFFFFF">&lt;boot dev='hd'/&gt;</span>
&lt;/os&gt;
&lt;memory&gt;524288&lt;/memory&gt;
&lt;vcpu&gt;1&lt;/vcpu&gt;
&lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
&lt;on_reboot&gt;restart&lt;/on_reboot&gt;
&lt;on_crash&gt;restart&lt;/on_crash&gt;
&lt;features&gt;
<span style="color: #E50000; background-color: #FFFFFF">&lt;pae/&gt;
&lt;acpi/&gt;
&lt;apic/&gt;</span>
&lt;/features&gt;
&lt;devices&gt;
<span style="color: #0000E5; background-color: #FFFFFF">&lt;emulator&gt;/usr/lib/xen/bin/qemu-dm&lt;/emulator&gt;</span>
&lt;interface type='bridge'&gt;
&lt;source bridge='xenbr0'/&gt;
&lt;mac address='00:16:3e:5d:c7:9e'/&gt;
&lt;script path='vif-bridge'/&gt;
&lt;/interface&gt;
&lt;disk type='file'&gt;
&lt;source file='/root/fv0'/&gt;
&lt;target <span style="color: #0000E5; background-color: #FFFFFF">dev='hda'</span>/&gt;
&lt;/disk&gt;
&lt;disk type='file' <span style="color: #0000E5; background-color: #FFFFFF">device='cdrom'</span>&gt;
&lt;source file='/root/fc5-x86_64-boot.iso'/&gt;
&lt;target <span style="color: #0000E5; background-color: #FFFFFF">dev='hdc'</span>/&gt;
&lt;readonly/&gt;
&lt;/disk&gt;
&lt;disk type='file' <span style="color: #0000E5; background-color: #FFFFFF">device='floppy'</span>&gt;
&lt;source file='/root/fd.img'/&gt;
&lt;target <span style="color: #0000E5; background-color: #FFFFFF">dev='fda'</span>/&gt;
&lt;/disk&gt;
<span style="color: #0000E5; background-color: #FFFFFF">&lt;graphics type='vnc' port='5904'/&gt;</span>
&lt;/devices&gt;
&lt;/domain&gt;</pre><p>There is a few things to notice specifically for HVM domains:</p><ul><li>the optional <code>&lt;features&gt;</code>block is used to
enablecertain guest CPU / system features. For HVM guests the
followingfeatures are defined:
<ul><li><code>pae</code>- enable PAE memory addressing</li>
<li><code>apic</code>- enable IO APIC</li>
<li><code>acpi</code>- enable ACPI bios</li>
</ul></li>
<li>the <code>&lt;os&gt;</code>block description is very different, firstit
indicates that the type is 'hvm' for hardware virtualization, theninstead
of a kernel, boot and command line arguments, it points to an osboot
loader which will extract the boot informations from the boot
devicespecified in a separate boot element. The <code>dev</code>attribute
onthe <code>boot</code>tag can be one of:
<ul><li><code>fd</code>- boot from first floppy device</li>
<li><code>hd</code>- boot from first harddisk device</li>
<li><code>cdrom</code>- boot from first cdrom device</li>
</ul></li>
<li>the <code>&lt;devices&gt;</code>section includes an emulator
entrypointing to an additional program in charge of emulating the
devices</li>
<li>the disk entry indicates in the dev target section that the
emulationfor the drive is the first IDE disk device hda. The list of
device namessupported is dependant on the Hypervisor, but for Xen it can
be any IDEdevice <code>hda</code>-<code>hdd</code>, or a floppy
device<code>fda</code>, <code>fdb</code>. The
<code>&lt;disk&gt;</code>elementalso supports a 'device' attribute to
indicate what kinda of hardware toemulate. The following values are
supported:
<ul><li><code>floppy</code>- a floppy disk controller</li>
<li><code>disk</code>- a generic hard drive (the default itomitted)</li>
<li><code>cdrom</code>- a CDROM device</li>
</ul>
For Xen 3.0.2 and earlier a CDROM device can only be emulated on
the<code>hdc</code>channel, while for 3.0.3 and later, it can be
emulatedon any IDE channel.</li>
<li>the <code>&lt;devices&gt;</code>section also include at least oneentry
for the graphic device used to render the os. Currently there isjust 2
types possible 'vnc' or 'sdl'. If the type is 'vnc', then anadditional
<code>port</code>attribute will be present indicating the TCPport on
which the VNC server is accepting client connections.</li>
</ul><p>It is likely that the HVM description gets additional optional elementsand
attributes as the support for fully virtualized domain expands,especially for
the variety of devices emulated and the graphic supportoptions offered.</p><h3><a name="KVM1" id="KVM1">KVM domain (added in 0.2.0)</a></h3><p>Support for the KVM virtualization is provided in recent Linux kernels
(2.6.20 and onward). This requires specific hardware with acceleration
support and the availability of the special version of the <a href="http://fabrice.bellard.free.fr/qemu/">QEmu</a> binary. Since this
relies on QEmu for the machine emulation like fully virtualized guests the
XML description is quite similar, here is a simple example:</p><pre>&lt;domain <span style="color: #FF0000; background-color: #FFFFFF">type='kvm'</span>&gt;
&lt;name&gt;demo2&lt;/name&gt;
&lt;uuid&gt;4dea24b3-1d52-d8f3-2516-782e98a23fa0&lt;/uuid&gt;
&lt;memory&gt;131072&lt;/memory&gt;
&lt;vcpu&gt;1&lt;/vcpu&gt;
&lt;os&gt;
&lt;type&gt;hvm&lt;/type&gt;
&lt;/os&gt;
&lt;devices&gt;
<span style="color: #FF0000; background-color: #FFFFFF">&lt;emulator&gt;/home/user/usr/kvm-devel/bin/qemu-system-x86_64&lt;/emulator&gt;</span>
&lt;disk type='file' device='disk'&gt;
&lt;source file='/home/user/fedora/diskboot.img'/&gt;
&lt;target dev='hda'/&gt;
&lt;/disk&gt;
&lt;interface <span style="color: #FF0000; background-color: #FFFFFF">type='user'</span>&gt;
&lt;mac address='24:42:53:21:52:45'/&gt;
&lt;/interface&gt;
&lt;graphics type='vnc' port='-1'/&gt;
&lt;/devices&gt;
&lt;/domain&gt;</pre><p>The specific points to note if using KVM are:</p><ul><li>the top level domain element carries a type of 'kvm'</li>
<li>the &lt;devices&gt; emulator points to the special qemu binary required
for KVM</li>
<li>networking interface definitions definitions are somewhat different due
to a different model from Xen (@@TODO)</li>
</ul><p>except those points the options should be quite similar to Xen HVM
ones.</p><h3><a name="QEmu1" id="QEmu1">QEmu domain (added in 0.2.0)</a></h3><p></p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="https://bugzilla.redhat.com/bugzilla/buglist.cgi?product=Fedora+Core&amp;component=libvirt&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;bug_status=MODIFIED&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;long_desc_type=allwordssubstr">Open bugs</a></li><li><a href="http://virt-manager.et.redhat.com/">virt-manager</a></li><li><a href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">Perl bindings</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>