Xmdomain.cfg

From blag.wiki.aktivix.org

Jump to: navigation, search

Contents

NAME

xmdomain.cfg - xm domain config file format

Introduction

This wiki briefly describes the use and syntax of the config files used to start (and to keep running) Xen domains. It was lifted from /usr/src/xen-foo/docs/. I've placed a few comments and examples here as it may not be obvious what good or valid examples may be. Note that there are a few examples to get you started in /etc/xen/xmexample{1,2}. Also refer to the example shown below and use and modify as you wish.

SYNOPSIS

generally you don't actually run this command yourself but Xen expects to see one of the following files for every domain that you start.

/etc/xen/myxendomain
/etc/xen/myxendomain2
/etc/xen/auto/myxenautostarted

Consult the docs for the xm command with xm --help to see how this wiki and the xm command overlap.

DESCRIPTION

The xm 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, e.g. /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. For example, if your kernel option points to /boot/vmlinuz-2.6.16-xen' then you may not need a ramdisk option.

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. For domUs created from file images using a "base" installation with no bells and whilstes, you may get away with as little as 64MB, but expect to use more once you are actually running services on them.

name

A unique name for the domain. Attempting to create two domains with the same name will cause an error. An example may be vm1 (for virtual machine number 1).

root

Specifies the root device for the domain. This is required for Linux domains, and possibly other OSes. An example may be

root = "/dev/sda1 ro"

pointing to the root device on the virtual machine.

nics

The number of network interfaces allocated to the domain on boot. It defaults to 1. I've used this option a couple of times and get error messages saying that this option is no longer required. Perhaps the man page needs to be updated?

disk

An array of block device stanzas, in the form:

disk = [ "stanza1", "stanza2", ... ]

Each stanza has 3 terms, seperated by commas, "backend-dev,frontend-dev,mode".

Example for the virtual machine bxvm whose file is /etc/xen/bxvm

disk =['file:/xen/images/bxvm.img,sda1,w','file:/xen/images/bxvm_swap.img,sda2,w']

This option specifies the image containing the file syetem and swap.


backend-dev

Hrm. Not seen or used this option *ever*! I'll leave this alone until I can experiment with actually using it, although I'm sure that it's not used.

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

Another option that I've not used before. Will leave the original text intact until otherwise required.

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

This is slightly misleading. This read/write business is specified in the disk option as shown above.

The access mode for the device. There are currently 2 valid options,

<r> (read-only), <w> (read/write).

vif

An arrray 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, ..."

You can have xen create an interface for you if you use the form of vif = [ ]


VIF 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.


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, so you don't actually have to specify this option.

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. it holds, so that the new one may take them.

EXAMPLES

Here's a real example of a config file that I use. I've included the lines that have been commented out (those starting with a #) to show other legitamate options that one can use.

#  -*- mode: python; -*-
kernel = "/boot/vmlinuz-2.6.16-xen"
memory = 64
name = "blag50k_play"
# vif = [ 'mac=00:16:3e:00:00:11, bridge=xenbr0' ]
# vif = [ , 'bridge=xenbr1' ]
# I'm too lazy to bother about all of that networking stuff so I've told Xen to..
# ...create a virtual interface for me and assign it a mac address.
vif = [  ]
disk=['file:/xen/images/blag50k_play.img,sda1,w','file:/xen/images/blag50k_play_swap.img,sda2,w']
# ...to allocate IPs to this domain via dhcp.
dhcp="dhcp"
hostname= "blag50k_play"
# It's gonna use the root file system located at:-
root = "/dev/sda1 ro" 
extra = "4"


This creates a domain called blag50k_play. It's a domU that I use to experiment with things like networking, dns and user configurations. I test and hack to my heart's content knowing that it's outcome does not affect other domains or the host machine.


SEE ALSO

The man page for xm covers a number of commands and options for running and configuring domains. Some of the options that have been described can me changed on the fly, (i.e. dynamically), with xm foo bah.

AUTHOR

The original author of this man page was Sean Dague <sean at dague dot net>. All I did was to place a few comments here and there in this wiki.

Personal tools