← Back to branch summary

~ubuntu-branches/ubuntu/utopic/xen/utopic

« back to all changes in this revision

Viewing changes to docs/man/xmdomain.cfg.pod.5

  • Committer: Bazaar Package Importer
  • Author(s): Bastian Blank
  • Date: 2010-05-06 15:47:38 UTC
  • mto: (1.3.1) (15.1.1 sid) (4.1.1 experimental)
  • mto: This revision was merged to the branch mainline in revision 3.
  • Revision ID: james.westby@ubuntu.com-20100506154738-agoz0rlafrh1fnq7
Tags: upstream-4.0.0
Import upstream version 4.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/man/xmdomain.cfg.pod.5
 
1
=head1 NAME
 
2
 
 
3
xmdomain.cfg - xm domain config file format
 
4
 
 
5
=head1 SYNOPSIS
 
6
 
 
7
 /etc/xen/myxendomain
 
8
 /etc/xen/myxendomain2
 
9
 /etc/xen/auto/myxenautostarted
 
10
 
 
11
=head1 DESCRIPTION
 
12
 
 
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.
 
16
 
 
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.
 
20
 
 
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.
 
26
 
 
27
Options are specified by I<name = value> statements in the
 
28
xmdomain.cfg files.
 
29
 
 
30
=head1 OPTIONS
 
31
 
 
32
The following lists the most commonly used options for a domain config
 
33
file.  
 
34
 
 
35
=over 4
 
36
 
 
37
=item B<kernel>
 
38
 
 
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>.
 
42
 
 
43
 
 
44
=item B<ramdisk>
 
45
 
 
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.
 
50
 
 
51
=item B<memory>
 
52
 
 
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.
 
57
 
 
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.
 
61
 
 
62
=item B<name>
 
63
 
 
64
A unique name for the domain.  Attempting to create two domains with
 
65
the same name will cause an error.
 
66
 
 
67
=item B<root>
 
68
 
 
69
Specifies the root device for the domain.  This is required for Linux
 
70
domains, and possibly other OSes.
 
71
 
 
72
=item B<nics>
 
73
 
 
74
The number of network interfaces allocated to the domain on boot.  It
 
75
defaults to 1.
 
76
 
 
77
=item B<disk>
 
78
 
 
79
An array of block device stanzas, in the form:
 
80
 
 
81
    disk = [ "stanza1", "stanza2", ... ]
 
82
 
 
83
Each stanza has 3 terms, separated by commas,
 
84
"backend-dev,frontend-dev,mode".
 
85
 
 
86
=over 4
 
87
 
 
88
=item I<backend-dev>
 
89
 
 
90
The device in the backend domain that will be exported to the guest
 
91
(frontend) domain.  Supported formats include:
 
92
 
 
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).
 
96
 
 
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.
 
99
 
 
100
=item I<frontend-dev>
 
101
 
 
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).
 
105
 
 
106
=item I<mode>
 
107
 
 
108
The access mode for the device.  There are currently 2 valid options,
 
109
I<r> (read-only), I<w> (read/write).
 
110
 
 
111
=back
 
112
 
 
113
=item B<vif>
 
114
 
 
115
An array of virtual interface stanzas in the form:
 
116
 
 
117
    vif = [ "stanza1", "stanza2", ... ]
 
118
 
 
119
Each stanza specifies a set of I<name = value> options separated by
 
120
commas, in the form: "name1=value1, name2=value2, ..."
 
121
 
 
122
B<OPTIONS>
 
123
 
 
124
=over 4
 
125
 
 
126
=item I<bridge>
 
127
 
 
128
The network bridge to be used for this device.  This is especially
 
129
needed if multiple bridges exist on the machine.
 
130
 
 
131
=item I<mac>
 
132
 
 
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.
 
135
 
 
136
=back
 
137
 
 
138
=item B<vfb>
 
139
 
 
140
A virtual frame buffer stanza in the form:
 
141
 
 
142
    vfb = [ "stanza" ]
 
143
 
 
144
The stanza specifies a set of I<name = value> options separated by
 
145
commas, in the form: "name1=value1, name2=value2, ..."
 
146
 
 
147
B<OPTIONS>
 
148
 
 
149
=over 4
 
150
 
 
151
=item I<type>
 
152
 
 
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.
 
156
 
 
157
=item I<vncdisplay>
 
158
 
 
159
The VNC display number to use, defaults to the domain ID.  The
 
160
VNC server listens on port 5900 + display number.
 
161
 
 
162
=item I<vnclisten>
 
163
 
 
164
The listening address for the VNC server, default 127.0.0.1.
 
165
 
 
166
=item I<vncunused>
 
167
 
 
168
If non-zero, the VNC server listens on the first unused port above
 
169
5900.
 
170
 
 
171
=item I<vncpasswd>
 
172
 
 
173
Overrides the XenD configured default password.
 
174
 
 
175
=item I<display>
 
176
 
 
177
Display to use for the internal viewer, defaults to environment
 
178
variable I<DISPLAY>.
 
179
 
 
180
=item I<xauthority>
 
181
 
 
182
Authority file to use for the internal viewer, defaults to environment
 
183
variable I<XAUTHORITY>.
 
184
 
 
185
=back
 
186
 
 
187
=back
 
188
 
 
189
=head1 ADDITIONAL OPTIONS
 
190
 
 
191
The following options are also supported in the config file, though
 
192
are far more rarely used.
 
193
 
 
194
=over 4
 
195
 
 
196
=item B<builder>
 
197
 
 
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.
 
201
 
 
202
=item B<cpu>
 
203
 
 
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.
 
207
 
 
208
=item B<cpus>
 
209
 
 
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:
 
213
 
 
214
    cpus = "0-3,5,^1"
 
215
 
 
216
Will result in CPUs 0, 2, 3, 5 being available for use by the domain.
 
217
 
 
218
=item B<extra>
 
219
 
 
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:
 
223
 
 
224
    extra = "4"
 
225
 
 
226
Will cause the domain to boot to runlevel 4.
 
227
 
 
228
=item B<nfs_server>
 
229
 
 
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>.
 
233
 
 
234
=item B<nfs_root>
 
235
 
 
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>.
 
238
 
 
239
=item B<vcpus>
 
240
 
 
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.
 
243
 
 
244
This defaults to 1, meaning running the domain as a UP.
 
245
 
 
246
=back
 
247
 
 
248
=head1 DOMAIN SHUTDOWN OPTIONS
 
249
 
 
250
There are 3 options which control domain shutdown (both planned and
 
251
unplanned) under certain events.  The 3 events currently captured are:
 
252
 
 
253
=over 4
 
254
 
 
255
=item B<on_shutdown>
 
256
 
 
257
Triggered on either an I<xm shutdown> or graceful shutdown from inside
 
258
the DomU.
 
259
 
 
260
=item B<on_reboot>
 
261
 
 
262
Triggered on either an I<xm reboot> or graceful reboot from inside the
 
263
DomU.
 
264
 
 
265
=item B<on_crash>
 
266
 
 
267
Triggered when a DomU goes to the crashed state for any reason.
 
268
 
 
269
=back
 
270
 
 
271
All of them take one of 4 valid states listed below.  
 
272
 
 
273
=over 4
 
274
 
 
275
=item B<destroy>
 
276
 
 
277
The domain will be cleaned up completely.  No attempt at respawning
 
278
will occur.  This is what a typical shutdown would look like.
 
279
 
 
280
=item B<restart>
 
281
 
 
282
The domain will be restarted with the same name as the old domain.
 
283
This is what a typical reboot would look like.
 
284
 
 
285
=item B<preserve>
 
286
 
 
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.
 
290
 
 
291
=item B<rename-restart>
 
292
 
 
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.
 
298
 
 
299
=back
 
300
 
 
301
=over 4
 
302
 
 
303
Additionally, the "on_crash" event can also take:
 
304
 
 
305
=item B<coredump-destroy>
 
306
 
 
307
Dump the crashed domain's core and then destroy it.
 
308
 
 
309
=back
 
310
 
 
311
=item B<coredump-restart>
 
312
 
 
313
Dump the crashed domain's core and then restart it.
 
314
 
 
315
=back
 
316
 
 
317
=head1 EXAMPLES
 
318
 
 
319
The following are quick examples of ways that domains might be
 
320
configured.  They should not be considered an exhaustive set.
 
321
 
 
322
=over 4
 
323
 
 
324
=item I<A Loopback File as Root>
 
325
 
 
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" ]
 
331
 
 
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.
 
335
 
 
336
=item I<NFS Root>
 
337
 
 
338
FIXME: write me
 
339
 
 
340
=item I<LVM Root>
 
341
 
 
342
FIXME: write me
 
343
 
 
344
=item I<Two Networks>
 
345
 
 
346
FIXME: write me
 
347
 
 
348
=back
 
349
 
 
350
=head1 SEE ALSO
 
351
 
 
352
B<xm>(1)
 
353
 
 
354
=head1 AUTHOR
 
355
 
 
356
  Sean Dague <sean at dague dot net>
 
357
 
 
358
=head1 BUGS
 
359
 
 
360
Not all options are currently documented