diff options
author | sean@dague.net <sean@dague.net> | 2005-11-18 13:01:30 +0100 |
---|---|---|
committer | sean@dague.net <sean@dague.net> | 2005-11-18 13:01:30 +0100 |
commit | 1443ca6d8c25047b73aec6699ca72c6d21136804 (patch) | |
tree | 54e43809ef0eb4f9be9bd0fbca232a079943ff54 /docs/man/xmdomain.cfg.pod.5 | |
parent | e198273e0e055ee90a64252d09c22e8f0df1204f (diff) | |
download | xen-1443ca6d8c25047b73aec6699ca72c6d21136804.tar.gz xen-1443ca6d8c25047b73aec6699ca72c6d21136804.tar.bz2 xen-1443ca6d8c25047b73aec6699ca72c6d21136804.zip |
updates to xmdomain.cfg.5 man page to document most used options, and
provide a basic template for examples
Diffstat (limited to 'docs/man/xmdomain.cfg.pod.5')
-rw-r--r-- | docs/man/xmdomain.cfg.pod.5 | 219 |
1 files changed, 182 insertions, 37 deletions
diff --git a/docs/man/xmdomain.cfg.pod.5 b/docs/man/xmdomain.cfg.pod.5 index 313c3bc4b4..4b9a35a446 100644 --- a/docs/man/xmdomain.cfg.pod.5 +++ b/docs/man/xmdomain.cfg.pod.5 @@ -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 @@ xmdomain.cfg - xm domain create config file format =head1 DESCRIPTION -The xm(1) program uses python executable config files to define +The B<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 by default, though the -full path to the config file must be specified in the I<xm create> -command, so they can exist anywhere in the filesystem. +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<xm create> command. -/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. +/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<xm create> to be +used without full paths. + +Options are specified by I<name = value> statements in the +xmdomain.cfg files. =head1 OPTIONS @@ -29,50 +34,157 @@ file. =over 4 -=item I<kernel> +=item B<kernel> + +The kernel image for the domain. The format of the parameter is the +fully qualified path to the kernel image file, +i.e. I</boot/vmlinuz-2.6.12-xenU>. -The kernel image used in the domain. -=item I<ramdisk> +=item B<ramdisk> -The initial ramdisk to be used in the domain. Default xen domU -kernels do not usually need a ramdisk. +The initial ramdisk for the domain. The format of the parameter is +the fully qualified path to the initrd, i.e. I</boot/initrd.gz>. On +many Linux distros you will not need a ramdisk if using the default +xen kernel. -=item I<memory> +=item B<memory> -The amount of memory, in megabytes to allocate to the domain when it +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. +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<name> + +A unique name for the domain. Attempting to create two domains with +the same name will cause an error. + +=item B<root> + +Specifies the root device for the domain. This is required for Linux +domains, and possibly other OSes. + +=item B<nics> + +The number of network interfaces allocated to the domain on boot. It +defaults to 1. -=item I<name> +=item B<disk> -A unique name for the domain. You can not create 2 domains with the -same name. +An array of block device stanzas, in the form: -=item I<root> + disk = [ "stanza1", "stanza2", ... ] -Root stanza for the domain (required for Linux domains). +Each stanza has 3 terms, seperated by commas, +"backend-dev,frontend-dev,mode". -=item I<disk> +=over 4 + +=item I<backend-dev> + +The device in the backend domain that will be exported to the guest +(frontend) domain. Supported formats include: + +I<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). + +I<file://path/to/file> - export the file listed as a loopback device. +This will take care of the loopback setup before exporting the device. -An array of disk stanzas +=item I<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). + +=item I<mode> + +The access mode for the device. There are currently 2 valid options, +I<r> (read-only), I<w> (read/write). =back -A bare minimal config file example might be as follows: +=item B<vif> - kernel = "/boot/vmlinuz-2.6-xenU" - memory = 128 - name = "MyLinux" - root = "/dev/hda1 ro" +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, ..." + +B<OPTIONS> + +=over 4 + +=item I<bridge> + +The network bridge to be used for this device. This is especially +needed if multiple bridges exist on the machine. + +=item I<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. + +=back + +=back =head1 ADDITIONAL OPTIONS +The following options are also supported in the config file, though +are far more rarely used. + =over 4 -=item I<builder> +=item B<builder> -=back +Which builder should be used to construct the domain. This defaults +to the I<linux> if not specified, which is the builder for +paravirtualized Linux domains. + +=item B<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. + +=item B<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. + +=item B<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 I<root=/dev/nfs>, +and specify I<nfs_root>. + +=item B<nfs_root> + +The directory on the NFS server to be used as the root filesystem. +Specified as a fully qualified path, i.e. I</full/path/to/root/dir>. + +=item B<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. + +=back =head1 DOMAIN SHUTDOWN OPTIONS @@ -81,17 +193,17 @@ unplanned) under certain events. The 3 events currently captured are: =over 4 -=item I<shutdown> +=item B<on_shutdown> Triggered on either an I<xm shutdown> or graceful shutdown from inside the DomU. -=item I<reboot> +=item B<on_reboot> Triggered on either an I<xm reboot> or graceful reboot from inside the DomU. -=item I<crash> +=item B<on_crash> Triggered when a DomU goes to the crashed state for any reason. @@ -101,23 +213,23 @@ All of them take one of 4 valid states listed below. =over 4 -=item I<destroy> +=item B<destroy> The domain will be cleaned up completely. No attempt at respawning will occur. This is what a typical shutdown would look like. -=item I<restart> +=item B<restart> The domain will be restarted with the same name as the old domain. This is what a typical reboot would look like. -=item I<preserve> +=item B<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. -=item I<rename-restart> +=item B<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 @@ -127,6 +239,39 @@ it holds, so that the new one may take them. =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<A Loopback File as Root> + + 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<NFS Root> + +FIXME: write me + +=item I<LVM Root> + +FIXME: write me + +=item I<Two Networks> + +FIXME: write me + +=back + =head1 SEE ALSO B<xm>(1) |