diff options
Diffstat (limited to 'docs/src/user/domain_configuration.tex')
| -rw-r--r-- | docs/src/user/domain_configuration.tex | 281 |
1 files changed, 0 insertions, 281 deletions
diff --git a/docs/src/user/domain_configuration.tex b/docs/src/user/domain_configuration.tex deleted file mode 100644 index 9f7b5edf6c..0000000000 --- a/docs/src/user/domain_configuration.tex +++ /dev/null @@ -1,281 +0,0 @@ -\chapter{Domain Configuration} -\label{cha:config} - -The following contains the syntax of the domain configuration files -and description of how to further specify networking, driver domain -and general scheduling behavior. - - -\section{Configuration Files} -\label{s:cfiles} - -Xen configuration files contain the following standard variables. -Unless otherwise stated, configuration items should be enclosed in -quotes: see \path{/etc/xen/xmexample1} and \path{/etc/xen/xmexample2} -for concrete examples of the syntax. - -\begin{description} -\item[kernel] Path to the kernel image. -\item[ramdisk] Path to a ramdisk image (optional). - % \item[builder] The name of the domain build function (e.g. - % {\tt'linux'} or {\tt'netbsd'}. -\item[memory] Memory size in megabytes. -\item[cpu] CPU to run this domain on, or {\tt -1} for auto-allocation. -\item[console] Port to export the domain console on (default 9600 + - domain ID). -\item[nics] Number of virtual network interfaces. -\item[vif] List of MAC addresses (random addresses are assigned if not - given) and bridges to use for the domain's network interfaces, e.g.\ -\begin{verbatim} -vif = [ 'mac=aa:00:00:00:00:11, bridge=xen-br0', - 'bridge=xen-br1' ] -\end{verbatim} - to assign a MAC address and bridge to the first interface and assign - a different bridge to the second interface, leaving \xend\ to choose - the MAC address. -\item[disk] List of block devices to export to the domain, e.g.\ \\ - \verb_disk = [ 'phy:hda1,sda1,r' ]_ \\ - exports physical device \path{/dev/hda1} to the domain as - \path{/dev/sda1} with read-only access. Exporting a disk read-write - which is currently mounted is dangerous -- if you are \emph{certain} - you wish to do this, you can specify \path{w!} as the mode. -\item[dhcp] Set to {\tt `dhcp'} if you want to use DHCP to configure - networking. -\item[netmask] Manually configured IP netmask. -\item[gateway] Manually configured IP gateway. -\item[hostname] Set the hostname for the virtual machine. -\item[root] Specify the root device parameter on the kernel command - line. -\item[nfs\_server] IP address for the NFS server (if any). -\item[nfs\_root] Path of the root filesystem on the NFS server (if - any). -\item[extra] Extra string to append to the kernel command line (if - any) -\item[restart] Three possible options: - \begin{description} - \item[always] Always restart the domain, no matter what its exit - code is. - \item[never] Never restart the domain. - \item[onreboot] Restart the domain iff it requests reboot. - \end{description} -\end{description} - -For additional flexibility, it is also possible to include Python -scripting commands in configuration files. An example of this is the -\path{xmexample2} file, which uses Python code to handle the -\path{vmid} variable. - - -%\part{Advanced Topics} - - -\section{Network Configuration} - -For many users, the default installation should work ``out of the -box''. More complicated network setups, for instance with multiple -Ethernet interfaces and/or existing bridging setups will require some -special configuration. - -The purpose of this section is to describe the mechanisms provided by -\xend\ to allow a flexible configuration for Xen's virtual networking. - -\subsection{Xen virtual network topology} - -Each domain network interface is connected to a virtual network -interface in dom0 by a point to point link (effectively a ``virtual -crossover cable''). These devices are named {\tt - vif$<$domid$>$.$<$vifid$>$} (e.g.\ {\tt vif1.0} for the first -interface in domain~1, {\tt vif3.1} for the second interface in -domain~3). - -Traffic on these virtual interfaces is handled in domain~0 using -standard Linux mechanisms for bridging, routing, rate limiting, etc. -Xend calls on two shell scripts to perform initial configuration of -the network and configuration of new virtual interfaces. By default, -these scripts configure a single bridge for all the virtual -interfaces. Arbitrary routing / bridging configurations can be -configured by customizing the scripts, as described in the following -section. - -\subsection{Xen networking scripts} - -Xen's virtual networking is configured by two shell scripts (by -default \path{network} and \path{vif-bridge}). These are called -automatically by \xend\ when certain events occur, with arguments to -the scripts providing further contextual information. These scripts -are found by default in \path{/etc/xen/scripts}. The names and -locations of the scripts can be configured in -\path{/etc/xen/xend-config.sxp}. - -\begin{description} -\item[network:] This script is called whenever \xend\ is started or - stopped to respectively initialize or tear down the Xen virtual - network. In the default configuration initialization creates the - bridge `xen-br0' and moves eth0 onto that bridge, modifying the - routing accordingly. When \xend\ exits, it deletes the Xen bridge - and removes eth0, restoring the normal IP and routing configuration. - - %% In configurations where the bridge already exists, this script - %% could be replaced with a link to \path{/bin/true} (for instance). - -\item[vif-bridge:] This script is called for every domain virtual - interface and can configure firewalling rules and add the vif to the - appropriate bridge. By default, this adds and removes VIFs on the - default Xen bridge. -\end{description} - -For more complex network setups (e.g.\ where routing is required or -integrate with existing bridges) these scripts may be replaced with -customized variants for your site's preferred configuration. - -%% There are two possible types of privileges: IO privileges and -%% administration privileges. - - -\section{Driver Domain Configuration} - -I/O privileges can be assigned to allow a domain to directly access -PCI devices itself. This is used to support driver domains. - -Setting back-end privileges is currently only supported in SXP format -config files. To allow a domain to function as a back-end for others, -somewhere within the {\tt vm} element of its configuration file must -be a {\tt back-end} element of the form {\tt (back-end ({\em type}))} -where {\tt \em type} may be either {\tt netif} or {\tt blkif}, -according to the type of virtual device this domain will service. -%% After this domain has been built, \xend will connect all new and -%% existing {\em virtual} devices (of the appropriate type) to that -%% back-end. - -Note that a block back-end cannot currently import virtual block -devices from other domains, and a network back-end cannot import -virtual network devices from other domains. Thus (particularly in the -case of block back-ends, which cannot import a virtual block device as -their root filesystem), you may need to boot a back-end domain from a -ramdisk or a network device. - -Access to PCI devices may be configured on a per-device basis. Xen -will assign the minimal set of hardware privileges to a domain that -are required to control its devices. This can be configured in either -format of configuration file: - -\begin{itemize} -\item SXP Format: Include device elements of the form: \\ - \centerline{ {\tt (device (pci (bus {\em x}) (dev {\em y}) (func {\em z})))}} \\ - inside the top-level {\tt vm} element. Each one specifies the - address of a device this domain is allowed to access --- the numbers - \emph{x},\emph{y} and \emph{z} may be in either decimal or - hexadecimal format. -\item Flat Format: Include a list of PCI device addresses of the - format: \\ - \centerline{{\tt pci = ['x,y,z', \ldots]}} \\ - where each element in the list is a string specifying the components - of the PCI device address, separated by commas. The components - ({\tt \em x}, {\tt \em y} and {\tt \em z}) of the list may be - formatted as either decimal or hexadecimal. -\end{itemize} - -%% \section{Administration Domains} - -%% Administration privileges allow a domain to use the `dom0 -%% operations' (so called because they are usually available only to -%% domain 0). A privileged domain can build other domains, set -%% scheduling parameters, etc. - -% Support for other administrative domains is not yet available... -% perhaps we should plumb it in some time - - -\section{Scheduler Configuration} -\label{s:sched} - -Xen offers a boot time choice between multiple schedulers. To select -a scheduler, pass the boot parameter \emph{sched=sched\_name} to Xen, -substituting the appropriate scheduler name. Details of the -schedulers and their parameters are included below; future versions of -the tools will provide a higher-level interface to these tools. - -It is expected that system administrators configure their system to -use the scheduler most appropriate to their needs. Currently, the BVT -scheduler is the recommended choice. - -\subsection{Borrowed Virtual Time} - -{\tt sched=bvt} (the default) \\ - -BVT provides proportional fair shares of the CPU time. It has been -observed to penalize domains that block frequently (e.g.\ I/O -intensive domains), but this can be compensated for by using warping. - -\subsubsection{Global Parameters} - -\begin{description} -\item[ctx\_allow] The context switch allowance is similar to the - ``quantum'' in traditional schedulers. It is the minimum time that - a scheduled domain will be allowed to run before being preempted. -\end{description} - -\subsubsection{Per-domain parameters} - -\begin{description} -\item[mcuadv] The MCU (Minimum Charging Unit) advance determines the - proportional share of the CPU that a domain receives. It is set - inversely proportionally to a domain's sharing weight. -\item[warp] The amount of ``virtual time'' the domain is allowed to - warp backwards. -\item[warpl] The warp limit is the maximum time a domain can run - warped for. -\item[warpu] The unwarp requirement is the minimum time a domain must - run unwarped for before it can warp again. -\end{description} - -\subsection{Atropos} - -{\tt sched=atropos} \\ - -Atropos is a soft real time scheduler. It provides guarantees about -absolute shares of the CPU, with a facility for sharing slack CPU time -on a best-effort basis. It can provide timeliness guarantees for -latency-sensitive domains. - -Every domain has an associated period and slice. The domain should -receive `slice' nanoseconds every `period' nanoseconds. This allows -the administrator to configure both the absolute share of the CPU a -domain receives and the frequency with which it is scheduled. - -%% When domains unblock, their period is reduced to the value of the -%% latency hint (the slice is scaled accordingly so that they still -%% get the same proportion of the CPU). For each subsequent period, -%% the slice and period times are doubled until they reach their -%% original values. - -Note: don't over-commit the CPU when using Atropos (i.e.\ don't reserve -more CPU than is available --- the utilization should be kept to -slightly less than 100\% in order to ensure predictable behavior). - -\subsubsection{Per-domain parameters} - -\begin{description} -\item[period] The regular time interval during which a domain is - guaranteed to receive its allocation of CPU time. -\item[slice] The length of time per period that a domain is guaranteed - to run for (in the absence of voluntary yielding of the CPU). -\item[latency] The latency hint is used to control how soon after - waking up a domain it should be scheduled. -\item[xtratime] This is a boolean flag that specifies whether a domain - should be allowed a share of the system slack time. -\end{description} - -\subsection{Round Robin} - -{\tt sched=rrobin} \\ - -The round robin scheduler is included as a simple demonstration of -Xen's internal scheduler API. It is not intended for production use. - -\subsubsection{Global Parameters} - -\begin{description} -\item[rr\_slice] The maximum time each domain runs before the next - scheduling decision is made. -\end{description} |