[Xen-changelog] updates to xmdomain.cfg.5 man page to document most used options, and

[Xen patchbot -unstable <patchbot-unstable@xxxxxxxxxxxxxxxxxxx>]

# HG changeset patch
# User sean@xxxxxxxxx
# Node ID d02fd103cbc603f4de0175a7c436de85c8704ff4
# Parent  ab845d97de72813985aa5ee1af4730a088c1d3e0
updates to xmdomain.cfg.5 man page to document most used options, and
provide a basic template for examples

diff -r ab845d97de72 -r d02fd103cbc6 docs/man/xmdomain.cfg.pod.5
--- a/docs/man/xmdomain.cfg.pod.5       Fri Nov 18 12:00:13 2005
+++ b/docs/man/xmdomain.cfg.pod.5       Fri Nov 18 12:01:30 2005
@@ -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<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.
-
-/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<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 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 @@
 
 =over 4
 
-=item I<kernel>
-
-The kernel image used in the domain.
-
-=item I<ramdisk>
-
-The initial ramdisk to be used in the domain.  Default xen domU
-kernels do not usually need a ramdisk.
-
-=item I<memory>
-
-The amount of memory, in megabytes to allocate to the domain when it
+=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>.
+
+
+=item B<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 B<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.
-
-=item I<name>
-
-A unique name for the domain.  You can not create 2 domains with the
-same name.
-
-=item I<root>
-
-Root stanza for the domain (required for Linux domains).
-
-=item I<disk>
-
-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<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 B<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".
+
+=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.
+
+=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
+
+=item B<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, ..."
+
+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
 
-=over 4
-
-=item I<builder>
-
-=back 
+The following options are also supported in the config file, though
+are far more rarely used.
+
+=over 4
+
+=item B<builder>
+
+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 @@
 
 =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 @@
 
 =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 @@
 
 =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)

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog