bitkeeper revision 1.335 (3f0d61daWuAj1MdY8xaA6enqSDZSEg)

Documentation update.

3 files changed, 98 insertions, 4 deletions

diff --git a/tools/control/doc/INSTALL-cmdline b/tools/control/doc/INSTALL-cmdline
new file mode 100644
index 0000000000..74db2236ad
--- /dev/null
+++ b/tools/control/doc/INSTALL-cmdline
@@ -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 --git a/tools/control/README-web b/tools/control/doc/INSTALL-web
index a3c84ead65..be97a0db0f 100644
--- a/tools/control/README-web
+++ b/tools/control/doc/INSTALL-web
@@ -1,5 +1,5 @@
 
-some notes on configuring xenctl...
+some notes on configuring xenctl web interface...
 
 to build:
 
@@ -7,14 +7,16 @@ to build:
  # this next step has already been done.
  # cp $CATALINA_HOME/server/lib/catalina-ant.jar $ANT_HOME/lib
  cd xeno.bk/tools/control
- make
+ 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/labyrinth/ach61
+ 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
@@ -26,9 +28,13 @@ to setup:
 
  ## 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
+ # 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:
diff --git a/tools/control/doc/USAGE-cmdline b/tools/control/doc/USAGE-cmdline
new file mode 100644
index 0000000000..1e4766b80f
--- /dev/null
+++ b/tools/control/doc/USAGE-cmdline
@@ -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