<html>
  <body>
    <h1>Xen hypervisor driver</h1>

    <ul id="toc"></ul>

    <p>
      The libvirt Xen driver provides the ability to manage virtual machines
      on any Xen release from 3.0.1 onwards.
    </p>

    <h2><a name="prereq">Deployment pre-requisites</a></h2>

    <p>
      The libvirt Xen driver uses a combination of channels to manage Xen
      virtual machines.
    </p>

    <ul>
      <li>
        <strong>XenD</strong>: Access to the Xen daemon is a mandatory
        requirement for the libvirt Xen driver. It requires that the UNIX
        socket interface be enabled in the <code>/etc/xen/xend-config.sxp</code>
        configuration file. Specifically the config settings
        <code>(xend-unix-server yes)</code>. This path is usually restricted
        to only allow the <code>root</code> user access. As an alternative,
        the HTTP interface can be used, however, this has significant security
        implications.
      </li>
      <li>
        <strong>XenStoreD</strong>: Access to the Xenstore daemon enables
        more efficient codepaths for looking up domain information which
        lowers the CPU overhead of management.
      </li>
      <li>
        <strong>Hypercalls</strong>: The ability to make direct hypercalls
        allows the most efficient codepaths in the driver to be used for
        monitoring domain status.
      </li>
      <li>
        <strong>XM config</strong>: When using Xen releases prior to 3.0.4,
        there is no inactive domain management in XenD. For such releases,
        libvirt will automatically process XM configuration files kept in
        the <code>/etc/xen</code> directory. It is important not to place
        any other non-config files in this directory.
      </li>
    </ul>

    <h2><a name="uri">Connections to Xen driver</a></h2>

    <p>
    The libvirt Xen driver is a single-instance privileged driver,
    with a driver name of 'xen'. Some example conection URIs for
    the libvirt driver are:
    </p>

<pre>
xen:///                        (local access, direct)
xen+unix:///                   (local access, via daemon)
xen://example.com/             (remote access, TLS/x509)
xen+tcp://example.com/         (remote access, SASl/Kerberos)
xen+ssh://root@example.com/    (remote access, SSH tunnelled)
</pre>

    <h2><a name="imex">Import and export of libvirt domain XML configs</a></h2>

    <p>The Xen driver currently supports two native
      config formats. The first known as <code>xen-xm</code> is the format
      used by the XM tool for files in <code>/etc/xen</code>. The second
      known as <code>xen-sxpr</code>, is the format used for interacting
      with the XenD's legacy HTTP RPC service.</p>

    <h3><a name="xmlimport">Converting from XM config files to domain XML</a></h3>

    <p>
      The <code>virsh domxml-from-native</code> provides a way to convert an
      existing set of XM config files into a guest description using libvirt Domain XML
      that can then be used by libvirt.
    </p>

    <pre>$ virsh -c xen:/// domxml-from-native xen-xm rhel5.cfg
&lt;domain type='xen'&gt;
  &lt;name&gt;rhel5pv&lt;/name&gt;
  &lt;uuid&gt;8f07fe28-753f-2729-d76d-bdbd892f949a&lt;/uuid&gt;
  &lt;memory&gt;2560000&lt;/memory&gt;
  &lt;currentMemory&gt;307200&lt;/currentMemory&gt;
  &lt;vcpu&gt;4&lt;/vcpu&gt;
  &lt;bootloader&gt;/usr/bin/pygrub&lt;/bootloader&gt;
  &lt;os&gt;
    &lt;type arch='x86_64' machine='xenpv'&gt;linux&lt;/type&gt;
  &lt;/os&gt;
  &lt;clock offset='utc'/&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;
    &lt;disk type='file' device='disk'&gt;
      &lt;driver name='tap' type='aio'/&gt;
      &lt;source file='/var/lib/xen/images/rhel5pv.img'/&gt;
      &lt;target dev='xvda' bus='xen'/&gt;
    &lt;/disk&gt;
    &lt;disk type='file' device='disk'&gt;
      &lt;driver name='tap' type='qcow'/&gt;
      &lt;source file='/root/qcow1-xen.img'/&gt;
      &lt;target dev='xvdd' bus='xen'/&gt;
    &lt;/disk&gt;
    &lt;interface type='bridge'&gt;
      &lt;mac address='00:16:3e:60:36:ba'/&gt;
      &lt;source bridge='xenbr0'/&gt;
    &lt;/interface&gt;
    &lt;console type='pty'&gt;
      &lt;target port='0'/&gt;
    &lt;/console&gt;
    &lt;input type='mouse' bus='xen'/&gt;
    &lt;graphics type='vnc' port='-1' autoport='yes' listen='0.0.0.0'/&gt;
  &lt;/devices&gt;
&lt;/domain&gt;</pre>

    <h3><a name="xmlexport">Converting from domain XML to XM config files</a></h3>

    <p>
      The <code>virsh domxml-to-native</code> provides a way to convert a
      guest description using libvirt Domain XML, into the XM config file
      format.
    </p>

    <pre>$ virsh -c xen:/// domxml-to-native xen-xm rhel5pv.xml
name = "rhel5pv"
uuid = "8f07fe28-753f-2729-d76d-bdbd892f949a"
maxmem = 2500
memory = 300
vcpus = 4
bootloader = "/usr/bin/pygrub"
kernel = "/var/lib/xen/boot_kernel.0YK-cS"
ramdisk = "/var/lib/xen/boot_ramdisk.vWgrxK"
extra = "ro root=/dev/VolGroup00/LogVol00 rhgb quiet"
on_poweroff = "destroy"
on_reboot = "restart"
on_crash = "restart"
sdl = 0
vnc = 1
vncunused = 1
vnclisten = "0.0.0.0"
disk = [ "tap:aio:/var/lib/xen/images/rhel5pv.img,xvda,w", "tap:qcow:/root/qcow1-xen.img,xvdd,w" ]
vif = [ "mac=00:16:3e:60:36:ba,bridge=virbr0,script=vif-bridge,vifname=vif5.0" ]</pre>

    <h2><a name="xmlconfig">Example domain XML config</a></h2>

    <p>
      Below are some example XML configurations for Xen guest domains.
      For full details of the available options, consult the <a href="formatdomain.html">domain XML format</a>
      guide.
    </p>

    <h3>Paravirtualized guest bootloader</h3>

    <p>
      Using a bootloader allows a paravirtualized guest to be booted using
      a kernel stored inside its virtual disk image
    </p>

        <pre>&lt;domain type='xen' &gt;
  &lt;name&gt;fc8&lt;/name&gt;
  &lt;bootloader&gt;/usr/bin/pygrub&lt;/bootloader&gt;
  &lt;os&gt;
    &lt;type&gt;linux&lt;/type&gt;
  &lt;/os&gt;
  &lt;memory&gt;131072&lt;/memory&gt;
  &lt;vcpu&gt;1&lt;/vcpu&gt;
  &lt;devices&gt;
    &lt;disk type='file'&gt;
      &lt;source file='/var/lib/xen/images/fc4.img'/&gt;
      &lt;target dev='sda1'/&gt;
    &lt;/disk&gt;
    &lt;interface type='bridge'&gt;
      &lt;source bridge='xenbr0'/&gt;
      &lt;mac address='aa:00:00:00:00:11'/&gt;
      &lt;script path='/etc/xen/scripts/vif-bridge'/&gt;
    &lt;/interface&gt;
    &lt;console tty='/dev/pts/5'/&gt;
  &lt;/devices&gt;
&lt;/domain&gt;</pre>

    <h3>Paravirtualized guest direct kernel boot</h3>

    <p>
      For installation of paravirtualized guests it is typical to boot the
      domain using a kernel and initrd stored in the host OS
    </p>

        <pre>&lt;domain type='xen' &gt;
  &lt;name&gt;fc8&lt;/name&gt;
  &lt;os&gt;
    &lt;type&gt;linux&lt;/type&gt;
    &lt;kernel&gt;/var/lib/xen/install/vmlinuz-fedora8-x86_64&lt;/kernel&gt;
    &lt;initrd&gt;/var/lib/xen/install/initrd-vmlinuz-fedora8-x86_64&lt;/initrd&gt;
    &lt;cmdline&gt; kickstart=http://example.com/myguest.ks &lt;/cmdline&gt;
  &lt;/os&gt;
  &lt;memory&gt;131072&lt;/memory&gt;
  &lt;vcpu&gt;1&lt;/vcpu&gt;
  &lt;devices&gt;
    &lt;disk type='file'&gt;
      &lt;source file='/var/lib/xen/images/fc4.img'/&gt;
      &lt;target dev='sda1'/&gt;
    &lt;/disk&gt;
    &lt;interface type='bridge'&gt;
      &lt;source bridge='xenbr0'/&gt;
      &lt;mac address='aa:00:00:00:00:11'/&gt;
      &lt;script path='/etc/xen/scripts/vif-bridge'/&gt;
    &lt;/interface&gt;
    &lt;graphics type='vnc' port='-1'/&gt;
    &lt;console tty='/dev/pts/5'/&gt;
  &lt;/devices&gt;
&lt;/domain&gt;</pre>

    <h3>Fullyvirtualized guest BIOS boot</h3>

    <p>
      Fullyvirtualized guests use the emulated BIOS to boot off the primary
      harddisk, CDROM or Network PXE ROM.
    </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;
    &lt;type&gt;hvm&lt;/type&gt;
    &lt;loader&gt;/usr/lib/xen/boot/hvmloader&lt;/loader&gt;
    &lt;boot dev='hd'/&gt;
  &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;features&gt;
    &lt;pae/&gt;
    &lt;acpi/&gt;
    &lt;apic/&gt;
  &lt;/features&gt;
  &lt;clock sync="localtime"/&gt;
  &lt;devices&gt;
    &lt;emulator&gt;/usr/lib/xen/bin/qemu-dm&lt;/emulator&gt;
    &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='/var/lib/xen/images/fv0'/&gt;
      &lt;target dev='hda'/&gt;
    &lt;/disk&gt;
    &lt;disk type='file' device='cdrom'&gt;
      &lt;source file='/var/lib/xen/images/fc5-x86_64-boot.iso'/&gt;
      &lt;target dev='hdc'/&gt;
      &lt;readonly/&gt;
    &lt;/disk&gt;
    &lt;disk type='file' device='floppy'&gt;
      &lt;source file='/root/fd.img'/&gt;
      &lt;target dev='fda'/&gt;
    &lt;/disk&gt;
    &lt;graphics type='vnc' port='5904'/&gt;
  &lt;/devices&gt;
&lt;/domain&gt;</pre>

    <h3>Fullyvirtualized guest direct kernel boot</h3>

    <p>
      With Xen 3.2.0 or later it is possible to bypass the BIOS and directly
      boot a Linux kernel and initrd as a fullyvirtualized domain. This allows
      for complete automation of OS installation, for example using the Anaconda
      kickstart support.
    </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;
    &lt;type&gt;hvm&lt;/type&gt;
    &lt;loader&gt;/usr/lib/xen/boot/hvmloader&lt;/loader&gt;
    &lt;kernel&gt;/var/lib/xen/install/vmlinuz-fedora8-x86_64&lt;/kernel&gt;
    &lt;initrd&gt;/var/lib/xen/install/initrd-vmlinuz-fedora8-x86_64&lt;/initrd&gt;
    &lt;cmdline&gt; kickstart=http://example.com/myguest.ks &lt;/cmdline&gt;
  &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;features&gt;
    &lt;pae/&gt;
    &lt;acpi/&gt;
    &lt;apic/&gt;
  &lt;/features&gt;
  &lt;clock sync="localtime"/&gt;
  &lt;devices&gt;
    &lt;emulator&gt;/usr/lib/xen/bin/qemu-dm&lt;/emulator&gt;
    &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='/var/lib/xen/images/fv0'/&gt;
      &lt;target dev='hda'/&gt;
    &lt;/disk&gt;
    &lt;disk type='file' device='cdrom'&gt;
      &lt;source file='/var/lib/xen/images/fc5-x86_64-boot.iso'/&gt;
      &lt;target dev='hdc'/&gt;
      &lt;readonly/&gt;
    &lt;/disk&gt;
    &lt;disk type='file' device='floppy'&gt;
      &lt;source file='/root/fd.img'/&gt;
      &lt;target dev='fda'/&gt;
    &lt;/disk&gt;
    &lt;graphics type='vnc' port='5904'/&gt;
  &lt;/devices&gt;
&lt;/domain&gt;</pre>

  </body>
</html>
