diff options
Diffstat (limited to 'docs/format.html')
| -rw-r--r-- | docs/format.html | 197 |
1 files changed, 97 insertions, 100 deletions
diff --git a/docs/format.html b/docs/format.html index d1204e2b2..21a8d96f4 100644 --- a/docs/format.html +++ b/docs/format.html @@ -1,20 +1,19 @@ <?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 Formats</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">XML Formats</h1><p>This section describes the XML formats used mostly to represent domains, -there are variations on the format based on the kind of domains run and the -options used to launch them:</p><ul><li><a href="#Normal1">Normal paravirtualized Xen domains</a></li> +<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><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="#Net1">Networking options for QEmu and KVM</a></li> <li><a href="#QEmu1">QEmu domains</a></li> <li><a href="#Capa1">Discovering virtualization capabilities</a></li> </ul><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 -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>> +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> @@ -37,72 +36,70 @@ domains:</p><pre><domain type='xen' <span style="color: #0071FF; background-c </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> +</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 - bedependant on the OS type + <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 - 0filesystem</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 bepassed - as part of the cmdline content too</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 -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>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 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>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 -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'> +</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> @@ -142,49 +139,49 @@ operatingsystems:</p><pre><domain type='xen' id='3'> </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> +</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, 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> + <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 - 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> + <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 - 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 <a href="http://kvm.qumranet.com/">KVM virtualization</a> + 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><h3><a name="KVM1" id="KVM1">KVM domain (added in 0.2.0)</a></h3><p>Support for the <a href="http://kvm.qumranet.com/">KVM virtualization</a> 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 @@ -415,4 +412,4 @@ Xen support, you will see the os_type of xen to indicate a paravirtual kernel, then architecture informations and potential features.</p><p>The third block (in green) gives similar informations but when running a 32 bit OS fully virtualized with Xen using the hvm support.</p><p>This section is likely to be updated and augmented in the future, see <a href="https://www.redhat.com/archives/libvir-list/2007-March/msg00215.html">the discussion</a> which led to the capabilities format in the mailing-list -archives.</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 Formats</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> +archives.</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> |