External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-02-03 18:35:19 +00:00
Code Issues Packages Projects Releases Wiki Activity
libvirt/docs/format.html

133 lines
11 KiB
HTML
Raw Normal View History

* src/libvirt.c src/xend_internal.c src/xend_internal.h: move the XML dump function around to make sure all entry points are centralized in libvirt.c and also avoid doc generation troubles. * docs/examples/Makefile.am docs/examples/index.py: fix the makefile a bit. * TODO: updated * docs/format.html: added a description of the XML used for the domains. * docs//*: rebuilt Daniel
2006-02-20 23:08:47 +00:00
<?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">
* docs/format.html docs/libvir.html docs/news.html: updated the XML format documentation to cover the new HVM domains. Daniel
2006-07-10 13:13:39 +00:00
<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>
* src/libvirt.c src/xend_internal.c src/xend_internal.h: move the XML dump function around to make sure all entry points are centralized in libvirt.c and also avoid doc generation troubles. * docs/examples/Makefile.am docs/examples/index.py: fix the makefile a bit. * TODO: updated * docs/format.html: added a description of the XML used for the domains. * docs//*: rebuilt Daniel
2006-02-20 23:08:47 +00:00
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>
&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' 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> and <code>interface</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 disk 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 interface 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>
* src/xend_internal.c src/xml.c: applied patch from Jim Fehlig for lifecycle events * docs/format.html docs/libvir.html: added the associated docs for the new constructs * TODO: small update Daniel
2006-04-10 08:32:34 +00:00
</ul><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>&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 more
* src/libvirt.c src/xend_internal.c src/xend_internal.h: move the XML dump function around to make sure all entry points are centralized in libvirt.c and also avoid doc generation troubles. * docs/examples/Makefile.am docs/examples/index.py: fix the makefile a bit. * TODO: updated * docs/format.html: added a description of the XML used for the domains. * docs//*: rebuilt Daniel
2006-02-20 23:08:47 +00:00
hypervisor types and features are added, it is expected that this core subset
* docs/format.html docs/libvir.html docs/news.html: updated the XML format documentation to cover the new HVM domains. Daniel
2006-07-10 13:13:39 +00:00
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 an 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>&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='hda'/&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;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='ioemu:hda'</span>/&gt;
&lt;/disk&gt;
<span style="color: #0000E5; background-color: #FFFFFF">&lt;graphics type='vnc'/&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 &lt;os&gt; 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 ill extract the boot informations from the boot device specified in
a separate boot element</li>
<li>the &lt;devices&gt; 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</li>
<li>the &lt;devices&gt; 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'</li>
</ul><p>It is likely that the HVM description gets additional elements and
attributes as the support for fully virtualized domain expands especially for
the kind of devices emulated and the graphic 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&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://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>
Reference in New Issue Copy Permalink