mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-23 14:15:28 +00:00
635ae38979
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
215 lines
15 KiB
HTML
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><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'
|
|
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><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
|
|
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><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
|
|
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><os></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><devices></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><disk></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><devices></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><domain <span style="color: #FF0000; background-color: #FFFFFF">type='kvm'</span>>
|
|
<name>demo2</name>
|
|
<uuid>4dea24b3-1d52-d8f3-2516-782e98a23fa0</uuid>
|
|
<memory>131072</memory>
|
|
<vcpu>1</vcpu>
|
|
<os>
|
|
<type>hvm</type>
|
|
</os>
|
|
<devices>
|
|
<span style="color: #FF0000; background-color: #FFFFFF"><emulator>/home/user/usr/kvm-devel/bin/qemu-system-x86_64</emulator></span>
|
|
<disk type='file' device='disk'>
|
|
<source file='/home/user/fedora/diskboot.img'/>
|
|
<target dev='hda'/>
|
|
</disk>
|
|
<interface <span style="color: #FF0000; background-color: #FFFFFF">type='user'</span>>
|
|
<mac address='24:42:53:21:52:45'/>
|
|
</interface>
|
|
<graphics type='vnc' port='-1'/>
|
|
</devices>
|
|
</domain></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 <devices> 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&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>
|