ia64/xen-unstable

changeset 7892:d02fd103cbc6

updates to xmdomain.cfg.5 man page to document most used options, and
provide a basic template for examples
author sean@dague.net
date Fri Nov 18 13:01:30 2005 +0100 (2005-11-18)
parents ab845d97de72
children 74d4d3be6b0a
files docs/man/xmdomain.cfg.pod.5
line diff
     1.1 --- a/docs/man/xmdomain.cfg.pod.5	Fri Nov 18 13:00:13 2005 +0100
     1.2 +++ b/docs/man/xmdomain.cfg.pod.5	Fri Nov 18 13:01:30 2005 +0100
     1.3 @@ -1,6 +1,6 @@
     1.4  =head1 NAME
     1.5  
     1.6 -xmdomain.cfg - xm domain create config file format
     1.7 +xmdomain.cfg - xm domain config file format
     1.8  
     1.9  =head1 SYNOPSIS
    1.10  
    1.11 @@ -10,17 +10,22 @@ xmdomain.cfg - xm domain create config f
    1.12  
    1.13  =head1 DESCRIPTION
    1.14  
    1.15 -The xm(1) program uses python executable config files to define
    1.16 +The B<xm>(1) program uses python executable config files to define
    1.17  domains to create from scratch.  Each of these config files needs to
    1.18  contain a number of required options, and may specify many more.
    1.19  
    1.20 -Domain configuration files live in /etc/xen by default, though the
    1.21 -full path to the config file must be specified in the I<xm create>
    1.22 -command, so they can exist anywhere in the filesystem.
    1.23 +Domain configuration files live in /etc/xen by default, if you store
    1.24 +config files anywhere else the full path to the config file must be
    1.25 +specified in the I<xm create> command.
    1.26  
    1.27 -/etc/xen/auto is a special case however, as domain config files in
    1.28 -that directory will be started automatically at system boot if the
    1.29 -xendomain init script is enabled.
    1.30 +/etc/xen/auto is a special case.  Domain config files in that
    1.31 +directory will be started automatically at system boot if the
    1.32 +xendomain init script is enabled.  The contents of /etc/xen/auto
    1.33 +should be symlinks to files in /etc/xen to allow I<xm create> to be
    1.34 +used without full paths.
    1.35 +
    1.36 +Options are specified by I<name = value> statements in the
    1.37 +xmdomain.cfg files.
    1.38  
    1.39  =head1 OPTIONS
    1.40  
    1.41 @@ -29,50 +34,157 @@ file.
    1.42  
    1.43  =over 4
    1.44  
    1.45 -=item I<kernel>
    1.46 +=item B<kernel>
    1.47  
    1.48 -The kernel image used in the domain.
    1.49 +The kernel image for the domain.  The format of the parameter is the
    1.50 +fully qualified path to the kernel image file,
    1.51 +i.e. I</boot/vmlinuz-2.6.12-xenU>.
    1.52  
    1.53 -=item I<ramdisk>
    1.54 +
    1.55 +=item B<ramdisk>
    1.56  
    1.57 -The initial ramdisk to be used in the domain.  Default xen domU
    1.58 -kernels do not usually need a ramdisk.
    1.59 +The initial ramdisk for the domain.  The format of the parameter is
    1.60 +the fully qualified path to the initrd, i.e. I</boot/initrd.gz>.  On
    1.61 +many Linux distros you will not need a ramdisk if using the default
    1.62 +xen kernel.
    1.63  
    1.64 -=item I<memory>
    1.65 +=item B<memory>
    1.66  
    1.67 -The amount of memory, in megabytes to allocate to the domain when it
    1.68 +The amount of RAM, in megabytes, to allocate to the domain when it
    1.69  starts.  Allocating insufficient memory for a domain may produce
    1.70 -extremely bizarre behavior.
    1.71 +extremely bizarre behavior.  If there isn't enough free memory left on
    1.72 +the machine to fulfill this request, the domain will fail to start.
    1.73 +
    1.74 +Xen does not support overcommit of memory, so the total memory of all
    1.75 +guests (+ 64 MB needed for Xen) must be less than or equal to the
    1.76 +physical RAM in the machine.
    1.77 +
    1.78 +=item B<name>
    1.79 +
    1.80 +A unique name for the domain.  Attempting to create two domains with
    1.81 +the same name will cause an error.
    1.82 +
    1.83 +=item B<root>
    1.84  
    1.85 -=item I<name>
    1.86 +Specifies the root device for the domain.  This is required for Linux
    1.87 +domains, and possibly other OSes.
    1.88 +
    1.89 +=item B<nics>
    1.90  
    1.91 -A unique name for the domain.  You can not create 2 domains with the
    1.92 -same name.
    1.93 +The number of network interfaces allocated to the domain on boot.  It
    1.94 +defaults to 1.
    1.95 +
    1.96 +=item B<disk>
    1.97 +
    1.98 +An array of block device stanzas, in the form:
    1.99 +
   1.100 +    disk = [ "stanza1", "stanza2", ... ]
   1.101  
   1.102 -=item I<root>
   1.103 +Each stanza has 3 terms, seperated by commas,
   1.104 +"backend-dev,frontend-dev,mode".
   1.105 +
   1.106 +=over 4
   1.107 +
   1.108 +=item I<backend-dev>
   1.109  
   1.110 -Root stanza for the domain (required for Linux domains).
   1.111 +The device in the backend domain that will be exported to the guest
   1.112 +(frontend) domain.  Supported formats include:
   1.113 +
   1.114 +I<phy:device> - export the physical device listed.  The device can be
   1.115 +in symbolic form, as in sda7, or as the hex major/minor number, as in
   1.116 +0x301 (which is hda1).
   1.117  
   1.118 -=item I<disk>
   1.119 +I<file://path/to/file> - export the file listed as a loopback device.
   1.120 +This will take care of the loopback setup before exporting the device.
   1.121 +
   1.122 +=item I<frontend-dev>
   1.123  
   1.124 -An array of disk stanzas 
   1.125 +How the device should appear in the guest domain.  The device can be
   1.126 +in symbolic form, as in sda7, or as the hex major/minor number, as in
   1.127 +0x301 (which is hda1).
   1.128 +
   1.129 +=item I<mode>
   1.130 +
   1.131 +The access mode for the device.  There are currently 2 valid options,
   1.132 +I<r> (read-only), I<w> (read/write).
   1.133  
   1.134  =back
   1.135  
   1.136 -A bare minimal config file example might be as follows:
   1.137 +=item B<vif>
   1.138 +
   1.139 +An arrray of virtual interface stanzas in the form:
   1.140 +
   1.141 +    vif = [ "stanza1", "stanza2", ... ]
   1.142 +
   1.143 +Each stanza specifies a set of I<name = value> options separated by
   1.144 +commas, in the form: "name1=value1, name2=value2, ..."
   1.145 +
   1.146 +B<OPTIONS>
   1.147 +
   1.148 +=over 4
   1.149  
   1.150 -    kernel = "/boot/vmlinuz-2.6-xenU"
   1.151 -    memory = 128
   1.152 -    name = "MyLinux"      
   1.153 -    root = "/dev/hda1 ro"
   1.154 +=item I<bridge>
   1.155 +
   1.156 +The network bridge to be used for this device.  This is especially
   1.157 +needed if multiple bridges exist on the machine.
   1.158 +
   1.159 +=item I<mac>
   1.160 +
   1.161 +The MAC address for the virtual interface.  If mac is not specified,
   1.162 +one will be randomly chosen by xen with the 00:16:3e vendor id prefix.
   1.163 +
   1.164 +=back
   1.165 +
   1.166 +=back
   1.167  
   1.168  =head1 ADDITIONAL OPTIONS
   1.169  
   1.170 +The following options are also supported in the config file, though
   1.171 +are far more rarely used.
   1.172 +
   1.173  =over 4
   1.174  
   1.175 -=item I<builder>
   1.176 +=item B<builder>
   1.177 +
   1.178 +Which builder should be used to construct the domain.  This defaults
   1.179 +to the I<linux> if not specified, which is the builder for
   1.180 +paravirtualized Linux domains.
   1.181 +
   1.182 +=item B<cpu>
   1.183 +
   1.184 +Specifies which CPU the domain should be started on, where 0 specifies
   1.185 +the first cpu, 1 the second, and so on.  This defaults to -1, which
   1.186 +means Xen is free to pick which CPU to start on.
   1.187 +
   1.188 +=item B<extra>
   1.189 +
   1.190 +Extra information to append to the end of the kernel parameter line.
   1.191 +The format is a string, the contents of which can be anything that the
   1.192 +kernel supports.  For instance:
   1.193 +
   1.194 +    extra = "4"
   1.195  
   1.196 -=back 
   1.197 +Will cause the domain to boot to runlevel 4.
   1.198 +
   1.199 +=item B<nfs_server>
   1.200 +
   1.201 +The IP address of the NFS server to use as the root device for the
   1.202 +domain.  In order to do this you'll need to specify I<root=/dev/nfs>,
   1.203 +and specify I<nfs_root>.
   1.204 +
   1.205 +=item B<nfs_root>
   1.206 +
   1.207 +The directory on the NFS server to be used as the root filesystem.
   1.208 +Specified as a fully qualified path, i.e. I</full/path/to/root/dir>.
   1.209 +
   1.210 +=item B<vcpus>
   1.211 +
   1.212 +The number of virtual cpus to allocate to the domain.  In order to use
   1.213 +this the xen kernel must be compiled with SMP support.
   1.214 +
   1.215 +This defaults to 1, meaning running the domain as a UP.
   1.216 +
   1.217 +=back
   1.218  
   1.219  =head1 DOMAIN SHUTDOWN OPTIONS
   1.220  
   1.221 @@ -81,17 +193,17 @@ unplanned) under certain events.  The 3 
   1.222  
   1.223  =over 4
   1.224  
   1.225 -=item I<shutdown>
   1.226 +=item B<on_shutdown>
   1.227  
   1.228  Triggered on either an I<xm shutdown> or graceful shutdown from inside
   1.229  the DomU.
   1.230  
   1.231 -=item I<reboot>
   1.232 +=item B<on_reboot>
   1.233  
   1.234  Triggered on either an I<xm reboot> or graceful reboot from inside the
   1.235  DomU.
   1.236  
   1.237 -=item I<crash>
   1.238 +=item B<on_crash>
   1.239  
   1.240  Triggered when a DomU goes to the crashed state for any reason.
   1.241  
   1.242 @@ -101,23 +213,23 @@ All of them take one of 4 valid states l
   1.243  
   1.244  =over 4
   1.245  
   1.246 -=item I<destroy>
   1.247 +=item B<destroy>
   1.248  
   1.249  The domain will be cleaned up completely.  No attempt at respawning
   1.250  will occur.  This is what a typical shutdown would look like.
   1.251  
   1.252 -=item I<restart>
   1.253 +=item B<restart>
   1.254  
   1.255  The domain will be restarted with the same name as the old domain.
   1.256  This is what a typical reboot would look like.
   1.257  
   1.258 -=item I<preserve>
   1.259 +=item B<preserve>
   1.260  
   1.261  The domain will not be cleaned up at all.  This is often useful for
   1.262  crash state domains which ensures that enough evidence is to debug the
   1.263  real issue.
   1.264  
   1.265 -=item I<rename-restart>
   1.266 +=item B<rename-restart>
   1.267  
   1.268  The old domain will not be cleaned up, but will be renamed so a new
   1.269  domain can be restarted in it's place.  The old domain will be renamed with
   1.270 @@ -127,6 +239,39 @@ it holds, so that the new one may take t
   1.271  
   1.272  =back
   1.273  
   1.274 +=head1 EXAMPLES
   1.275 +
   1.276 +The following are quick examples of ways that domains might be
   1.277 +configured.  They should not be considered an exhaustive set.
   1.278 +
   1.279 +=over 4
   1.280 +
   1.281 +=item I<A Loopback File as Root>
   1.282 +
   1.283 +    kernel = "/boot/vmlinuz-2.6-xenU"
   1.284 +    memory = 128
   1.285 +    name = "MyLinux"      
   1.286 +    root = "/dev/hda1 ro"
   1.287 +    disk = [ "file:/var/xen/mylinux.img,hda1,w" ]
   1.288 +
   1.289 +This creates a domain called MyLinux with 128 MB of memory using a
   1.290 +default xen kernel, and the file /var/xen/mylinux.img loopback mounted
   1.291 +at hda1, which is the root filesystem.
   1.292 +
   1.293 +=item I<NFS Root>
   1.294 +
   1.295 +FIXME: write me
   1.296 +
   1.297 +=item I<LVM Root>
   1.298 +
   1.299 +FIXME: write me
   1.300 +
   1.301 +=item I<Two Networks>
   1.302 +
   1.303 +FIXME: write me
   1.304 +
   1.305 +=back
   1.306 +
   1.307  =head1 SEE ALSO
   1.308  
   1.309  B<xm>(1)