Xm config reference
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]
- 1 List of directives
- 2 kernel
- 3 ramdisk
- 4 maxmem
- 5 memory
- 6 shadow_memory
- 7 name
- 8 on_shutdown
- 9 on_reboot
- 10 on_crash
- 11 bootloader
- 12 bootargs
- 13 vif
- 14 disk
- 15 nics
- 16 vfb
- 17 vnc
- 18 vncpasswd
- 19 vncconsole
- 20 vncdisplay
- 21 vnclisten
- 22 vncunused
- 23 videoram
- 24 sdl
- 25 opengl
- 26 builder
- 27 cpu
- 28 cpus
- 29 vcpus
- 30 vcpu_avail
- 31 cpu_cap *
- 32 cpu_weight *
- 33 rtc_offset
- 34 hpet
- 35 root
- 36 extra
- 37 nfs_server
- 38 dhcp
- 39 uuid
- 40 builder
- 41 loader
- 42 pae
- 43 device_model
- 44 fda
- 45 fdb
- 46 serial
- 47 monitor
- 48 localtime
- 49 keymap
- 50 usb
- 51 usbdevice
- 52 guest_os_type
- 53 stdvga
- 54 boot
- 55 nographic
- 56 soundhw
- 57 feature
- 58 blkif
- 59 netif
- 60 tpmif
- 61 pci=BUS:DEV.FUNC
- 62 vscsi=PDEV,VDEV,DOM *
- 63 ioports=FROM-TO
- 64 irq=IRQ
- 65 vtpm=instance=INSTANCE,backend=DOM,type=TYPE
- 66 access_control_policy=POLICY,label=LABEL
- 67 hap
- 68 XML config file format
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.
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.]
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.
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.
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.
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.
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.
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.
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.
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'
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."
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."
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 = [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.
Set vnc to 1 to enable the VNC console.
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.]
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.
This specifies a VNC display to use. By default, VNC will attach to the display number that corresponds to the domain ID.
Specifies an IP address on which to listen for incoming VNC connections.
Tells the domain to use the first unused vnc display. Otherwise, by default, display=domain ID.
The videoram option specifies the maximum amount of memory that a PV domain may use for its frame buffer.
Xen supports an SDL console as well as the VNC console -- although not both at the same time.
Whether the domain's virtual video card should support OpenGL. Note that this is an unaccelerated, software-only form of OpenGL support.
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.
This option specifies the physical CPU that the domain should run VCPU0 on.
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.
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.
[FIXME look for examples.]
Specifies a maximum share of the CPU time for the domain, expressed in hundredths of a CPU.
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 allows you to specify an offset from the machine's real-time clock for the guest domain.
Enable virtual high-precision event timer.
This specifies the root device for the domain.
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"
These two arguments are used by the kernel when booting via NFS. We describe setting up an NFS root in Chapter 4, "Storage."
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.
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.
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.
Path to HVM firmware. Now you know as much as I do. [FIXME]
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.
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.
The disk image or device file used to emulate the first floppy drive.
The disk image or device file used to emulate the second floppy drive.
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".
This is a simple boolean option indicating whether the hardware clock is set to local time or GMT.
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.
Boolean value indicating whether to emulate USB.
This item indicates the name of the USB device to add.
This is the type of the guest OS. It's a freeform identifier, limited to 8 characters.
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.
Set boot to one of a, b, c, or d to boot from the first floppy, second floppy, hard drive, or cdrom drive respectively.
Indicates whether the device model should use graphics.
Indicates whether to emulate an audio device.
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.
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.
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.
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.
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.