1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4  <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
5  <title>Xen Configuration Syntax</title>
6</head>
7<body>
8<center>
9<h1>Xen Configuration Syntax</h1>
10<br>
11<!-- Version 0.1<br>2004 June 21<br> -->
12Version 0.2<br>2004 July 19<br>
13</center>
14
15<h1>Xen Configuration</h1>
16The Xen virtual machine creation tools provide command-line interfaces and
17HTTP interfaces to creating virtual machines. Underneath all these interfaces
18virtual machine configuration data is represented in a common configuration syntax
19called SXP.
20
21The SXP syntax is s-expressions (sxprs), a simple bracketed abstract syntax.
22Python lists are used to represent its parsed form, with a support
23api providing  access to fields and values (class xen.xend.sxp).
24
25<h1>SXP syntax</h1>
26<p>A general s-expression has the syntax:
27<code><pre>
28s-exp = '(' s-exp* ')' | atom | string
29</pre></code>
30Where an <code>atom</code> is an unquoted string, such as fred or /domain/0.
31A <code>string</code> is a quoted string, supporting the usual escape sequences.
32Strings support single or double quotes: 'fred 1' or "fred 2" are both accepted.
33The characters ()[]&lt;&gt{} are separators.
34
35<p>An <code>element</code> is an s-expression representing data similar to XML.
36It has the form:
37<code><pre>
38element    = '(' name attributes? value* ')'
39name       = atom
40attributes = '(' '@' attribute* ')'
41attribute  = '(' attrname attrval ')'
42attrname   = atom
43attrval    = atom | string
44value      = element | atom | string
45</pre></code>
46The <code>name</code> is the element name (roughly indentifying its type).
47The <code>attributes</code> is a list of attribute-values.
48We usually prefer to avoid using attributes, and use sub-elements instead.
49As in XML, any element may have the attribute <code>id</code> to give it an identifier
50for later reference.
51
52<h1>VM configuration</h1>
53A vm configuration is a single SXP vm element, with subelements for
54vm parameters and devices. The supported elements and their fields
55are listed below.
56
57<h2>(vm) element</h2>
58The top-level element, a virtual machine configuration.
59<ul>
60    <li>name: string, required. Domain name.
61    <li>id: int, optional, default generated. Domain unique id.
62    <li>memory: int, required. Domain memory in MB.
63    <li>maxmem: int, optional. Maximum domain memory in MB.
64    <li>cpu: int, optional. Cpu to run on.
65    <li>cpu_weight, float, optional, default 1. Cpu weight - controls share of CPU.
66    <li>image: linux | netbsd | ..., required. Domain image (OS-specific element).
67    <li>backend: any backend device type, optional, default none.
68    <li>device: any device type, optional, repeats. Device.
69    <li>restart: string, optional, default onreboot. Restart mode, one of
70        <ul><li>onreboot: restart the domain when it exits with code reboot.
71            <li>always: always restart the domain when it exits.
72            <li>never:  never restart the domain.
73        </ul>
74    <li>console: int, optional, default 9600 + domain id. Console port.
75</ul>
76
77<h2>(image (linux)) element</h2>
78Defines a linux kernel image and its command-line parameters.
79<ul>
80    <li>kernel: string, required. Kernel image file (absolute path).
81    <li>root: string, optional. Root device.
82    <li>ip: string, optional. IP address specifier.
83    <li>ramdisk: string, optional, default none. Ramdisk file (absolute path).
84    <li>args: string, optional. Extra kernel args.
85</ul>
86
87<h2>(image (netbsd)) element</h2>
88Defines a netbsd kernel image and its command-line parameters.
89<ul>
90    <li>kernel: string, required. Kernel image file.
91    <li>root: string, optional. Root device.
92    <li>ip: string, optional. IP address specifier.
93    <li>ramdisk: string, optional, default none. Ramdisk file.
94    <li>args: string, optional. Extra kernel args.
95</ul>
96
97<h2>(backend (blkif)) element</h2>
98The vm is a block device backend.
99The vm can have pci devices configured.
100
101<h2>(backend (netif)) element</h2>
102The vm is a net device backend.
103
104<h2>(device (vif)) element</h2>
105Defines a virtual network interface.
106<ul>
107    <li>mac: string, required. Interface MAC address.
108    <li>bridge: string, optional, default system-dependent. Bridge to connect to.
109    <li>script: string, optional, default system-dependent. Vif script to use
110        when bringing the interface up or down.
111    <li>ip: IP address, optional, no default. May be repeated. An IP address
112    or CIDR-format subnet the vif may use.
113    <li>backend: domain name or id, optional, default 0.
114    Defines the domain to use as  the backend for the interface.
115</ul>
116
117<h2>(device (vbd)) element</h2>
118Defines a virtual block device.
119<ul>
120    <li>uname: string, required. Virtual block device id, e.g phys:hda1.
121    <li>dev: string, required. Device file name in domain, e.g. xda1.
122    <li>mode: string, optional, default r. Read-write mode: r | rw | w.
123    <li>backend: domain name or id, optional, default 0.
124     Defines the domain to use as the backend for the device.
125</ul>
126The uname field defines the device being exported from the block device
127controller. The dev field defines the device name the vm will see.
128The device is read-only unless the mode contains w.
129
130<h2>(device (pci)) element</h2>
131Defines a pci device.
132<ul>
133    <li>bus: int, required. PCI bus id.
134    <li>dev: int, required. PCI dev id.
135    <li>func: int, required. PCI func id.
136</ul>
137The bus, dev or func may be given in hex,
138e.g. 0xff. With no leading 0x they are interpreted as decimal.
139
140<h1>Examples</h1>
141<p> A vm  with 64 MB memory, root on /dev/xda1 (mapped from /dev/hda1),
142one vif with default MAC.
143<code><pre>
144(vm
145    (name xendom1)
146    (memory 64)
147    (image
148        (linux
149            (kernel /boot/vmlinuz-2.6.12-xen)
150            (ip ::::xendom1:eth0:dhcp)
151            (root /dev/xda1)
152            (args 'rw fastboot 4')
153        )
154    )
155    (device (vif))
156    (device (vbd (uname phy:hda1) (dev xda1) (mode w)))
157)
158</pre></code>
159
160</body>
161</html>
162