xen/docs/xen_config.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
  <title>Xen Configuration Syntax</title>
</head>
<body>
<center>
<h1>Xen Configuration Syntax</h1>
<br>
<!-- Version 0.1<br>2004 June 21<br> -->
Version 0.2<br>2004 July 19<br>
</center>

<h1>Xen Configuration</h1>
The Xen virtual machine creation tools provide command-line interfaces and
HTTP interfaces to creating virtual machines. Underneath all these interfaces
virtual machine configuration data is represented in a common configuration syntax
called SXP.

The SXP syntax is s-expressions (sxprs), a simple bracketed abstract syntax.
Python lists are used to represent its parsed form, with a support
api providing  access to fields and values (class xen.xend.sxp).

<h1>SXP syntax</h1>
<p>A general s-expression has the syntax:
<code><pre>
s-exp = '(' s-exp* ')' | atom | string
</pre></code>
Where an <code>atom</code> is an unquoted string, such as fred or /domain/0.
A <code>string</code> is a quoted string, supporting the usual escape sequences.
Strings support single or double quotes: 'fred 1' or "fred 2" are both accepted.
The characters ()[]&lt;&gt{} are separators.

<p>An <code>element</code> is an s-expression representing data similar to XML.
It has the form:
<code><pre>
element    = '(' name attributes? value* ')'
name       = atom
attributes = '(' '@' attribute* ')'
attribute  = '(' attrname attrval ')'
attrname   = atom
attrval    = atom | string
value      = element | atom | string
</pre></code>
The <code>name</code> is the element name (roughly indentifying its type).
The <code>attributes</code> is a list of attribute-values.
We usually prefer to avoid using attributes, and use sub-elements instead.
As in XML, any element may have the attribute <code>id</code> to give it an identifier
for later reference.

<h1>VM configuration</h1>
A vm configuration is a single SXP vm element, with subelements for
vm parameters and devices. The supported elements and their fields
are listed below.

<h2>(vm) element</h2>
The top-level element, a virtual machine configuration.
<ul>
    <li>name: string, required. Domain name.
    <li>id: int, optional, default generated. Domain unique id.
    <li>memory: int, required. Domain memory in MB.
    <li>cpu: int, optional. Cpu to run on.
    <li>image: linux | netbsd | ..., required. Domain image (OS-specific element).
    <li>controller: any device controller type, optional, default none.
    <li>device: any device type, optional, repeats. Device.
    <li>restart: string, optional, default onreboot. Restart mode, one of
        <ul><li>onreboot: restart the domain when it exits with code reboot.
            <li>always: always restart the domain when it exits.
            <li>never:  never restart the domain.
        </ul>
    <li>console: int, optional, default 9600 + domain id. Console port.
</ul>

<h2>(image (linux)) element</h2>
Defines a linux kernel image and its command-line parameters.
<ul>
    <li>kernel: string, required. Kernel image file (absolute path).
    <li>root: string, optional. Root device.
    <li>ip: string, optional. IP address specifier.
    <li>ramdisk: string, optional, default none. Ramdisk file (absolute path).
    <li>args: string, optional. Extra kernel args.
</ul>

<h2>(image (netbsd)) element</h2>
Defines a netbsd kernel image and its command-line parameters.
<ul>
    <li>kernel: string, required. Kernel image file.
    <li>root: string, optional. Root device.
    <li>ip: string, optional. IP address specifier.
    <li>ramdisk: string, optional, default none. Ramdisk file.
    <li>args: string, optional. Extra kernel args.
</ul>

<h2>(backend (blkif)) element</h2>
The vm is a block device backend.
The vm can have pci devices configured, but no virtual
block devices.

<h2>(backend (netif)) element</h2>
The vm is a net device backend.
The domain may not have virtual network interfaces (vifs) configured.

<h2>(device (vif)) element</h2>
Defines a virtual network interface.
<ul>
    <li>mac: string, required. Interface MAC address.
    <li>bridge: string, optional, default system-dependent. Bridge to connect to.
    <li>script: string, optional, default system-dependent. Vif script to use
        when bringing the interface up or down.
    <li>ip: IP address, optional, no default. May be repeated. An IP address
    or CIDR-format subnet the vif may use.
</ul>

<h2>(device (vbd)) element</h2>
Defines a virtual block device.
<ul>
    <li>uname: string, required. Virtual block device id, e.g phys:hda1.
    <li>dev: string, required. Device file name in domain, e.g. xda1.
    <li>mode: string, optional, default r. Read-write mode: r | rw | w.
</ul>
The uname field defines the device being exported from the block device
controller. The dev field defines the device name the vm will see.
The device is read-only unless the mode contains w.

<h2>(device (pci)) element</h2>
Defines a pci device. 
<ul>
    <li>bus: int, required. PCI bus id.
    <li>dev: int, required. PCI dev id.
    <li>func: int, required. PCI func id.
</ul>
The bus, dev or func may be given in hex,
e.g. 0xff. With no leading 0x they are interpreted as decimal.

<h2>(vnet) element</h2>
Defines the virtual networks associated with vifs (may go away soon).
Contains a list of vif elements:
<ul>
  <li>id: id of the vif being configured.
  <li>vnet: id of vnet the vif is assigned to.
</ul>

<h1>Examples</h1>
<p> A vm  with 64 MB memory, root on /dev/xda1 (mapped from /dev/hda1),
one vif with default MAC.
<code><pre>
(vm
    (name xendom1)
    (memory 64)
    (image
        (linux
            (kernel /boot/vmlinuz-2.4.26-xen)
            (ip ::::xendom1:eth0:dhcp)
            (root /dev/xda1)
            (args 'rw fastboot 4')
        )
    )
    (device (vif))
    (device (vbd (uname phy:hda1) (dev xda1) (mode w)))
)
</pre></code>

<p>A vm with 64 MB memory, NFS root, and 2 vifs on separate vnets.
<code><pre>
(vm 
   (name xendom2)
   (memory 64)
    # Define a linux image.
    (image
        (linux 
            (kernel "/boot/vmlinuz-2.4.26-xen")
            (ip     "::::xendom2:eth0:dhcp")
            (root   "/dev/nfs")
            (args   "rw fastboot nfsroot=15.144.25.79:/opt/xen/xendom2 4")
         )
    )
    # Define some vifs, with ids for use later.
    (device (vif (@ (id vif1)) (mac aa:00:00:00:00:12)))
    (device (vif (@ (id vif2)) (mac aa:00:00:00:10:12)))

     # Configure vnets. Refer to vifs by id.
     (vnet (vif (id vif1) (vnet 1))
           (vif (id vif2) (vnet 2)))

)
</pre></code>

</body>
</html>