1xmdomain.cfg(5) Xen xmdomain.cfg(5)
2
6 xmdomain.cfg - xm domain config file format
7
9 /etc/xen/myxendomain
10 /etc/xen/myxendomain2
11 /etc/xen/auto/myxenautostarted
12
14 The xm(1) program uses python executable config files to define domains
15 to create from scratch. Each of these config files needs to contain a
16 number of required options, and may specify many more.
17 Domain configuration files live in /etc/xen by default, if you store
19 config files anywhere else the full path to the config file must be
20 specified in the xm create command.
21 /etc/xen/auto is a special case. Domain config files in that directory
23 will be started automatically at system boot if the xendomain init
24 script is enabled. The contents of /etc/xen/auto should be symlinks to
25 files in /etc/xen to allow xm create to be used without full paths.
26 Options are specified by name = value statements in the xmdomain.cfg
28 files.
29
31 The following lists the most commonly used options for a domain config
32 file.
33 kernel
35 The kernel image for the domain. The format of the parameter is
36 the fully qualified path to the kernel image file, i.e.
37 /boot/vmlinuz-2.6.12-xenU.
38 ramdisk
40 The initial ramdisk for the domain. The format of the parameter is
41 the fully qualified path to the initrd, i.e. /boot/initrd.gz. On
42 many Linux distros you will not need a ramdisk if using the default
43 xen kernel.
44 memory
46 The amount of RAM, in megabytes, to allocate to the domain when it
47 starts. Allocating insufficient memory for a domain may produce
48 extremely bizarre behavior. If there isn't enough free memory left
49 on the machine to fulfill this request, the domain will fail to
50 start.
51 Xen does not support overcommit of memory, so the total memory of
53 all guests (+ 64 MB needed for Xen) must be less than or equal to
54 the physical RAM in the machine.
55 name
57 A unique name for the domain. Attempting to create two domains
58 with the same name will cause an error.
59 root
61 Specifies the root device for the domain. This is required for
62 Linux domains, and possibly other OSes.
63 nics
65 The number of network interfaces allocated to the domain on boot.
66 It defaults to 1.
67 disk
69 An array of block device stanzas, in the form:
70 disk = [ "stanza1", "stanza2", ... ]
72 Each stanza has 3 terms, separated by commas,
74 "backend-dev,frontend-dev,mode".
75 backend-dev
77 The device in the backend domain that will be exported to the
78 guest (frontend) domain. Supported formats include:
79 phy:device - export the physical device listed. The device can
81 be in symbolic form, as in sda7, or as the hex major/minor
82 number, as in 0x301 (which is hda1).
83 file://path/to/file - export the file listed as a loopback
85 device. This will take care of the loopback setup before
86 exporting the device.
87 frontend-dev
89 How the device should appear in the guest domain. The device
90 can be in symbolic form, as in sda7, or as the hex major/minor
91 number, as in 0x301 (which is hda1).
92 mode
94 The access mode for the device. There are currently 2 valid
95 options, r (read-only), w (read/write).
96 vif An array of virtual interface stanzas in the form:
98 vif = [ "stanza1", "stanza2", ... ]
100 Each stanza specifies a set of name = value options separated by
102 commas, in the form: "name1=value1, name2=value2, ..."
103 OPTIONS
105 bridge
107 The network bridge to be used for this device. This is
108 especially needed if multiple bridges exist on the machine.
109 mac The MAC address for the virtual interface. If mac is not
111 specified, one will be randomly chosen by xen with the 00:16:3e
112 vendor id prefix.
113 vfb A virtual frame buffer stanza in the form:
115 vfb = [ "stanza" ]
117 The stanza specifies a set of name = value options separated by
119 commas, in the form: "name1=value1, name2=value2, ..."
120 OPTIONS
122 type
124 There are currently two valid options: vnc starts a VNC server
125 that lets you connect an external VNC viewer, and sdl starts an
126 internal viewer.
127 vncdisplay
129 The VNC display number to use, defaults to the domain ID. The
130 VNC server listens on port 5900 + display number.
131 vnclisten
133 The listening address for the VNC server, default 127.0.0.1.
134 vncunused
136 If non-zero, the VNC server listens on the first unused port
137 above 5900.
138 vncpasswd
140 Overrides the XenD configured default password.
141 display
143 Display to use for the internal viewer, defaults to environment
144 variable DISPLAY.
145 xauthority
147 Authority file to use for the internal viewer, defaults to
148 environment variable XAUTHORITY.
149
151 The following options are also supported in the config file, though are
152 far more rarely used.
153 builder
155 Which builder should be used to construct the domain. This
156 defaults to the linux if not specified, which is the builder for
157 paravirtualized Linux domains.
158 cpu Specifies which CPU the domain should be started on, where 0
160 specifies the first cpu, 1 the second, and so on. This defaults to
161 -1, which means Xen is free to pick which CPU to start on.
162 cpus
164 Specifies a list of CPUs on which the domains' VCPUs are allowed to
165 execute upon. The syntax supports ranges (0-3), and negation, ^1.
166 For instance:
167 cpus = "0-3,5,^1"
169 Will result in CPUs 0, 2, 3, 5 being available for use by the
171 domain.
172 extra
174 Extra information to append to the end of the kernel parameter
175 line. The format is a string, the contents of which can be
176 anything that the kernel supports. For instance:
177 extra = "4"
179 Will cause the domain to boot to runlevel 4.
181 nfs_server
183 The IP address of the NFS server to use as the root device for the
184 domain. In order to do this you'll need to specify root=/dev/nfs,
185 and specify nfs_root.
186 nfs_root
188 The directory on the NFS server to be used as the root filesystem.
189 Specified as a fully qualified path, i.e. /full/path/to/root/dir.
190 vcpus
192 The number of virtual cpus to allocate to the domain. In order to
193 use this the xen kernel must be compiled with SMP support.
194 This defaults to 1, meaning running the domain as a UP.
196
198 There are 3 options which control domain shutdown (both planned and
199 unplanned) under certain events. The 3 events currently captured are:
200 on_shutdown
202 Triggered on either an xm shutdown or graceful shutdown from inside
203 the DomU.
204 on_reboot
206 Triggered on either an xm reboot or graceful reboot from inside the
207 DomU.
208 on_crash
210 Triggered when a DomU goes to the crashed state for any reason.
211 All of them take one of 4 valid states listed below.
213 destroy
215 The domain will be cleaned up completely. No attempt at respawning
216 will occur. This is what a typical shutdown would look like.
217 restart
219 The domain will be restarted with the same name as the old domain.
220 This is what a typical reboot would look like.
221 preserve
223 The domain will not be cleaned up at all. This is often useful for
224 crash state domains which ensures that enough evidence is to debug
225 the real issue.
226 rename-restart
228 The old domain will not be cleaned up, but will be renamed so a new
229 domain can be restarted in it's place. The old domain will be
230 renamed with a suffix -1, -2, etc, and assigned a new random UUID;
231 the new domain will keep the original name and UUID. The old
232 domain will release the devices that it holds, so that the new one
233 may take them.
234 Additionally, the "on_crash" event can also take:
236 coredump-destroy
238 Dump the crashed domain's core and then destroy it.
240 coredump-restart
242 Dump the crashed domain's core and then restart it.
243
245 The following are quick examples of ways that domains might be
246 configured. They should not be considered an exhaustive set.
247 A Loopback File as Root
249 kernel = "/boot/vmlinuz-2.6-xenU"
250 memory = 128
251 name = "MyLinux"
252 root = "/dev/hda1 ro"
253 disk = [ "file:/var/xen/mylinux.img,hda1,w" ]
254 This creates a domain called MyLinux with 128 MB of memory using a
256 default xen kernel, and the file /var/xen/mylinux.img loopback
257 mounted at hda1, which is the root filesystem.
258 NFS Root
260 FIXME: write me
261 LVM Root
263 FIXME: write me
264 Two Networks
266 FIXME: write me
267
269 xm(1)
270
272 Sean Dague <sean at dague dot net>
273
275 Not all options are currently documented
276
278 Hey! The above document had some coding errors, which are explained
279 below:
280 Around line 301:
282 You can't have =items (as at line 305) unless the first thing after
283 the =over is an =item
284 Around line 311:
286 '=item' outside of any '=over'
287xen-unstable 2011-10-20 xmdomain.cfg(5)