view docs/src/user/domain_configuration.tex @ 7176:0e1838de9db8

Move XendDomainInfo.{create,recreate,parseConfig} to the top level of the
domain. This allows us to refer to them using an import statement, rather than
a from .. import. This is a step towards getting rid of the xroot hack. All
other references to XendDomainInfo methods need to be doubly qualified (once
for the module, once for the class).

Remove XendDomainDict, replacing it with a simple dictionary, folding the
get_by_name method into XendDomain.

Replace XendDomain.refresh_lock with a domains_lock which goes around any
reference to XendDomain.domains or anything that will create or destroy a
domain. This serialises most accesses through XendDomain, ensuring that we will
not return stale state when racing against the watches fired in separate
threads. This should have fixed bugs #270 and #234.

Added a number of domain_get_xyz methods. Those named xyz_nr are to allow
components internal to XendDomain (XendDomainInfo, XendCheckpoint) to call back
into XendDomain without triggering further calls to XendDomain.refresh. The
other methods simply make it clear which fallback behaviour is expected.

Replace XendDomainInfo.domain_exists with XendDomainInfo.domain_by_name; the
internals of this method needed to change to match those changes above, and it
has been a misnomer for some time.

Signed-off-by: Ewan Mellor <ewan@xensource.com>
author emellor@ewan
date Tue Oct 04 02:21:28 2005 +0100 (2005-10-04)
parents 06d84bf87159
line source
1 \chapter{Domain Configuration}
2 \label{cha:config}
4 The following contains the syntax of the domain configuration files
5 and description of how to further specify networking, driver domain
6 and general scheduling behavior.
9 \section{Configuration Files}
10 \label{s:cfiles}
12 Xen configuration files contain the following standard variables.
13 Unless otherwise stated, configuration items should be enclosed in
14 quotes: see \path{/etc/xen/xmexample1} and \path{/etc/xen/xmexample2}
15 for concrete examples of the syntax.
17 \begin{description}
18 \item[kernel] Path to the kernel image.
19 \item[ramdisk] Path to a ramdisk image (optional).
20 % \item[builder] The name of the domain build function (e.g.
21 % {\tt'linux'} or {\tt'netbsd'}.
22 \item[memory] Memory size in megabytes.
23 \item[cpu] CPU to run this domain on, or {\tt -1} for auto-allocation.
24 \item[console] Port to export the domain console on (default 9600 +
25 domain ID).
26 \item[nics] Number of virtual network interfaces.
27 \item[vif] List of MAC addresses (random addresses are assigned if not
28 given) and bridges to use for the domain's network interfaces, e.g.\
29 \begin{verbatim}
30 vif = [ 'mac=aa:00:00:00:00:11, bridge=xen-br0',
31 'bridge=xen-br1' ]
32 \end{verbatim}
33 to assign a MAC address and bridge to the first interface and assign
34 a different bridge to the second interface, leaving \xend\ to choose
35 the MAC address.
36 \item[disk] List of block devices to export to the domain, e.g.\ \\
37 \verb_disk = [ 'phy:hda1,sda1,r' ]_ \\
38 exports physical device \path{/dev/hda1} to the domain as
39 \path{/dev/sda1} with read-only access. Exporting a disk read-write
40 which is currently mounted is dangerous -- if you are \emph{certain}
41 you wish to do this, you can specify \path{w!} as the mode.
42 \item[dhcp] Set to {\tt `dhcp'} if you want to use DHCP to configure
43 networking.
44 \item[netmask] Manually configured IP netmask.
45 \item[gateway] Manually configured IP gateway.
46 \item[hostname] Set the hostname for the virtual machine.
47 \item[root] Specify the root device parameter on the kernel command
48 line.
49 \item[nfs\_server] IP address for the NFS server (if any).
50 \item[nfs\_root] Path of the root filesystem on the NFS server (if
51 any).
52 \item[extra] Extra string to append to the kernel command line (if
53 any)
54 \item[restart] Three possible options:
55 \begin{description}
56 \item[always] Always restart the domain, no matter what its exit
57 code is.
58 \item[never] Never restart the domain.
59 \item[onreboot] Restart the domain iff it requests reboot.
60 \end{description}
61 \end{description}
63 For additional flexibility, it is also possible to include Python
64 scripting commands in configuration files. An example of this is the
65 \path{xmexample2} file, which uses Python code to handle the
66 \path{vmid} variable.
69 %\part{Advanced Topics}
72 \section{Network Configuration}
74 For many users, the default installation should work ``out of the
75 box''. More complicated network setups, for instance with multiple
76 Ethernet interfaces and/or existing bridging setups will require some
77 special configuration.
79 The purpose of this section is to describe the mechanisms provided by
80 \xend\ to allow a flexible configuration for Xen's virtual networking.
82 \subsection{Xen virtual network topology}
84 Each domain network interface is connected to a virtual network
85 interface in dom0 by a point to point link (effectively a ``virtual
86 crossover cable''). These devices are named {\tt
87 vif$<$domid$>$.$<$vifid$>$} (e.g.\ {\tt vif1.0} for the first
88 interface in domain~1, {\tt vif3.1} for the second interface in
89 domain~3).
91 Traffic on these virtual interfaces is handled in domain~0 using
92 standard Linux mechanisms for bridging, routing, rate limiting, etc.
93 Xend calls on two shell scripts to perform initial configuration of
94 the network and configuration of new virtual interfaces. By default,
95 these scripts configure a single bridge for all the virtual
96 interfaces. Arbitrary routing / bridging configurations can be
97 configured by customizing the scripts, as described in the following
98 section.
100 \subsection{Xen networking scripts}
102 Xen's virtual networking is configured by two shell scripts (by
103 default \path{network} and \path{vif-bridge}). These are called
104 automatically by \xend\ when certain events occur, with arguments to
105 the scripts providing further contextual information. These scripts
106 are found by default in \path{/etc/xen/scripts}. The names and
107 locations of the scripts can be configured in
108 \path{/etc/xen/xend-config.sxp}.
110 \begin{description}
111 \item[network:] This script is called whenever \xend\ is started or
112 stopped to respectively initialize or tear down the Xen virtual
113 network. In the default configuration initialization creates the
114 bridge `xen-br0' and moves eth0 onto that bridge, modifying the
115 routing accordingly. When \xend\ exits, it deletes the Xen bridge
116 and removes eth0, restoring the normal IP and routing configuration.
118 %% In configurations where the bridge already exists, this script
119 %% could be replaced with a link to \path{/bin/true} (for instance).
121 \item[vif-bridge:] This script is called for every domain virtual
122 interface and can configure firewalling rules and add the vif to the
123 appropriate bridge. By default, this adds and removes VIFs on the
124 default Xen bridge.
125 \end{description}
127 For more complex network setups (e.g.\ where routing is required or
128 integrate with existing bridges) these scripts may be replaced with
129 customized variants for your site's preferred configuration.
131 %% There are two possible types of privileges: IO privileges and
132 %% administration privileges.
135 \section{Driver Domain Configuration}
137 I/O privileges can be assigned to allow a domain to directly access
138 PCI devices itself. This is used to support driver domains.
140 Setting back-end privileges is currently only supported in SXP format
141 config files. To allow a domain to function as a back-end for others,
142 somewhere within the {\tt vm} element of its configuration file must
143 be a {\tt back-end} element of the form {\tt (back-end ({\em type}))}
144 where {\tt \em type} may be either {\tt netif} or {\tt blkif},
145 according to the type of virtual device this domain will service.
146 %% After this domain has been built, \xend will connect all new and
147 %% existing {\em virtual} devices (of the appropriate type) to that
148 %% back-end.
150 Note that a block back-end cannot currently import virtual block
151 devices from other domains, and a network back-end cannot import
152 virtual network devices from other domains. Thus (particularly in the
153 case of block back-ends, which cannot import a virtual block device as
154 their root filesystem), you may need to boot a back-end domain from a
155 ramdisk or a network device.
157 Access to PCI devices may be configured on a per-device basis. Xen
158 will assign the minimal set of hardware privileges to a domain that
159 are required to control its devices. This can be configured in either
160 format of configuration file:
162 \begin{itemize}
163 \item SXP Format: Include device elements of the form: \\
164 \centerline{ {\tt (device (pci (bus {\em x}) (dev {\em y}) (func {\em z})))}} \\
165 inside the top-level {\tt vm} element. Each one specifies the
166 address of a device this domain is allowed to access --- the numbers
167 \emph{x},\emph{y} and \emph{z} may be in either decimal or
168 hexadecimal format.
169 \item Flat Format: Include a list of PCI device addresses of the
170 format: \\
171 \centerline{{\tt pci = ['x,y,z', \ldots]}} \\
172 where each element in the list is a string specifying the components
173 of the PCI device address, separated by commas. The components
174 ({\tt \em x}, {\tt \em y} and {\tt \em z}) of the list may be
175 formatted as either decimal or hexadecimal.
176 \end{itemize}
178 %% \section{Administration Domains}
180 %% Administration privileges allow a domain to use the `dom0
181 %% operations' (so called because they are usually available only to
182 %% domain 0). A privileged domain can build other domains, set
183 %% scheduling parameters, etc.
185 % Support for other administrative domains is not yet available...
186 % perhaps we should plumb it in some time
189 \section{Scheduler Configuration}
190 \label{s:sched}
192 Xen offers a boot time choice between multiple schedulers. To select
193 a scheduler, pass the boot parameter \emph{sched=sched\_name} to Xen,
194 substituting the appropriate scheduler name. Details of the
195 schedulers and their parameters are included below; future versions of
196 the tools will provide a higher-level interface to these tools.
198 It is expected that system administrators configure their system to
199 use the scheduler most appropriate to their needs. Currently, the BVT
200 scheduler is the recommended choice.
202 \subsection{Borrowed Virtual Time}
204 {\tt sched=bvt} (the default) \\
206 BVT provides proportional fair shares of the CPU time. It has been
207 observed to penalize domains that block frequently (e.g.\ I/O
208 intensive domains), but this can be compensated for by using warping.
210 \subsubsection{Global Parameters}
212 \begin{description}
213 \item[ctx\_allow] The context switch allowance is similar to the
214 ``quantum'' in traditional schedulers. It is the minimum time that
215 a scheduled domain will be allowed to run before being preempted.
216 \end{description}
218 \subsubsection{Per-domain parameters}
220 \begin{description}
221 \item[mcuadv] The MCU (Minimum Charging Unit) advance determines the
222 proportional share of the CPU that a domain receives. It is set
223 inversely proportionally to a domain's sharing weight.
224 \item[warp] The amount of ``virtual time'' the domain is allowed to
225 warp backwards.
226 \item[warpl] The warp limit is the maximum time a domain can run
227 warped for.
228 \item[warpu] The unwarp requirement is the minimum time a domain must
229 run unwarped for before it can warp again.
230 \end{description}
232 \subsection{Atropos}
234 {\tt sched=atropos} \\
236 Atropos is a soft real time scheduler. It provides guarantees about
237 absolute shares of the CPU, with a facility for sharing slack CPU time
238 on a best-effort basis. It can provide timeliness guarantees for
239 latency-sensitive domains.
241 Every domain has an associated period and slice. The domain should
242 receive `slice' nanoseconds every `period' nanoseconds. This allows
243 the administrator to configure both the absolute share of the CPU a
244 domain receives and the frequency with which it is scheduled.
246 %% When domains unblock, their period is reduced to the value of the
247 %% latency hint (the slice is scaled accordingly so that they still
248 %% get the same proportion of the CPU). For each subsequent period,
249 %% the slice and period times are doubled until they reach their
250 %% original values.
252 Note: don't over-commit the CPU when using Atropos (i.e.\ don't reserve
253 more CPU than is available --- the utilization should be kept to
254 slightly less than 100\% in order to ensure predictable behavior).
256 \subsubsection{Per-domain parameters}
258 \begin{description}
259 \item[period] The regular time interval during which a domain is
260 guaranteed to receive its allocation of CPU time.
261 \item[slice] The length of time per period that a domain is guaranteed
262 to run for (in the absence of voluntary yielding of the CPU).
263 \item[latency] The latency hint is used to control how soon after
264 waking up a domain it should be scheduled.
265 \item[xtratime] This is a boolean flag that specifies whether a domain
266 should be allowed a share of the system slack time.
267 \end{description}
269 \subsection{Round Robin}
271 {\tt sched=rrobin} \\
273 The round robin scheduler is included as a simple demonstration of
274 Xen's internal scheduler API. It is not intended for production use.
276 \subsubsection{Global Parameters}
278 \begin{description}
279 \item[rr\_slice] The maximum time each domain runs before the next
280 scheduling decision is made.
281 \end{description}