XML Format

The library use an XML format to describe domains, as input to virDomainCreateLinux() and as the output of virDomainGetXMLDesc(), the following is an example of the format as returned by the shell command virsh xmldump fc4 , where fc4 was one of the running domains:

<domain type='xen' id='18'>
  <name>fc4</name>
  <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>
  <memory>131072</memory>
  <vcpu>1</vcpu>
  <devices>
    <disk type='file'>
      <source file='/u/fc4.img'/>
      <target dev='sda1'/>
    </disk>
    <interface type='bridge'>
      <source bridge='xenbr0'/>
      <mac address='aa:00:00:00:00:11'/>
      <script path='/etc/xen/scripts/vif-bridge'/>
    </interface>
  </devices>
</domain>

The root element must be called domain with no namespace, the type attribute indicates the kind of hypervisor used, 'xen' is the default value. The id 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:

• name: the domain name, preferably ASCII based
• memory: the maximum memory allocated to the domain in kilobytes
• vcpu: the number of virtual cpu configured for the domain
• os: a block describing the Operating System, its content will be dependant on the OS type
  • type: indicate the OS type, always linux at this point
  • kernel: path to the kernel on the Domain 0 filesystem
  • initrd: an optional path for the init ramdisk on the Domain 0 filesystem
  • cmdline: optional command line to the kernel
  • root: the root filesystem from the guest viewpoint, it may be passed as part of the cmdline content too
• devices: a list of disk and interface descriptions in no special order

The format of the devices and their type may grow over time, but the following should be sufficient for basic use:

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:

• 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')
• target indicates in a dev attribute the device where it is mapped in the guest
• readonly an optional empty element indicating the device is read-only

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:

• source: indicating the bridge name
• mac: the optional mac address provided in the address attribute
• ip: the optional IP address provided in the address attribute
• script: the script used to bridge the interfcae in the Domain 0
• target: and optional target indicating the device name.

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:

• destroy: The domain is cleaned up (that's the default normal processing in Xen)
• restart: A new domain is started in place of the old one with the same configuration parameters
• preserve: The domain will remain in memory until it is destroyed manually, it won't be running but allows for post-mortem debugging
• rename-restart: a variant of the previous one but where the old domain is renamed before being saved to allow a restart

The following could be used for a Xen production system:

<domain>
  ...
  <on_reboot>restart</on_reboot>
  <on_poweroff>destroy</on_poweroff>
  <on_crash>rename-restart</on_crash>
  ...
</domain>

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.