view docs/man/xmdomain.cfg.pod.5 @ 18947:2dffa6ceb0af

Support S3 for MSI interrupt

From: "Jiang, Yunhong" <yunhong.jiang@intel.com>
Signed-off-by: Keir Fraser <keir.fraser@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Fri Dec 19 14:56:36 2008 +0000 (2008-12-19)
parents 58e5e9ae0f8d
line source
1 =head1 NAME
3 xmdomain.cfg - xm domain config file format
5 =head1 SYNOPSIS
7 /etc/xen/myxendomain
8 /etc/xen/myxendomain2
9 /etc/xen/auto/myxenautostarted
13 The B<xm>(1) program uses python executable config files to define
14 domains to create from scratch. Each of these config files needs to
15 contain a number of required options, and may specify many more.
17 Domain configuration files live in /etc/xen by default, if you store
18 config files anywhere else the full path to the config file must be
19 specified in the I<xm create> command.
21 /etc/xen/auto is a special case. Domain config files in that
22 directory will be started automatically at system boot if the
23 xendomain init script is enabled. The contents of /etc/xen/auto
24 should be symlinks to files in /etc/xen to allow I<xm create> to be
25 used without full paths.
27 Options are specified by I<name = value> statements in the
28 xmdomain.cfg files.
30 =head1 OPTIONS
32 The following lists the most commonly used options for a domain config
33 file.
35 =over 4
37 =item B<kernel>
39 The kernel image for the domain. The format of the parameter is the
40 fully qualified path to the kernel image file,
41 i.e. I</boot/vmlinuz-2.6.12-xenU>.
44 =item B<ramdisk>
46 The initial ramdisk for the domain. The format of the parameter is
47 the fully qualified path to the initrd, i.e. I</boot/initrd.gz>. On
48 many Linux distros you will not need a ramdisk if using the default
49 xen kernel.
51 =item B<memory>
53 The amount of RAM, in megabytes, to allocate to the domain when it
54 starts. Allocating insufficient memory for a domain may produce
55 extremely bizarre behavior. If there isn't enough free memory left on
56 the machine to fulfill this request, the domain will fail to start.
58 Xen does not support overcommit of memory, so the total memory of all
59 guests (+ 64 MB needed for Xen) must be less than or equal to the
60 physical RAM in the machine.
62 =item B<name>
64 A unique name for the domain. Attempting to create two domains with
65 the same name will cause an error.
67 =item B<root>
69 Specifies the root device for the domain. This is required for Linux
70 domains, and possibly other OSes.
72 =item B<nics>
74 The number of network interfaces allocated to the domain on boot. It
75 defaults to 1.
77 =item B<disk>
79 An array of block device stanzas, in the form:
81 disk = [ "stanza1", "stanza2", ... ]
83 Each stanza has 3 terms, separated by commas,
84 "backend-dev,frontend-dev,mode".
86 =over 4
88 =item I<backend-dev>
90 The device in the backend domain that will be exported to the guest
91 (frontend) domain. Supported formats include:
93 I<phy:device> - export the physical device listed. The device can be
94 in symbolic form, as in sda7, or as the hex major/minor number, as in
95 0x301 (which is hda1).
97 I<file://path/to/file> - export the file listed as a loopback device.
98 This will take care of the loopback setup before exporting the device.
100 =item I<frontend-dev>
102 How the device should appear in the guest domain. The device can be
103 in symbolic form, as in sda7, or as the hex major/minor number, as in
104 0x301 (which is hda1).
106 =item I<mode>
108 The access mode for the device. There are currently 2 valid options,
109 I<r> (read-only), I<w> (read/write).
111 =back
113 =item B<vif>
115 An array of virtual interface stanzas in the form:
117 vif = [ "stanza1", "stanza2", ... ]
119 Each stanza specifies a set of I<name = value> options separated by
120 commas, in the form: "name1=value1, name2=value2, ..."
124 =over 4
126 =item I<bridge>
128 The network bridge to be used for this device. This is especially
129 needed if multiple bridges exist on the machine.
131 =item I<mac>
133 The MAC address for the virtual interface. If mac is not specified,
134 one will be randomly chosen by xen with the 00:16:3e vendor id prefix.
136 =back
138 =item B<vfb>
140 A virtual frame buffer stanza in the form:
142 vfb = [ "stanza" ]
144 The stanza specifies a set of I<name = value> options separated by
145 commas, in the form: "name1=value1, name2=value2, ..."
149 =over 4
151 =item I<type>
153 There are currently two valid options: I<vnc> starts a VNC server that
154 lets you connect an external VNC viewer, and I<sdl> starts an internal
155 viewer.
157 =item I<vncdisplay>
159 The VNC display number to use, defaults to the domain ID. The
160 VNC server listens on port 5900 + display number.
162 =item I<vnclisten>
164 The listening address for the VNC server, default
166 =item I<vncunused>
168 If non-zero, the VNC server listens on the first unused port above
169 5900.
171 =item I<vncpasswd>
173 Overrides the XenD configured default password.
175 =item I<display>
177 Display to use for the internal viewer, defaults to environment
178 variable I<DISPLAY>.
180 =item I<xauthority>
182 Authority file to use for the internal viewer, defaults to environment
183 variable I<XAUTHORITY>.
185 =back
187 =back
191 The following options are also supported in the config file, though
192 are far more rarely used.
194 =over 4
196 =item B<builder>
198 Which builder should be used to construct the domain. This defaults
199 to the I<linux> if not specified, which is the builder for
200 paravirtualized Linux domains.
202 =item B<cpu>
204 Specifies which CPU the domain should be started on, where 0 specifies
205 the first cpu, 1 the second, and so on. This defaults to -1, which
206 means Xen is free to pick which CPU to start on.
208 =item B<cpus>
210 Specifies a list of CPUs on which the domains' VCPUs are allowed to
211 execute upon. The syntax supports ranges (0-3), and negation, ^1.
212 For instance:
214 cpus = "0-3,5,^1"
216 Will result in CPUs 0, 2, 3, 5 being available for use by the domain.
218 =item B<extra>
220 Extra information to append to the end of the kernel parameter line.
221 The format is a string, the contents of which can be anything that the
222 kernel supports. For instance:
224 extra = "4"
226 Will cause the domain to boot to runlevel 4.
228 =item B<nfs_server>
230 The IP address of the NFS server to use as the root device for the
231 domain. In order to do this you'll need to specify I<root=/dev/nfs>,
232 and specify I<nfs_root>.
234 =item B<nfs_root>
236 The directory on the NFS server to be used as the root filesystem.
237 Specified as a fully qualified path, i.e. I</full/path/to/root/dir>.
239 =item B<vcpus>
241 The number of virtual cpus to allocate to the domain. In order to use
242 this the xen kernel must be compiled with SMP support.
244 This defaults to 1, meaning running the domain as a UP.
246 =back
250 There are 3 options which control domain shutdown (both planned and
251 unplanned) under certain events. The 3 events currently captured are:
253 =over 4
255 =item B<on_shutdown>
257 Triggered on either an I<xm shutdown> or graceful shutdown from inside
258 the DomU.
260 =item B<on_reboot>
262 Triggered on either an I<xm reboot> or graceful reboot from inside the
263 DomU.
265 =item B<on_crash>
267 Triggered when a DomU goes to the crashed state for any reason.
269 =back
271 All of them take one of 4 valid states listed below.
273 =over 4
275 =item B<destroy>
277 The domain will be cleaned up completely. No attempt at respawning
278 will occur. This is what a typical shutdown would look like.
280 =item B<restart>
282 The domain will be restarted with the same name as the old domain.
283 This is what a typical reboot would look like.
285 =item B<preserve>
287 The domain will not be cleaned up at all. This is often useful for
288 crash state domains which ensures that enough evidence is to debug the
289 real issue.
291 =item B<rename-restart>
293 The old domain will not be cleaned up, but will be renamed so a new
294 domain can be restarted in it's place. The old domain will be renamed with
295 a suffix -1, -2, etc, and assigned a new random UUID; the new domain will
296 keep the original name and UUID. The old domain will release the devices that
297 it holds, so that the new one may take them.
299 =back
301 =over 4
303 Additionally, the "on_crash" event can also take:
305 =item B<coredump-destroy>
307 Dump the crashed domain's core and then destroy it.
309 =back
311 =item B<coredump-restart>
313 Dump the crashed domain's core and then restart it.
315 =back
317 =head1 EXAMPLES
319 The following are quick examples of ways that domains might be
320 configured. They should not be considered an exhaustive set.
322 =over 4
324 =item I<A Loopback File as Root>
326 kernel = "/boot/vmlinuz-2.6-xenU"
327 memory = 128
328 name = "MyLinux"
329 root = "/dev/hda1 ro"
330 disk = [ "file:/var/xen/mylinux.img,hda1,w" ]
332 This creates a domain called MyLinux with 128 MB of memory using a
333 default xen kernel, and the file /var/xen/mylinux.img loopback mounted
334 at hda1, which is the root filesystem.
336 =item I<NFS Root>
338 FIXME: write me
340 =item I<LVM Root>
342 FIXME: write me
344 =item I<Two Networks>
346 FIXME: write me
348 =back
350 =head1 SEE ALSO
352 B<xm>(1)
354 =head1 AUTHOR
356 Sean Dague <sean at dague dot net>
358 =head1 BUGS
360 Not all options are currently documented