XenMan version 0.4.1 README
===========================

Introduction
------------

This tool provides easy user interface to creating, managing and
monitoring Xen Virtual machines or Xen Domains or Doms. This tool is
definitely for you, if you want to take Xen virtual machines for a
ride.


Prerequisites
-------------

* Run as root. Most of the Xen management operations require root
  privilege

* Make sure that you run this from a Xen enabled kernel.

* Confirm that Xen-3.0.2 is installed.  


Features
--------

When you start XenMan the first time, it will prompt you with a dialog
box requesting you to specify

Disk Location : The Doms can have disks supported by files in a file
system. This is the directory where the disks for the doms would get
created. Choose a directory with enough disk space. (few GB)

Snapshot Location : Xen supports saving a state of a running Virtual
Machine and restoring it at a later time. The snapshot location is
default directory where snapshot of running virtual machines would be
stored. Again, choose a directory with enough disk space.(few GBs)

---
Toolbar buttons

start    : Start the selected domain
Pause    : Toggle button to Pause/Restore running domain
Reboot   : Reboot a selected domain
Shutdown : Shutdown a running domain
Kill     : Hard kill on a domain
Snapshot : Save state of a running domain to a file
Restore  : Restore a domain from a file

---
Menu Items

Create Domain: This allows you to create a new domain with very few
parameters.

Create Domain File: Allows you to create a relatively complex config
file. Once created, you will see it in the list and can be started
using the start button.

Open Domain File : Allows you to add a new domain file to the list
which can then be edited using the settings context menu or started
using the start button.

---
The Home tab shows basic state and statistics for running doms.  When
you select a domain, a new tab is shown that has the console for that
virtual machine.


Configuration (xenman.conf)
---------------------------

XenMan's default configuration is kept in the xenman.conf file. This
file is human read/edit-able, so feel free to customise XenMan to suit
your environment. A brief description of some of the more important
configuration parameters you'll find in this file follows:

- ramdisk/kernel: the fully specified location to the default (guest)
  kernel and ramdisk. XenMan uses these to create new guest
  domains. If these properties are not specified, XenMan attempts to
  fetch copies from the 'staging_location' (see below).

- staging_location: the location where an installable image is
  staged. XenMan looks for the kernel and ramdisk images here at
  the relative paths designated by the staging_path_kernel/ramdisk
  properties. Local filesystem, http and ftp are supported. 
  NOTE: if the ramdisk and kernel parameters (see above) are set, 
  this property is not used.

- disks_dir: the location where XenMan will create Virtual Block
  Devices (VBD's) for use as disks by guest domains. NOTE: make sure
  you have plenty of space available at this location.

- snapshots_dir: the location where XenMan stores snapshots of running
  guest domains when the Snapshot/Restore feature is used.

- cache_dir: the location where XenMan stores the default kernel and
  ramdisk images (see ramdisk/kernel & staging_location above). By
  default, this is set to /var/cache/xenman.

- xenconf_dir: the default location for storing and retrieving Xen
  guest domain configuration files. By default, this is set to
  /etc/xen.
 
A couple of additional things worth noting:

* upon startup, XenMan looks for xenman.conf under the current
  directory, the user's home directory and /etc, in that order. If it
  doesn't find the file, XenMan creates a default file under the
  current directory.

* fetching the kernel/ramdisk images from the staging_location can
  become slow depending the network conditions. We recommend you set
  the staging_location property to a locally mounted volume (or a
  known, fast http/ftp location) before attempting to create
  your first guest domain.


A Note about Domain Configuration Files
---------------------------------------

As of v0.4.2, XenMan treats dom config files as python code (which
they actually are). If a domain file carries explicit python code
blocks, these are executed during load and only the resulting values 
are stored by XenMan. 

This means that if you load such a file and use the XenMan 
settings editor to change any values, the resulting dom config file will
no longer have the original code blocks. XenMan does, however, make
a backup in the same directory as the original file. 

Another important thing worth noting is that XenMan doesn't yet support
template-style (see /etc/xen/xmexample2) config files. These are configs
that expect various parameters (e.g. vmid) to be passed to them during 
launch and change their content dynamically in response. This is advanced
behaviour and the current limitation should not affect most users. 



Platforms Tested
----------------
Fedora Core 5
OpenSUSE 10.1
Xen 3.0.2 


Known Issues
------------

* Under some circumstances, the guest domain tab showing the virtual
  machine terminal fails to redraw properly. Clicking on the terminal
  and sending a Ctrl+l and/or some keystrokes often helps.


Licensing
---------

GNU Lesser General Public License (LGPL)
For details, see: http://www.gnu.org/licenses/lgpl.html
