Xen Configuration Syntax

Version 0.2
2004 July 19

Xen Configuration

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).

SXP syntax

A general s-expression has the syntax:

s-exp = '(' s-exp* ')' | atom | string

Where an atom is an unquoted string, such as fred or /domain/0. A string 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 ()[]<>{} are separators.

An element is an s-expression representing data similar to XML. It has the form:

element    = '(' name attributes? value* ')'
name       = atom
attributes = '(' '@' attribute* ')'
attribute  = '(' attrname attrval ')'
attrname   = atom
attrval    = atom | string
value      = element | atom | string

The name is the element name (roughly indentifying its type). The attributes 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 id to give it an identifier for later reference.

VM configuration

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.

(vm) element

The top-level element, a virtual machine configuration.

name: string, required. Domain name.
id: int, optional, default generated. Domain unique id.
memory: int, required. Domain memory in MB.
maxmem: int, optional. Maximum domain memory in MB.
cpu: int, optional. Cpu to run on.
cpu_weight, float, optional, default 1. Cpu weight - controls share of CPU.
image: linux | netbsd | ..., required. Domain image (OS-specific element).
backend: any backend device type, optional, default none.
device: any device type, optional, repeats. Device.
restart: string, optional, default onreboot. Restart mode, one of
- onreboot: restart the domain when it exits with code reboot.
- always: always restart the domain when it exits.
- never: never restart the domain.
console: int, optional, default 9600 + domain id. Console port.

(image (linux)) element

Defines a linux kernel image and its command-line parameters.

kernel: string, required. Kernel image file (absolute path).
root: string, optional. Root device.
ip: string, optional. IP address specifier.
ramdisk: string, optional, default none. Ramdisk file (absolute path).
args: string, optional. Extra kernel args.

(image (netbsd)) element

Defines a netbsd kernel image and its command-line parameters.

kernel: string, required. Kernel image file.
root: string, optional. Root device.
ip: string, optional. IP address specifier.
ramdisk: string, optional, default none. Ramdisk file.
args: string, optional. Extra kernel args.

(backend (blkif)) element

The vm is a block device backend. The vm can have pci devices configured.

(backend (netif)) element

The vm is a net device backend.

(device (vif)) element

Defines a virtual network interface.

mac: string, required. Interface MAC address.
bridge: string, optional, default system-dependent. Bridge to connect to.
script: string, optional, default system-dependent. Vif script to use when bringing the interface up or down.
ip: IP address, optional, no default. May be repeated. An IP address or CIDR-format subnet the vif may use.
backend: domain name or id, optional, default 0. Defines the domain to use as the backend for the interface.

(device (vbd)) element

Defines a virtual block device.

uname: string, required. Virtual block device id, e.g phys:hda1.
dev: string, required. Device file name in domain, e.g. xda1.
mode: string, optional, default r. Read-write mode: r | rw | w.
backend: domain name or id, optional, default 0. Defines the domain to use as the backend for the device.

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.

(device (pci)) element

Defines a pci device.

bus: int, required. PCI bus id.
dev: int, required. PCI dev id.
func: int, required. PCI func id.

The bus, dev or func may be given in hex, e.g. 0xff. With no leading 0x they are interpreted as decimal.

(vnet) element

Defines the virtual networks associated with vifs (may go away soon). Contains a list of vif elements:

id: id of the vif being configured.
vnet: id of vnet the vif is assigned to.

Examples

A vm with 64 MB memory, root on /dev/xda1 (mapped from /dev/hda1), one vif with default MAC.

(vm
    (name xendom1)
    (memory 64)
    (image
        (linux
            (kernel /boot/vmlinuz-2.6.12-xen)
            (ip ::::xendom1:eth0:dhcp)
            (root /dev/xda1)
            (args 'rw fastboot 4')
        )
    )
    (device (vif))
    (device (vbd (uname phy:hda1) (dev xda1) (mode w)))
)

A vm with 64 MB memory, NFS root, and 2 vifs on separate vnets.

(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)))

)