source: trunk/packages/xen-3.1/xen-3.1/docs/misc/xen_config.html @ 34

Last change on this file since 34 was 34, checked in by hartmans, 18 years ago

Add xen and xen-common
File size: 6.7 KB
Line 
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<h2>(vnet) element</h2>
141Defines the virtual networks associated with vifs (may go away soon).
142Contains 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),
150one 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>
Note: See TracBrowser for help on using the repository browser.