xmdomain.cfg(5) Xen xmdomain.cfg(5)NAMExmdomain.cfg - xm domain config file format
SYNOPSIS
/etc/xen/auto/
/etc/xen/examples/
/etc/xen/vm/
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/vm 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/vm 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-xen.
ramdisk
The initial ramdisk for the domain. The format of the parameter is
the fully qualified path to the initrd, i.e. /boot/initrd-xen. 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 fulfil 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.
acpi_firmware
Specify a path to a file that contains extra ACPI firmware tables
to pass in to a guest. The file can contain several tables in their
binary AML form concatenated together. Each table self describes
its length so no additional information is needed. These tables
will be added to the ACPI table set in the guest. Note that
existing tables cannot be overridden by this feature. For example
this cannot be used to override tables like DSDT, FADT, etc.
smbios_firmware
Specify a path to a file that contains extra SMBIOS firmware
structures to pass in to a guest. The file can contain a set DMTF
predefined structures which will override the internal defaults.
Not all predefined structures can be overridden, only the following
types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any number
of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS
structures do not present their overall size, each entry in the
file must be preceded by a 32b integer indicating the size of the
next structure.
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-xen"
memory = 128
name = "MyLinux"
root = "/dev/hda1"
disk = [ "file:/var/lib/xen/images/MyLinux/hda1,hda1,w" ]
This creates a domain called MyLinux with 128 MB of memory using a
default xen kernel, and the file hda1 loopback mounted at hda1,
which is the root filesystem.
NFS Root
LVM Root
Two Networks
SEE ALSOxm(1)AUTHOR
Sean Dague <sean at dague dot net>
BUGS
Not all options are currently documented
xen-unstable 2013-06-14 xmdomain.cfg(5)
