mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-31 05:57:16 +00:00
179 lines
14 KiB
HTML
179 lines
14 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 are
|
|
variations on the format based on the kind of domains run and the options
|
|
used to launch them:</p><p><a href="#Normal1">Normal paravirtualized Xen domains</a></p><p><a href="#Fully1">Fully virtualized Xen domains</a></p><p>The formats try as much as possible to follow the same structure and reuse
|
|
elements and attributes where it makes sense.</p><h3 id="Normal"><a name="Normal1" id="Normal1">Normal paravirtualized Xen
|
|
guests</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><domain type='xen' <span style="color: #0071FF; background-color: #FFFFFF">id='18'</span>>
|
|
<name>fc4</name>
|
|
<span style="color: #00B200; background-color: #FFFFFF"><os>
|
|
<type>linux</type>
|
|
<kernel>/boot/vmlinuz-2.6.15-1.43_FC5guest</kernel>
|
|
<initrd>/boot/initrd-2.6.15-1.43_FC5guest.img</initrd>
|
|
<root>/dev/sda1</root>
|
|
<cmdline> ro selinux=0 3</cmdline>
|
|
</os></span>
|
|
<memory>131072</memory>
|
|
<vcpu>1</vcpu>
|
|
<devices>
|
|
<span style="color: #FF0080; background-color: #FFFFFF"><disk type='file'>
|
|
<source file='/u/fc4.img'/>
|
|
<target dev='sda1'/>
|
|
</disk></span>
|
|
<span style="color: #0000FF; background-color: #FFFFFF"><interface type='bridge'>
|
|
<source bridge='xenbr0'/>
|
|
<mac address='</span><span style="color: #0000FF; background-color: #FFFFFF"></span><span style="color: #0000FF; background-color: #FFFFFF">aa:00:00:00:00:11'/>
|
|
<script path='/etc/xen/scripts/vif-bridge'/>
|
|
</interface></span>
|
|
<span style="color: #FF8000; background-color: #FFFFFF"><console tty='/dev/pts/5'/></span>
|
|
</devices>
|
|
</domain></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' is
|
|
the default value. The <code>id</code> attribute gives the domain id at
|
|
runtime (not however that this may change, for example if the domain is saved
|
|
to disk and restored). The domain has a few children whose order is not
|
|
significant:</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 be
|
|
dependant 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 0
|
|
filesystem</li>
|
|
<li>cmdline: optional command line to the kernel</li>
|
|
<li>root: the root filesystem from the guest viewpoint, it may be
|
|
passed 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 the
|
|
following should be sufficient for basic use:</p><p>A <code>disk</code> device indicates a block device, it can have two
|
|
values for the type attribute either 'file' or 'block' corresponding to the 2
|
|
options availble at the Xen layer. It has two mandatory children, and one
|
|
optional one in no specific order:</p><ul><li>source with a file attribute containing the path in Domain 0 to the
|
|
file or a dev attribute if using a block device, containing the device
|
|
name ('hda5' or '/dev/hda5')</li>
|
|
<li>target indicates in a dev attribute the device where it is mapped in
|
|
the guest</li>
|
|
<li>readonly an optional empty element indicating the device is
|
|
read-only</li>
|
|
</ul><p>An <code>interface</code> element describes a network device mapped on the
|
|
guest, it also has a type whose value is currently 'bridge', it also have a
|
|
number 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 to
|
|
the guest. It has no children, and a single attribute <code>tty</code> which
|
|
provides the path to the Pseudo TTY on which the guest console can be
|
|
accessed</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 is
|
|
poweroff. There is various actions possible when this happen:</p><ul><li>destroy: The domain is cleaned up (that's the default normal processing
|
|
in Xen)</li>
|
|
<li>restart: A new domain is started in place of the old one with the same
|
|
configuration parameters</li>
|
|
<li>preserve: The domain will remain in memory until it is destroyed
|
|
manually, 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 domain
|
|
is renamed before being saved to allow a restart</li>
|
|
</ul><p>The following could be used for a Xen production system:</p><pre><domain>
|
|
...
|
|
<on_reboot>restart</on_reboot>
|
|
<on_poweroff>destroy</on_poweroff>
|
|
<on_crash>rename-restart</on_crash>
|
|
...
|
|
</domain></pre><p>While the format may be extended in various ways as support for more
|
|
hypervisor types and features are added, it is expected that this core subset
|
|
will 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 fully
|
|
virtualized (a.k.a. HVM) Xen domain. This requires hardware virtualization
|
|
support at the processor level but allows to run unmodified operating
|
|
systems:</p><pre><domain type='xen' id='3'>
|
|
<name>fv0</name>
|
|
<uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
|
|
<os>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><type>hvm</type></span>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><loader>/usr/lib/xen/boot/hvmloader</loader></span>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><boot dev='hd'/></span>
|
|
</os>
|
|
<memory>524288</memory>
|
|
<vcpu>1</vcpu>
|
|
<on_poweroff>destroy</on_poweroff>
|
|
<on_reboot>restart</on_reboot>
|
|
<on_crash>restart</on_crash>
|
|
<features>
|
|
<span style="color: #E50000; background-color: #FFFFFF"><pae/>
|
|
<acpi/>
|
|
<apic/></span>
|
|
</features>
|
|
<devices>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><emulator>/usr/lib/xen/bin/qemu-dm</emulator></span>
|
|
<interface type='bridge'>
|
|
<source bridge='xenbr0'/>
|
|
<mac address='00:16:3e:5d:c7:9e'/>
|
|
<script path='vif-bridge'/>
|
|
</interface>
|
|
<disk type='file'>
|
|
<source file='/root/fv0'/>
|
|
<target <span style="color: #0000E5; background-color: #FFFFFF">dev='hda'</span>/>
|
|
</disk>
|
|
<disk type='file' <span style="color: #0000E5; background-color: #FFFFFF">device='cdrom'</span>>
|
|
<source file='/root/fc5-x86_64-boot.iso'/>
|
|
<target <span style="color: #0000E5; background-color: #FFFFFF">dev='hdc'</span>/>
|
|
<readonly/>
|
|
</disk>
|
|
<disk type='file' <span style="color: #0000E5; background-color: #FFFFFF">device='floppy'</span>>
|
|
<source file='/root/fd.img'/>
|
|
<target <span style="color: #0000E5; background-color: #FFFFFF">dev='fda'</span>/>
|
|
</disk>
|
|
<span style="color: #0000E5; background-color: #FFFFFF"><graphics type='vnc' port='5904'/></span>
|
|
</devices>
|
|
</domain></pre><p>There is a few things to notice specifically for HVM domains:</p><ul><li>the optional <code><features></code> block is used to enable
|
|
certain guest CPU / system features. For HVM guests the following
|
|
features 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><os></code> block description is very different, first
|
|
it indicates that the type is 'hvm' for hardware virtualization, then
|
|
instead of a kernel, boot and command line arguments, it points to an os
|
|
boot loader which will extract the boot informations from the boot device
|
|
specified in a separate boot element. The <code>dev</code> attribute on
|
|
the <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><devices></code> section includes an emulator entry
|
|
pointing to an additional program in charge of emulating the devices</li>
|
|
<li>the disk entry indicates in the dev target section that the emulation
|
|
for the drive is the first IDE disk device hda. The list of device names
|
|
supported is dependant on the Hypervisor, but for Xen it can be any IDE
|
|
device <code>hda</code>-<code>hdd</code>, or a floppy device
|
|
<code>fda</code>, <code>fdb</code>. The <code><disk></code> element
|
|
also supports a 'device' attribute to indicate what kinda of hardware to
|
|
emulate. 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 it
|
|
omitted)</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 emulated
|
|
on any IDE channel.</li>
|
|
<li>the <code><devices></code> section also include at least one
|
|
entry for the graphic device used to render the os. Currently there is
|
|
just 2 types possible 'vnc' or 'sdl'. If the type is 'vnc', then an
|
|
additional <code>port</code> attribute will be present indicating the TCP
|
|
port on which the VNC server is accepting client connections.</li>
|
|
</ul><p>It is likely that the HVM description gets additional optional elements
|
|
and attributes as the support for fully virtualized domain expands,
|
|
especially for the variety of devices emulated and the graphic support
|
|
options offered.</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&component=libvirt&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED&short_desc_type=allwordssubstr&short_desc=&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>
|