bitkeeper revision 1.700 (401d7e17TsVIdmq0QNgdFLXJHFN1kg)

transfer new domain tools and readmes from the 1.2 tree

1 files changed, 109 insertions, 0 deletions

diff --git a/tools/examples/README b/tools/examples/README
new file mode 100644
index 0000000000..13379bb5c4
--- /dev/null
+++ b/tools/examples/README
@@ -0,0 +1,109 @@
+Xen Control Tools - Example Scripts
+===================================
+
+This directory contains a set of example scripts for common Xen operations.
+For many operations you will either be able to use these scripts directly, or
+incorporate code from them into your own scripts.
+
+The Xc and XenoUtil Python modules provide an API for accessing all this
+functionality - and more - from your own Python programs.  These libraries may
+contain features for which there aren't yet example scripts written for...
+
+If you write a useful script and would like to share it, please do
+send it (preferably with a little summary to go in this file) to
+<xen-devel@lists.sourceforge.net> so we can add it to this directory.
+
+xc_dom_control.py
+ - general tool for controling running domains
+  Usage: xc_dom_control.py [command] <params>
+  stop      [dom]        -- pause a domain
+  start     [dom]        -- un-pause a domain
+  shutdown  [dom]        -- request a domain to shutdown
+  destroy   [dom]        -- immediately terminate a domain
+  pincpu    [dom] [cpu]  -- pin a domain to the specified CPU
+  save      [dom] [file] -- suspend a domain's memory to file
+  restore   [file]       -- resume a domain from a file
+  list                   -- print info about all domains
+  listvbds               -- print info about all virtual block devs
+  cpu_bvtset [dom] [mcuadv] [warp] [warpl] [warpu]
+                         -- set scheduling parameters for domain
+  cpu_bvtslice [slice]   -- default scheduler slice
+  vif_stats [dom] [vif]  -- get stats for a given network vif
+  vif_addip [dom] [vif] [ip]  -- add an IP address to a given vif
+  vif_setsched [dom] [vif] [bytes] [usecs] -- rate limit vif bandwidth
+  vif_getsched [dom] [vif] -- print vif's scheduling parameters
+  vbd_add [dom] [uname] [dev] [mode] -- make disk/partition uname available to 
+                            domain as dev e.g. 'vbd_add phy:sda3 hda1 rw'
+  vbd_remove [dom] [dev] -- remove disk or partition attached as 'dev' 
+
+
+xc_dom_create.py
+ - This tool is used to create and start new domains. It reads defaults
+from a file written in Python, having allowed variables to be set and
+passed into the file. Further command line arguments allow the
+defaults to be overridden. The defaults for each parameter are listed
+in [] brackets. Arguments are as follows:
+
+Arguments to control the parsing of the defaults file:
+ -f config_file   -- Use the specified defaults script. 
+                     Default: ['/etc/xc/defaults']
+ -D foo=bar       -- Set variable foo=bar before parsing config
+                     E.g. '-D vmid=3:ip=1.2.3.4'
+ -h               -- Print extended help message, including all arguments
+ -n               -- Dry run only, don't actually create domain
+
+
+The config file 'defaults' requires the following variable to be defined:
+ vmid             -- Numeric identifier for the new domain, used to calculate
+                     the VM's IP address and root partition. E.g. -Dvmid=1
+
+
+Arguments to override current config read from 'defaults':
+ -k image         -- Path to kernel image ['']
+ -r ramdisk       -- Path to ramdisk (or empty) ['']
+ -b builder_fn    -- Function to use to build domain ['']
+ -m mem_size      -- Initial memory allocation in MB [0MB]
+ -N domain_name   -- Set textual name of domain ['']
+ -a auto_restart  -- Restart domain on exit, yes/no ['0']
+ -e vbd_expert    -- Saftey catch to avoid some disk accidents ['0'] 
+ -d udisk,dev,rw  -- Add disk, partition, or virtual disk to domain. E.g. to 
+                     make partion sda4 available to the domain as hda1 with 
+                     read-write access: '-b phy:sda4,hda1,rw' To add 
+                     multiple disks use multiple -d flags or seperate with ':'
+                     Default: ['']
+ -i vfr_ipaddr    -- Add IP address to the list which Xen will route to
+                     the domain. Use multiple times to add more IP addrs.
+                     Default: ['']
+
+Args to override the kernel command line, which is concatenated from these:
+ -I cmdline_ip    -- Override 'ip=ipaddr:nfsserv:gateway:netmask::eth0:off'
+                     Default: ['']
+ -R cmdline_root  -- Override root device parameters.
+                     Default: ['']
+ -E cmdline_extra -- Override extra kernel args and rc script env vars.
+                     Default: ['']
+
+
+
+xc_vd_tool
+ - tool for manipulating virtual disks
+   Usage: xc_vd_tool command <params>
+
+   initalise [dev] [[ext_size]]  - init. a physcial partition to store vd's
+   create [size] [[expiry]]      - allocate a vd of specified size (and expiry)
+   delete [vdid]                 - delete a vd
+   import [filename] [[expiry]]  - create a vd and populate w/ image from file
+   export [vdid] [filename]      - copy vd's contents to a file
+   setexpiry [vdid] [[expiry]]   - update the expiry time for a vd
+   list                          - list all the unexpired virtual disks  
+   undelete [vdid] [[expiry]]    - attempts to recover an expired vd
+   freespace                     - print out the amount of space in free pool
+
+   notes:
+   vdid      - the virtual disk's identity string
+   size      - measured in MB
+   expiry    - is the expiry time of the virtual disk in seconds from now
+               (0 = don't expire) 
+   device    - physical partition to 'format' to hold vd's. e.g. hda4
+   ext_size  - extent size (default 64MB)
+