ia64/xen-unstable

changeset 2763:4b524192e62b

bitkeeper revision 1.1159.138.1 (41811be9-M5W9ujjnrgAr5BvIUxzIQ)

Doc fixes. Definitely more still to do.
author kaf24@freefall.cl.cam.ac.uk
date Thu Oct 28 16:18:49 2004 +0000 (2004-10-28)
parents 66b1445a11a0
children b6703e4c6e16
files .rootkeys README README.CD docs/misc/xend.tex docs/src/interface.tex docs/src/user.tex docs/src/xend.tex
line diff
     1.1 --- a/.rootkeys	Thu Oct 28 13:03:45 2004 +0000
     1.2 +++ b/.rootkeys	Thu Oct 28 16:18:49 2004 +0000
     1.3 @@ -5,16 +5,15 @@ 3ddb79c9_hgSp-gsQm8HqWM_9W3B_A BitKeeper
     1.4  4177dbbfqsi01p2zgZa0geUOgScONw COPYING
     1.5  3eb788d6Kleck_Cut0ouGneviGzliQ Makefile
     1.6  3f5ef5a24IaQasQE2tyMxrfxskMmvw README
     1.7 -3f5ef5a2l4kfBYSQTUaOyyD76WROZQ README.CD
     1.8  3f69d8abYB1vMyD_QVDvzxy5Zscf1A TODO
     1.9  3f9e7d53iC47UnlfORp9iC1vai6kWw docs/Makefile
    1.10  3f9e7d60PWZJeVh5xdnk0nLUdxlqEA docs/figs/xenlogo.eps
    1.11  4022a73cgxX1ryj1HgS-IwwB6NUi2A docs/misc/XenDebugger-HOWTO
    1.12  412f4bd9sm5mCQ8BkrgKcAKZGadq7Q docs/misc/blkif-drivers-explained.txt
    1.13  40d6ccbfKKBq8jE0ula4eHEzBiQuDA docs/misc/xen_config.html
    1.14 +410a4c2bAO_m_l4RsiiPHnZ4ixHWbQ docs/misc/xend.tex
    1.15  3f9e7d564bWFB-Czjv1qdmE6o0GqNg docs/src/interface.tex
    1.16  410144afnSd2Yw68AHGO5gXu2m3y6A docs/src/user.tex
    1.17 -410a4c2bAO_m_l4RsiiPHnZ4ixHWbQ docs/src/xend.tex
    1.18  3f9e7d5bz8BwYkNuwyiPVu7JJG441A docs/xenstyle.cls
    1.19  3f815144d1vI2777JI-dO4wk49Iw7g extras/mini-os/Makefile
    1.20  3f815144zTnCV5591ulIJQrpe5b-5Q extras/mini-os/README
     2.1 --- a/README	Thu Oct 28 13:03:45 2004 +0000
     2.2 +++ b/README	Thu Oct 28 16:18:49 2004 +0000
     2.3 @@ -8,7 +8,7 @@
     2.4  ###############################
     2.5  
     2.6  University of Cambridge Computer Laboratory
     2.7 -28 Aug 2004
     2.8 +28 October 2004
     2.9  
    2.10  http://www.cl.cam.ac.uk/netos/xen
    2.11  
    2.12 @@ -100,7 +100,7 @@ more normal to use some smaller number, 
    2.13  A common question is "how many virtual machines can I run on hardware
    2.14  xyz?". The answer is very application dependent, but the rule of thumb
    2.15  is that you should expect to be able to run the same workload under
    2.16 -multiple guest OSes that you could run under a single Linux instance,
    2.17 +multiple guest OSs that you could run under a single Linux instance,
    2.18  with an additional overhead of a few MB per OS instance.
    2.19  
    2.20  One key feature in this new release of Xen is `live migration'. This
    2.21 @@ -111,7 +111,6 @@ node down for maintenance, or to load ba
    2.22  virtual machines across a cluster.
    2.23  
    2.24  
    2.25 -
    2.26  Hardware support
    2.27  ================
    2.28  
    2.29 @@ -132,9 +131,8 @@ run on Opterons in 32-bit mode just fine
    2.30  Xen can currently use up to 4GB of memory. It's possible for x86
    2.31  machines to address more than that (64GB), but it requires using a
    2.32  different page table format (3-level rather than 2-level) that we
    2.33 -currently don't support. Adding 3-level PAE support wouldn't be
    2.34 -difficult, but we'd also need to add support to all the guest
    2.35 -OSs. Volunteers welcome!
    2.36 +don't currently support, as we are concentrating on an x86_64 port
    2.37 +that will more easily support large-memory configurations.
    2.38  
    2.39  In contrast to previous Xen versions, in Xen 2.0 device drivers run
    2.40  within a privileged guest OS rather than within Xen itself. This means
    2.41 @@ -204,6 +202,7 @@ If you don't want to use bitkeeper to do
    2.42  download prebuilt binaries and src tar balls from the project
    2.43  downloads page:  http://www.cl.cam.ac.uk/netos/xen/downloads/
    2.44  
    2.45 +
    2.46  Using the domain control tools
    2.47  ==============================
    2.48  
    2.49 @@ -212,8 +211,6 @@ daemon: "xend start".
    2.50  The primary tool for starting and controlling domains is "xm". 
    2.51  "xm help <cmd>" will tell you how to use it.
    2.52  
    2.53 -README.CD contains some example invocations.
    2.54 -
    2.55 -Further documentation is in docs/ (e.g., docs/Xen-HOWTO), and also in
    2.56 -
    2.57 -
    2.58 +Further documentation is in the docs/ directory. Postscript, PDF and
    2.59 +HTML versions of the user manual can be found in the ps/, pdf/ and
    2.60 +html/ subdirectories.
     3.1 --- a/README.CD	Thu Oct 28 13:03:45 2004 +0000
     3.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.3 @@ -1,737 +0,0 @@
     3.4 -###############################
     3.5 -__  __            ____    ___
     3.6 -\ \/ /___ _ __   |___ \  / _ \
     3.7 - \  // _ \ '_ \    __) || | | |
     3.8 - /  \  __/ | | |  / __/ | |_| |
     3.9 -/_/\_\___|_| |_| |_____(_)___/
    3.10 -
    3.11 -###############################
    3.12 -
    3.13 - XenDemoCD 2.0
    3.14 - University of Cambridge Computer Laboratory
    3.15 - 28 Aug 2004
    3.16 -
    3.17 - http://www.cl.cam.ac.uk/netos/xen
    3.18 -
    3.19 -Welcome to the Xen Demo CD! 
    3.20 -
    3.21 -Executive Summary
    3.22 -=================
    3.23 -
    3.24 -This CD is a standalone demo of the Xen Virtual Machine Monitor (VMM),
    3.25 - Linux-2.4 and Linux-2.6 OS port (Xenlinux). It runs entirely off the
    3.26 -CD, without requiring hard disk installation. This is achieved using a
    3.27 -RAM disk to store mutable file system data while using the CD for
    3.28 -everything else. The CD can also be used for installing Xen/Xenlinux
    3.29 -to disk, and includes a source code snapshot along with all of the
    3.30 -tools required to build it.
    3.31 -
    3.32 -Booting the CD
    3.33 -==============
    3.34 -
    3.35 -It should be possible to get Xen working with any relatively modern
    3.36 -hardware supported by standard Linux. However, the version of XenLinux
    3.37 -built for the DemoCD is fairly h/w specific. If you need other
    3.38 -hardware, you'll have to configure and build your own xenlinux kernel.
    3.39 -Xen does require an 'i686'-class CPU or newer, so won't work on 486's
    3.40 -or plain Pentiums.
    3.41 -
    3.42 -We have compiled in drivers for the following hardware:
    3.43 -
    3.44 -CPU:  Pentium Pro/II/III/IV/Xeon, Athlon (i.e. P6 or newer) SMP supported
    3.45 -IDE:  Intel PIIX chipset, others will be PIO only (slow)
    3.46 -SCSI: Adaptec / Dell PERC Raid (aacraid), fusion MPT, megaraid, Adaptec aic7xxx
    3.47 -Net:  Recommended: Intel e1000, Broadcom BCM57xx (tg3), 3c905 (3c59x)
    3.48 -      Also supported: pcnet32, Intel e100, tulip
    3.49 -
    3.50 -Because of the demo CD's use of RAM disks, make sure you have plenty
    3.51 -of RAM (256MB+).
    3.52 -
    3.53 -To try out the Demo, boot from CD (you may need to change your BIOS
    3.54 -configuration to do this), then select one of the four boot options 
    3.55 -from the Grub menu:
    3.56 -
    3.57 - Xen / linux-2.4.27
    3.58 - Xen / linux-2.4.27 using cmdline IP configuration
    3.59 - Xen / linux-2.4.27 in "safe mode"
    3.60 - linux-2.4.22
    3.61 -
    3.62 -The last option is a plain linux kernel that runs on the bare machine,
    3.63 -and is included simply to help diagnose driver compatibility
    3.64 -problems. The "safe mode" boot option might be useful if you're having
    3.65 -problems getting Xen to work with your hardware, as it disables various
    3.66 -features such as SMP, and enables some debugging.
    3.67 -
    3.68 -If you are going for a command line IP config, hit "e" at
    3.69 -the grub menu, then edit the "ip=" parameters to reflect your setup
    3.70 -e.g. "ip=<ipaddr>::<gateway>:<netmask>::eth0:off". It shouldn't be
    3.71 -necessary to set either the nfs server or hostname
    3.72 -parameters. Alternatively, once Xenlinux has booted you can login and
    3.73 -setup networking with 'dhclient' or 'ifconfig' and 'route' in the
    3.74 -normal way. 
    3.75 -
    3.76 -To make things easier for yourself, it's worth trying to arrange for an
    3.77 -IP address which is the first in a sequential range of free IP
    3.78 -addresses.  It's useful to give each VM instance its own public IP
    3.79 -address (though it is possible to do NAT or use private addresses), 
    3.80 -and the configuration files on the CD allocate IP addresses
    3.81 -sequentially for subsequent domains unless told otherwise.
    3.82 -
    3.83 -After selecting the kernel to boot, stand back and watch Xen boot,
    3.84 -closely followed by "domain 0" running the Xenlinux kernel. The boot
    3.85 -messages can also sent to the serial line by specifying the baud rate
    3.86 -on the Xen cmdline (e.g., 'com1=9600,8n1'); this can be very useful
    3.87 -for debugging should anything important scroll off the screen. Xen's
    3.88 -startup messages will look quite familiar as much of the hardware
    3.89 -initialisation (SMP boot, apic setup) and device drivers are derived
    3.90 -from Linux.
    3.91 -
    3.92 -If everything is well, you should see the linux rc scripts start a
    3.93 -bunch of standard services including sshd.  Login on the console or
    3.94 -via ssh::
    3.95 - username: user         root
    3.96 - password: xendemo      xendemo
    3.97 -
    3.98 -Once logged in, it should look just like any regular linux box. All
    3.99 -the usual tools and commands should work as per usual.  However,
   3.100 -because of the poor random access performance of CD drives, the
   3.101 -machine will feel very slugish, and you may run out of memory if you
   3.102 -make significant modifications to the ramfs filesystem -- for the full
   3.103 -experience, install a Xen and Xenlinux image on you hard drive :-)
   3.104 -
   3.105 -You can configure networking, either with 'dhclient' or manually via
   3.106 -'ifconfig' and 'route', remembering to edit /etc/resolv.conf if you
   3.107 -want DNS to work.
   3.108 -
   3.109 -You can start an X server with 'startx'. It defaults to a conservative
   3.110 -1024x768, but you can edit the script for higher resoloutions.  The CD
   3.111 -contains a load of standard software. You should be able to start
   3.112 -Apache, PostgreSQL, Mozilla etc in the normal way, but because
   3.113 -everything is running off CD the performance will be very sluggish and
   3.114 -you may run out of memory for the 'tmpfs' file system.  You may wish
   3.115 -to go ahead and install Xen/Xenlinux on your hard drive, either
   3.116 -dropping Xen and the Xenlinux kernel down onto a pre-existing Linux
   3.117 -distribution, or using the file systems from the CD (which are based
   3.118 -on RH9). See the installation instructions later in this document.
   3.119 -
   3.120 -If your video card requires 'agpgart' then it unfortunately won't yet
   3.121 -work with Xen, and you'll only be able to configure a VGA X
   3.122 -server. We're working on a fix for this for the next release.
   3.123 -
   3.124 -If you want to browse the Xen / Xenlinux source, it's all located
   3.125 -under /usr/local/src/xen-2.0.bk, complete with BitKeeper
   3.126 -repository. We've also included source code and configuration
   3.127 -information for the various benchmarks we used in the SOSP paper.
   3.128 -
   3.129 -
   3.130 -Starting other domains
   3.131 -======================
   3.132 -
   3.133 -The first thing you need to do is to start the "xend" control daemon
   3.134 -with "xend start". You may wish to add an appropriate link to xend in
   3.135 -you /etc/rcX.d directory e.g. "ln -sf ../init.d/xend S97xend"
   3.136 -
   3.137 -If you're not intending to configure the new domain with an IP address
   3.138 -on your LAN, then you'll probably want to use NAT. The
   3.139 -'xen_nat_enable' installs a few useful iptables rules into domain0 to
   3.140 -enable NAT. [NB: We plan to support RSIP in future]
   3.141 -
   3.142 -Xen has a management interface that can be manipulated from domain0 to
   3.143 -create new domains, control their CPU, network and memory resource
   3.144 -allocations, allocate IP addresses, grant access to disk partitions,
   3.145 -and suspend/resume domains to files, etc.  The management interface is
   3.146 -implemented as a set of library functions (implemented in C) for which
   3.147 -there are Python language bindings. 
   3.148 -
   3.149 -We have developed a simple set of example python tools for
   3.150 -manipulating the interface, with the intention that more sophisticated
   3.151 -high-level management tools will be developed in due course. Within
   3.152 -the source repository the tools live in tools/examples/ but are
   3.153 -installed in /usr/local/bin/ on the CD.
   3.154 -
   3.155 -Starting a new domain is achieved using the command 'xm create' which
   3.156 -allocates resources to a new domain, populates it with a kernel image
   3.157 -(and optionally a ramdisk) and then starts it.
   3.158 -
   3.159 -It parses a configuration file written in the Python language, the
   3.160 -default location of which is "/etc/xc/defaults", but this may be
   3.161 -overridden with the "-f" option. For the Demo CD, the defaults file
   3.162 -will cause domains to be created with ram-based root file systems, and
   3.163 -mount their /usr partition from the CD, just like domain0. (If you are
   3.164 -writing your own config file, the "example" script may be a better
   3.165 -starting point)
   3.166 -
   3.167 -Variables can be initialised and passed into configuration files. Some
   3.168 -of these may be compulsory, others optional.
   3.169 -
   3.170 -The 'defaults' file on the CD requires the 'ip' variable to be set to
   3.171 -tell Xen what IP address(es) should be routed to this domain.  Xen
   3.172 -will route packets to the domain if they bear one of these addresses
   3.173 -as a destination address, and will also ensure that packets sent from
   3.174 -the domain contain one of the addresses as a source address (to
   3.175 -prevent spoofing).  If multiple IP addresses are to be assigned to a
   3.176 -domain they can be listed in a comma separated list (with no
   3.177 -whitespace).
   3.178 -
   3.179 -The 'mem' variable can be used to change the default memory allocation
   3.180 -of 64MB. For example to start a domain with two IP addresses and
   3.181 -72MB:
   3.182 -
   3.183 -  xm create ip=128.23.45.34,169.254.1.1mem=72
   3.184 -
   3.185 -When invoked with the '-n' option 'xm create' will do a dry run
   3.186 -and just print out what resources and configuration the domain will
   3.187 -have e.g.:
   3.188 -
   3.189 -  [root@xendemo]# xm create -n ip=commando-1.xeno,169.254.2.3 mem=100
   3.190 -  Parsing config file 'defaults'
   3.191 -
   3.192 -  VM image           : "/boot/xenlinux.gz"
   3.193 -  VM ramdisk         : "/boot/initrd.gz"
   3.194 -  VM memory (MB)     : "100"
   3.195 -  VM IP address(es)  : "128.232.38.51:169.254.2.3"
   3.196 -  VM block device(s) : "phy:cdrom,hdd,r"
   3.197 -  VM cmdline         : "ip=128.232.38.51:169.254.1.0:128.232.32.1:255.255.240.0::eth0:off root=/dev/ram0 rw init=/linuxrc 4 LOCALIP=169.254.2.3"
   3.198 -
   3.199 -xm create will print the local TCP port to which you should
   3.200 -connect to perform console I/O. A suitable console client is provided
   3.201 -by the Python module xenctl.console_client: running this module from
   3.202 -the command line with <host> and <port> parameters will start a
   3.203 -terminal session. This module is also installed as /usr/bin/xencons,
   3.204 -from a copy in tools/misc/xencons.  An alternative to manually running
   3.205 -a terminal client is to specify '-c' to xm create, or add
   3.206 -'auto_console=True' to the defaults file. This will cause
   3.207 -'xm create' to automatically become the console terminal after
   3.208 -starting the domain.
   3.209 -
   3.210 -The 169.254.x.x network is special in that it is the 'link local'
   3.211 -subnet, and is isolated from the external network and hence can only
   3.212 -be used for communication between virtual machines. By convention, we
   3.213 -usually give each domain a link local address. The startup scripts on
   3.214 -the CD have been modified to accept a LINKLOCAL= parameter on the
   3.215 -kernel command line and initialise an IP alias accordingly (see
   3.216 -/etc/sysinit/network-scripts/ifcfg-eth0).
   3.217 -
   3.218 -Linux only allows one IP address to be specified on the kernel command
   3.219 -line, so if you specify multiple IP addresses you'll need to configure
   3.220 -the new Linux VM with the other addresses manually (using ifconfig)
   3.221 -having logged in.
   3.222 -
   3.223 -If you inspect the 'defaults' config script you'll see that the new
   3.224 -domain was started with a '4' on the kernel command line to tell
   3.225 -'init' to go to runlevel 4 rather than the default of 3 used by
   3.226 -domain0. This is done simply to suppress a bunch of harmless error
   3.227 -messages that would otherwise occur when the new (unprivileged) domain
   3.228 -tried to access physical hardware resources to try setting the
   3.229 -hwclock, system font, run gpm etc.
   3.230 -
   3.231 -After it's booted, you should be able to ssh into your new domain from
   3.232 -domain0 using the link local 19.254.x.x address you assigned. If you
   3.233 -assigned a further IP address you should be able to ssh in using that
   3.234 -address too. If you ran the xen_enable_nat script, a bunch of port
   3.235 -redirects have been installed to enable you to ssh in to other domains
   3.236 -remotely even if you didn't assign an externally routeable address.
   3.237 -To access the new virtual machine remotely, use:
   3.238 -
   3.239 - ssh -p2201 root@IP.address.Of.Domain0  # use 2202 for domain 2 etc.
   3.240 -
   3.241 -You can manipulate running domains using the xm tool.
   3.242 -Invoking it without arguments prints some usage information.
   3.243 -
   3.244 -To see what domains are running, run 'xm list'.  Using the
   3.245 -tool you can change scheduling parameters, pause a domain, send it a
   3.246 -shutdown request, or blow it away with the 'destroy' command. You can
   3.247 -even suspend it to disk (but you probably won't have enough memory to
   3.248 -do the latter if you're running off the demo CD).
   3.249 -
   3.250 -To find usage information for xm, run the script with no arguments or
   3.251 -with the 'help' argument.  To get help on a particular xm command, use
   3.252 -'xm cmdname help'.
   3.253 -
   3.254 -
   3.255 -Troubleshooting Problems
   3.256 -========================
   3.257 -
   3.258 -If you have problems booting Xen, there are a number of boot parameters 
   3.259 -that may be able to help diagnose problems:
   3.260 -
   3.261 - ignorebiostables Disable parsing of BIOS-supplied tables. This may
   3.262 -                  help with some chipsets that aren't fully supported
   3.263 -                  by Xen. If you specify this option then ACPI tables are
   3.264 -                  also ignored, and SMP support is disabled.
   3.265 -
   3.266 - noreboot         Don't reboot the machine automatically on errors.
   3.267 -                  This is useful to catch debug output if you aren't
   3.268 -                  catching console messages via the serial line.
   3.269 -
   3.270 - nosmp		  Disable SMP support.
   3.271 -                  This option is implied by 'ignorebiostables'.
   3.272 -
   3.273 - noacpi   	  Disable ACPI tables, which confuse Xen on some chipsets.
   3.274 -                  This option is implied by 'ignorebiostables'.
   3.275 -
   3.276 - watchdog	  Enable NMI watchdog which can report certain failures.
   3.277 -
   3.278 - noht		  Disable Hyperthreading.
   3.279 -
   3.280 - badpage=<page number>[,<page number>]*
   3.281 -                  Specify a list of pages not to be allocated for use 
   3.282 -                  because they contain bad bytes. For example, if your
   3.283 -                  memory tester says that byte 0x12345678 is bad, you would
   3.284 -                  place 'badpage=0x12345' on Xen's command line (i.e., the
   3.285 -                  last three digits of the byte address are not included!).
   3.286 -
   3.287 - com1=<baud>,DPS[,<io_base>,<irq>]
   3.288 - com2=<baud>,DPS[,<io_base>,<irq>]
   3.289 -                  Xen supports up to two 16550-compatible serial ports.
   3.290 -                  For example: 'com1=9600,8n1,0x408,5' maps COM1 to a
   3.291 -                  9600-baud port, 8 data bits, no parity, 1 stop bit,
   3.292 -                  I/O port base 0x408, IRQ 5.
   3.293 -                  If the I/O base and IRQ are standard (com1:0x3f8,4;
   3.294 -                  com2:0x2f8,3) then they need not be specified.
   3.295 -
   3.296 - console=<specifier list>
   3.297 -                  Specify the destination for Xen console I/O.
   3.298 -                  This is a comma-separated list of, for example:
   3.299 -                   vga:  use VGA console and allow keyboard input
   3.300 -                   com1: use serial port com1
   3.301 -                   com2H: use serial port com2. Transmitted chars will
   3.302 -                          have the MSB set. Received chars must have
   3.303 -                          MSB set.
   3.304 -                   com2L: use serial port com2. Transmitted chars will
   3.305 -                          have the MSB cleared. Received chars must
   3.306 -                          have MSB cleared.
   3.307 -                  The latter two examples allow a single port to be
   3.308 -                  shared by two subsystems (eg. console and
   3.309 -                  debugger). Sharing is controlled by MSB of each
   3.310 -                  transmitted/received character.
   3.311 - [NB. Default for this option is 'com1,vga']
   3.312 -
   3.313 - conswitch=<switch-char><auto-switch-char>
   3.314 -                  Specify how to switch serial-console input between
   3.315 -                  Xen and DOM0. The required sequence is CTRL-<switch_char>
   3.316 -                  pressed three times. Specifying '`' disables switching.
   3.317 -                  The <auto-switch-char> specifies whether Xen should
   3.318 -                  auto-switch input to DOM0 when it boots -- if it is 'x'
   3.319 -                  then auto-switching is disabled. Any other value, or
   3.320 -                  omitting the character, enables auto-switching.
   3.321 - [NB. Default for this option is 'a']
   3.322 -
   3.323 - nmi=<nmi-error-behaviour>
   3.324 -                  Specify what to do with an NMI parity or I/O error.
   3.325 -                  'nmi=fatal':  Xen prints a diagnostic and then hangs.
   3.326 -                  'nmi=dom0':   Inform DOM0 of the NMI.
   3.327 -                  'nmi=ignore': Ignore the NMI.
   3.328 - [NB. Default is 'dom0' ('fatal' for debug builds).]
   3.329 -
   3.330 - dom0_mem=xxx 	  Set the initial amount of memory for domain0.
   3.331 -
   3.332 - pdb=xxx          Enable the pervasive debugger.  See docs/pdb.txt
   3.333 -                  xxx defines how the gdb stub will communicate:
   3.334 -                     com1    use com1
   3.335 -                     com1H   use com1 (with high bit set)
   3.336 -                     com2    use on com2
   3.337 -                     com2H   use com2 (with high bit set)
   3.338 -
   3.339 -It's probably a good idea to join the Xen developer's mailing list on
   3.340 -Sourceforge:    http://lists.sourceforge.net/lists/listinfo/xen-devel   
   3.341 -
   3.342 -
   3.343 -About The Xen Demo CD
   3.344 -=====================
   3.345 -
   3.346 -The purpose of the Demo CD is to distribute a snapshot of Xen's
   3.347 -source, and simultaneously provide a convenient means for enabling
   3.348 -people to get experience playing with Xen without needing to install
   3.349 -it on their hard drive. If you decide to install Xen/Xenlinux you can
   3.350 -do so simply by following the installation instructions below -- which
   3.351 -essentially involves copying the contents of the CD on to a suitably
   3.352 -formated disk partition, and then installing or updating the Grub
   3.353 -bootloader.
   3.354 -
   3.355 -This is a bootable CD that loads Xen, and then a Linux 2.4.27 OS image
   3.356 -ported to run on Xen. The CD contains a copy of a file system based on
   3.357 -the RedHat 9 distribution that is able to run directly off the CD
   3.358 -("live ISO"), using a "tmpfs" RAM-based file system for root (/etc
   3.359 -/var etc). Changes you make to the tmpfs will obviously not be
   3.360 -persistent across reboots!
   3.361 -
   3.362 -Because of the use of a RAM-based file system for root, you'll need
   3.363 -plenty of memory to run this CD -- something like 96MB per VM. This is
   3.364 -not a restriction of Xen : once you've installed Xen, Xenlinux and
   3.365 -the file system images on your hard drive you'll find you can boot VMs
   3.366 -in just a few MBs.
   3.367 -
   3.368 -The CD contains a snapshot of the Xen and Xenlinux code base that we
   3.369 -believe to be pretty stable, but lacks some of the features that are
   3.370 -currently still work in progress e.g. OS suspend/resume to disk, and
   3.371 -various memory management enhancements to provide fast inter-OS
   3.372 -communication and sharing of memory pages between OSs. We'll release
   3.373 -newer snapshots as required, making use of a BitKeeper repository
   3.374 -hosted on http://xen.bkbits.net (follow instructions from the project
   3.375 -home page).  We're obviously grateful to receive any bug fixes or
   3.376 -other code you can contribute. We suggest you join the
   3.377 -xen-devel@lists.sourceforge.net mailing list.
   3.378 -
   3.379 -
   3.380 -Installing from the CD
   3.381 -======================
   3.382 -
   3.383 -If you're installing Xen/Xenlinux onto an existing linux file system
   3.384 -distribution, just copy the Xen VMM (/boot/image.gz) and Xenlinux
   3.385 -kernels (/boot/xenlinux.gz), then modify the Grub config
   3.386 -(/boot/grub/menu.lst or /boot/grub/grub.conf) on the target system.
   3.387 -It should work on pretty much any distribution.
   3.388 -
   3.389 -Xen is a "multiboot" standard boot image. Despite being a 'standard',
   3.390 -few boot loaders actually support it. The only two we know of are
   3.391 -Grub, and our modified version of linux kexec (for booting off a
   3.392 -XenoBoot CD -- PlanetLab have adopted the same boot CD approach).
   3.393 -
   3.394 -If you need to install grub on your system, you can do so either by
   3.395 -building the Grub source tree
   3.396 -/usr/local/src/grub-0.93-iso9660-splashimage or by copying over all
   3.397 -the files in /boot/grub and then running /sbin/grub and following the
   3.398 -usual grub documentation. You'll then need to edit the Grub
   3.399 -config file.
   3.400 -
   3.401 -A typical Grub menu option might look like:
   3.402 -
   3.403 -title Xen 2.0 / Xenlinux 2.4.27
   3.404 -        kernel /boot/xen.gz dom0_mem=131072 com1=115200 noht watchdog
   3.405 -        module /boot/vmlinuz-2.4.27-xen0 root=/dev/sda4 ro
   3.406 -
   3.407 -The first line specifies which Xen image to use, and what command line
   3.408 -arguments to pass to Xen. In this case we set the maximum amount of
   3.409 -memory to allocate to domain0, and enable serial I/O on COM1 at 115200
   3.410 -baud.  We could also disable smp support (nosmp) or disable
   3.411 -hyper-threading support (noht). 
   3.412 -
   3.413 -The second line specifies which xenlinux image to use, and the
   3.414 -standard linux command line arguments to pass to the kernel. In this
   3.415 -case, we're configuring the root partition and stating that it should
   3.416 -initially be mounted read-only (normal practice).
   3.417 -
   3.418 -If we were booting with an initial ram disk (initrd), then this would
   3.419 -require a second "module" line.
   3.420 -
   3.421 -Installing the Xen tools and source
   3.422 -===================================
   3.423 -
   3.424 -The tools and source live in the /usr/local/src/xen-2.0.bk directory on
   3.425 -the CD (and may also be downloaded from the project downloads
   3.426 -page). You'll need to copy them to some mutable storage before using
   3.427 -them.
   3.428 -
   3.429 -If you have the BitKeeper BK tools installed you can check the
   3.430 -repository is up to date by cd'ing into the xeno-2.0.bk directory and
   3.431 -typing 'bk pull' (assuming you have an Internet connection). 
   3.432 -
   3.433 -You can rebuild Xen, the tools and XenLinux by typing 'make
   3.434 -world'. You can install them to the standard directories with 'make
   3.435 -install', or into the ./install subtree with 'make dist'.
   3.436 -
   3.437 -
   3.438 -Modifying xc_mycreatelinuxdom1.py
   3.439 -=================================
   3.440 -
   3.441 -xc_mycreatelinuxdom1.py.py can be used to set the new kernel's command line,
   3.442 -and hence determine what it uses as a root file system, etc. Although
   3.443 -the default is to boot in the same manner that domain0 did (using the
   3.444 -RAM-based file system for root and the CD for /usr) it's possible to
   3.445 -configure any of the following possibilities, for example:
   3.446 -
   3.447 - * initrd=/boot/initrd init=/linuxrc
   3.448 -     boot using an initial ram disk, executing /linuxrc (as per this CD)     
   3.449 -
   3.450 - * root=/dev/hda3 ro
   3.451 -     boot using a standard hard disk partition as root
   3.452 -     !!! remember to grant access in createlinuxdom.py.
   3.453 -
   3.454 - * root=/dev/xvda1 ro
   3.455 -     boot using a pre-configured 'virtual block device' that will be
   3.456 -     attached to a virtual disk that previously has had a file system
   3.457 -     installed on it.
   3.458 -
   3.459 - * root=/dev/nfs nfsroot=/path/on/server ip=<blah_including server_IP>
   3.460 -     Boot using an NFS mounted root file system. This could be from a
   3.461 -     remote NFS server, or from an NFS server running in another
   3.462 -     domain. The latter is rather a useful option.
   3.463 -
   3.464 -A typical setup might be to allocate a standard disk partition for
   3.465 -each domain and populate it with files. To save space, having a shared
   3.466 -read-only usr partition might make sense.
   3.467 -
   3.468 -Block devices should only be shared between domains in a read-only
   3.469 -fashion otherwise the linux kernels will obviously get very confused
   3.470 -as the file system structure may change underneath them (having the
   3.471 -same partition mounted rw twice is a sure fire way to cause
   3.472 -irreparable damage)!  If you want read-write sharing, export the
   3.473 -directory to other domains via NFS from domain0.
   3.474 -
   3.475 -
   3.476 -
   3.477 -
   3.478 -Installing the file systems from the CD
   3.479 -=======================================
   3.480 -
   3.481 -If you haven't got an existing Linux installation onto which you can
   3.482 -just drop down the Xen and Xenlinux images, then the file systems on
   3.483 -the CD provide a quick way of doing an install. However, you would be
   3.484 -better off in the long run doing a proper install of your preferred
   3.485 -distro and installing Xen onto that, rather than just doing the hack
   3.486 -described below:
   3.487 -
   3.488 -Choose one or two partitions, depending on whether you want a separate
   3.489 -/usr or not. Make file systems on it/them e.g.: 
   3.490 -  mkfs -t ext3 /dev/hda3
   3.491 -  [or mkfs -t ext2 /dev/hda3 && tune2fs -j /dev/hda3 if using an old
   3.492 -version of mkfs]
   3.493 -
   3.494 -Next, mount the file system(s) e.g.:
   3.495 -  mkdir /mnt/root && mount /dev/hda3 /mnt/root
   3.496 -  [mkdir /mnt/usr && mount /dev/hda4 /mnt/usr]
   3.497 -  
   3.498 -To install the root file system, simply untar /usr/XenDemoCD/root.tar.gz:
   3.499 -  cd /mnt/root && tar -zxpf /usr/XenDemoCD/root.tar.gz
   3.500 -
   3.501 -You'll need to edit /mnt/root/etc/fstab to reflect your file system
   3.502 -configuration. Changing the password file (etc/shadow) is probably a
   3.503 -good idea too.
   3.504 -
   3.505 -To install the usr file system, copy the file system from CD on /usr,
   3.506 -though leaving out the "XenDemoCD" and "boot" directories:
   3.507 -  cd /usr && cp -a X11R6 etc java libexec root src bin dict kerberos local sbin tmp doc include lib man share /mnt/usr
   3.508 -
   3.509 -If you intend to boot off these file systems (i.e. use them for
   3.510 -domain 0), then you probably want to copy the /usr/boot directory on
   3.511 -the cd over the top of the current symlink to /boot on your root
   3.512 -filesystem (after deleting the current symlink) i.e.:
   3.513 -  cd /mnt/root ; rm boot ; cp -a /usr/boot .
   3.514 -
   3.515 -The XenDemoCD directory is only useful if you want to build your own
   3.516 -version of the XenDemoCD (see below).
   3.517 -
   3.518 -
   3.519 -Debugging
   3.520 -=========
   3.521 -
   3.522 -Xen has a set of debugging features that can be useful to try and
   3.523 -figure out what's going on. Hit 'h' on the serial line (if you
   3.524 -specified a baud rate on the Xen command line) or ScrollLock-h on the
   3.525 -keyboard to get a list of supported commands.
   3.526 -
   3.527 -If you have a crash you'll likely get a crash dump containing an EIP
   3.528 -(PC) which, along with an 'objdump -d image', can be useful in
   3.529 -figuring out what's happened.  Debug a Xenlinux image just as you
   3.530 -would any other Linux kernel.
   3.531 -
   3.532 -We supply a handy debug terminal program which you can find in
   3.533 -/usr/local/src/xen-2.0.bk/tools/misc/miniterm/
   3.534 -This should be built and executed on another machine that is connected
   3.535 -via a null modem cable. Documentation is included.
   3.536 -Alternatively, if the Xen machine is connected to a serial-port server
   3.537 -then we supply a dumb TCP terminal client:
   3.538 - 'tools/xenctl/lib/console_client.py <server host> <server port>'
   3.539 -
   3.540 -
   3.541 -Installing Xen / Xenlinux on a RedHat distribution
   3.542 -===================================================
   3.543 -
   3.544 -When using Xen / Xenlinux on a standard Linux distribution there are
   3.545 -a couple of things to watch out for:
   3.546 -
   3.547 -The first Linux VM that is started when Xen boots start (Domain 0) is
   3.548 -given direct access to the graphics card, so it may use it as a
   3.549 -console. Other domains don't have ttyN consoles, so attempts to run a
   3.550 -'mingetty' against them will fail, generating periodic warning
   3.551 -messages from 'init' about services respawning too fast. They should
   3.552 -work for domain0 just fine.  
   3.553 -IMPORTANT: To prevent warning messages when running RH9 you'll need to
   3.554 -remove ttyN from /etc/inittab for domains>0.  Due to a bug in the RH9
   3.555 -/etc/rc.sysinit script #'ing the lines out of /etc/inittab won't work
   3.556 -as it ignores the '#' and tries to access them anyway.
   3.557 -
   3.558 -Every Xenlinux instance owns a bidirectional 'virtual console'.
   3.559 -The device node to which this console is attached can be configured
   3.560 -by specifying 'xencons=' on the OS command line:
   3.561 - 'xencons=off'  --> disable virtual console
   3.562 - 'xencons=tty'  --> attach console to /dev/tty1 (tty0 at boot-time)
   3.563 - 'xencons=ttyS' --> attach console to /dev/ttyS0
   3.564 -The default is to attach to /dev/tty1, and also to create dummy
   3.565 -devices for /dev/tty2-63 to avoid warnings from many standard distro
   3.566 -startup scripts. The exception is domain 0, which by default attaches
   3.567 -to /dev/ttyS0.
   3.568 -
   3.569 -Note that, because domains>0 don't have any privileged access at all,
   3.570 -certain commands in the default boot sequence will fail e.g. attempts
   3.571 -to update the hwclock, change the console font, update the keytable
   3.572 -map, start apmd (power management), or gpm (mouse cursor).  Either
   3.573 -ignore the errors, or remove them from the startup scripts.  Deleting
   3.574 -the following links are a good start: S24pcmcia S09isdn S17keytable
   3.575 -S26apmd S85gpm
   3.576 -
   3.577 -If you want to use a single root file system that works cleanly for
   3.578 -domain0 and domains>0, one trick is to use different 'init' run
   3.579 -levels. For example, on the Xen Demo CD we use run level 3 for domain
   3.580 -0, and run level 4 for domains>0. This enables different startup
   3.581 -scripts to be run in depending on the run level number passed on the
   3.582 -kernel command line.
   3.583 -
   3.584 -Xenlinux kernels can be built to use runtime loadable modules just
   3.585 -like normal linux kernels. Modules should be installed under
   3.586 -/lib/modules in the normal way.
   3.587 -
   3.588 -If there's some kernel feature that hasn't been built into our default
   3.589 -kernel, there's a pretty good change that if its a non-hardware
   3.590 -related option you'll just be able to enable it and rebuild.  If its
   3.591 -not on the xconfig menu, hack the arch/xen/config.in to put the menu
   3.592 -back in.
   3.593 -
   3.594 -If you're going to use the link local 169.254.1.x addresses to
   3.595 -communicate between VMs, there are a couple of other issues to watch
   3.596 -out for. RH9 appears to have a bug where by default it configures the
   3.597 -loopback interface with a 169.254 address, which stops it working
   3.598 -properly on eth0 for communicating with other domains.
   3.599 -
   3.600 -This utterly daft RH9 behaviour can be stopped by appending
   3.601 -"NOZEROCONF=yes" to /etc/sysconfig/networking-scripts/ifcfg-lo
   3.602 -
   3.603 -If you're going to use NFS root files systems mounted either from an
   3.604 -external server or from domain0 there are a couple of other gotchas.
   3.605 -The default /etc/sysconfig/iptables rules block NFS, so part way
   3.606 -through the boot sequence things will suddenly go dead.
   3.607 -
   3.608 -If you're planning on having a separate NFS /usr partition, the RH9
   3.609 -boot scripts don't make life easy, as they attempt to mount NFS file
   3.610 -systems way to late in the boot process. The easiest way I found to do
   3.611 -this was to have a '/linuxrc' script run ahead of /sbin/init that
   3.612 -mounts /usr:
   3.613 - #!/bin/bash
   3.614 - /sbin/ipconfig lo 127.0.0.1
   3.615 - /sbin/portmap
   3.616 - /bin/mount /usr
   3.617 - exec /sbin/init "$@" <>/dev/console 2>&1
   3.618 -
   3.619 -The one slight complication with the above is that /sbib/portmap is
   3.620 -dynamically linked against /usr/lib/libwrap.so.0 Since this is in
   3.621 -/usr, it won't work. I solved this by copying the file (and link)
   3.622 -below the /usr mount point, and just let the file be 'covered' when
   3.623 -the mount happens.
   3.624 -
   3.625 -In some installations, where a shared read-only /usr is being used, it
   3.626 -may be desirable to move other large directories over into the
   3.627 -read-only /usr. For example, on the XenDemoCD we replace /bin /lib and
   3.628 -/sbin with links into /usr/root/bin /usr/root/lib and /usr/root/sbin
   3.629 -respectively. This creates other problems for running the /linuxrc
   3.630 -script, requiring bash, portmap, mount, ifconfig, and a handful of
   3.631 -other shared libraries to be copied below the mount point. I guess I
   3.632 -should have written a little statically linked C program...
   3.633 -
   3.634 -
   3.635 -
   3.636 -Description of how the XenDemoCD boots
   3.637 -======================================
   3.638 -
   3.639 -1. Grub is used to load Xen, a Xenlinux kernel, and an initrd (initial
   3.640 -ram disk). [The source of the version of Grub used is in /usr/local/src]
   3.641 -
   3.642 -2. the init=/linuxrc command line causes linux to execute /linuxrc in
   3.643 -the initrd. 
   3.644 -
   3.645 -3. the /linuxrc file attempts to mount the CD by trying the likely
   3.646 -locations : /dev/hd[abcd].  
   3.647 -
   3.648 -4. it then creates a 'tmpfs' file system and untars the
   3.649 -'XenDemoCD/root.tar.gz' file into the tmpfs. This contains hopefully
   3.650 -all the files that need to be mutable (this would be so much easier
   3.651 -if Linux supported 'stacked' or union file systems...)
   3.652 -
   3.653 -5. Next, /linuxrc uses the pivot_root call to change the root file
   3.654 -system to the tmpfs, with the CD mounted as /usr.
   3.655 -
   3.656 -6. It then invokes /sbin/init in the tmpfs and the boot proceeds
   3.657 -normally.
   3.658 -
   3.659 -
   3.660 -Building your own version of the XenDemoCD
   3.661 -==========================================
   3.662 -
   3.663 -The 'live ISO' version of RedHat is based heavily on Peter Anvin's
   3.664 -SuperRescue CD version 2.1.2 and J. McDaniel's Plan-B:
   3.665 -
   3.666 - http://www.kernel.org/pub/dist/superrescue/v2/
   3.667 - http://projectplanb.org/
   3.668 -
   3.669 -Since Xen uses a "multiboot" image format, it was necessary to change
   3.670 -the bootloader from isolinux to Grub0.93 with Leonid Lisovskiy's
   3.671 -<lly@pisem.net> grub.0.93-iso9660.patch
   3.672 -
   3.673 -The Xen Demo CD contains all of the build scripts that were used to
   3.674 -create it, so it is possible to 'unpack' the current iso, modifiy it,
   3.675 -then build a new iso. The procedure for doing so is as follows:
   3.676 -
   3.677 -First, mount either the CD, or the iso image of the CD:
   3.678 - 
   3.679 -  mount /dev/cdrom /mnt/cdrom 
   3.680 -or:
   3.681 -  mount -o loop xendemo-1.0.iso  /mnt/cdrom
   3.682 -
   3.683 -cd to the directory you want to 'unpack' the iso into then run the
   3.684 -unpack script:
   3.685 -
   3.686 -  cd /local/xendemocd
   3.687 -  /mnt/cdrom/XenDemoCD/unpack-iso.sh
   3.688 -
   3.689 -The result is a 'build' directory containing the file system tree
   3.690 -under the 'root' directory. e.g. /local/xendemocd/build/root
   3.691 -
   3.692 -To add or remove rpms, its possible to use 'rpm' with the --root
   3.693 -option to set the path. For more complex changes, it easiest to boot a
   3.694 -machine using using the tree via NFS root. Before doing this, you'll
   3.695 -need to edit fstab to comment out the seperate mount of /usr.
   3.696 -
   3.697 -One thing to watch out for: as part of the CD build process, the
   3.698 -contents of the 'rootpatch' tree gets copied over the existing 'root'
   3.699 -tree replacing various files. The intention of the rootpatch tree is
   3.700 -to contain the files that have been modified from the original RH
   3.701 -distribution (e.g. various /etc files). This was done to make it
   3.702 -easier to upgrade to newer RH versions in the future. The downside of
   3.703 -this is that if you edit an existing file in the root tree you should
   3.704 -check that you don't also need to propagate the change to the
   3.705 -rootpatch tree to avoid it being overwritten.
   3.706 -
   3.707 -Once you've made the changes and want to build a new iso, here's the
   3.708 -procedure:
   3.709 -
   3.710 -cd /local/xendemocd/build  
   3.711 -echo '<put_your_name_here>' > Builder
   3.712 -./make.sh put_your_version_id_here >../buildlog 2>&1            
   3.713 -
   3.714 -This process can take 30 mins even on a fast machine, but you should
   3.715 -eventually end up with an iso image in the build directory.
   3.716 -
   3.717 -Notes:
   3.718 -
   3.719 -  root      - the root of the file system heirarchy as presented to the
   3.720 -              running system
   3.721 -
   3.722 -  rootpatch - contains files that have been modified from the standard
   3.723 -              RH, and copied over the root tree as part of the build
   3.724 -              procedure.
   3.725 -
   3.726 -  irtree    - the file system tree that will go into the initrd (initial
   3.727 -              ram disk)
   3.728 -
   3.729 -  work      - a working directory used in the build process
   3.730 -
   3.731 -  usr       - this should really be in 'work' as its created as part of the
   3.732 -              build process. It contains the 'immutable' files that will
   3.733 -              be served from the CD rather than the tmpfs containing the
   3.734 -              contents of root.tar.gz. Some files that are normally in /etc 
   3.735 -              or /var that are large and actually unlikely to need changing 
   3.736 -              have been moved into /usr/root and replaced with links.
   3.737 -
   3.738 -
   3.739 -Ian Pratt
   3.740 -9 Sep 2003
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/docs/misc/xend.tex	Thu Oct 28 16:18:49 2004 +0000
     4.3 @@ -0,0 +1,443 @@
     4.4 +% -*- mode: LaTeX -*-
     4.5 +\def\seca{\chapter}
     4.6 +\def\secb{\section}
     4.7 +\def\secc{\subsection}
     4.8 +\def\secd{\subsubsection}
     4.9 +\def\refa{chapter}
    4.10 +\def\refb{section}
    4.11 +\def\refc{section}
    4.12 +\def\refd{section}
    4.13 +
    4.14 +%\def\seca{\section}
    4.15 +%\def\secb{\subsection}
    4.16 +%\def\secc{\subsubsection}
    4.17 +%\def\refa{section}
    4.18 +%\def\refb{section}
    4.19 +%\def\refc{section}
    4.20 +
    4.21 +\documentclass[11pt,twoside,final,openright]{xenstyle}
    4.22 +\usepackage{a4,graphicx,setspace}
    4.23 +\setstretch{1.15}
    4.24 +
    4.25 +\begin{document}
    4.26 +
    4.27 +% TITLE PAGE
    4.28 +\pagestyle{empty}
    4.29 +\begin{center}
    4.30 +\vspace*{\fill}
    4.31 +\includegraphics{figs/xenlogo.eps}
    4.32 +\vfill
    4.33 +\vfill
    4.34 +\vfill
    4.35 +\begin{tabular}{l}
    4.36 +{\Huge \bf Xend} \\[4mm]
    4.37 +{\huge Xen v2.0 for x86} \\[80mm]
    4.38 +
    4.39 +{\Large Xen is Copyright (c) 2004, The Xen Team} \\[3mm]
    4.40 +{\Large University of Cambridge, UK} \\[20mm]
    4.41 +{\large Last updated 30 August 2004}
    4.42 +\end{tabular}
    4.43 +\vfill
    4.44 +\end{center}
    4.45 +\cleardoublepage
    4.46 +
    4.47 +% TABLE OF CONTENTS
    4.48 +\pagestyle{plain}
    4.49 +\pagenumbering{roman}
    4.50 +{ \parskip 0pt plus 1pt
    4.51 +  \tableofcontents }
    4.52 +\cleardoublepage
    4.53 +% PREPARE FOR MAIN TEXT
    4.54 +\pagenumbering{arabic}
    4.55 +\raggedbottom
    4.56 +\widowpenalty=10000
    4.57 +\clubpenalty=10000
    4.58 +\parindent=0pt
    4.59 +\renewcommand{\topfraction}{.8}
    4.60 +\renewcommand{\bottomfraction}{.8}
    4.61 +\renewcommand{\textfraction}{.2}
    4.62 +\renewcommand{\floatpagefraction}{.8}
    4.63 +
    4.64 +\setstretch{1.15}
    4.65 +
    4.66 +\seca{Introduction}
    4.67 +Xend is the control daemon used to manage a machine running the Xen hypervisor.
    4.68 +Xend is responsible for creating and destroying domains and managing their
    4.69 +resources, such as virtual block devices and virtual network interfaces.
    4.70 +
    4.71 +Xend exists because the Xen hypervisor itself only manages the memory image
    4.72 +of a domain and its scheduling. Xen provides the event channels that connect
    4.73 +a domain to its devices, but is intentionally not involved in setting them up.
    4.74 +
    4.75 +Xend runs as a daemon in the privileged domain 0 and uses a low-level api
    4.76 +to communicate with Xen via the domain 0 kernel. Xend exports its control
    4.77 +interface to its clients using HTTP. Most programming languages have
    4.78 +HTTP client libraries, so this interface can be used from most popular 
    4.79 +languages, for example Python, Perl, C, Java.
    4.80 +Xend itself is written in Python, as are most of the Xen tools.
    4.81 +
    4.82 +The xend interface is intended to be a complete interface for the creation
    4.83 +and management of domains. It supports domain creation, shutdown, reboot,
    4.84 +destruction, save, restore and migration.
    4.85 +
    4.86 +When xend creates a domain it creates the domain memory image and communicates
    4.87 +with the device driver domain(s) to configure the devices for the domain.
    4.88 +This sets up connections between the domain and backend device controllers
    4.89 +in the driver domain. When a domain shuts down its memory image cannot be fully released
    4.90 +unless its backend devices are released and disconnected. This is done by xend.
    4.91 +In order to protect against loss of this information when xend is restarted,
    4.92 +xend maintains a persistent database of domain configurations. This allows
    4.93 +xend to be stopped and restarted without loss of configuration information.
    4.94 +For example, in order to upgrade the xend software.
    4.95 +
    4.96 +\seca{Domain lifecycle}
    4.97 +\secb{Domain creation}
    4.98 +Xend is instructed to create a domain by posting a domain\_create message to it,
    4.99 +containing the domain configuration to be instantiated. The domain configuration
   4.100 +is in sxp format and is as far as possible {\em fully-bound}, that is, all
   4.101 +parameters are fully-specified. The domain configuration is saved in the filesystem
   4.102 +so that it can be reused later if necessary.
   4.103 +
   4.104 +The domain configuration specifies the domain name, memory size, kernel image
   4.105 +and parameters, and all the domain devices. Xend uses the Xen api to create
   4.106 +the domain memory image, and then {\em builds} the memory image for the domain
   4.107 +using the kernel image. At this point the domain exists, but it cannot be run because
   4.108 +it has no devices. Xend then communicates with the device driver domain to create
   4.109 +the configured devices. Once the devices are created it sets up event channels
   4.110 +for them between the driver domain and the new domain, and notifies the new domain
   4.111 +that its devices are connected. At this point the domain can be started.
   4.112 +
   4.113 +Xend is also responsible for managing domain consoles. When a domain is created,
   4.114 +xend sets up a console event channel to the domain, and creates a TCP listening port
   4.115 +for the domain console. When a connection is accepted to the port, xend
   4.116 +connects input and output for the port to the domain console channel.
   4.117 +
   4.118 +\secb{Domain destruction}
   4.119 +When a domain terminates, because it has been shutdown or it has crashed, the
   4.120 +domain resources must be released so that the domain memory image can be
   4.121 +finally removed from xen. Xend monitors the domains, and is also signaled by
   4.122 +xen (using a VIRQ) when a domain exits. Xend examines the domain states and
   4.123 +determines which domains have exited. It then communicates with the driver domain
   4.124 +to release the devices for exited domains. Xend also closes any open console
   4.125 +connections and removes the TCP listeners for exited domains.
   4.126 +Once all devices have been released it instructs xen to destroy the memory image.
   4.127 +
   4.128 +\secb{Domain restart}
   4.129 +Domain restart is the xen equivalent of a machine reboot. When a domain
   4.130 +exits because it has been shutdown in reboot mode, its exit code is reboot.
   4.131 +When examining domains to find those that have exited and destroy them,
   4.132 +xend detects those that have exited for reboot and does not completely destroy
   4.133 +them. It disconnects all their devices, and detaches the console listener
   4.134 +from its channel to the domain, but does not close it. Instead it schedules
   4.135 +a call to rebuild the domain from its configuration. This proceeds almost
   4.136 +identically to creating the domain, except that the console listener is
   4.137 +reused and connected to the new domain. This allows existing console
   4.138 +connections to remain connected across a domain restart. The restarted
   4.139 +domain keeps the same name and domain id.
   4.140 +
   4.141 +The determination of when to restart a domain is in fact slightly more
   4.142 +complex than described above. A domain is configured with a 
   4.143 +{\em restart mode}. If the restart mode is {\em onreboot}, the default,
   4.144 +restart happens when the domain is shutdown normally and
   4.145 +exits with code reboot. If the restart mode is {\em never} the domain is
   4.146 +not restarted. If the restart mode is {\em always} the domain is always
   4.147 +restarted, regardless of how it exited.
   4.148 +
   4.149 +In order to prevent continual domain crash causing restart loops, xend
   4.150 +has a {\em minimum restart time}. Xend remembers when a domain was last
   4.151 +restarted and will fail a restart that happens inside the minimum
   4.152 +restart time.
   4.153 +
   4.154 +\seca{Devices}
   4.155 +\secb{Virtual network interfaces}
   4.156 +Each virtual network interface (vif) has 2 parts: the font-end device in its domain,
   4.157 +and the back-end device in the driver domain. Usually the driver domain is domain 0,
   4.158 +and there is a linux network device corresponding to the vif. The linux device for
   4.159 +interface N on domain D is called vifD.N. When a packet is sent on the vif in the 
   4.160 +domain the packet is received from the linux device. The linux devices are connected
   4.161 +to network interfaces using ethernet bridging.
   4.162 +
   4.163 +The default setup is a bridge xen-br0, with eth0 connected to it, and the routes
   4.164 +for eth0 directed at xen-br0. This is controlled by the xend network setup script,
   4.165 +default {\tt /etc/xen/network}, which is run when xend starts.
   4.166 +
   4.167 +When the vifs for a domain are created, a vif control script, default {\tt /etc/xen/vif-bridge},
   4.168 +is run to connect the vif to its bridge. The default script connects the vif
   4.169 +to xen-br0 and optionally sets up iptables rules to prevent IP address spoofing.
   4.170 +The bridge a vif is connected to can be defined in its configuration, and this is useful
   4.171 +for setting up virtual networks using several bridges.
   4.172 +
   4.173 +\secb{Virtual block devices}
   4.174 +Virtual block devices in a domain are interfaces onto back-end device drivers
   4.175 +that export physical devices to domains. In the default configuration the back-end
   4.176 +driver is in domain 0 and can export any linux block device to a domain. This includes
   4.177 +physical disk partitions, LVM volumes and loopback mounts of files. In fact anything
   4.178 +that linux can represent as a block device can be exported to a domain as virtual
   4.179 +block device.
   4.180 +
   4.181 +\seca{Xend invocation}
   4.182 +Xend is started (by root) using the command
   4.183 +\begin{verbatim}
   4.184 +xend start
   4.185 +\end{verbatim}
   4.186 +Xend can be stopped using
   4.187 +\begin{verbatim}
   4.188 +xend stop
   4.189 +\end{verbatim}
   4.190 +Xend must be started before any domains (apart from domain 0) can be created.
   4.191 +If you try to use the {\tt xm} tool when xend is not running you will get a
   4.192 +'connection refused' message.
   4.193 +
   4.194 +\secb{Xend configuration}
   4.195 +Xend reads its own configuration from {\tt /etc/xen/xend-config.sxp}, which is
   4.196 +a sequence of s-expressions. The configuration parameters are:
   4.197 +\begin{itemize}
   4.198 +
   4.199 +\item xend-port: Port xend should use for the HTTP interface (default 8000).
   4.200 +
   4.201 +\item xend-address: Address xend should listen on.
   4.202 +  Specifying 'localhost' prevents remote connections.
   4.203 +  Specifying the empty string '' allows all connections, and is the default.
   4.204 +
   4.205 +\item network-script: The script used to start/stop networking for xend (default network).
   4.206 +
   4.207 +\item vif-bridge: The default bridge that virtual interfaces should be connected to
   4.208 +  (default xen-br0).
   4.209 +
   4.210 +\item vif-script: The default script used to control virtual interfaces
   4.211 +  (default vif-bridge).
   4.212 +
   4.213 +\item vif-antispoof: Whether iptables should be set up to prevent IP spoofing for
   4.214 +  virtual interfaces (default yes).
   4.215 +\end{itemize}
   4.216 +
   4.217 +Configuration scripts ({\it e.g.} for network-script) are looked for in {\tt /etc/xen}
   4.218 +unless their name begins with '/'.
   4.219 +
   4.220 +Xend sends its log output to {\tt /var/log/xend.log}. This is a rotating logfile,
   4.221 +and logs are moved onto {\tt xend.log.1} {\it etc.} as they get large. Old logs may
   4.222 +be deleted.
   4.223 +
   4.224 +\secb{Xend database}
   4.225 +Xend needs to make some data persistent, and it uses files under {\tt /var/xen/xend-db}
   4.226 +for this. The persistent data is stored in files in SXP format. Domain information
   4.227 +is saved when domains are created. When xend starts it reads the file {\tt /var/xen/lastboot}
   4.228 +(if it exists) to determine the last time the system was rebooted. It compares this time
   4.229 +with the last reboot time in {\tt wtmp} to determine if the system has been rebooted
   4.230 +since xend last ran. If the system has been rebooted xend removes all its saved data
   4.231 +that is not persistent across reboots (for example domain data).
   4.232 +
   4.233 +\seca{Xend HTTP Interface}
   4.234 + The xend interface uses HTTP 1.1 \cite{http} as its transport.
   4.235 +Simple PUT and GET calls can encode parameters using the standard url-encoding 
   4.236 +for parameters: MIME type {\tt application/x-www-form-urlencoded}.
   4.237 +When file upload is required, the {\tt multipart/form-data} encoding is used.
   4.238 +See the HTML 4.1 specification for details \cite{html}.
   4.239 +
   4.240 +Xend functions as a webserver and supports two interfaces: one
   4.241 +for web-browsers and one for programs.
   4.242 +The web-browser interface returns replies in HTML and includes forms
   4.243 +for interactive operations such as stopping domains and creating domains
   4.244 +from an uploaded configuration. The programmatic interface usually returns replies
   4.245 +in s-expression format. Both interfaces are accessed
   4.246 +in exactly the same way over HTTP - the only difference is the data returned.
   4.247 +
   4.248 +The webserver distinguishes browsers from programs using the {\tt User-Agent}
   4.249 +and {\tt Accept} headers in the HTTP request. If there is no {\tt User-Agent} or no
   4.250 +{\tt Acccept} header, or {\tt Accept} includes the type {\tt application/sxp}, the
   4.251 +webserver assumes the client is a program and returns SXP. Otherwise
   4.252 +it assumes the client is a webserver and returns HTML.
   4.253 +In some cases the return value is essentially a string, so {\tt Content-Type}
   4.254 +{\tt text/plain} is returned.
   4.255 +
   4.256 +The HTTP api supported is listed below. All paths in it are relative to the
   4.257 +server root, for example {\tt http://localhost:8000/xend}.
   4.258 +As defined in the HTTP specification, we use GET for side-effect free
   4.259 +operations that may safely be repeated, and POST for operations with
   4.260 +side-effects. For each request we list the HTTP method (GET or POST),
   4.261 +the url relative to the server root, the operation name and arguments (if any).
   4.262 +The operation name is passed as request parameter 'op', and the arguments
   4.263 +are passed by name. Operation name and parameters can be encoded using either
   4.264 +encoding described above. We also list the corresponding api function from the
   4.265 +Python client interface in {\tt xen.xend.XendClient}.
   4.266 +
   4.267 +\begin{itemize}
   4.268 +\item {\tt GET /},\\
   4.269 +  {\tt xend()}:\\
   4.270 +  Get list of urls under xend root.
   4.271 +
   4.272 +\item {\tt GET /node},\\
   4.273 +  {\tt xend\_node()}:\\
   4.274 +  Get node information.
   4.275 +
   4.276 +\item {\tt POST /node shutdown()},\\
   4.277 +  {\tt xend\_node\_shutdown()}:\\
   4.278 +  Shutdown the node
   4.279 +
   4.280 +\item {\tt POST /node reboot()},\\
   4.281 +  {\tt xend\_node\_reboot()}:\\
   4.282 +  Reboot the node
   4.283 +
   4.284 +\item {\tt POST /node notify()}:\\
   4.285 +  Set node notification url
   4.286 +  
   4.287 +\item {\tt GET /node/dmesg},\\
   4.288 +  {\tt xend\_node\_dmesg()}:\\
   4.289 +  Get xen boot message.
   4.290 +
   4.291 +\item {\tt GET /node/log},\\
   4.292 +  {\tt xend\_node\_log()}:\\
   4.293 +  Get xend log.
   4.294 +
   4.295 +\item {\tt GET /domain}\\
   4.296 +  {\tt xend\_domains()}:\\
   4.297 +  Get list of domains.
   4.298 +
   4.299 +\item {\tt POST /domain create(config)},\\
   4.300 +  {\tt xend\_domain\_create(config)}:\\
   4.301 +  Create a domain.
   4.302 +
   4.303 +\item {\tt POST /domain restore(file)},\\
   4.304 +  {\tt xend\_domain\_restore(filename)}:\\
   4.305 +  Restore a saved domain.
   4.306 +
   4.307 +\item {\tt GET /domain/<dom>},\\
   4.308 +  {\tt xend\_domain(dom)}:\\
   4.309 +  Get domain information.
   4.310 +
   4.311 +\item {\tt POST /domain/[dom] configure(config)},\\
   4.312 +  {\tt xend\_domain\_configure(dom, conf)}:\\
   4.313 +  Configure an existing domain (for internal use by restore and migrate).
   4.314 +
   4.315 +\item {\tt POST /domain/[dom] unpause()},\\
   4.316 +  {\tt xend\_domain\_unpause(dom)}:\\
   4.317 +  Start domain running
   4.318 +
   4.319 +\item {\tt POST /domain/[dom] pause()},\\
   4.320 +  {\tt xend\_domain\_pause(dom)}:\\
   4.321 +  Stop domain running.
   4.322 +
   4.323 +\item {\tt POST /domain/[dom] shutdown(reason)},\\
   4.324 +  {\tt xend\_domain\_shutdown(dom, reason)}:\\
   4.325 +  Shutdown domain, reason can be reboot, poweroff, halt.
   4.326 +
   4.327 +\item {\tt POST /domain/[dom] destroy(reason)},\\
   4.328 +  {\tt xend\_domain\_destroy(dom, reason)}:\\
   4.329 +  Destroy domain, reason can be reboot, halt.
   4.330 +
   4.331 +\item {\tt POST /domain/[dom] save(file)},\\
   4.332 +  {\tt xend\_domain\_save(dom, filename)}:\\
   4.333 +  Save a domain to a file.
   4.334 +
   4.335 +\item {\tt POST /domain/[dom] migrate(dst)},\\
   4.336 +  {\tt xend\_domain\_migrate(dom, dst)}:\\
   4.337 +  Migrate a domain.
   4.338 +
   4.339 +\item {\tt POST /domain/[dom] pincpu(cpu)},\\
   4.340 +  {\tt xend\_domain\_pincpu(self, id, cpu)}\\:
   4.341 +  Pin a domain to a cpu.
   4.342 +
   4.343 +\item {\tt POST /domain/[dom] bvt\_set(mcuadv, warp, warpl, warpu)},\\
   4.344 +  {\tt xend\_domain\_cpu\_bvt\_set(dom, mcuadv, warp, warpl, warpu)}:\\
   4.345 +  Set BVT scheduler parameters.
   4.346 +
   4.347 +\item {\tt POST /domain/[dom] atropos\_set(period, slice, latency, xtratime)},\\
   4.348 +  {\tt xend\_domain\_cpu\_atropos\_set(dom, period, slice, latency, xtratime)}:\\
   4.349 +  Set atropos scheduler parameters.
   4.350 +
   4.351 +\item {\tt POST /domain/[dom] maxmem\_set(memory)},\\
   4.352 +  {\tt xend\_domain\_maxmem\_set(dom, memory)}:\\
   4.353 +  Set domain maximum memory limit.
   4.354 +
   4.355 +\item {\tt POST /domain/[dom] device\_create(config)}\\
   4.356 +  {\tt xend\_domain\_device\_create(dom, config)}:\\
   4.357 +  Add a device to a domain.
   4.358 +
   4.359 +\item {\tt POST /domain/[dom] device\_destroy(type, index)},\\
   4.360 +  {\tt xend\_domain\_device\_destroy(dom, type, index)}:\\
   4.361 +  Delete a device from a domain
   4.362 +
   4.363 +\item {\tt GET /domain/[dom] vifs()},\\
   4.364 +  {\tt xend\_domain\_vifs(dom)}:\\
   4.365 +  Get virtual network interfaces.
   4.366 +
   4.367 +\item {\tt GET /domain/[dom] vif(vif)},\\
   4.368 +  {\tt xend\_domain\_vif(dom, vif)}:\\
   4.369 +  Get virtual network interface.
   4.370 +
   4.371 +\item {\tt GET /domain/[dom] vbds()},\\
   4.372 +  {\tt xend\_domain\_vbds(dom)}:\\
   4.373 +  Get virtual block devices.
   4.374 +
   4.375 +\item {\tt GET /domain/[dom] vbd(vbd)},\\
   4.376 +  {\tt xend\_domain\_vbd(dom, vbd)}:\\
   4.377 +  Get virtual block device.
   4.378 +
   4.379 +\item {\tt GET /console},\\
   4.380 +  {\tt xend\_consoles()}:\\
   4.381 +  Get list of consoles.
   4.382 +
   4.383 +\item {\tt GET /console/[id]}\\
   4.384 +  {\tt xend\_console(id)}:\\
   4.385 +  Get information about a console.
   4.386 +
   4.387 +\item {\tt GET /console/[id] disconnect()}\\
   4.388 +  {\tt xend\_console\_disconnect(self, id)}:\\
   4.389 +  Disconnect any console TCP connection.
   4.390 +
   4.391 +\item {\tt GET /vnet}\\
   4.392 +  {\tt xend\_vnets()}:\\
   4.393 +  Get list of vnets (virtual networks).
   4.394 +
   4.395 +\item {\tt GET /vnet/[id]}\\
   4.396 +  {\tt xend\_vnet(id)}:\\
   4.397 +  Get information about a virtual network.
   4.398 +
   4.399 +\item {\tt POST /vnet create(config)}\\
   4.400 +  {\tt xend\_vnet\_create(conf)}:\\
   4.401 +  Create a vnet.
   4.402 +
   4.403 +\item {\tt POST /vnet/[id] delete()}\\
   4.404 +  {\tt xend\_vnet\_delete(id)}:\\
   4.405 +  Delete a vnet.
   4.406 +
   4.407 +\item {\tt POST /event inject(event)}\\
   4.408 +  {\tt xend\_event\_inject(sxpr)}:\\
   4.409 +  Inject an event.
   4.410 +
   4.411 +\end{itemize}
   4.412 +
   4.413 +\secb{Xend debugging interface}
   4.414 +Xend also listens on port 8001. Connecting to this port (for example via telnet)
   4.415 +allows access to some debugging functions:
   4.416 +\begin{itemize}
   4.417 +\item help: list functions
   4.418 +\item traceon: turn xend tracing on
   4.419 +\item traceoff: turn xend tracing off
   4.420 +\item quit: disconnect.
   4.421 +\item info: list console listeners, block and network device controllers.
   4.422 +\end{itemize}
   4.423 +
   4.424 +When tracing is on xend logs all functions calls and exceptions to
   4.425 +{\tt /var/log/xend.trace}.
   4.426 +
   4.427 +\begin{thebibliography}{99}
   4.428 +
   4.429 +\bibitem{html}
   4.430 +HTML 4.01 Specification,\\
   4.431 +http://www.w3.org/TR/html4/,\\
   4.432 +W3C Recommendation, 24 December 1999.
   4.433 +
   4.434 +\bibitem{http}
   4.435 +Hypertext Transfer Protocol -- HTTP/1.1,\\
   4.436 +http://www.ietf.org/rfc/rfc2616.txt,\\
   4.437 +RFC 2616, IETF 1999.
   4.438 +
   4.439 +\bibitem{ssh}
   4.440 +http://www.openssh.org.
   4.441 +
   4.442 +\bibitem{stunnel}
   4.443 +http://www.stunnel.org.
   4.444 +
   4.445 +\end{thebibliography}
   4.446 +\end{document}
     5.1 --- a/docs/src/interface.tex	Thu Oct 28 13:03:45 2004 +0000
     5.2 +++ b/docs/src/interface.tex	Thu Oct 28 16:18:49 2004 +0000
     5.3 @@ -1,5 +1,5 @@
     5.4  \documentclass[11pt,twoside,final,openright]{xenstyle}
     5.5 -\usepackage{a4,graphicx,setspace}
     5.6 +\usepackage{a4,graphicx,setspace,times}
     5.7  \setstretch{1.15}
     5.8  
     5.9  \begin{document}
    5.10 @@ -37,6 +37,7 @@
    5.11  \widowpenalty=10000
    5.12  \clubpenalty=10000
    5.13  \parindent=0pt
    5.14 +\parskip=5pt
    5.15  \renewcommand{\topfraction}{.8}
    5.16  \renewcommand{\bottomfraction}{.8}
    5.17  \renewcommand{\textfraction}{.2}
     6.1 --- a/docs/src/user.tex	Thu Oct 28 13:03:45 2004 +0000
     6.2 +++ b/docs/src/user.tex	Thu Oct 28 16:18:49 2004 +0000
     6.3 @@ -1,5 +1,5 @@
     6.4  \documentclass[11pt,twoside,final,openright]{xenstyle}
     6.5 -\usepackage{a4,graphicx,setspace}
     6.6 +\usepackage{a4,graphicx,setspace,times}
     6.7  \setstretch{1.15}
     6.8  
     6.9  \begin{document}
    6.10 @@ -37,6 +37,7 @@
    6.11  \widowpenalty=10000
    6.12  \clubpenalty=10000
    6.13  \parindent=0pt
    6.14 +\parskip=5pt
    6.15  \renewcommand{\topfraction}{.8}
    6.16  \renewcommand{\bottomfraction}{.8}
    6.17  \renewcommand{\textfraction}{.2}
    6.18 @@ -55,137 +56,110 @@ these and please report any you find to 
    6.19  Contributions of material, suggestions and corrections are welcome.
    6.20  }
    6.21  
    6.22 -Xen is a { \em paravirtualising } virtual machine monitor (VMM) or
    6.23 -``Hypervisor'' for the x86 processor architecture.  Xen can securely
    6.24 -multiplex heterogeneous virtual machines on a single physical with
    6.25 -near-native performance.  The virtual machine technology facilitates
    6.26 -enterprise-grade functionality, including:
    6.27 +\vspace{5mm}
    6.28 +
    6.29 +Xen is a { \em paravirtualising } virtual machine monitor (VMM), or
    6.30 +`hypervisor', for the x86 processor architecture.  Xen can securely
    6.31 +execute multiple virtual machines on a single physical system with
    6.32 +close-to-native performance.  The virtual machine technology
    6.33 +facilitates enterprise-grade functionality, including:
    6.34  
    6.35  \begin{itemize}
    6.36 -\item Virtual machines with close to native performance.
    6.37 +\item Virtual machines with performance nearly identical to native
    6.38 +  hardware.
    6.39  \item Live migration of running virtual machines.
    6.40 -\item Excellent hardware support (use unmodified Linux device drivers).
    6.41 +\item Excellent hardware support (supports most Linux device drivers).
    6.42  \item Suspend to disk / resume from disk of running virtual machines.
    6.43 -\item Transparent copy on write disks.
    6.44 +\item Transparent copy-on-write disks for simple sharing across VMs.
    6.45  \item Sandboxed, restartable device drivers.
    6.46 -\item Pervasive debugging - debug whole OSes, from kernel to applications.
    6.47  \end{itemize}
    6.48  
    6.49 -Xen support is available for increasingly many operating systems.  The
    6.50 -following OSs have either been ported already or a port is in
    6.51 -progress:
    6.52 -\begin{itemize}
    6.53 -\item Linux 2.4
    6.54 -\item Linux 2.6
    6.55 -\item NetBSD 2.0
    6.56 -\item Dragonfly BSD
    6.57 -\item FreeBSD 5.3
    6.58 -\item Plan 9
    6.59 -% \item Windows XP
    6.60 -\end{itemize}
    6.61 +Paravirtualisation allows very high performance virtual machine
    6.62 +technology, even on architectures like x86 that are traditionally
    6.63 +hard to virtualise.
    6.64 +The drawback of this approach is that it requires operating systems to
    6.65 +be {\em ported} to run on Xen.  This process is similar to a port of
    6.66 +an operating system to a new hardware platform, although the process
    6.67 +is simplified because the paravirtual machine architecture is very
    6.68 +similar to the underlying native hardware. Although operating system
    6.69 +kernels must explicitly support Xen, a key feature is that user space
    6.70 +applications and libraries {\em do not} require modification.
    6.71  
    6.72 -Right now, Linux 2.4, Linux 2.6 and NetBSD are available for Xen 2.0.
    6.73 -It is intended that Xen support be integrated into the official
    6.74 -releases of Linux 2.6, NetBSD 2.0, FreeBSD and Dragonfly BSD.
    6.75 +Xen support is available for increasingly many operating systems:
    6.76 +right now, Linux 2.4, Linux 2.6 and NetBSD are available for Xen 2.0.
    6.77 +We expect that Xen support will ultimately be integrated into the
    6.78 +official releases of Linux, NetBSD, FreeBSD and Dragonfly BSD. 
    6.79 +Other OS ports, including Plan 9, are in progress.
    6.80  
    6.81 -Even running multiple copies of Linux can be very useful, providing a
    6.82 -means of containing faults to one OS image, providing performance
    6.83 -isolation between the various OS instances and trying out multiple
    6.84 -distros.
    6.85 -
    6.86 -% The Windows XP port is only available to those who have signed the
    6.87 -% Microsoft Academic Source License.  Publically available XP support
    6.88 -% will not be available for the foreseeable future (this may change when
    6.89 -% Intel's Vanderpool Technology becomes available).
    6.90 +%Even running multiple copies of Linux can be very useful, providing a
    6.91 +%means of containing faults to one OS image, providing performance
    6.92 +%isolation between the various OS instances and trying out multiple
    6.93 +%distros.
    6.94  
    6.95  Possible usage scenarios for Xen include:
    6.96  \begin{description}
    6.97 -\item [Kernel development] test and debug kernel modifications in a
    6.98 +\item [Kernel development.] Test and debug kernel modifications in a
    6.99        sandboxed virtual machine --- no need for a separate test
   6.100 -      machine
   6.101 -\item [Multiple OS Configurations] run multiple operating systems
   6.102 -      simultaneously, for instance for compatibility or QA purposes
   6.103 -\item [Server consolidation] move multiple servers onto one box,
   6.104 +      machine.
   6.105 +\item [Multiple OS configurations.] Run multiple operating systems
   6.106 +      simultaneously, for instance for compatibility or QA purposes.
   6.107 +\item [Server consolidation.] Move multiple servers onto one box,
   6.108        provided performance and fault isolation at virtual machine
   6.109 -      boundaries
   6.110 -\item [Cluster computing] improve manageability and efficiency by
   6.111 +      boundaries.
   6.112 +\item [Cluster computing.] Improve manageability and efficiency by
   6.113        running services in virtual machines, isolated from
   6.114 -      machine-specifics and load balance using live migration
   6.115 -\item [High availability computing] run device drivers in sandboxed
   6.116 -      domains for increased robustness
   6.117 -\item [Hardware support for custom OSes] export drivers from a
   6.118 +      machine-specifics and load balance using live migration.
   6.119 +\item [High availability computing.] Run device drivers in sandboxed
   6.120 +      domains for increased robustness.
   6.121 +\item [Hardware support for custom OSes.] Export drivers from a
   6.122        mainstream OS (e.g. Linux) with good hardware support
   6.123        to your custom OS, avoiding the need for you to port existing
   6.124 -      drivers to achieve good hardware support
   6.125 +      drivers to achieve good hardware support.
   6.126  \end{description}
   6.127  
   6.128 -\section{Structure}
   6.129 -
   6.130 -\subsection{High level}
   6.131 +\section{Structure of a Xen-Based System}
   6.132  
   6.133 -A Xen system has multiple layers.  The lowest layer is Xen itself ---
   6.134 -the most privileged piece of code in the system.  On top of Xen run
   6.135 -guest operating system kernels.  These are scheduled pre-emptively by
   6.136 -Xen.  On top of these run the applications of the guest OSs.  Guest
   6.137 -OSs are responsible for scheduling their own applications within the
   6.138 -time allotted to them by Xen.
   6.139 +A Xen system has multiple layers, the lowest and most privileged of
   6.140 +which is Xen itself. Xen in turn may host multiple {\em guest}
   6.141 +operating systems, each of which is executed within a secure virtual
   6.142 +machine (in Xen terminology, a {\em domain}). Domains are scheduled by
   6.143 +Xen to make effective use of the available physical CPUs.  Each guest
   6.144 +OS manages its own applications, which includes responsibility for
   6.145 +scheduling each application within the time allotted to the VM by Xen.
   6.146  
   6.147 -One of the domains --- { \em Domain 0 } --- is privileged.  It is
   6.148 -started by Xen at system boot and is responsible for initialising and
   6.149 -managing the whole machine.  Domain 0 builds other domains and manages
   6.150 -their virtual devices.  It also performs suspend, resume and
   6.151 -migration of other virtual machines.  Where it is used, the X server
   6.152 -is also run in domain 0.
   6.153 +The first domain, {\em Domain 0}, is created automatically when the
   6.154 +system boots and has special management privileges. Domain 0 builds
   6.155 +other domains and manages their virtual devices. It also performs
   6.156 +suspend, resume and migration of virtual machines. Where one is
   6.157 +required, the X server is also run in domain 0.
   6.158  
   6.159 -Within Domain 0, a process called ``Xend'' runs to manage the system.
   6.160 +Within Domain 0, a process called `Xend' runs to manage the system.
   6.161  Xend is responsible for managing virtual machines and providing access
   6.162  to their consoles.  Commands are issued to Xend over an HTTP
   6.163  interface, either from a command-line tool or from a web browser.
   6.164  
   6.165 -XXX need diagram(s) here to make this make sense
   6.166 -
   6.167 -\subsection{Paravirtualisation}
   6.168 -
   6.169 -Paravirtualisation allows very high performance virtual machine
   6.170 -technology, even on architectures (like x86) which are traditionally
   6.171 -hard to virtualise.
   6.172 -
   6.173 -Paravirtualisation requires guest operating systems to be { \em ported
   6.174 -} to run on the VMM.  This process is similar to a port of an
   6.175 -operating system to a new hardware platform.  Although operating
   6.176 -system kernels must explicitly support Xen in order to run in a
   6.177 -virtual machine, { \em user space applications and libraries
   6.178 -do not require modification }.
   6.179 -
   6.180  \section{Hardware Support}
   6.181  
   6.182 -Xen currently runs on the x86 architecture, but could in principle be
   6.183 -ported to others. In fact, it would have been rather easier to write
   6.184 -Xen for pretty much any other architecture as x86 is particularly
   6.185 -tricky to handle. A good description of Xen's design, implementation
   6.186 -and performance is contained in the October 2003 SOSP paper, available
   6.187 -at:\\
   6.188 -{\tt http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}\\
   6.189 -Work to port Xen to x86\_64 and IA64 is currently underway.
   6.190 -
   6.191 -Xen requires a ``P6'' or newer processor (e.g. Pentium Pro, Celeron,
   6.192 +Xen currently runs only on the x86 architecture (however, ports to other
   6.193 +architectures, including x86/64 and IA64, are in progress).
   6.194 +Xen requires a `P6' or newer processor (e.g. Pentium Pro, Celeron,
   6.195  Pentium II, Pentium III, Pentium IV, Xeon, AMD Athlon, AMD Duron).
   6.196  Multiprocessor machines are supported, and we also have basic support
   6.197  for HyperThreading (SMT), although this remains a topic for ongoing
   6.198 -research.  We're also working on an x86\_64 port (though Xen already
   6.199 -runs on these systems just fine in 32-bit mode).
   6.200 +research.  As mentioned above, a port specifically for x86/64 is in
   6.201 +progress, although Xen already runs on such systems in 32-bit legacy
   6.202 +mode.
   6.203  
   6.204  Xen can currently use up to 4GB of memory.  It is possible for x86
   6.205 -machines to address up to 64GB of physical memory but (unless an
   6.206 -external developer volunteers) there are no plans to support these
   6.207 -systems.  The x86\_64 port is the planned route to supporting more
   6.208 -than 4GB of memory.
   6.209 +machines to address up to 64GB of physical memory but there are no
   6.210 +plans to support these systems.  The x86\_64 port is the planned route
   6.211 +to supporting more than 4GB of memory.
   6.212  
   6.213  Xen offloads most of the hardware support issues to the guest OS
   6.214  running in Domain 0.  Xen itself only contains code to detect and
   6.215 -start additional processors, setup interrupt routing and perform PCI
   6.216 +start additional processors, set up interrupt routing and perform PCI
   6.217  bus enumeration.  Device drivers run within a privileged guest OS
   6.218 -rather than within Xen itself.  This means that we should be
   6.219 +rather than within Xen itself, meaning that we should be
   6.220  compatible with the majority of device hardware supported by Linux.
   6.221  The default XenLinux build contains support for relatively modern
   6.222  server-class network and disk hardware, but you can add support for
   6.223 @@ -195,12 +169,11 @@ other hardware by configuring your XenLi
   6.224  \section{History}
   6.225  
   6.226  
   6.227 -``Xen'' is a Virtual Machine Monitor (VMM) originally developed by the
   6.228 -Systems Research Group of the University of Cambridge Computer
   6.229 -Laboratory, as part of the UK-EPSRC funded XenoServers project.
   6.230 -
   6.231 -The XenoServers project aims to provide a ``public infrastructure for
   6.232 -global distributed computing'', and Xen plays a key part in that,
   6.233 +Xen was originally developed by the Systems Research Group at the
   6.234 +University of Cambridge Computer Laboratory as part of the XenoServers
   6.235 +project, funded by UK-EPSRC.
   6.236 +XenoServers aim to provide a `public infrastructure for
   6.237 +global distributed computing', and Xen plays a key part in that,
   6.238  allowing us to efficiently partition a single machine to enable
   6.239  multiple independent clients to run their operating systems and
   6.240  applications in an environment providing protection, resource
   6.241 @@ -213,25 +186,18 @@ investigate interesting research issues 
   6.242  for virtualizing resources such as the CPU, memory, disk and network.
   6.243  The project has been bolstered by support from Intel Research
   6.244  Cambridge, and HP Labs, who are now working closely with us.
   6.245 -% We're also in receipt of support from Microsoft Research Cambridge to
   6.246 -% port Windows XP to run on Xen.
   6.247  
   6.248 -Xen was first described in the 2003 paper at SOSP \\
   6.249 -({\tt http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}).
   6.250 -The first public release of Xen (1.0) was made in October 2003.  Xen
   6.251 -was developed as a research project by the University of Cambridge
   6.252 -Computer Laboratory (UK).  Xen was the first Virtual Machine Monitor
   6.253 -to make use of {\em paravirtualisation} to achieve near-native
   6.254 -performance virtualisation of commodity operating systems.  Since
   6.255 +Xen was first described in the 2003 paper at SOSP\footnote{\tt
   6.256 +http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}, and the
   6.257 +first public release (1.0) was made in October 2003.  Since
   6.258  then, Xen has been extensively developed and is now used in production
   6.259  scenarios on multiple sites.
   6.260  
   6.261 -Xen 2.0 is the latest release, featuring greatly enhanced hardware
   6.262 -support, configuration flexibility, usability and a larger complement
   6.263 -of supported operating systems.  We think that Xen has the potential
   6.264 -to become {\em the} definitive open source virtualisation solution and
   6.265 -will work to conclusively achieve that position.
   6.266 -
   6.267 +Xen 2.0 feature greatly enhanced hardware support, configuration
   6.268 +flexibility, usability and a larger complement of supported operating
   6.269 +systems. We think that Xen has the potential to become {\em the}
   6.270 +definitive open source virtualisation solution and will work to
   6.271 +conclusively achieve that position.
   6.272  
   6.273  \chapter{Installation}
   6.274  
   6.275 @@ -330,7 +296,7 @@ The Xen source code repository is struct
   6.276  
   6.277  \section{Build and install}
   6.278  
   6.279 -The Xen makefile includes a target ``world'' that will do the
   6.280 +The Xen makefile includes a target `world' that will do the
   6.281  following:
   6.282  
   6.283  \begin{itemize}
   6.284 @@ -351,15 +317,15 @@ makefile the location of the appropriate
   6.285  setting the LINUX\_SRC environment variable, e.g. \\
   6.286  \verb!# LINUX_SRC=/tmp/linux-2.6.8.1.tar.bz2 make world! \\ or by
   6.287  placing the tar file somewhere in the search path of {\tt
   6.288 -LINUX\_SRC\_PATH} which defaults to ``{\tt .:..}".  If the makefile
   6.289 +LINUX\_SRC\_PATH} which defaults to `{\tt .:..}'.  If the makefile
   6.290  can't find a suitable kernel tar file it attempts to download it from
   6.291  kernel.org (this won't work if you're behind a firewall).
   6.292  
   6.293  After untaring the pristine kernel tree, the makefile uses the {\tt
   6.294  mkbuildtree} script to add the Xen patches to the kernel.  It then
   6.295 -builds two different XenLinux images, one with a ``-xen0'' extension
   6.296 +builds two different XenLinux images, one with a `-xen0' extension
   6.297  which contains hardware device drivers and drivers for Xen's virtual
   6.298 -devices, and one with a ``-xenU'' extension that just contains the
   6.299 +devices, and one with a `-xenU' extension that just contains the
   6.300  virtual ones.
   6.301  
   6.302  The procedure is similar to build the Linux 2.4 port: \\
   6.303 @@ -407,7 +373,7 @@ The difference between the two Linux ker
   6.304  the configuration file used for each.  The "U" suffixed unprivileged
   6.305  version doesn't contain any of the physical hardware device drivers
   6.306  --- it is 30\% smaller and hence may be preferred for your
   6.307 -non-privileged domains.  The ``0'' suffixed privileged version can be
   6.308 +non-privileged domains.  The `0' suffixed privileged version can be
   6.309  used to boot the system, as well as in driver domains and unprivileged
   6.310  domains.
   6.311  
   6.312 @@ -989,13 +955,13 @@ domains and provides a user friendly dom
   6.313                             a complete system of real hardware devices.
   6.314  
   6.315  \item[Hypervisor]          An alternative term for { \bf VMM }, used
   6.316 -                           because it means ``beyond supervisor'',
   6.317 +                           because it means `beyond supervisor',
   6.318                             since it is responsible for managing multiple
   6.319 -                           ``supervisor'' kernels.
   6.320 +                           `supervisor' kernels.
   6.321  
   6.322  \item[Live migration]      A technique for moving a running virtual
   6.323                             machine to another physical host, without
   6.324 -			   stopping it or the services running on it.
   6.325 +                           stopping it or the services running on it.
   6.326  
   6.327  \item[Microkernel]         A small base of code running at the highest
   6.328                             hardware privilege level.  A microkernel is
   6.329 @@ -1018,10 +984,10 @@ domains and provides a user friendly dom
   6.330  
   6.331  \item[Shadow pagetables]   A technique for hiding the layout of machine
   6.332                             memory from a virtual machine's operating
   6.333 -			   system.  Used in some {\bf VMM}s to provide
   6.334 -			   the illusion of contiguous physical memory,
   6.335 -			   in Xen this is used during
   6.336 -			   {\bf live migration}.
   6.337 +                           system.  Used in some {\bf VMM}s to provide
   6.338 +                           the illusion of contiguous physical memory,
   6.339 +                           in Xen this is used during
   6.340 +                           {\bf live migration}.
   6.341  
   6.342  \item[Virtual Machine]     The environment in which a hosted operating
   6.343                             system runs, providing the abstraction of a
   6.344 @@ -1049,8 +1015,8 @@ domains and provides a user friendly dom
   6.345  \chapter{Advanced Network Configuration}
   6.346  
   6.347  For simple systems with a single ethernet interface with a simple
   6.348 -configuration, the default installation should work ``out of the
   6.349 -box''.  More complicated network setups, for instance with multiple
   6.350 +configuration, the default installation should work `out of the
   6.351 +box'.  More complicated network setups, for instance with multiple
   6.352  ethernet interfaces and / or existing bridging setups will require
   6.353  some special configuration.
   6.354  
   6.355 @@ -1073,7 +1039,7 @@ Xen virtual network when Xend starts and
   6.356  cleanup when Xend exits.
   6.357  
   6.358  In the default configuration, this script creates the bridge
   6.359 -``xen-br0'' and moves eth0 onto that bridge, modifying the routing
   6.360 +`xen-br0' and moves eth0 onto that bridge, modifying the routing
   6.361  accordingly.
   6.362  
   6.363  In configurations where the bridge already exists, this script could
   6.364 @@ -1254,8 +1220,8 @@ can be configured in either format of co
   6.365  
   6.366  \section{Administration Domains}
   6.367  
   6.368 -Administration privileges allow a domain to use the ``dom0
   6.369 -operations'' (so called because they are usually available only to
   6.370 +Administration privileges allow a domain to use the `dom0
   6.371 +operations' (so called because they are usually available only to
   6.372  domain 0).  A privileged domain can build other domains, set scheduling
   6.373  parameters, etc.
   6.374  
     7.1 --- a/docs/src/xend.tex	Thu Oct 28 13:03:45 2004 +0000
     7.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.3 @@ -1,443 +0,0 @@
     7.4 -% -*- mode: LaTeX -*-
     7.5 -\def\seca{\chapter}
     7.6 -\def\secb{\section}
     7.7 -\def\secc{\subsection}
     7.8 -\def\secd{\subsubsection}
     7.9 -\def\refa{chapter}
    7.10 -\def\refb{section}
    7.11 -\def\refc{section}
    7.12 -\def\refd{section}
    7.13 -
    7.14 -%\def\seca{\section}
    7.15 -%\def\secb{\subsection}
    7.16 -%\def\secc{\subsubsection}
    7.17 -%\def\refa{section}
    7.18 -%\def\refb{section}
    7.19 -%\def\refc{section}
    7.20 -
    7.21 -\documentclass[11pt,twoside,final,openright]{xenstyle}
    7.22 -\usepackage{a4,graphicx,setspace}
    7.23 -\setstretch{1.15}
    7.24 -
    7.25 -\begin{document}
    7.26 -
    7.27 -% TITLE PAGE
    7.28 -\pagestyle{empty}
    7.29 -\begin{center}
    7.30 -\vspace*{\fill}
    7.31 -\includegraphics{figs/xenlogo.eps}
    7.32 -\vfill
    7.33 -\vfill
    7.34 -\vfill
    7.35 -\begin{tabular}{l}
    7.36 -{\Huge \bf Xend} \\[4mm]
    7.37 -{\huge Xen v2.0 for x86} \\[80mm]
    7.38 -
    7.39 -{\Large Xen is Copyright (c) 2004, The Xen Team} \\[3mm]
    7.40 -{\Large University of Cambridge, UK} \\[20mm]
    7.41 -{\large Last updated 30 August 2004}
    7.42 -\end{tabular}
    7.43 -\vfill
    7.44 -\end{center}
    7.45 -\cleardoublepage
    7.46 -
    7.47 -% TABLE OF CONTENTS
    7.48 -\pagestyle{plain}
    7.49 -\pagenumbering{roman}
    7.50 -{ \parskip 0pt plus 1pt
    7.51 -  \tableofcontents }
    7.52 -\cleardoublepage
    7.53 -% PREPARE FOR MAIN TEXT
    7.54 -\pagenumbering{arabic}
    7.55 -\raggedbottom
    7.56 -\widowpenalty=10000
    7.57 -\clubpenalty=10000
    7.58 -\parindent=0pt
    7.59 -\renewcommand{\topfraction}{.8}
    7.60 -\renewcommand{\bottomfraction}{.8}
    7.61 -\renewcommand{\textfraction}{.2}
    7.62 -\renewcommand{\floatpagefraction}{.8}
    7.63 -
    7.64 -\setstretch{1.15}
    7.65 -
    7.66 -\seca{Introduction}
    7.67 -Xend is the control daemon used to manage a machine running the Xen hypervisor.
    7.68 -Xend is responsible for creating and destroying domains and managing their
    7.69 -resources, such as virtual block devices and virtual network interfaces.
    7.70 -
    7.71 -Xend exists because the Xen hypervisor itself only manages the memory image
    7.72 -of a domain and its scheduling. Xen provides the event channels that connect
    7.73 -a domain to its devices, but is intentionally not involved in setting them up.
    7.74 -
    7.75 -Xend runs as a daemon in the privileged domain 0 and uses a low-level api
    7.76 -to communicate with Xen via the domain 0 kernel. Xend exports its control
    7.77 -interface to its clients using HTTP. Most programming languages have
    7.78 -HTTP client libraries, so this interface can be used from most popular 
    7.79 -languages, for example Python, Perl, C, Java.
    7.80 -Xend itself is written in Python, as are most of the Xen tools.
    7.81 -
    7.82 -The xend interface is intended to be a complete interface for the creation
    7.83 -and management of domains. It supports domain creation, shutdown, reboot,
    7.84 -destruction, save, restore and migration.
    7.85 -
    7.86 -When xend creates a domain it creates the domain memory image and communicates
    7.87 -with the device driver domain(s) to configure the devices for the domain.
    7.88 -This sets up connections between the domain and backend device controllers
    7.89 -in the driver domain. When a domain shuts down its memory image cannot be fully released
    7.90 -unless its backend devices are released and disconnected. This is done by xend.
    7.91 -In order to protect against loss of this information when xend is restarted,
    7.92 -xend maintains a persistent database of domain configurations. This allows
    7.93 -xend to be stopped and restarted without loss of configuration information.
    7.94 -For example, in order to upgrade the xend software.
    7.95 -
    7.96 -\seca{Domain lifecycle}
    7.97 -\secb{Domain creation}
    7.98 -Xend is instructed to create a domain by posting a domain\_create message to it,
    7.99 -containing the domain configuration to be instantiated. The domain configuration
   7.100 -is in sxp format and is as far as possible {\em fully-bound}, that is, all
   7.101 -parameters are fully-specified. The domain configuration is saved in the filesystem
   7.102 -so that it can be reused later if necessary.
   7.103 -
   7.104 -The domain configuration specifies the domain name, memory size, kernel image
   7.105 -and parameters, and all the domain devices. Xend uses the Xen api to create
   7.106 -the domain memory image, and then {\em builds} the memory image for the domain
   7.107 -using the kernel image. At this point the domain exists, but it cannot be run because
   7.108 -it has no devices. Xend then communicates with the device driver domain to create
   7.109 -the configured devices. Once the devices are created it sets up event channels
   7.110 -for them between the driver domain and the new domain, and notifies the new domain
   7.111 -that its devices are connected. At this point the domain can be started.
   7.112 -
   7.113 -Xend is also responsible for managing domain consoles. When a domain is created,
   7.114 -xend sets up a console event channel to the domain, and creates a TCP listening port
   7.115 -for the domain console. When a connection is accepted to the port, xend
   7.116 -connects input and output for the port to the domain console channel.
   7.117 -
   7.118 -\secb{Domain destruction}
   7.119 -When a domain terminates, because it has been shutdown or it has crashed, the
   7.120 -domain resources must be released so that the domain memory image can be
   7.121 -finally removed from xen. Xend monitors the domains, and is also signaled by
   7.122 -xen (using a VIRQ) when a domain exits. Xend examines the domain states and
   7.123 -determines which domains have exited. It then communicates with the driver domain
   7.124 -to release the devices for exited domains. Xend also closes any open console
   7.125 -connections and removes the TCP listeners for exited domains.
   7.126 -Once all devices have been released it instructs xen to destroy the memory image.
   7.127 -
   7.128 -\secb{Domain restart}
   7.129 -Domain restart is the xen equivalent of a machine reboot. When a domain
   7.130 -exits because it has been shutdown in reboot mode, its exit code is reboot.
   7.131 -When examining domains to find those that have exited and destroy them,
   7.132 -xend detects those that have exited for reboot and does not completely destroy
   7.133 -them. It disconnects all their devices, and detaches the console listener
   7.134 -from its channel to the domain, but does not close it. Instead it schedules
   7.135 -a call to rebuild the domain from its configuration. This proceeds almost
   7.136 -identically to creating the domain, except that the console listener is
   7.137 -reused and connected to the new domain. This allows existing console
   7.138 -connections to remain connected across a domain restart. The restarted
   7.139 -domain keeps the same name and domain id.
   7.140 -
   7.141 -The determination of when to restart a domain is in fact slightly more
   7.142 -complex than described above. A domain is configured with a 
   7.143 -{\em restart mode}. If the restart mode is {\em onreboot}, the default,
   7.144 -restart happens when the domain is shutdown normally and
   7.145 -exits with code reboot. If the restart mode is {\em never} the domain is
   7.146 -not restarted. If the restart mode is {\em always} the domain is always
   7.147 -restarted, regardless of how it exited.
   7.148 -
   7.149 -In order to prevent continual domain crash causing restart loops, xend
   7.150 -has a {\em minimum restart time}. Xend remembers when a domain was last
   7.151 -restarted and will fail a restart that happens inside the minimum
   7.152 -restart time.
   7.153 -
   7.154 -\seca{Devices}
   7.155 -\secb{Virtual network interfaces}
   7.156 -Each virtual network interface (vif) has 2 parts: the font-end device in its domain,
   7.157 -and the back-end device in the driver domain. Usually the driver domain is domain 0,
   7.158 -and there is a linux network device corresponding to the vif. The linux device for
   7.159 -interface N on domain D is called vifD.N. When a packet is sent on the vif in the 
   7.160 -domain the packet is received from the linux device. The linux devices are connected
   7.161 -to network interfaces using ethernet bridging.
   7.162 -
   7.163 -The default setup is a bridge xen-br0, with eth0 connected to it, and the routes
   7.164 -for eth0 directed at xen-br0. This is controlled by the xend network setup script,
   7.165 -default {\tt /etc/xen/network}, which is run when xend starts.
   7.166 -
   7.167 -When the vifs for a domain are created, a vif control script, default {\tt /etc/xen/vif-bridge},
   7.168 -is run to connect the vif to its bridge. The default script connects the vif
   7.169 -to xen-br0 and optionally sets up iptables rules to prevent IP address spoofing.
   7.170 -The bridge a vif is connected to can be defined in its configuration, and this is useful
   7.171 -for setting up virtual networks using several bridges.
   7.172 -
   7.173 -\secb{Virtual block devices}
   7.174 -Virtual block devices in a domain are interfaces onto back-end device drivers
   7.175 -that export physical devices to domains. In the default configuration the back-end
   7.176 -driver is in domain 0 and can export any linux block device to a domain. This includes
   7.177 -physical disk partitions, LVM volumes and loopback mounts of files. In fact anything
   7.178 -that linux can represent as a block device can be exported to a domain as virtual
   7.179 -block device.
   7.180 -
   7.181 -\seca{Xend invocation}
   7.182 -Xend is started (by root) using the command
   7.183 -\begin{verbatim}
   7.184 -xend start
   7.185 -\end{verbatim}
   7.186 -Xend can be stopped using
   7.187 -\begin{verbatim}
   7.188 -xend stop
   7.189 -\end{verbatim}
   7.190 -Xend must be started before any domains (apart from domain 0) can be created.
   7.191 -If you try to use the {\tt xm} tool when xend is not running you will get a
   7.192 -'connection refused' message.
   7.193 -
   7.194 -\secb{Xend configuration}
   7.195 -Xend reads its own configuration from {\tt /etc/xen/xend-config.sxp}, which is
   7.196 -a sequence of s-expressions. The configuration parameters are:
   7.197 -\begin{itemize}
   7.198 -
   7.199 -\item xend-port: Port xend should use for the HTTP interface (default 8000).
   7.200 -
   7.201 -\item xend-address: Address xend should listen on.
   7.202 -  Specifying 'localhost' prevents remote connections.
   7.203 -  Specifying the empty string '' allows all connections, and is the default.
   7.204 -
   7.205 -\item network-script: The script used to start/stop networking for xend (default network).
   7.206 -
   7.207 -\item vif-bridge: The default bridge that virtual interfaces should be connected to
   7.208 -  (default xen-br0).
   7.209 -
   7.210 -\item vif-script: The default script used to control virtual interfaces
   7.211 -  (default vif-bridge).
   7.212 -
   7.213 -\item vif-antispoof: Whether iptables should be set up to prevent IP spoofing for
   7.214 -  virtual interfaces (default yes).
   7.215 -\end{itemize}
   7.216 -
   7.217 -Configuration scripts ({\it e.g.} for network-script) are looked for in {\tt /etc/xen}
   7.218 -unless their name begins with '/'.
   7.219 -
   7.220 -Xend sends its log output to {\tt /var/log/xend.log}. This is a rotating logfile,
   7.221 -and logs are moved onto {\tt xend.log.1} {\it etc.} as they get large. Old logs may
   7.222 -be deleted.
   7.223 -
   7.224 -\secb{Xend database}
   7.225 -Xend needs to make some data persistent, and it uses files under {\tt /var/xen/xend-db}
   7.226 -for this. The persistent data is stored in files in SXP format. Domain information
   7.227 -is saved when domains are created. When xend starts it reads the file {\tt /var/xen/lastboot}
   7.228 -(if it exists) to determine the last time the system was rebooted. It compares this time
   7.229 -with the last reboot time in {\tt wtmp} to determine if the system has been rebooted
   7.230 -since xend last ran. If the system has been rebooted xend removes all its saved data
   7.231 -that is not persistent across reboots (for example domain data).
   7.232 -
   7.233 -\seca{Xend HTTP Interface}
   7.234 - The xend interface uses HTTP 1.1 \cite{http} as its transport.
   7.235 -Simple PUT and GET calls can encode parameters using the standard url-encoding 
   7.236 -for parameters: MIME type {\tt application/x-www-form-urlencoded}.
   7.237 -When file upload is required, the {\tt multipart/form-data} encoding is used.
   7.238 -See the HTML 4.1 specification for details \cite{html}.
   7.239 -
   7.240 -Xend functions as a webserver and supports two interfaces: one
   7.241 -for web-browsers and one for programs.
   7.242 -The web-browser interface returns replies in HTML and includes forms
   7.243 -for interactive operations such as stopping domains and creating domains
   7.244 -from an uploaded configuration. The programmatic interface usually returns replies
   7.245 -in s-expression format. Both interfaces are accessed
   7.246 -in exactly the same way over HTTP - the only difference is the data returned.
   7.247 -
   7.248 -The webserver distinguishes browsers from programs using the {\tt User-Agent}
   7.249 -and {\tt Accept} headers in the HTTP request. If there is no {\tt User-Agent} or no
   7.250 -{\tt Acccept} header, or {\tt Accept} includes the type {\tt application/sxp}, the
   7.251 -webserver assumes the client is a program and returns SXP. Otherwise
   7.252 -it assumes the client is a webserver and returns HTML.
   7.253 -In some cases the return value is essentially a string, so {\tt Content-Type}
   7.254 -{\tt text/plain} is returned.
   7.255 -
   7.256 -The HTTP api supported is listed below. All paths in it are relative to the
   7.257 -server root, for example {\tt http://localhost:8000/xend}.
   7.258 -As defined in the HTTP specification, we use GET for side-effect free
   7.259 -operations that may safely be repeated, and POST for operations with
   7.260 -side-effects. For each request we list the HTTP method (GET or POST),
   7.261 -the url relative to the server root, the operation name and arguments (if any).
   7.262 -The operation name is passed as request parameter 'op', and the arguments
   7.263 -are passed by name. Operation name and parameters can be encoded using either
   7.264 -encoding described above. We also list the corresponding api function from the
   7.265 -Python client interface in {\tt xen.xend.XendClient}.
   7.266 -
   7.267 -\begin{itemize}
   7.268 -\item {\tt GET /},\\
   7.269 -  {\tt xend()}:\\
   7.270 -  Get list of urls under xend root.
   7.271 -
   7.272 -\item {\tt GET /node},\\
   7.273 -  {\tt xend\_node()}:\\
   7.274 -  Get node information.
   7.275 -
   7.276 -\item {\tt POST /node shutdown()},\\
   7.277 -  {\tt xend\_node\_shutdown()}:\\
   7.278 -  Shutdown the node
   7.279 -
   7.280 -\item {\tt POST /node reboot()},\\
   7.281 -  {\tt xend\_node\_reboot()}:\\
   7.282 -  Reboot the node
   7.283 -
   7.284 -\item {\tt POST /node notify()}:\\
   7.285 -  Set node notification url
   7.286 -  
   7.287 -\item {\tt GET /node/dmesg},\\
   7.288 -  {\tt xend\_node\_dmesg()}:\\
   7.289 -  Get xen boot message.
   7.290 -
   7.291 -\item {\tt GET /node/log},\\
   7.292 -  {\tt xend\_node\_log()}:\\
   7.293 -  Get xend log.
   7.294 -
   7.295 -\item {\tt GET /domain}\\
   7.296 -  {\tt xend\_domains()}:\\
   7.297 -  Get list of domains.
   7.298 -
   7.299 -\item {\tt POST /domain create(config)},\\
   7.300 -  {\tt xend\_domain\_create(config)}:\\
   7.301 -  Create a domain.
   7.302 -
   7.303 -\item {\tt POST /domain restore(file)},\\
   7.304 -  {\tt xend\_domain\_restore(filename)}:\\
   7.305 -  Restore a saved domain.
   7.306 -
   7.307 -\item {\tt GET /domain/<dom>},\\
   7.308 -  {\tt xend\_domain(dom)}:\\
   7.309 -  Get domain information.
   7.310 -
   7.311 -\item {\tt POST /domain/[dom] configure(config)},\\
   7.312 -  {\tt xend\_domain\_configure(dom, conf)}:\\
   7.313 -  Configure an existing domain (for internal use by restore and migrate).
   7.314 -
   7.315 -\item {\tt POST /domain/[dom] unpause()},\\
   7.316 -  {\tt xend\_domain\_unpause(dom)}:\\
   7.317 -  Start domain running
   7.318 -
   7.319 -\item {\tt POST /domain/[dom] pause()},\\
   7.320 -  {\tt xend\_domain\_pause(dom)}:\\
   7.321 -  Stop domain running.
   7.322 -
   7.323 -\item {\tt POST /domain/[dom] shutdown(reason)},\\
   7.324 -  {\tt xend\_domain\_shutdown(dom, reason)}:\\
   7.325 -  Shutdown domain, reason can be reboot, poweroff, halt.
   7.326 -
   7.327 -\item {\tt POST /domain/[dom] destroy(reason)},\\
   7.328 -  {\tt xend\_domain\_destroy(dom, reason)}:\\
   7.329 -  Destroy domain, reason can be reboot, halt.
   7.330 -
   7.331 -\item {\tt POST /domain/[dom] save(file)},\\
   7.332 -  {\tt xend\_domain\_save(dom, filename)}:\\
   7.333 -  Save a domain to a file.
   7.334 -
   7.335 -\item {\tt POST /domain/[dom] migrate(dst)},\\
   7.336 -  {\tt xend\_domain\_migrate(dom, dst)}:\\
   7.337 -  Migrate a domain.
   7.338 -
   7.339 -\item {\tt POST /domain/[dom] pincpu(cpu)},\\
   7.340 -  {\tt xend\_domain\_pincpu(self, id, cpu)}\\:
   7.341 -  Pin a domain to a cpu.
   7.342 -
   7.343 -\item {\tt POST /domain/[dom] bvt\_set(mcuadv, warp, warpl, warpu)},\\
   7.344 -  {\tt xend\_domain\_cpu\_bvt\_set(dom, mcuadv, warp, warpl, warpu)}:\\
   7.345 -  Set BVT scheduler parameters.
   7.346 -
   7.347 -\item {\tt POST /domain/[dom] atropos\_set(period, slice, latency, xtratime)},\\
   7.348 -  {\tt xend\_domain\_cpu\_atropos\_set(dom, period, slice, latency, xtratime)}:\\
   7.349 -  Set atropos scheduler parameters.
   7.350 -
   7.351 -\item {\tt POST /domain/[dom] maxmem\_set(memory)},\\
   7.352 -  {\tt xend\_domain\_maxmem\_set(dom, memory)}:\\
   7.353 -  Set domain maximum memory limit.
   7.354 -
   7.355 -\item {\tt POST /domain/[dom] device\_create(config)}\\
   7.356 -  {\tt xend\_domain\_device\_create(dom, config)}:\\
   7.357 -  Add a device to a domain.
   7.358 -
   7.359 -\item {\tt POST /domain/[dom] device\_destroy(type, index)},\\
   7.360 -  {\tt xend\_domain\_device\_destroy(dom, type, index)}:\\
   7.361 -  Delete a device from a domain
   7.362 -
   7.363 -\item {\tt GET /domain/[dom] vifs()},\\
   7.364 -  {\tt xend\_domain\_vifs(dom)}:\\
   7.365 -  Get virtual network interfaces.
   7.366 -
   7.367 -\item {\tt GET /domain/[dom] vif(vif)},\\
   7.368 -  {\tt xend\_domain\_vif(dom, vif)}:\\
   7.369 -  Get virtual network interface.
   7.370 -
   7.371 -\item {\tt GET /domain/[dom] vbds()},\\
   7.372 -  {\tt xend\_domain\_vbds(dom)}:\\
   7.373 -  Get virtual block devices.
   7.374 -
   7.375 -\item {\tt GET /domain/[dom] vbd(vbd)},\\
   7.376 -  {\tt xend\_domain\_vbd(dom, vbd)}:\\
   7.377 -  Get virtual block device.
   7.378 -
   7.379 -\item {\tt GET /console},\\
   7.380 -  {\tt xend\_consoles()}:\\
   7.381 -  Get list of consoles.
   7.382 -
   7.383 -\item {\tt GET /console/[id]}\\
   7.384 -  {\tt xend\_console(id)}:\\
   7.385 -  Get information about a console.
   7.386 -
   7.387 -\item {\tt GET /console/[id] disconnect()}\\
   7.388 -  {\tt xend\_console\_disconnect(self, id)}:\\
   7.389 -  Disconnect any console TCP connection.
   7.390 -
   7.391 -\item {\tt GET /vnet}\\
   7.392 -  {\tt xend\_vnets()}:\\
   7.393 -  Get list of vnets (virtual networks).
   7.394 -
   7.395 -\item {\tt GET /vnet/[id]}\\
   7.396 -  {\tt xend\_vnet(id)}:\\
   7.397 -  Get information about a virtual network.
   7.398 -
   7.399 -\item {\tt POST /vnet create(config)}\\
   7.400 -  {\tt xend\_vnet\_create(conf)}:\\
   7.401 -  Create a vnet.
   7.402 -
   7.403 -\item {\tt POST /vnet/[id] delete()}\\
   7.404 -  {\tt xend\_vnet\_delete(id)}:\\
   7.405 -  Delete a vnet.
   7.406 -
   7.407 -\item {\tt POST /event inject(event)}\\
   7.408 -  {\tt xend\_event\_inject(sxpr)}:\\
   7.409 -  Inject an event.
   7.410 -
   7.411 -\end{itemize}
   7.412 -
   7.413 -\secb{Xend debugging interface}
   7.414 -Xend also listens on port 8001. Connecting to this port (for example via telnet)
   7.415 -allows access to some debugging functions:
   7.416 -\begin{itemize}
   7.417 -\item help: list functions
   7.418 -\item traceon: turn xend tracing on
   7.419 -\item traceoff: turn xend tracing off
   7.420 -\item quit: disconnect.
   7.421 -\item info: list console listeners, block and network device controllers.
   7.422 -\end{itemize}
   7.423 -
   7.424 -When tracing is on xend logs all functions calls and exceptions to
   7.425 -{\tt /var/log/xend.trace}.
   7.426 -
   7.427 -\begin{thebibliography}{99}
   7.428 -
   7.429 -\bibitem{html}
   7.430 -HTML 4.01 Specification,\\
   7.431 -http://www.w3.org/TR/html4/,\\
   7.432 -W3C Recommendation, 24 December 1999.
   7.433 -
   7.434 -\bibitem{http}
   7.435 -Hypertext Transfer Protocol -- HTTP/1.1,\\
   7.436 -http://www.ietf.org/rfc/rfc2616.txt,\\
   7.437 -RFC 2616, IETF 1999.
   7.438 -
   7.439 -\bibitem{ssh}
   7.440 -http://www.openssh.org.
   7.441 -
   7.442 -\bibitem{stunnel}
   7.443 -http://www.stunnel.org.
   7.444 -
   7.445 -\end{thebibliography}
   7.446 -\end{document}