Xm config reference

From PrgmrWiki

Appendix B: The structure of the xen domain config file

(often this is refered to the xm config file)

This is the conventional way to define a Xen domain (and the method that we've used throughout this book.) It works by specifying Python variables in a config file, conventionally kept under /etc/xen/ . When the domain is created, xend executes this file and uses it to set variables that will eventually control the output of the domain builder.

Note also that you can override values in the config file from the xm command line. For example, to create the domain coriolanus with a different name:

xm create coriolanus name=menenius

This file -- and it would be difficult to overstate this point -- is executed as a standard Python script. Thus, you can embed arbitrary Python in the config file, making it easy to autogenerate configurations based on external constraints. You can see a simple example of this the example HVM config shipped with Xen -- the library path is selected based on the processor type.

Python in the config file isn't limited to domain configuration, either. If you're using Xen for hosting, for example, we might suggest tying the domain configuration to the billing and support-ticketing systems, using some Python glue to keep them in sync. By embedding this logic in the config files, or in a separate module included by the config files, you can build a complex infrastructure around the Xen domains.

But first, let's start with the basic elements of a domain configuration. Here's a basic config file, specifying the VM name, kernel image, three network cards, a block device, and a kernel paramenter.

name = coriolanus kernel = "/boot/linux-2.6-xen" vif = [,,] disk = ['phy:/dev/coriolanus/coriolanus-root,sda,rw'] root = "/dev/sda ro"

Here we're setting some variables (name, kernel, disk, etc.) to strings or lists. You can easily identify the lists because they're enclosed in square brackets.

String quoting follows the standard Python conventions -- a single quote for noninterpreted strings, double quotes for strings with variable substitution, and three single quotes to begin and end a multiline string.

Whitespace has significance just as in standard Python -- newlines are significant, spacing doesn't matter, except when used as indentation.

Here's another, more complex example, with an NFS root and virtual framebuffer.

[FIXME pull it out.]

Finally, HVM domains take some other options:

[FIXME HVM example]

One can also feed an XML domain definition to Xen using the xm new command. [FIXME test]


List of directives

Here we've tried to list every directive we know about, whether we use it or not, with notes indicating where we cover it in the main text of this book. We have, however, left out stuff that's marked "deprecated" as of 3.3.

There are some commands that work with the Xen.org version of Xen, but not with the version of Xen included with RedHat Enterprise Linux/CentOS 5.x.

kernel

This option specifies the kernel image that Xen will load and boot. Its value should be set to the absolute path to the kernel, from the dom0 perspective. It is required if no bootloader line is specified.

If you're using Pygrub and specify a kernel, Pygrub will try to load that file from the boot media. [FIXME test that.]

ramdisk

The ramdisk option funtions like the initrd line in grub -- it specifies an initial ramdisk, which usually contains drivers and scripts used to access hardware required to mount the root filesystem.

Many distros won't require an initrd for domUs, since the domU only needs drivers for extremely simple virtual devices. However, since the distro expects to have an initrd, it's often easier to create one. We go into more detail on that subject in Chapter 3, Provisioning DomUs.

maxmem

This specifies the amount of memory given to the domU. From the guest's perspective, this is the amount of memory "plugged in" when it boots.

memory

This is the target memory allocation for the domain. If maxmem isn't specified, the memory= line will also set the domain's maximum memory.

Since we don't oversubscribe memory, we use this directive rather than max-mem.

shadow_memory

Domain shadow memory in MB. PV domains will default to none.

Xen uses shadow memory to keep copies of domain-specific page tables. We go into more detail on the role of page table shadows in Chapter 12, HVM.

name

This is a unique name for the domain. Make it whatever you like, but we recommend keeping it under 15 characters, since RedHat's (and possibly other distros') xendomains script has trouble with longer names.

This is one of the few non-optional directives. Every domain needs a name.

on_shutdown

on_reboot

on_crash

These three commands control how the domain will react to various halt states -- on_shutdown for graceful shutdowns, on_reboot for graceful reboot, and on_crash for when the domain crashes.

Allowed values are . . . [FIXME what?]

on_xend_start= ignore|start on_xen_xend_stop=ignore|shutdown|suspend

Similarly, these two items control how the domain will react to xend exiting.

Since xend sometimes needs to be restarted, we leave these at "ignore", which is the default.

bootloader

The bootloader line specifies a program that will be run within dom0 to load and initialize the domain kernel. For example, you can specify bootloader=pygrub to get a domain that, on startup, presents a GRUB-like boot menu.

bootargs

This is a list of arguments to pass to the boot loader.

For example, to tell Pygrub to load a particular kernel image, you can specify bootargs='kernel=vmlinuz-2.6.24'

vif

The vif directive tells Xen about the domain's virtual network devices.

Allowable options in the vifs line are 'backend', 'bridge', 'ip', 'mac', 'script', 'type', 'vifname', 'rate', 'model', 'accel', 'policy', and 'label'

Each vif specification can include many options, including bridge, ip, and mac. For more information on these, see chapter 5, "networking."

disk

The disk line specifies one (or more) virtual disk devices. Almost all domains will need at least one, although it's not a requirement as far as Xen's concerned.

Each definition is a stanza in the list, each of which has three terms: backend device, frontend device, and mode.

uname, dev, mode, backend, protocol [FIXME define]

We go into considerably more detail on the various types of storage in chapter 4, "storage."

nics

This option is deprecated, but you may see it referenced in other documentation -- it specifies the number of virtual NICs allocated to the domain. In practice, we always just rely on the number of vif stanzas to implicitly declare the NICs.

vfb

vfb = [type='vnc' vncunused=1]

In this case, we specify a VNC virtual framebuffer, which uses the first unused port in the VNC range. (The default behavior is to use the base VNC port + domain ID as the listen port for each domain's virtual framebuffer.)

Valid options for the vfb line are: 'vnclisten', 'vncunused', 'vncdisplay', 'display', 'videoram', 'xauthority', 'type', 'vncpasswd', 'opengl', and 'keymap'

We discuss more details about virtual framebuffers in Chapter 14, Tips, and a bit in 12, HVM.

See the vnc= option for an alternative syntax.

vnc

Set vnc to 1 to enable the VNC console.

vncpasswd

vncpasswd="Swordfish"

Sets the password for the VNC console to the given value. Note that this is independent of any authentication that the domU does.

[note: Terry Pratchett, in "Night Watch", has this to say on the subject of passwords: "/Every/ password was "swordfish"! Whenever anyone tried to think of a word that no one would ever guess, they /always/ chose "swordfish." It was just one of those strange quirks of the human mind.]

vncconsole

Set this to either "no" or "yes". Synonyms such as "yeah" or "sure" will not work. If "yes", automatically spawns a VNC viewer and connects to the domain console when the domain starts up.

vncdisplay

This specifies a VNC display to use. By default, VNC will attach to the display number that corresponds to the domain ID.

vnclisten

Specifies an IP address on which to listen for incoming VNC connections.

vncunused

Tells the domain to use the first unused vnc display. Otherwise, by default, display=domain ID.

videoram

The videoram option specifies the maximum amount of memory that a PV domain may use for its frame buffer.

sdl

Xen supports an SDL console as well as the VNC console -- although not both at the same time.

opengl

Whether the domain's virtual video card should support OpenGL. Note that this is an unaccelerated, software-only form of OpenGL support.

builder

This defaults to "Linux", which is the paravirtualized Linux (and other Unix-like OSes) domain builder.

Ordinarily you will either leave this option blank or specify HVM. Other domain builders are generally regarded as historical curiosities.

cpu

This option specifies the physical CPU that the domain should run VCPU0 on.

cpus

The cpus option specifies a list of CPUs that the domain may use. The syntax of the list is fairly expressive. For example

cpus = "0-3,5,^1"

specifies 0, 2, 3, and 5 while excluding CPU 1.

vcpus

This specifies the number of virtual CPUs to report to the domain. For performance reasons, we strongly recommend that this be equal to or fewer than the number of physical CPU cores that the domain can run on.

vcpu_avail

vcpu_avail=VCPUS

[FIXME look for examples.]

cpu_cap *

Specifies a maximum share of the CPU time for the domain, expressed in hundredths of a CPU.

cpu_weight *

This specifies the domain's weight for the credit scheduler, just like the xm sched-credit -w command. For example:

cpu_weight = 1024

will give the domain four times as much weight as the default. We talk more about CPU weight in Chapter 7, Hosting.

rtc_offset

rtc_offset allows you to specify an offset from the machine's real-time clock for the guest domain.

hpet

Enable virtual high-precision event timer.


root

This specifies the root device for the domain.


extra

The extra option specifies a string which is appended, unchanged, to the domU kernel options. For example, to boot the domU in single user mode:

extra = "s"

nfs_server

nfs_root

These two arguments are used by the kernel when booting via NFS. We describe setting up an NFS root in Chapter 4, "Storage."

dhcp

This directive is also only needed if the kernel is getting its IP at boot -- usually because you're using an NFS root device.

Ordinary DHCP is handled from within the domain by standard userspace daemons, and so the DHCP directive is not required.

uuid

The Xenstore requires a UUID to, as the name suggests, uniquely identify a domain. If you don't specify one, it'll be generated for you. The odds of collision are low enough that we don't bother, but you may find it useful, if, for example, you want to encode additional information into your UUID.

HVM directives

builder

With HVM domains, you'll use the "HVM" domain builder. With most paravirtualized domains, you'll want the default "Linux" domain builder.

We talk a bit about the domain builder in chapter 15, "troubleshooting," if you're interested. However, since we're focusing on the serious day-to-day business of administering Xen, it's a bit low-level. For the most part, we are content to let it do its thing.

loader

loader=FILE

Path to HVM firmware. Now you know as much as I do. [FIXME]

pae

Enable or disable PAE on an HVM domain. Note that this won't enable a non-PAE kernel to run on a PAE or 64-bit box.

device_model

The device_model directive specifies the full path of the executable being used to emulate devices for HVM domains (and for PV domains if the framebuffer's being used.) In most situations, the default qemu-dm should work fine.

There are some directives that specify options for the device model.

fda

fda=FILE

The disk image or device file used to emulate the first floppy drive.

fdb

fdb=FILE

The disk image or device file used to emulate the second floppy drive.

serial

serial=FILE

monitor

If monitor is set to "yes", the device model will attach the QEMU monitor, which you can use to give commands to the device model.

Use ctrl+alt+2 to connect to the monitor. From there, you can issue commands -- try "help".

localtime

This is a simple boolean option indicating whether the hardware clock is set to local time or GMT.

keymap

The keymap option specifies a keymap file. Xen (or rather, the device model) keeps its keymaps under /usr/share/xen/qemu/keymaps . On our machines, the default is en-us.

usb

Boolean value indicating whether to emulate USB.

usbdevice

This item indicates the name of the USB device to add.

guest_os_type

This is the type of the guest OS. It's a freeform identifier, limited to 8 characters.

stdvga

If stdvga is set to "yes", the device model will use standard VGA emulation. If it's set to "no" or omitted, it'll use emulated Cirrus Logic graphics instead.

boot

Set boot to one of a, b, c, or d to boot from the first floppy, second floppy, hard drive, or cdrom drive respectively.

nographic

Indicates whether the device model should use graphics.

soundhw

Indicates whether to emulate an audio device.

feature

This is a pipe-separated list of features to enable in the guest kernel. The list of available features, fresh from the source, is as follows:

[XENFEAT_writable_page_tables] = "writable_page_tables", [XENFEAT_writable_descriptor_tables] = "writable_descriptor_tables",

	    [XENFEAT_auto_translated_physmap]    = "auto_translated_physmap",

[XENFEAT_supervisor_mode_kernel] = "supervisor_mode_kernel",

	    [XENFEAT_pae_pgdir_above_4gb]        = "pae_pgdir_above_4gb"

We have always had good luck using the defaults for this option.

blkif

netif

tpmif

These three variables are all booleans -- if enabled, the builder will make the domain a backend for the specified device type.

With a non-dom0 backend, specify the 'backend' parameter in the definition for your device of choice.

pci=BUS:DEV.FUNC

Adds a PCI device to the domain, using the given parameters (which can be found with lspci in the dom0).

We give an example of PCI forwarding in Chapter 15, Tips.

vscsi=PDEV,VDEV,DOM *

Adds a SCSI device to the domain.

The paravirtualized SCSI devices are a mechanism for passing a physical SCSI generic device through to a domain. It's not meant to replace the Xen block driver.

ioports=FROM-TO

irq=IRQ

vtpm=instance=INSTANCE,backend=DOM,type=TYPE

access_control_policy=POLICY,label=LABEL

hap

This directive tells the domain whether or not to take advantage of Hardware-Assisted Paging on recent machines.

[FIXME HVM only?]

XML config file format

The gratuitiously different XML format may appeal to those who don't hold that configuration files are a good place to keep executable code.