Signed off by: Sean Dague xmdomain.cfg.pod.5 | 257 +++++++++++++++++++++++++++++++++++++++++------------ 1 files changed, 201 insertions(+), 56 deletions(-) # HG changeset patch # User sean@xxxxxxxxx # Node ID 53d4810efe476ee3f704d9df719a90133351fe75 # Parent 1607effa1bc6a56abc035ca7d3168f982d0d270d updates to xmdomain.cfg.5 man page to document most used options, and provide a basic template for examples diff -r 1607effa1bc6 -r 53d4810efe47 docs/man/xmdomain.cfg.pod.5 --- a/docs/man/xmdomain.cfg.pod.5 Thu Nov 17 14:50:45 2005 -0500 +++ b/docs/man/xmdomain.cfg.pod.5 Thu Nov 17 17:00:56 2005 -0500 @@ -1,6 +1,6 @@ =head1 NAME -xmdomain.cfg - xm domain create config file format +xmdomain.cfg - xm domain config file format =head1 SYNOPSIS @@ -10,17 +10,22 @@ =head1 DESCRIPTION -The xm(1) program uses python executable config files to define +The B(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, though the -full path to the config file must be specified in the I -command, so they can exist anywhere in the filesystem. - -/etc/xen/auto is a special case however, as domain config files in -that directory will be started automatically at system boot if the -xendomain init script is enabled. +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 I 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 I to be +used without full paths. + +Options are specified by I statements in the +xmdomain.cfg files. =head1 OPTIONS @@ -29,50 +34,157 @@ =over 4 -=item I - -The kernel image used in the domain. - -=item I - -The initial ramdisk to be used in the domain. Default xen domU -kernels do not usually need a ramdisk. - -=item I - -The amount of memory, in megabytes to allocate to the domain when it +=item B + +The kernel image for the domain. The format of the parameter is the +fully qualified path to the kernel image file, +i.e. I. + + +=item B + +The initial ramdisk for the domain. The format of the parameter is +the fully qualified path to the initrd, i.e. I. On +many Linux distros you will not need a ramdisk if using the default +xen kernel. + +=item B + +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. - -=item I - -A unique name for the domain. You can not create 2 domains with the -same name. - -=item I - -Root stanza for the domain (required for Linux domains). - -=item I - -An array of disk stanzas - -=back - -A bare minimal config file example might be as follows: - - kernel = "/boot/vmlinuz-2.6-xenU" - memory = 128 - name = "MyLinux" - root = "/dev/hda1 ro" +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. + +=item B + +A unique name for the domain. Attempting to create two domains with +the same name will cause an error. + +=item B + +Specifies the root device for the domain. This is required for Linux +domains, and possibly other OSes. + +=item B + +The number of network interfaces allocated to the domain on boot. It +defaults to 1. + +=item B + +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". + +=over 4 + +=item I + +The device in the backend domain that will be exported to the guest +(frontend) domain. Supported formats include: + +I - 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). + +I - export the file listed as a loopback device. +This will take care of the loopback setup before exporting the device. + +=item I + +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). + +=item I + +The access mode for the device. There are currently 2 valid options, +I (read-only), I (read/write). + +=back + +=item B + +An arrray of virtual interface stanzas in the form: + + vif = [ "stanza1", "stanza2", ... ] + +Each stanza specifies a set of I options separated by +commas, in the form: "name1=value1, name2=value2, ..." + +B + +=over 4 + +=item I + +The network bridge to be used for this device. This is especially +needed if multiple bridges exist on the machine. + +=item I + +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. + +=back + +=back =head1 ADDITIONAL OPTIONS -=over 4 - -=item I - -=back +The following options are also supported in the config file, though +are far more rarely used. + +=over 4 + +=item B + +Which builder should be used to construct the domain. This defaults +to the I if not specified, which is the builder for +paravirtualized Linux domains. + +=item B + +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. + +=item B + +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. + +=item B + +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 I, +and specify I. + +=item B + +The directory on the NFS server to be used as the root filesystem. +Specified as a fully qualified path, i.e. I. + +=item B + +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. + +=back =head1 DOMAIN SHUTDOWN OPTIONS @@ -81,17 +193,17 @@ =over 4 -=item I +=item B Triggered on either an I or graceful shutdown from inside the DomU. -=item I +=item B Triggered on either an I or graceful reboot from inside the DomU. -=item I +=item B Triggered when a DomU goes to the crashed state for any reason. @@ -101,23 +213,23 @@ =over 4 -=item I +=item B The domain will be cleaned up completely. No attempt at respawning will occur. This is what a typical shutdown would look like. -=item I +=item B The domain will be restarted with the same name as the old domain. This is what a typical reboot would look like. -=item I +=item B 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. -=item I +=item B 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 @@ -127,6 +239,39 @@ =back +=head1 EXAMPLES + +The following are quick examples of ways that domains might be +configured. They should not be considered an exhaustive set. + +=over 4 + +=item I + + 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. + +=item I + +FIXME: write me + +=item I + +FIXME: write me + +=item I + +FIXME: write me + +=back + =head1 SEE ALSO B(1)