.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "xmdomain.cfg 5"
.TH xmdomain.cfg 5 "2013-01-22" "xen-unstable" "Xen"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
xmdomain.cfg \- xm domain config file format
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& /etc/xen/myxendomain
\& /etc/xen/myxendomain2
\& /etc/xen/auto/myxenautostarted
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBxm\fR(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.
.PP
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 \fIxm create\fR command.
.PP
/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 \fIxm create\fR to be
used without full paths.
.PP
Options are specified by \fIname = value\fR statements in the
xmdomain.cfg files.
.SH "OPTIONS"
.IX Header "OPTIONS"
The following lists the most commonly used options for a domain config
file.
.IP "\fBkernel\fR" 4
.IX Item "kernel"
The kernel image for the domain.  The format of the parameter is the
fully qualified path to the kernel image file,
i.e. \fI/boot/vmlinuz\-2.6.12\-xenU\fR.
.IP "\fBramdisk\fR" 4
.IX Item "ramdisk"
The initial ramdisk for the domain.  The format of the parameter is
the fully qualified path to the initrd, i.e. \fI/boot/initrd.gz\fR.  On
many Linux distros you will not need a ramdisk if using the default
xen kernel.
.IP "\fBmemory\fR" 4
.IX Item "memory"
The amount of \s-1RAM\s0, 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 fulfill this request, the domain will fail to start.
.Sp
Xen does not support overcommit of memory, so the total memory of all
guests (+ 64 \s-1MB\s0 needed for Xen) must be less than or equal to the
physical \s-1RAM\s0 in the machine.
.IP "\fBname\fR" 4
.IX Item "name"
A unique name for the domain.  Attempting to create two domains with
the same name will cause an error.
.IP "\fBroot\fR" 4
.IX Item "root"
Specifies the root device for the domain.  This is required for Linux
domains, and possibly other OSes.
.IP "\fBnics\fR" 4
.IX Item "nics"
The number of network interfaces allocated to the domain on boot.  It
defaults to 1.
.IP "\fBdisk\fR" 4
.IX Item "disk"
An array of block device stanzas, in the form:
.Sp
.Vb 1
\&    disk = [ "stanza1", "stanza2", ... ]
.Ve
.Sp
Each stanza has 3 terms, separated by commas,
\&\*(L"backend\-dev,frontend\-dev,mode\*(R".
.RS 4
.IP "\fIbackend-dev\fR" 4
.IX Item "backend-dev"
The device in the backend domain that will be exported to the guest
(frontend) domain.  Supported formats include:
.Sp
\&\fIphy:device\fR \- 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).
.Sp
\&\fIfile://path/to/file\fR \- export the file listed as a loopback device.
This will take care of the loopback setup before exporting the device.
.IP "\fIfrontend-dev\fR" 4
.IX Item "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).
.IP "\fImode\fR" 4
.IX Item "mode"
The access mode for the device.  There are currently 2 valid options,
\&\fIr\fR (read-only), \fIw\fR (read/write).
.RE
.RS 4
.RE
.IP "\fBvif\fR" 4
.IX Item "vif"
An array of virtual interface stanzas in the form:
.Sp
.Vb 1
\&    vif = [ "stanza1", "stanza2", ... ]
.Ve
.Sp
Each stanza specifies a set of \fIname = value\fR options separated by
commas, in the form: \*(L"name1=value1, name2=value2, ...\*(R"
.Sp
\&\fB\s-1OPTIONS\s0\fR
.RS 4
.IP "\fIbridge\fR" 4
.IX Item "bridge"
The network bridge to be used for this device.  This is especially
needed if multiple bridges exist on the machine.
.IP "\fImac\fR" 4
.IX Item "mac"
The \s-1MAC\s0 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.
.RE
.RS 4
.RE
.IP "\fBvfb\fR" 4
.IX Item "vfb"
A virtual frame buffer stanza in the form:
.Sp
.Vb 1
\&    vfb = [ "stanza" ]
.Ve
.Sp
The stanza specifies a set of \fIname = value\fR options separated by
commas, in the form: \*(L"name1=value1, name2=value2, ...\*(R"
.Sp
\&\fB\s-1OPTIONS\s0\fR
.RS 4
.IP "\fItype\fR" 4
.IX Item "type"
There are currently two valid options: \fIvnc\fR starts a \s-1VNC\s0 server that
lets you connect an external \s-1VNC\s0 viewer, and \fIsdl\fR starts an internal
viewer.
.IP "\fIvncdisplay\fR" 4
.IX Item "vncdisplay"
The \s-1VNC\s0 display number to use, defaults to the domain \s-1ID\s0.  The
\&\s-1VNC\s0 server listens on port 5900 + display number.
.IP "\fIvnclisten\fR" 4
.IX Item "vnclisten"
The listening address for the \s-1VNC\s0 server, default 127.0.0.1.
.IP "\fIvncunused\fR" 4
.IX Item "vncunused"
If non-zero, the \s-1VNC\s0 server listens on the first unused port above
5900.
.IP "\fIvncpasswd\fR" 4
.IX Item "vncpasswd"
Overrides the XenD configured default password.
.IP "\fIdisplay\fR" 4
.IX Item "display"
Display to use for the internal viewer, defaults to environment
variable \fI\s-1DISPLAY\s0\fR.
.IP "\fIxauthority\fR" 4
.IX Item "xauthority"
Authority file to use for the internal viewer, defaults to environment
variable \fI\s-1XAUTHORITY\s0\fR.
.RE
.RS 4
.RE
.SH "ADDITIONAL OPTIONS"
.IX Header "ADDITIONAL OPTIONS"
The following options are also supported in the config file, though
are far more rarely used.
.IP "\fBbuilder\fR" 4
.IX Item "builder"
Which builder should be used to construct the domain.  This defaults
to the \fIlinux\fR if not specified, which is the builder for
paravirtualized Linux domains.
.IP "\fBcpu\fR" 4
.IX Item "cpu"
Specifies which \s-1CPU\s0 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 \s-1CPU\s0 to start on.
.IP "\fBcpus\fR" 4
.IX Item "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:
.Sp
.Vb 1
\&    cpus = "0\-3,5,^1"
.Ve
.Sp
Will result in CPUs 0, 2, 3, 5 being available for use by the domain.
.IP "\fBextra\fR" 4
.IX Item "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:
.Sp
.Vb 1
\&    extra = "4"
.Ve
.Sp
Will cause the domain to boot to runlevel 4.
.IP "\fBnfs_server\fR" 4
.IX Item "nfs_server"
The \s-1IP\s0 address of the \s-1NFS\s0 server to use as the root device for the
domain.  In order to do this you'll need to specify \fIroot=/dev/nfs\fR,
and specify \fInfs_root\fR.
.IP "\fBnfs_root\fR" 4
.IX Item "nfs_root"
The directory on the \s-1NFS\s0 server to be used as the root filesystem.
Specified as a fully qualified path, i.e. \fI/full/path/to/root/dir\fR.
.IP "\fBvcpus\fR" 4
.IX Item "vcpus"
The number of virtual cpus to allocate to the domain.  In order to use
this the xen kernel must be compiled with \s-1SMP\s0 support.
.Sp
This defaults to 1, meaning running the domain as a \s-1UP\s0.
.SH "DOMAIN SHUTDOWN OPTIONS"
.IX Header "DOMAIN SHUTDOWN OPTIONS"
There are 3 options which control domain shutdown (both planned and
unplanned) under certain events.  The 3 events currently captured are:
.IP "\fBon_shutdown\fR" 4
.IX Item "on_shutdown"
Triggered on either an \fIxm shutdown\fR or graceful shutdown from inside
the DomU.
.IP "\fBon_reboot\fR" 4
.IX Item "on_reboot"
Triggered on either an \fIxm reboot\fR or graceful reboot from inside the
DomU.
.IP "\fBon_crash\fR" 4
.IX Item "on_crash"
Triggered when a DomU goes to the crashed state for any reason.
.PP
All of them take one of 4 valid states listed below.
.IP "\fBdestroy\fR" 4
.IX Item "destroy"
The domain will be cleaned up completely.  No attempt at respawning
will occur.  This is what a typical shutdown would look like.
.IP "\fBrestart\fR" 4
.IX Item "restart"
The domain will be restarted with the same name as the old domain.
This is what a typical reboot would look like.
.IP "\fBpreserve\fR" 4
.IX Item "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.
.IP "\fBrename-restart\fR" 4
.IX Item "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 \s-1UUID\s0; the new domain will
keep the original name and \s-1UUID\s0.  The old domain will release the devices that
it holds, so that the new one may take them.
.PP
Additionally, the \*(L"on_crash\*(R" event can also take:
.IP "\fBcoredump-destroy\fR" 4
.IX Item "coredump-destroy"
Dump the crashed domain's core and then destroy it.
.IP "\fBcoredump-restart\fR" 4
.IX Item "coredump-restart"
Dump the crashed domain's core and then restart it.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The following are quick examples of ways that domains might be
configured.  They should not be considered an exhaustive set.
.IP "\fIA Loopback File as Root\fR" 4
.IX Item "A Loopback File as Root"
.Vb 5
\&    kernel = "/boot/vmlinuz\-2.6\-xenU"
\&    memory = 128
\&    name = "MyLinux"      
\&    root = "/dev/hda1 ro"
\&    disk = [ "file:/var/xen/mylinux.img,hda1,w" ]
.Ve
.Sp
This creates a domain called MyLinux with 128 \s-1MB\s0 of memory using a
default xen kernel, and the file /var/xen/mylinux.img loopback mounted
at hda1, which is the root filesystem.
.IP "\fI\s-1NFS\s0 Root\fR" 4
.IX Item "NFS Root"
\&\s-1FIXME:\s0 write me
.IP "\fI\s-1LVM\s0 Root\fR" 4
.IX Item "LVM Root"
\&\s-1FIXME:\s0 write me
.IP "\fITwo Networks\fR" 4
.IX Item "Two Networks"
\&\s-1FIXME:\s0 write me
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBxm\fR(1)
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  Sean Dague <sean at dague dot net>
.Ve
.SH "BUGS"
.IX Header "BUGS"
Not all options are currently documented