NAME¶
xmdomain.cfg - xm domain config file format
SYNOPSIS¶
/etc/xen/myxendomain
/etc/xen/myxendomain2
/etc/xen/auto/myxenautostarted
DESCRIPTION¶
The
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
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
xm create to be used without full paths.
Options are specified by
name = value statements in the xmdomain.cfg
files.
OPTIONS¶
The following lists the most commonly used options for a domain config file.
- kernel
- The kernel image for the domain. The format of the
parameter is the fully qualified path to the kernel image file, i.e.
/boot/vmlinuz-2.6.12-xenU.
- ramdisk
- The initial ramdisk for the domain. The format of the
parameter is the fully qualified path to the initrd, i.e.
/boot/initrd.gz. On many Linux distros you will not need a ramdisk
if using the default xen kernel.
- 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.
- name
- A unique name for the domain. Attempting to create two
domains with the same name will cause an error.
- root
- Specifies the root device for the domain. This is required
for Linux domains, and possibly other OSes.
- nics
- The number of network interfaces allocated to the domain on
boot. It defaults to 1.
- 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".
- backend-dev
- The device in the backend domain that will be exported to
the guest (frontend) domain. Supported formats include:
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).
file://path/to/file - export the file listed as a loopback device.
This will take care of the loopback setup before exporting the
device.
- 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).
- mode
- The access mode for the device. There are currently 2 valid
options, r (read-only), w (read/write).
- vif
- An array of virtual interface stanzas in the form:
vif = [ "stanza1", "stanza2", ... ]
Each stanza specifies a set of name = value options separated by
commas, in the form: "name1=value1, name2=value2, ..."
OPTIONS
- bridge
- The network bridge to be used for this device. This is
especially needed if multiple bridges exist on the machine.
- 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.
- vfb
- A virtual frame buffer stanza in the form:
vfb = [ "stanza" ]
The stanza specifies a set of name = value options separated by
commas, in the form: "name1=value1, name2=value2, ..."
OPTIONS
- type
- There are currently two valid options: vnc starts a
VNC server that lets you connect an external VNC viewer, and sdl
starts an internal viewer.
- vncdisplay
- The VNC display number to use, defaults to the domain ID.
The VNC server listens on port 5900 + display number.
- vnclisten
- The listening address for the VNC server, default
127.0.0.1.
- vncunused
- If non-zero, the VNC server listens on the first unused
port above 5900.
- vncpasswd
- Overrides the XenD configured default password.
- display
- Display to use for the internal viewer, defaults to
environment variable DISPLAY.
- xauthority
- Authority file to use for the internal viewer, defaults to
environment variable XAUTHORITY.
ADDITIONAL OPTIONS¶
The following options are also supported in the config file, though are far more
rarely used.
- builder
- Which builder should be used to construct the domain. This
defaults to the linux if not specified, which is the builder for
paravirtualized Linux domains.
- 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.
- 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.
- 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.
- 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
root=/dev/nfs, and specify nfs_root.
- nfs_root
- The directory on the NFS server to be used as the root
filesystem. Specified as a fully qualified path, i.e.
/full/path/to/root/dir.
- 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.
DOMAIN SHUTDOWN OPTIONS¶
There are 3 options which control domain shutdown (both planned and unplanned)
under certain events. The 3 events currently captured are:
- on_shutdown
- Triggered on either an xm shutdown or graceful
shutdown from inside the DomU.
- on_reboot
- Triggered on either an xm reboot or graceful reboot
from inside the DomU.
- on_crash
- Triggered when a DomU goes to the crashed state for any
reason.
All of them take one of 4 valid states listed below.
- destroy
- The domain will be cleaned up completely. No attempt at
respawning will occur. This is what a typical shutdown would look
like.
- restart
- The domain will be restarted with the same name as the old
domain. This is what a typical reboot would look like.
- 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.
- 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.
Additionally, the "on_crash" event can also take:
- coredump-destroy
- Dump the crashed domain's core and then destroy it.
- coredump-restart
- Dump the crashed domain's core and then restart it.
EXAMPLES¶
The following are quick examples of ways that domains might be configured. They
should not be considered an exhaustive set.
- 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.
- NFS Root
- FIXME: write me
- LVM Root
- FIXME: write me
- Two Networks
- FIXME: write me
SEE ALSO¶
xm(1)
AUTHOR¶
Sean Dague <sean at dague dot net>
BUGS¶
Not all options are currently documented