# HG changeset patch
# User rac61@labyrinth.cl.cam.ac.uk
# Date 1057841626 0
# Node ID 4515f4d0701f26126afff2d53c54f330624ac154
# Parent  75e23848b2381760f6c153e2aab5c8ccdc32fb06
bitkeeper revision 1.335 (3f0d61daWuAj1MdY8xaA6enqSDZSEg)

Documentation update.


diff -r 75e23848b238 -r 4515f4d0701f .rootkeys
--- a/.rootkeys	Thu Jul 10 12:32:49 2003 +0000
+++ b/.rootkeys	Thu Jul 10 12:53:46 2003 +0000
@@ -7,10 +7,12 @@ 3e6377b24eQqYMsDi9XrFkIgTzZ47A tools/bal
 3e6377d6eiFjF1hHIS6JEIOFk62xSA tools/balloon/README
 3e6377dbGcgnisKw16DPCaND7oGO3Q tools/balloon/balloon.c
 3eb781edFwm_pW9FwnQACIe68viLOw tools/control/Makefile
-3eca6a96a31IwaKtkEa4jmzwTWlm8Q tools/control/README-web
 3eb781fceEYkUi1XHKf2V0KX7si2JA tools/control/build-cmdline.xml
 3ec41f7cWCxQ8pdH8ZWqhhv-38qQ1w tools/control/build-web.xml
 3ec41f7ca6IBXDSe0HVcMPp3PPloOQ tools/control/build.properties
+3f0d61da3O5gkcntbIOdUmN2-RcZbQ tools/control/doc/INSTALL-cmdline
+3eca6a96a31IwaKtkEa4jmzwTWlm8Q tools/control/doc/INSTALL-web
+3f0d61daCTHGCpQK0Brz3PAp80d_2Q tools/control/doc/USAGE-cmdline
 3eb781fcabCKRogwxJA3-jJKstw9Vg tools/control/domctl.xml
 3f042c35FzVap5QW0UBPnZ2ZM0l3QA tools/control/src/org/xenoserver/cmdline/CommandParser.java
 3eb781fdNQvEJW3tNvovjqoN7GlePA tools/control/src/org/xenoserver/cmdline/Main.java
diff -r 75e23848b238 -r 4515f4d0701f tools/control/README-web
--- a/tools/control/README-web	Thu Jul 10 12:32:49 2003 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,44 +0,0 @@
-
-some notes on configuring xenctl...
-
-to build:
-
- export PATH=/usr/groups/xeno/build_tools/bin:${PATH}
- # this next step has already been done.
- # cp $CATALINA_HOME/server/lib/catalina-ant.jar $ANT_HOME/lib
- cd xeno.bk/tools/control
- make
- cd xeno.bk/tools/internal
- make
-
-to setup:
-
- ## expand the jakarta (aka catalina) tree somewhere accessible by dom0
- export ROOTDIR=/anfs/scratch/labyrinth/ach61
- cd $ROOTDIR
- tar zxf /usr/groups/xeno/archive/tomcat-4.1.24.tar.gz 
- export CATALINA_HOME=$ROOTDIR/jakarta-tomcat-4.1.24
- export JAVA_HOME=/usr/groups/xeno/build_tools/java-1.4.1
-
- ## edit $CATALINA_HOME/conf/server.xml, change port 8080 to port 80
- cp $CATALINA_HOME/conf/server.xml $CATALINA_HOME/conf/server.orig
- sed 's/8080/80/g' $CATALINA_HOME/conf/server.orig > $CATALINA_HOME/conf/server.xml 
-
- ## install the xenctl web archive
- cp xeno.bk/tools/control/dist/xenctl-0.1-dev.war $CATALINA_HOME/webapps/xenctl.war
- cp xeno.bk/tools/control/domctl.xml /var/lib/xen
-
- ## either edit xi_tools_dir in domctl.xml or copy the binaries
- # find xeno.bk/tools/internal -perm +111 -type f -exec cp {} /usr/local/bin \;
-
-to run:
- $CATALINA_HOME/bin/startup.sh
- # point your browser at hostname-0.xeno.cl.cam.ac.uk:80/xenctl
-
-
-for development:
- ## edit xeno.bk/tools/control/build.properties
- # change manger.url to your xenoserver: mousetrap-0.xeno.cl.cam.ac.uk
- ## to "make install-web" in xeno.bk/tools/control  instead of copying the war file
- cp $CATALINA_HOME/conf/tomcat-users.xml $CATALINA_HOME/conf/tomcat-users.orig
- sed -e 's/<tomcat-users>/<tomcat-users>\
  <role rolename="standard"\/>\
  <role rolename="manager"\/>\
  <user username="hobbes" password="tiger" roles="standard,manager"\/>/' $CATALINA_HOME/conf/tomcat-users.orig > $CATALINA_HOME/conf/tomcat-users.xml
diff -r 75e23848b238 -r 4515f4d0701f tools/control/doc/INSTALL-cmdline
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tools/control/doc/INSTALL-cmdline	Thu Jul 10 12:53:46 2003 +0000
@@ -0,0 +1,11 @@
+To install command line interface:
+
+cd xeno.bk/tools/control
+make cmdline
+cp xenctl xenctl-cmdline.jar <dom0>/usr/local/bin
+cp domctl.xml <dom0>/etc
+mkdir <dom0>/var/lib/xen
+
+First invocation of command line interface will give a warning about not being
+able to load the disk state from /var/lib/xen/vdstate.xml. This is ok, it'll
+be created the first time you change any state in the virtual disk manager.
\ No newline at end of file
diff -r 75e23848b238 -r 4515f4d0701f tools/control/doc/INSTALL-web
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tools/control/doc/INSTALL-web	Thu Jul 10 12:53:46 2003 +0000
@@ -0,0 +1,50 @@
+
+some notes on configuring xenctl web interface...
+
+to build:
+
+ export PATH=/usr/groups/xeno/build_tools/bin:${PATH}
+ # this next step has already been done.
+ # cp $CATALINA_HOME/server/lib/catalina-ant.jar $ANT_HOME/lib
+ cd xeno.bk/tools/control
+ make web
+ # You only need to make/install internal if you haven't already
+ # it's also needed by the cmdline tool
+ cd xeno.bk/tools/internal
+ make
+
+to setup:
+
+ ## expand the jakarta (aka catalina) tree somewhere accessible by dom0
+ export ROOTDIR=/anfs/scratch/<somewhere>
+ cd $ROOTDIR
+ tar zxf /usr/groups/xeno/archive/tomcat-4.1.24.tar.gz 
+ export CATALINA_HOME=$ROOTDIR/jakarta-tomcat-4.1.24
+ export JAVA_HOME=/usr/groups/xeno/build_tools/java-1.4.1
+
+ ## edit $CATALINA_HOME/conf/server.xml, change port 8080 to port 80
+ cp $CATALINA_HOME/conf/server.xml $CATALINA_HOME/conf/server.orig
+ sed 's/8080/80/g' $CATALINA_HOME/conf/server.orig > $CATALINA_HOME/conf/server.xml 
+
+ ## install the xenctl web archive
+ cp xeno.bk/tools/control/dist/xenctl-0.1-dev.war $CATALINA_HOME/webapps/xenctl.war
+ # Only if you have not already copied this file for the command line tool
+ cp xeno.bk/tools/control/domctl.xml /etc
+ # If it doesn't exist:
+ mkdir /var/lib/xen
+
+ ## either edit xi_tools_dir in domctl.xml or copy the binaries
+ ## unless already installed for the command line tool
+ # find xeno.bk/tools/internal -perm +111 -type f -exec cp {} /usr/local/bin \;
+
+to run:
+ $CATALINA_HOME/bin/startup.sh
+ # point your browser at hostname-0.xeno.cl.cam.ac.uk:80/xenctl
+
+
+for development:
+ ## edit xeno.bk/tools/control/build.properties
+ # change manger.url to your xenoserver: mousetrap-0.xeno.cl.cam.ac.uk
+ ## to "make install-web" in xeno.bk/tools/control  instead of copying the war file
+ cp $CATALINA_HOME/conf/tomcat-users.xml $CATALINA_HOME/conf/tomcat-users.orig
+ sed -e 's/<tomcat-users>/<tomcat-users>\
  <role rolename="standard"\/>\
  <role rolename="manager"\/>\
  <user username="hobbes" password="tiger" roles="standard,manager"\/>/' $CATALINA_HOME/conf/tomcat-users.orig > $CATALINA_HOME/conf/tomcat-users.xml
diff -r 75e23848b238 -r 4515f4d0701f tools/control/doc/USAGE-cmdline
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tools/control/doc/USAGE-cmdline	Thu Jul 10 12:53:46 2003 +0000
@@ -0,0 +1,77 @@
+General
+-------
+
+Invoking xenctl with no arguments, or with 'help' gives general usage
+xenctl help command, or xenctl command -?, gives specific command help
+
+Domain control
+--------------
+
+xenctl's command line interface is based on domctl. Defaults for domain
+creation are found in /etc/domctl.xml.
+
+Creating a domain: xenctl domain new <parameters>
+All parameters may be omitted to get defaults from domctl.xml, see help
+for ful details of available parameters.
+
+Starting a domain: xenctl domain start -n<domain_no>
+Stopping a domain: xenctl domain stop -n<domain_no>
+Destroying a domain: xenctl domain destroy -n<domain_no> (add -f to force
+                     destruction of a running domain)
+
+Listing all domains: xenctl domain list
+
+Physical disk access management
+-------------------------------
+
+Grant read-only access to a disk or partition:
+  xenctl physical grant -n<domain_no> -p<partition_name> (e.g. sda10, sdc..etc)
+Grant read-write access to a disk or partition:
+  xenctl physical grant -w -n<domain_no> -p<partition_name>
+  (if you grant read-write to a domain which already has read for the same
+   partition, it will be upgraded quite happily, and vice versa)
+Revoke access to a disk or partition:
+  xenctl physical revoke -n<domain_no> -p<partition_name>
+List access a domain has:
+  xenctl physical list -n<domain_no>
+   will list all the physical disks/partitions which the given domain may access
+   and the rights assigned.
+   
+Virtual disk management
+-----------------------
+
+Add a disk partition as a XenoPartition (raw space to create VDs on):
+  xenctl partitions add -p<partition_name> -c<chunk_size>
+    adds the partition, splitting it up into chunks of the size given
+    Sizes can all be specified as k, m, g.
+Lists partitions:
+  xenctl partitions list
+    XenoPartitions are shown in [ ]
+    
+Create a virtual disk:
+  xenctl vd create -n<name> -s<size> [-e<expiry>]
+    Name is for identification only and need not be unique. Expiry may be none.
+    Size can be in k, m, g
+    You will be given a 10-digit key for the disk which is its unique identifier.
+Delete a virtual disk:
+  xenctl vd delete -k<key>
+    Virtual disks with VBDs mapped to them may not be deleted.
+Refresh the expiry on a disk:
+  xenctl vd refresh -k<key> [-e<expiry>]
+    Sets a new expiry, may be none.
+List virtual disks:
+  xenctl vd show
+  
+List space free:
+  xenctl vd free
+    Shows how much space has been added with partitions add, but not allocated
+    to a virtual disk.
+    
+Create a virtual block device:
+  xenctl vbd create -n<domain> -k<key> -v<vbd_number> [-w]
+    Maps the disk with the given key into the domain. -w allows read-write.
+    vbd number 0 = /dev/xvda, number 1 = /dev/xvdb, and so on.
+Lists virtual block devices:
+  xenctl vbd show
+  
+Virtual block devices are automatically deleted when their domain is destroyed.
\ No newline at end of file