ia64/xen-unstable

changeset 978:6ec887aa9d16

bitkeeper revision 1.631 (3fbf9627n3_R5gJx6eFdJQwWUIKLCQ)

createlinuxdom.py, Xeno-HOWTO, TODO, README, README.CD:
Updated the docs to get rid of xenctl references.
author kaf24@scramble.cl.cam.ac.uk
date Sat Nov 22 17:00:23 2003 +0000 (2003-11-22)
parents 32f065cf544b
children e392f2509f23
files README README.CD TODO docs/Xeno-HOWTO tools/examples/createlinuxdom.py
line diff
     1.1 --- a/README	Sat Nov 22 11:45:34 2003 +0000
     1.2 +++ b/README	Sat Nov 22 17:00:23 2003 +0000
     1.3 @@ -154,14 +154,6 @@ There's also a pre-built source tree on 
     1.4  Using the domain control tools
     1.5  ==============================
     1.6  
     1.7 -The README.CD file contains some examples of how to use 'xenctl' and
     1.8 -the other domain control tools. Invoking the tool without any
     1.9 -arguments prints some usage inforamtion. There's also some
    1.10 -documentation in the the repository under tools/control/doc
    1.11 -
    1.12 +See example Python scripts in tools/examples/
    1.13  
    1.14 -
    1.15 -Ian Pratt
    1.16 -9 Sep 2003
    1.17 -
    1.18 -
    1.19 +Further documentation is in docs/ (e.g., docs/Xeno-HOWTO).
     2.1 --- a/README.CD	Sat Nov 22 11:45:34 2003 +0000
     2.2 +++ b/README.CD	Sat Nov 22 17:00:23 2003 +0000
     2.3 @@ -123,14 +123,9 @@ benchmarks we used in the SOSP paper.
     2.4  Starting other domains
     2.5  ======================
     2.6  
     2.7 -There's a web interface for starting and managing other domains (VMs),
     2.8 -but since we generally use the command line tools they're probably
     2.9 -rather better debugged at present. The key command is 'xenctl' which
    2.10 -lives in /usr/local/bin and uses /etc/xenctl.xml for its default
    2.11 -configuration. Run 'xenctl' without any arguments to get a help
    2.12 -message. Note that xenctl is a java front end to various underlying 
    2.13 -internal tools written in C (xi_*). Running off CD, it seems to take 
    2.14 -an age to start...
    2.15 +Xen's privileged control interfaces can be accessed using a handy C
    2.16 +library (libxc.so) or an even easier-to-use Python wrapper module
    2.17 +(Xc). Example script templates are provided in tools/examples/.
    2.18  
    2.19  Abyway, the first thing to do is to set up a window in which you will
    2.20  receive console output from other domains. Console output will arrive
    2.21 @@ -150,42 +145,15 @@ Next, run a the xen UDP console displaye
    2.22    xen_read_console &
    2.23  
    2.24  
    2.25 -As mentioned above, xenctl uses /etc/xenctl.xml as its default
    2.26 -configuration. The directory contains two different configs depending
    2.27 -on whether you want to use NAT, or multiple sequential external IPs
    2.28 -(it's possible to override any of the parameters on the command line
    2.29 -if you want to set specific IPs, etc).
    2.30 -
    2.31 -The default configuration file supports NAT. To change to use multiple IPs:
    2.32 -
    2.33 - cp /etc/xenctl.xml-publicip /etc/xenctl.xml
    2.34 +As mentioned above, a template Python script is provided:
    2.35 +tools/examples/craetelinuxdom.py. This can be modified to set up a
    2.36 +virtual Ethernet interface, access to local discs, and various other
    2.37 +parameters.
    2.38  
    2.39 -A sequence of commands must be given to xenctl to start a new 
    2.40 -domain. First a new domain must be created, which requires specifying
    2.41 -the initial memory allocation, the kernel image to use, and the kernel
    2.42 -command line. As well as the root file system details, you'll need to
    2.43 -set the IP address on the command line: since Xen currently doesn't
    2.44 -support a virtual console for domains >1, you won't be able to log to
    2.45 -your new domain unless you've got networking configured and an sshd
    2.46 -running! (using dhcp for new domains should work too).
    2.47 -
    2.48 -After creating the domain, xenctl must be used to grant the domain
    2.49 -access to other resources such as physical or virtual disk partions.
    2.50 -Then, the domain must be started.
    2.51 +When you execute your modified screipt, you should see the domain
    2.52 +booting on your xen_read_console window.
    2.53  
    2.54 -These commands can be entered manually, but for convenience, xenctl
    2.55 -will also read them from a script and infer which domain number you're
    2.56 -referring to (-nX). To use the sample script:
    2.57 -
    2.58 - xenctl script -f/etc/xen-mynewdom     [NB: no space after the -f]
    2.59 -
    2.60 -You should see the domain booting on your xen_read_console window.
    2.61 -
    2.62 -The xml defaults start another domain running off the CD, using a
    2.63 -separate RAM-based file system for mutable data in root (just like
    2.64 -domain 0). 
    2.65 -
    2.66 -The new domain is started with a '4' on the kernel command line to
    2.67 +The new domain may be started with a '4' on the kernel command line to
    2.68  tell 'init' to go to runlevel 4 rather than the default of 3. This is
    2.69  done simply to suppress a bunch of harmless error messages that would
    2.70  otherwise occur when the new (unprivileged) domain tried to access
    2.71 @@ -204,31 +172,22 @@ virtual machine remotely, use:
    2.72  If you configured the new domain with its own IP address, you should
    2.73  be able to ssh into it directly.
    2.74  
    2.75 -
    2.76 -"xenctl domain list" provides status information about running domains,
    2.77 -though is currently only allowed to be run by domain 0. It accesses
    2.78 -/proc/xeno/domains to read this information from Xen. You can also use
    2.79 -xenctl to 'stop' (pause) a domain, or 'kill' a domain. You can either
    2.80 -kill it nicely by sending a shutdown event and waiting for it to
    2.81 -terminate, or blow the sucker away with extreme prejudice. 
    2.82 +Script 'tools/examples/listdoms.py' demonstrates how to generate a
    2.83 +list of all extant domains. Prettier printing is an exercise for the
    2.84 +reader!
    2.85  
    2.86 -If you want to configure a new domain differently, type 'xenctl' to
    2.87 -get a list of arguments, e.g. at the 'xenctl domain new' command line
    2.88 -use the "-4" option to set a diffrent IPv4 address. 
    2.89 -
    2.90 -xenctl can be used to set the new kernel's command line, and hence
    2.91 -determine what it uses as a root file system, etc. Although the default
    2.92 -is to boot in the same manner that domain0 did (using the RAM-based
    2.93 -file system for root and the CD for /usr) it's possible to configure any
    2.94 -of the following possibilities, for example:
    2.95 +createlinuxdom.py can be used to set the new kernel's command line,
    2.96 +and hence determine what it uses as a root file system, etc. Although
    2.97 +the default is to boot in the same manner that domain0 did (using the
    2.98 +RAM-based file system for root and the CD for /usr) it's possible to
    2.99 +configure any of the following possibilities, for example:
   2.100  
   2.101   * initrd=/boot/initrd init=/linuxrc
   2.102       boot using an initial ram disk, executing /linuxrc (as per this CD)     
   2.103  
   2.104   * root=/dev/hda3 ro
   2.105       boot using a standard hard disk partition as root
   2.106 -     !!! remember to do "xenctl physical grant -phda3 -w -n<dom>" first
   2.107 -     (grant domain <dom> read/write access to partition 3)
   2.108 +     !!! remember to grant access in createlinuxdom.py.
   2.109  
   2.110   * root=/dev/xvda1 ro
   2.111       boot using a pre-configured 'virtual block device' that will be
   2.112 @@ -240,28 +199,16 @@ of the following possibilities, for exam
   2.113       remote NFS server, or from an NFS server running in another
   2.114       domain. The latter is rather a useful option.
   2.115  
   2.116 -
   2.117  A typical setup might be to allocate a standard disk partition for
   2.118  each domain and populate it with files. To save space, having a shared
   2.119  read-only usr partition might make sense.
   2.120  
   2.121 -Alternatively, you can use 'virtual disks', which are stored as files
   2.122 -within a custom file system. "xenctl partitions add" can be used to
   2.123 -'format' a partition with the file system, and then virtual disks can
   2.124 -be created with "xenctl vd create". Virtual disks can then be attached
   2.125 -to a running domain as a 'virtual block device' using "xenctl vbd
   2.126 -create". The virtual disk can optionally be partitioned (e.g. "fdisk
   2.127 -/dev/xvda") or have a file system created on it directly (e.g. "mkfs
   2.128 --t ext3 /dev/xvda").  The virtual disk can then be accessed by a
   2.129 -virtual block device associated with another domain, and even used as
   2.130 -a boot device.
   2.131 -
   2.132 -Both virtual disks and real partitions should only be shared between
   2.133 -domains in a read-only fashion otherwise the linux kernels will
   2.134 -obviously get very confused as the file system structure may change
   2.135 -underneath them (having the same partition mounted rw twice is a sure
   2.136 -fire way to cause irreparable damage)!  If you want read-write
   2.137 -sharing, export the directory to other domains via NFS from domain0.
   2.138 +Block devices should only be shared between domains in a read-only
   2.139 +fashion otherwise the linux kernels will obviously get very confused
   2.140 +as the file system structure may change underneath them (having the
   2.141 +same partition mounted rw twice is a sure fire way to cause
   2.142 +irreparable damage)!  If you want read-write sharing, export the
   2.143 +directory to other domains via NFS from domain0.
   2.144  
   2.145  
   2.146  Troubleshooting Problems
   2.147 @@ -478,8 +425,7 @@ domain0 and domains>0, one trick is to u
   2.148  levels. For example, on the Xen Demo CD we use run level 3 for domain
   2.149  0, and run level 4 for domains>0. This enables different startup
   2.150  scripts to be run in depending on the run level number passed on the
   2.151 -kernel command line. The xenctl.xml config file on the CD passes '4'
   2.152 -on the kernel command line to domains that it starts.
   2.153 +kernel command line.
   2.154  
   2.155  Xenolinux kernels can be built to use runtime loadable modules just
   2.156  like normal linux kernels. Modules should be installed under
     3.1 --- a/TODO	Sat Nov 22 11:45:34 2003 +0000
     3.2 +++ b/TODO	Sat Nov 22 17:00:23 2003 +0000
     3.3 @@ -3,23 +3,6 @@
     3.4  Known limitations and work in progress
     3.5  ======================================
     3.6  
     3.7 -The "xenctl" tool used for controling domains is still rather clunky
     3.8 -and not very user friendly. In particular, it should have an option to
     3.9 -create and start a domain with all the necessary parameters set from a
    3.10 -named xml file. Update: the 'xenctl script' functionality combined
    3.11 -with the '-i' option to 'domain new' sort of does this.
    3.12 -
    3.13 -The java xenctl tool is really just a frontend for a bunch of C tools
    3.14 -named xi_* that do the actual work of talking to Xen and setting stuff
    3.15 -up. Some local users prefer to drive the xi_ tools directly, typically
    3.16 -from simple shell scripts. These tools are even less user friendly
    3.17 -than xenctl but its arguably clearer what's going on.
    3.18 -
    3.19 -There's also a nice web based interface for controlling domains that
    3.20 -uses apache/tomcat. Unfortunately, this has fallen out of sync with
    3.21 -respect to the underlying tools, so is currently not built by default
    3.22 -and needs fixing. It shouldn't be hard to bring it up to date.
    3.23 -
    3.24  The current Xen Virtual Firewall Router (VFR) implementation in the
    3.25  snapshot tree is very rudimentary, and in particular, lacks the RSIP
    3.26  IP port-space sharing across domains that provides a better
    3.27 @@ -28,38 +11,13 @@ development which also supports much bet
    3.28  support. For now, if you want NAT, see the xen_nat_enable scripts and
    3.29  get domain0 to do it for you.
    3.30  
    3.31 -The current network scheduler is just simple round-robin between
    3.32 -domains, without any rate limiting or rate guarantees. Dropping in a
    3.33 -new scheduler is straightforward, and is planned as part of the
    3.34 -VFRv2 work package.
    3.35 -
    3.36 -Another area that needs further work is the interface between Xen and
    3.37 -domain0 user space where the various XenoServer control daemons run.
    3.38 -The current interface is somewhat ad-hoc, making use of various
    3.39 -/proc/xeno entries that take a random assortment of arguments. We
    3.40 -intend to reimplement this to provide a consistent means of feeding
    3.41 -back accounting and logging information to the control daemon, and
    3.42 -enabling control instructions to be sent the other way (e.g. domain 3:
    3.43 -reduce your memory footprint to 10000 pages. You have 1s to comply.)
    3.44 -We should also use the same interface to provide domains with a
    3.45 -read/write virtual console interface. The current implemenation is
    3.46 -output only, though domain0 can use the VGA console read/write.
    3.47 -
    3.48 -There's also a number of memory management hacks that didn't make this
    3.49 -release: We have plans for a "universal buffer cache" that enables
    3.50 -otherwise unused system memory to be used by domains in a read-only
    3.51 -fashion. We also have plans for inter-domain shared-memory to enable
    3.52 -high-performance bulk transport for cases where the usual internal
    3.53 -networking performance isn't good enough (e.g. communication with a
    3.54 -internal file server on another domain).
    3.55 -
    3.56 -We also have plans to implement domain suspend/resume-to-file. This is
    3.57 -basically an extension to the current domain building process to
    3.58 -enable domain0 to read out all of the domain's state and store it in a
    3.59 -file. There are complications here due to Xen's para-virtualised
    3.60 -design, whereby since the physical machine memory pages available to
    3.61 -the guest OS are likely to be different when the OS is resumed, we
    3.62 -need to re-write the page tables appropriately. 
    3.63 +There are also a number of memory management enhancements that didn't
    3.64 +make this release: We have plans for a "universal buffer cache" that
    3.65 +enables otherwise unused system memory to be used by domains in a
    3.66 +read-only fashion. We also have plans for inter-domain shared-memory
    3.67 +to enable high-performance bulk transport for cases where the usual
    3.68 +internal networking performance isn't good enough (e.g. communication
    3.69 +with a internal file server on another domain).
    3.70  
    3.71  We have the equivalent of balloon driver functionality to control
    3.72  domain's memory usage, enabling a domain to give back unused pages to
     4.1 --- a/docs/Xeno-HOWTO	Sat Nov 22 11:45:34 2003 +0000
     4.2 +++ b/docs/Xeno-HOWTO	Sat Nov 22 17:00:23 2003 +0000
     4.3 @@ -210,7 +210,7 @@ UDP packets to  the local virtual networ
     4.4  by xen_read_console running in Domain  0 and output are printed out to
     4.5  the standard output.
     4.6  
     4.7 -Now edit the tools/examples/xi_createlinuxdom.py script to your taste. This
     4.8 +Now edit the tools/examples/createlinuxdom.py script to your taste. This
     4.9  should then be executed as root to create a new domain.
    4.10  
    4.11  You should be able to see XenoLinux boot message on standard output
    4.12 @@ -221,14 +221,14 @@ List and Stop Domains
    4.13  ==============================
    4.14  
    4.15  You can see a list of existing domains with:
    4.16 -# tools/examples/xi_listdoms.py
    4.17 +# tools/examples/listdoms.py
    4.18  
    4.19  In order to stop a domain, you use:
    4.20 -# tools/examples/xi_stopdom.py <domain_id>
    4.21 +# tools/examples/stopdom.py <domain_id>
    4.22  
    4.23  To destroy a domain use ('force' causes an immediate destruction
    4.24  without waiting for the guest OS to shut down cleanly):
    4.25 -# tools/examples/xi_destroydom.py <domain_id> [force]
    4.26 +# tools/examples/destroydom.py <domain_id> [force]
    4.27  
    4.28  
    4.29  Other Control Tasks using Python
     5.1 --- a/tools/examples/createlinuxdom.py	Sat Nov 22 11:45:34 2003 +0000
     5.2 +++ b/tools/examples/createlinuxdom.py	Sat Nov 22 17:00:23 2003 +0000
     5.3 @@ -12,20 +12,26 @@ nfsserv = nfspath = root_partn = usr_par
     5.4  # STEP 1. Specify kernel image file.
     5.5  image = "FULL_PATH_TO_IMAGE"
     5.6  
     5.7 -# STEP 2. Specify IP address, netmask and gateway for the new domain.
     5.8 +# STEP 2. How many megabytes of memory for the new domain?
     5.9 +memory_megabytes = 64
    5.10 +
    5.11 +# STEP 3. A handy name for your new domain.
    5.12 +domain_name = "My new domain"
    5.13 +
    5.14 +# STEP 4. Specify IP address, netmask and gateway for the new domain.
    5.15  ipaddr  = "ADDRESS"
    5.16  netmask = XenoUtil.get_current_ipmask()
    5.17  gateway = XenoUtil.get_current_ipgw()
    5.18  
    5.19 -# STEP 3a. Specify NFS server and path to rootfs (only needed for network boot)
    5.20 +# STEP 5a. Specify NFS server and path to rootfs (only needed for network boot)
    5.21  nfsserv = "ADDRESS"
    5.22  nfspath = "FULL_PATH_TO_ROOT_DIR"
    5.23  
    5.24 -# STEP 3b. Specify root (and possibly /usr) on local disc (if not NFS booting)
    5.25 +# STEP 5b. Specify root (and possibly /usr) on local disc (if not NFS booting)
    5.26  #root_partn = "/dev/sda2"
    5.27  #usr_partn  = "/dev/sda6"
    5.28  
    5.29 -# STEP 4. Check that the following cmdline setup is to your taste.
    5.30 +# STEP 6. Check that the following cmdline setup is to your taste.
    5.31  cmdline = "ip="+ipaddr+":"+nfsserv+":"+gateway+":"+netmask+"::eth0:off"
    5.32  if root_partn:
    5.33      # Boot from local disc. May specify a separate /usr.
    5.34 @@ -55,7 +61,7 @@ if not os.path.isfile( image ):
    5.35  
    5.36  xc = Xc.new()
    5.37  
    5.38 -id = xc.domain_create()
    5.39 +id = xc.domain_create( mem_kb=memory_megabytes*1024, name=domain_name )
    5.40  if id <= 0:
    5.41      print "Error creating domain"
    5.42      sys.exit()