ia64/xen-unstable

view docs/xen_config.html @ 2006:bd310c8b4b5c

bitkeeper revision 1.1108.43.1 (410a5973b_ww-XNociMt5BotV87vBQ)

Tweaks.
author mwilli2@equilibrium.research.intel-research.net
date Fri Jul 30 14:21:39 2004 +0000 (2004-07-30)
parents dcfb8f179d72
children dae98734f12e
line source
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>
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.
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).
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 ()[]&lt;&gt{} are separators.
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.
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.
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>cpu: int, optional. Cpu to run on.
64 <li>image: linux | netbsd | ..., required. Domain image (OS-specific element).
65 <li>controller: any device controller type, optional, default none.
66 <li>device: any device type, optional, repeats. Device.
67 <li>restart: string, optional, default onreboot. Restart mode, one of
68 <ul><li>onreboot: restart the domain when it exits with code reboot.
69 <li>always: always restart the domain when it exits.
70 <li>never: never restart the domain.
71 </ul>
72 <li>console: int, optional, default 9600 + domain id. Console port.
73 </ul>
75 <h2>(image (linux)) element</h2>
76 Defines a linux kernel image and its command-line parameters.
77 <ul>
78 <li>kernel: string, required. Kernel image file (absolute path).
79 <li>root: string, optional. Root device.
80 <li>ip: string, optional. IP address specifier.
81 <li>ramdisk: string, optional, default none. Ramdisk file (absolute path).
82 <li>args: string, optional. Extra kernel args.
83 </ul>
85 <h2>(image (netbsd)) element</h2>
86 Defines a netbsd kernel image and its command-line parameters.
87 <ul>
88 <li>kernel: string, required. Kernel image file.
89 <li>root: string, optional. Root device.
90 <li>ip: string, optional. IP address specifier.
91 <li>ramdisk: string, optional, default none. Ramdisk file.
92 <li>args: string, optional. Extra kernel args.
93 </ul>
95 <h2>(backend (blkif)) element</h2>
96 The vm is a block device backend.
97 The vm can have pci devices configured, but no virtual
98 block devices.
100 <h2>(backend (netif)) element</h2>
101 The vm is a net device backend.
102 The domain may not have virtual network interfaces (vifs) configured.
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 </ul>
115 <h2>(device (vbd)) element</h2>
116 Defines a virtual block device.
117 <ul>
118 <li>uname: string, required. Virtual block device id, e.g phys:hda1.
119 <li>dev: string, required. Device file name in domain, e.g. xda1.
120 <li>mode: string, optional, default r. Read-write mode: r | rw | w.
121 </ul>
122 The uname field defines the device being exported from the block device
123 controller. The dev field defines the device name the vm will see.
124 The device is read-only unless the mode contains w.
126 <h2>(device (pci)) element</h2>
127 Defines a pci device.
128 <ul>
129 <li>bus: int, required. PCI bus id.
130 <li>dev: int, required. PCI dev id.
131 <li>func: int, required. PCI func id.
132 </ul>
133 The bus, dev or func may be given in hex,
134 e.g. 0xff. With no leading 0x they are interpreted as decimal.
136 <h2>(vnet) element</h2>
137 Defines the virtual networks associated with vifs (may go away soon).
138 Contains a list of vif elements:
139 <ul>
140 <li>id: id of the vif being configured.
141 <li>vnet: id of vnet the vif is assigned to.
142 </ul>
144 <h1>Examples</h1>
145 <p> A vm with 64 MB memory, root on /dev/xda1 (mapped from /dev/hda1),
146 one vif with default MAC.
147 <code><pre>
148 (vm
149 (name xendom1)
150 (memory 64)
151 (image
152 (linux
153 (kernel /boot/vmlinuz-2.4.26-xen)
154 (ip ::::xendom1:eth0:dhcp)
155 (root /dev/xda1)
156 (args 'rw fastboot 4')
157 )
158 )
159 (device (vif))
160 (device (vbd (uname phy:hda1) (dev xda1) (mode w)))
161 )
162 </pre></code>
164 <p>A vm with 64 MB memory, NFS root, and 2 vifs on separate vnets.
165 <code><pre>
166 (vm
167 (name xendom2)
168 (memory 64)
169 # Define a linux image.
170 (image
171 (linux
172 (kernel "/boot/vmlinuz-2.4.26-xen")
173 (ip "::::xendom2:eth0:dhcp")
174 (root "/dev/nfs")
175 (args "rw fastboot nfsroot=15.144.25.79:/opt/xen/xendom2 4")
176 )
177 )
178 # Define some vifs, with ids for use later.
179 (device (vif (@ (id vif1)) (mac aa:00:00:00:00:12)))
180 (device (vif (@ (id vif2)) (mac aa:00:00:00:10:12)))
182 # Configure vnets. Refer to vifs by id.
183 (vnet (vif (id vif1) (vnet 1))
184 (vif (id vif2) (vnet 2)))
186 )
187 </pre></code>
189 </body>
190 </html>