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> --> |
---|
12 | Version 0.2<br>2004 July 19<br> |
---|
13 | </center> |
---|
14 | |
---|
15 | <h1>Xen Configuration</h1> |
---|
16 | The Xen virtual machine creation tools provide command-line interfaces and |
---|
17 | HTTP interfaces to creating virtual machines. Underneath all these interfaces |
---|
18 | virtual machine configuration data is represented in a common configuration syntax |
---|
19 | called SXP. |
---|
20 | |
---|
21 | The SXP syntax is s-expressions (sxprs), a simple bracketed abstract syntax. |
---|
22 | Python lists are used to represent its parsed form, with a support |
---|
23 | api 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> |
---|
28 | s-exp = '(' s-exp* ')' | atom | string |
---|
29 | </pre></code> |
---|
30 | Where an <code>atom</code> is an unquoted string, such as fred or /domain/0. |
---|
31 | A <code>string</code> is a quoted string, supporting the usual escape sequences. |
---|
32 | Strings support single or double quotes: 'fred 1' or "fred 2" are both accepted. |
---|
33 | The characters ()[]<>{} are separators. |
---|
34 | |
---|
35 | <p>An <code>element</code> is an s-expression representing data similar to XML. |
---|
36 | It has the form: |
---|
37 | <code><pre> |
---|
38 | element = '(' name attributes? value* ')' |
---|
39 | name = atom |
---|
40 | attributes = '(' '@' attribute* ')' |
---|
41 | attribute = '(' attrname attrval ')' |
---|
42 | attrname = atom |
---|
43 | attrval = atom | string |
---|
44 | value = element | atom | string |
---|
45 | </pre></code> |
---|
46 | The <code>name</code> is the element name (roughly indentifying its type). |
---|
47 | The <code>attributes</code> is a list of attribute-values. |
---|
48 | We usually prefer to avoid using attributes, and use sub-elements instead. |
---|
49 | As in XML, any element may have the attribute <code>id</code> to give it an identifier |
---|
50 | for later reference. |
---|
51 | |
---|
52 | <h1>VM configuration</h1> |
---|
53 | A vm configuration is a single SXP vm element, with subelements for |
---|
54 | vm parameters and devices. The supported elements and their fields |
---|
55 | are listed below. |
---|
56 | |
---|
57 | <h2>(vm) element</h2> |
---|
58 | The 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> |
---|
78 | Defines 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> |
---|
88 | Defines 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> |
---|
98 | The vm is a block device backend. |
---|
99 | The vm can have pci devices configured. |
---|
100 | |
---|
101 | <h2>(backend (netif)) element</h2> |
---|
102 | The vm is a net device backend. |
---|
103 | |
---|
104 | <h2>(device (vif)) element</h2> |
---|
105 | Defines 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> |
---|
118 | Defines 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> |
---|
126 | The uname field defines the device being exported from the block device |
---|
127 | controller. The dev field defines the device name the vm will see. |
---|
128 | The device is read-only unless the mode contains w. |
---|
129 | |
---|
130 | <h2>(device (pci)) element</h2> |
---|
131 | Defines 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> |
---|
137 | The bus, dev or func may be given in hex, |
---|
138 | e.g. 0xff. With no leading 0x they are interpreted as decimal. |
---|
139 | |
---|
140 | <h2>(vnet) element</h2> |
---|
141 | Defines the virtual networks associated with vifs (may go away soon). |
---|
142 | Contains a list of vif elements: |
---|
143 | <ul> |
---|
144 | <li>id: id of the vif being configured. |
---|
145 | <li>vnet: id of vnet the vif is assigned to. |
---|
146 | </ul> |
---|
147 | |
---|
148 | <h1>Examples</h1> |
---|
149 | <p> A vm with 64 MB memory, root on /dev/xda1 (mapped from /dev/hda1), |
---|
150 | one vif with default MAC. |
---|
151 | <code><pre> |
---|
152 | (vm |
---|
153 | (name xendom1) |
---|
154 | (memory 64) |
---|
155 | (image |
---|
156 | (linux |
---|
157 | (kernel /boot/vmlinuz-2.6.12-xen) |
---|
158 | (ip ::::xendom1:eth0:dhcp) |
---|
159 | (root /dev/xda1) |
---|
160 | (args 'rw fastboot 4') |
---|
161 | ) |
---|
162 | ) |
---|
163 | (device (vif)) |
---|
164 | (device (vbd (uname phy:hda1) (dev xda1) (mode w))) |
---|
165 | ) |
---|
166 | </pre></code> |
---|
167 | |
---|
168 | <p>A vm with 64 MB memory, NFS root, and 2 vifs on separate vnets. |
---|
169 | <code><pre> |
---|
170 | (vm |
---|
171 | (name xendom2) |
---|
172 | (memory 64) |
---|
173 | # Define a linux image. |
---|
174 | (image |
---|
175 | (linux |
---|
176 | (kernel "/boot/vmlinuz-2.4.26-xen") |
---|
177 | (ip "::::xendom2:eth0:dhcp") |
---|
178 | (root "/dev/nfs") |
---|
179 | (args "rw fastboot nfsroot=15.144.25.79:/opt/xen/xendom2 4") |
---|
180 | ) |
---|
181 | ) |
---|
182 | # Define some vifs, with ids for use later. |
---|
183 | (device (vif (@ (id vif1)) (mac aa:00:00:00:00:12))) |
---|
184 | (device (vif (@ (id vif2)) (mac aa:00:00:00:10:12))) |
---|
185 | |
---|
186 | # Configure vnets. Refer to vifs by id. |
---|
187 | (vnet (vif (id vif1) (vnet 1)) |
---|
188 | (vif (id vif2) (vnet 2))) |
---|
189 | |
---|
190 | ) |
---|
191 | </pre></code> |
---|
192 | |
---|
193 | </body> |
---|
194 | </html> |
---|