<!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 ()[]<>{} 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>maxmem: int, optional. Maximum domain memory in MB.
<li>cpu: int, optional. Cpu to run on.
<li>cpu_weight, float, optional, default 1. Cpu weight - controls share of CPU.
<li>image: linux | netbsd | ..., required. Domain image (OS-specific element).
<li>backend: any backend device 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.
<h2>(backend (netif)) element</h2>
The vm is a net device backend.
<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.
<li>backend: domain name or id, optional, default 0.
Defines the domain to use as the backend for the interface.
</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.
<li>backend: domain name or id, optional, default 0.
Defines the domain to use as the backend for the device.
</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.
<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.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)))
)
</pre></code>
</body>
</html>