NAME

       xmdomain.cfg - xm domain config file format

SYNOPSIS

        /etc/xen/myxendomain
        /etc/xen/myxendomain2
        /etc/xen/auto/myxenautostarted

DESCRIPTION

       The 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, if you store config files anywhere
       else the full path to the config file must be specified in the 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 xm create to be used
       without full paths.

       Options are specified by name = value statements in the xmdomain.cfg files.

OPTIONS

       The following lists the most commonly used options for a domain config file.

       kernel
           The kernel image for the domain.  The format of the parameter is the fully qualified
           path to the kernel image file, i.e. /boot/vmlinuz-2.6.12-xenU.

       ramdisk
           The initial ramdisk for the domain.  The format of the parameter is the fully
           qualified path to the initrd, i.e. /boot/initrd.gz.  On many Linux distros you will
           not need a ramdisk if using the default xen kernel.

       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.  If there
           isn't enough free memory left on the machine to fulfil 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.

       name
           A unique name for the domain.  Attempting to create two domains with the same name
           will cause an error.

       root
           Specifies the root device for the domain.  This is required for Linux domains, and
           possibly other OSes.

       nics
           The number of network interfaces allocated to the domain on boot.  It defaults to 1.

       disk
           An array of block device stanzas, in the form:

               disk = [ "stanza1", "stanza2", ... ]

           Each stanza has 3 terms, separated by commas, "backend-dev,frontend-dev,mode".

           backend-dev
               The device in the backend domain that will be exported to the guest (frontend)
               domain.  Supported formats include:

               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).

               file://path/to/file - export the file listed as a loopback device.  This will take
               care of the loopback setup before exporting the device.

           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).

           mode
               The access mode for the device.  There are currently 2 valid options, r (read-
               only), w (read/write).

       vif An array of virtual interface stanzas in the form:

               vif = [ "stanza1", "stanza2", ... ]

           Each stanza specifies a set of name = value options separated by commas, in the form:
           "name1=value1, name2=value2, ..."

           OPTIONS

           bridge
               The network bridge to be used for this device.  This is especially needed if
               multiple bridges exist on the machine.

           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.

       vfb A virtual frame buffer stanza in the form:

               vfb = [ "stanza" ]

           The stanza specifies a set of name = value options separated by commas, in the form:
           "name1=value1, name2=value2, ..."

           OPTIONS

           type
               There are currently two valid options: vnc starts a VNC server that lets you
               connect an external VNC viewer, and sdl starts an internal viewer.

           vncdisplay
               The VNC display number to use, defaults to the domain ID.  The VNC server listens
               on port 5900 + display number.

           vnclisten
               The listening address for the VNC server, default 127.0.0.1.

           vncunused
               If non-zero, the VNC server listens on the first unused port above 5900.

           vncpasswd
               Overrides the XenD configured default password.

           display
               Display to use for the internal viewer, defaults to environment variable DISPLAY.

           xauthority
               Authority file to use for the internal viewer, defaults to environment variable
               XAUTHORITY.

ADDITIONAL OPTIONS

       The following options are also supported in the config file, though are far more rarely
       used.

       builder
           Which builder should be used to construct the domain.  This defaults to the linux if
           not specified, which is the builder for paravirtualized Linux domains.

       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.

       cpus
           Specifies a list of CPUs on which the domains' VCPUs are allowed to execute upon.  The
           syntax supports ranges (0-3), and negation, ^1.  For instance:

               cpus = "0-3,5,^1"

           Will result in CPUs 0, 2, 3, 5 being available for use by the domain.

       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.

       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 root=/dev/nfs, and specify nfs_root.

       nfs_root
           The directory on the NFS server to be used as the root filesystem.  Specified as a
           fully qualified path, i.e. /full/path/to/root/dir.

       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.

DOMAIN SHUTDOWN OPTIONS

       There are 3 options which control domain shutdown (both planned and unplanned) under
       certain events.  The 3 events currently captured are:

       on_shutdown
           Triggered on either an xm shutdown or graceful shutdown from inside the DomU.

       on_reboot
           Triggered on either an xm reboot or graceful reboot from inside the DomU.

       on_crash
           Triggered when a DomU goes to the crashed state for any reason.

       All of them take one of 4 valid states listed below.

       destroy
           The domain will be cleaned up completely.  No attempt at respawning will occur.  This
           is what a typical shutdown would look like.

       restart
           The domain will be restarted with the same name as the old domain.  This is what a
           typical reboot would look like.

       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.

       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 a suffix -1, -2, etc,
           and assigned a new random UUID; the new domain will keep the original name and UUID.
           The old domain will release the devices that it holds, so that the new one may take
           them.

       Additionally, the "on_crash" event can also take:

       coredump-destroy
           Dump the crashed domain's core and then destroy it.

       coredump-restart
           Dump the crashed domain's core and then restart it.

EXAMPLES

       The following are quick examples of ways that domains might be configured.  They should
       not be considered an exhaustive set.

       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.

       NFS Root
           FIXME: write me

       LVM Root
           FIXME: write me

       Two Networks
           FIXME: write me

SEE ALSO

       xm(1)

AUTHOR

         Sean Dague <sean at dague dot net>

BUGS

       Not all options are currently documented