mirror of
https://github.com/xen-project/xen.git
synced 2026-10-30 03:00:05 +01:00
Keir Fraser
e63b739dff
Xen-API already specifies these actions for the 'on_crash' domain exit event. This patch makes them available for use in traditional domU config files and through the xm tool as well. Signed-off-by: Jim Fehlig <jfehlig@novell.com>
361 lines
8.5 KiB
Plaintext
361 lines
8.5 KiB
Plaintext
=head1 NAME
|
|
|
|
xmdomain.cfg - xm domain config file format
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
/etc/xen/myxendomain
|
|
/etc/xen/myxendomain2
|
|
/etc/xen/auto/myxenautostarted
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<xm>(1) program uses python executable config files to define
|
|
domains to create from scratch. Each of these config files needs to
|
|
contain a number of required options, and may specify many more.
|
|
|
|
Domain configuration files live in /etc/xen by default, if you store
|
|
config files anywhere else the full path to the config file must be
|
|
specified in the I<xm create> command.
|
|
|
|
/etc/xen/auto is a special case. Domain config files in that
|
|
directory will be started automatically at system boot if the
|
|
xendomain init script is enabled. The contents of /etc/xen/auto
|
|
should be symlinks to files in /etc/xen to allow I<xm create> to be
|
|
used without full paths.
|
|
|
|
Options are specified by I<name = value> statements in the
|
|
xmdomain.cfg files.
|
|
|
|
=head1 OPTIONS
|
|
|
|
The following lists the most commonly used options for a domain config
|
|
file.
|
|
|
|
=over 4
|
|
|
|
=item B<kernel>
|
|
|
|
The kernel image for the domain. The format of the parameter is the
|
|
fully qualified path to the kernel image file,
|
|
i.e. I</boot/vmlinuz-2.6.12-xenU>.
|
|
|
|
|
|
=item B<ramdisk>
|
|
|
|
The initial ramdisk for the domain. The format of the parameter is
|
|
the fully qualified path to the initrd, i.e. I</boot/initrd.gz>. On
|
|
many Linux distros you will not need a ramdisk if using the default
|
|
xen kernel.
|
|
|
|
=item B<memory>
|
|
|
|
The amount of RAM, in megabytes, to allocate to the domain when it
|
|
starts. Allocating insufficient memory for a domain may produce
|
|
extremely bizarre behavior. If there isn't enough free memory left on
|
|
the machine to fulfill this request, the domain will fail to start.
|
|
|
|
Xen does not support overcommit of memory, so the total memory of all
|
|
guests (+ 64 MB needed for Xen) must be less than or equal to the
|
|
physical RAM in the machine.
|
|
|
|
=item B<name>
|
|
|
|
A unique name for the domain. Attempting to create two domains with
|
|
the same name will cause an error.
|
|
|
|
=item B<root>
|
|
|
|
Specifies the root device for the domain. This is required for Linux
|
|
domains, and possibly other OSes.
|
|
|
|
=item B<nics>
|
|
|
|
The number of network interfaces allocated to the domain on boot. It
|
|
defaults to 1.
|
|
|
|
=item B<disk>
|
|
|
|
An array of block device stanzas, in the form:
|
|
|
|
disk = [ "stanza1", "stanza2", ... ]
|
|
|
|
Each stanza has 3 terms, separated by commas,
|
|
"backend-dev,frontend-dev,mode".
|
|
|
|
=over 4
|
|
|
|
=item I<backend-dev>
|
|
|
|
The device in the backend domain that will be exported to the guest
|
|
(frontend) domain. Supported formats include:
|
|
|
|
I<phy:device> - export the physical device listed. The device can be
|
|
in symbolic form, as in sda7, or as the hex major/minor number, as in
|
|
0x301 (which is hda1).
|
|
|
|
I<file://path/to/file> - export the file listed as a loopback device.
|
|
This will take care of the loopback setup before exporting the device.
|
|
|
|
=item I<frontend-dev>
|
|
|
|
How the device should appear in the guest domain. The device can be
|
|
in symbolic form, as in sda7, or as the hex major/minor number, as in
|
|
0x301 (which is hda1).
|
|
|
|
=item I<mode>
|
|
|
|
The access mode for the device. There are currently 2 valid options,
|
|
I<r> (read-only), I<w> (read/write).
|
|
|
|
=back
|
|
|
|
=item B<vif>
|
|
|
|
An array of virtual interface stanzas in the form:
|
|
|
|
vif = [ "stanza1", "stanza2", ... ]
|
|
|
|
Each stanza specifies a set of I<name = value> options separated by
|
|
commas, in the form: "name1=value1, name2=value2, ..."
|
|
|
|
B<OPTIONS>
|
|
|
|
=over 4
|
|
|
|
=item I<bridge>
|
|
|
|
The network bridge to be used for this device. This is especially
|
|
needed if multiple bridges exist on the machine.
|
|
|
|
=item I<mac>
|
|
|
|
The MAC address for the virtual interface. If mac is not specified,
|
|
one will be randomly chosen by xen with the 00:16:3e vendor id prefix.
|
|
|
|
=back
|
|
|
|
=item B<vfb>
|
|
|
|
A virtual frame buffer stanza in the form:
|
|
|
|
vfb = [ "stanza" ]
|
|
|
|
The stanza specifies a set of I<name = value> options separated by
|
|
commas, in the form: "name1=value1, name2=value2, ..."
|
|
|
|
B<OPTIONS>
|
|
|
|
=over 4
|
|
|
|
=item I<type>
|
|
|
|
There are currently two valid options: I<vnc> starts a VNC server that
|
|
lets you connect an external VNC viewer, and I<sdl> starts an internal
|
|
viewer.
|
|
|
|
=item I<vncdisplay>
|
|
|
|
The VNC display number to use, defaults to the domain ID. The
|
|
VNC server listens on port 5900 + display number.
|
|
|
|
=item I<vnclisten>
|
|
|
|
The listening address for the VNC server, default 127.0.0.1.
|
|
|
|
=item I<vncunused>
|
|
|
|
If non-zero, the VNC server listens on the first unused port above
|
|
5900.
|
|
|
|
=item I<vncpasswd>
|
|
|
|
Overrides the XenD configured default password.
|
|
|
|
=item I<display>
|
|
|
|
Display to use for the internal viewer, defaults to environment
|
|
variable I<DISPLAY>.
|
|
|
|
=item I<xauthority>
|
|
|
|
Authority file to use for the internal viewer, defaults to environment
|
|
variable I<XAUTHORITY>.
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
=head1 ADDITIONAL OPTIONS
|
|
|
|
The following options are also supported in the config file, though
|
|
are far more rarely used.
|
|
|
|
=over 4
|
|
|
|
=item B<builder>
|
|
|
|
Which builder should be used to construct the domain. This defaults
|
|
to the I<linux> if not specified, which is the builder for
|
|
paravirtualized Linux domains.
|
|
|
|
=item B<cpu>
|
|
|
|
Specifies which CPU the domain should be started on, where 0 specifies
|
|
the first cpu, 1 the second, and so on. This defaults to -1, which
|
|
means Xen is free to pick which CPU to start on.
|
|
|
|
=item B<cpus>
|
|
|
|
Specifies a list of CPUs on which the domains' VCPUs are allowed to
|
|
execute upon. The syntax supports ranges (0-3), and negation, ^1.
|
|
For instance:
|
|
|
|
cpus = "0-3,5,^1"
|
|
|
|
Will result in CPUs 0, 2, 3, 5 being available for use by the domain.
|
|
|
|
=item B<extra>
|
|
|
|
Extra information to append to the end of the kernel parameter line.
|
|
The format is a string, the contents of which can be anything that the
|
|
kernel supports. For instance:
|
|
|
|
extra = "4"
|
|
|
|
Will cause the domain to boot to runlevel 4.
|
|
|
|
=item B<nfs_server>
|
|
|
|
The IP address of the NFS server to use as the root device for the
|
|
domain. In order to do this you'll need to specify I<root=/dev/nfs>,
|
|
and specify I<nfs_root>.
|
|
|
|
=item B<nfs_root>
|
|
|
|
The directory on the NFS server to be used as the root filesystem.
|
|
Specified as a fully qualified path, i.e. I</full/path/to/root/dir>.
|
|
|
|
=item B<vcpus>
|
|
|
|
The number of virtual cpus to allocate to the domain. In order to use
|
|
this the xen kernel must be compiled with SMP support.
|
|
|
|
This defaults to 1, meaning running the domain as a UP.
|
|
|
|
=back
|
|
|
|
=head1 DOMAIN SHUTDOWN OPTIONS
|
|
|
|
There are 3 options which control domain shutdown (both planned and
|
|
unplanned) under certain events. The 3 events currently captured are:
|
|
|
|
=over 4
|
|
|
|
=item B<on_shutdown>
|
|
|
|
Triggered on either an I<xm shutdown> or graceful shutdown from inside
|
|
the DomU.
|
|
|
|
=item B<on_reboot>
|
|
|
|
Triggered on either an I<xm reboot> or graceful reboot from inside the
|
|
DomU.
|
|
|
|
=item B<on_crash>
|
|
|
|
Triggered when a DomU goes to the crashed state for any reason.
|
|
|
|
=back
|
|
|
|
All of them take one of 4 valid states listed below.
|
|
|
|
=over 4
|
|
|
|
=item B<destroy>
|
|
|
|
The domain will be cleaned up completely. No attempt at respawning
|
|
will occur. This is what a typical shutdown would look like.
|
|
|
|
=item B<restart>
|
|
|
|
The domain will be restarted with the same name as the old domain.
|
|
This is what a typical reboot would look like.
|
|
|
|
=item B<preserve>
|
|
|
|
The domain will not be cleaned up at all. This is often useful for
|
|
crash state domains which ensures that enough evidence is to debug the
|
|
real issue.
|
|
|
|
=item B<rename-restart>
|
|
|
|
The old domain will not be cleaned up, but will be renamed so a new
|
|
domain can be restarted in it's place. The old domain will be renamed with
|
|
a suffix -1, -2, etc, and assigned a new random UUID; the new domain will
|
|
keep the original name and UUID. The old domain will release the devices that
|
|
it holds, so that the new one may take them.
|
|
|
|
=back
|
|
|
|
=over 4
|
|
|
|
Additionally, the "on_crash" event can also take:
|
|
|
|
=item B<coredump-destroy>
|
|
|
|
Dump the crashed domain's core and then destroy it.
|
|
|
|
=back
|
|
|
|
=item B<coredump-restart>
|
|
|
|
Dump the crashed domain's core and then restart it.
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
The following are quick examples of ways that domains might be
|
|
configured. They should not be considered an exhaustive set.
|
|
|
|
=over 4
|
|
|
|
=item I<A Loopback File as Root>
|
|
|
|
kernel = "/boot/vmlinuz-2.6-xenU"
|
|
memory = 128
|
|
name = "MyLinux"
|
|
root = "/dev/hda1 ro"
|
|
disk = [ "file:/var/xen/mylinux.img,hda1,w" ]
|
|
|
|
This creates a domain called MyLinux with 128 MB of memory using a
|
|
default xen kernel, and the file /var/xen/mylinux.img loopback mounted
|
|
at hda1, which is the root filesystem.
|
|
|
|
=item I<NFS Root>
|
|
|
|
FIXME: write me
|
|
|
|
=item I<LVM Root>
|
|
|
|
FIXME: write me
|
|
|
|
=item I<Two Networks>
|
|
|
|
FIXME: write me
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
B<xm>(1)
|
|
|
|
=head1 AUTHOR
|
|
|
|
Sean Dague <sean at dague dot net>
|
|
|
|
=head1 BUGS
|
|
|
|
Not all options are currently documented
|