XenMan v0.5 README
------------------


Table of Contents
================

- XenMan
- Definitions
- Whats New (features)
- Deployment Instructions
- Prerequisites
- Setup
- XenMan Features
- Tips
- Changes since last release
- Platforms 
- Licensing
- Feedback
- Copyright


XenMan 
======

	XenMan is an open source tool for management of virtualized data 
centers using Xen hypervisor. It is simple enough for novice users to try out, 
yet sophisticated enough for use by experts. XenMan supports managing Virtual 
machines running on multiple physical machines.


Definitions:
===========
Domain/Dom : Virtual machine (Xen Virtual Machine in this context)
Node       : Refers to a physical host or machine
Client Node: Node on which the XenMan is invoked is referred to as client
             machine.
Managed Node : Node to be managed using XenMan.
Server Pool  : A collection of managed nodes typically owned/managed by a
               department or used to provide related services/applications.


Whats New ?
===========

- Multi node management : 
	With this new feature, administrators can now manage the 
Virtual Machines (Doms) on the remote nodes similar to that of local node. 
This expands the horizon of XenMan from local management to managing a
departmental data centers. A secure SSH mechanism is used to connect to
remote nodes.

- Image management : 
	XenMan now allows administrators to specify their image library, 
and provision Virtual Machines on any managed node.

- Multi-Dom operations : 
	Now administrators can start and stop all doms on any node with a 
single click.

- Node information : 
	You can now see some basic information about the host in the 
Information tab with a node selected.

- On line help 
	You can now see this document from XenMan help menu.


XenMan v0.5 - Deployment Instructions
=======================================

XenMan is distributed both as a source/binary tar ball and
as a binary rpm for a few specific distributions** (see the 
important note at the bottom). Depending on your 
method of installation, the deployment procedure may
differ slightly. 


I. Deployment from tar ball
--------------------------

1. cd to the location where you've extracted the tar ball.
	
	e.g.> cd ~/xenman.0.5/

2. Make sure your environment fulfills XenMan's pre-requisites. 
Consult the client and managed-node configuration sections
contained in the main README under the ./doc directory.

3. If you haven't already, deploy python-paramiko 
(an SSH client library XenMan uses for remote management) 
in your environment. Python-Paramiko is available for 
download at:

	http://www.lag.net/paramiko. 

(follow the installation instructions at the site carefully). 

4. Execute the default configuration script if you 
see one for for your distro. (e.g. configure_defaults-suse.sh for 
SUSE):

	e.g. > sh ./configure_defaults-suse.sh

5. If you see a default configuration file for your distro
in the current directory (e.g. xenman.conf.fedora for FC), 
rename it to xenman.conf. 

	e.g. > mv xenman.conf.fedora xenman.conf

NOTE: If you do not see a default configuration file specific to 
your distro, don't worry, XenMan will create one for you 
upon startup. However, you will have to manually specify a default 
image in this auto generated configuration file if you wish to use 
the "Create Domain" function. Consult the main README for 
more information on the XenMan configuration file. 

6. Make sure XenMan has execute permissions:

	e.g. > chmod 0755 ./xenman

7. Run XenMan and enjoy! 

	e.g. > ./xenman



II. Deployment from an RPM package
----------------------------------

1. Remove any earlier versions of xenman from your environment.

	e.g.> rpm -e xenman

2. cd to the directory you've downloaded the rpm package to and 
install XenMan:

	e.g.> rpm -Uvh xenman-0.5.1.fc5.noarch.rpm

If all goes well, you are good to go. Run XenMan and enjoy!

	e.g.> xenman

NOTE:  XenMan requires the python-paramiko package for remote operations
over SSH. A python-paramiko rpm package is available for most distro's;
however, if you cannot locate a suitable package for your distro, you can 
manually deploy it (see section I.3 above), and then run rpm with dependency
checks disabled.

	e.g.>rpm -Uvh xenman-0.5.1.suse.noarch.rpm --nodeps


** IMPORTANT NOTE:

We are looking for help from the community to package for other platforms 
and distro's (e.g.debian, windows, etc.). If you have already, or are 
interested in making one for your favorite environment, please do get in 
touch with us at http://xenman.sf.net/



Prerequisites
=============

Prerequisites for running XenMan

client node :
- Xen 3.0.2 or later installed.
- X server (to display XenMan UI)
- Ability to connect to Managed Node through SSH
- Paramiko library (if you have problems installing along with xenman)
- XenMan installed

managed node :
- Xen 3.0.2 or later (booted in to Xen kernel and Xend running)
- Xend daemon listening on TCP/IP port
- SSH daemon running
- X server is NOT required


Environment setup
=================

This section describes some additional setup for managing multiple node.
This is NOT required if you want to manage virtual machines 
on local host/client node only.

Xen Server setup :
----------------
    On the node to be managed, the Xen daemon (xend) needs to start listening using 
tcp-xmlrpc. 
To enable this, follow the following instructions.

  - login as root

  - uncomment the following line in /etc/xen/xend-config.sxp (change no to yes)
    (xend-tcp-xmlrpc-server yes) 

  - and restart xend service 

     # service xend restart


SSH setup : 
---------

  XenMan uses an ssh tunnel to communicate to with the Xend server. In addition,
  it needs to read a bunch of configuration files, create VBDs, LVMs and 
  give few other remote commands.  Basically all managed nodes
  need to trust all client nodes. (Yes, u can have more than one client nodes) 

   From client node, ssh to managed node from the client node using the account
   from which xenman would be started. 

    # ssh <managed node name> 

    This will prompt you to add the key to the known_hosts. Say yes.
    This will add the /etc/ssh_host_key.pub from the managed node  
    to users $HOME/.ssh/known_hosts on client node
    
    (Alternatively you can manually add it)

   ## Repeat above steps for each managed node.

   If you want to use password based authentication, the you are done. 
   You can skip the rest of the section. 

   For a small environment it may be ok to use password based authentication, 
   but in a large setup we recommend using key based authentication for 
   convenience and tractability.


   Refer to SSH manuals and on line material for setting up key based trust and
   using ssh-agent.
 
   Here are some useful urls

   http://www.suso.org/docs/shell/ssh.sdf
   http://www.linux.ie/articles/tutorials/ssh.php
  


Remote file browsing :
--------------------
While managing remote nodes, there are operations like, "Open Domain File" etc
that would require selecting a file on a remote node. For GNOME users, 
XenMan uses gnome-vfs to browse files on the remote node. Unfortunately 
this is done on a separate channel and hence would require user to enter the
 password again for the managed node.  When prompted for saving the password, 
it is recommended not to save password in key-ring for security reasons.

The user is NOT prompted for password if the key based authentication is used.
The user experience is quite seamless between localhost vs remote managed node 
management.

NOTE : There is a small bug in paramiko library used by XenMan. The XenMan distribution
contains the necessary files to patch this bug. In order to apply this patch, 

Use the patch_paramiko script as root. 

 # cd <xenman install>/patches
 # ./patch_paramiko


XenMan Features
===============

Server Pool Operations : 
----------------------
 	XenMan shows a Global Server Pool node which refers to a pool in which 
all managed nodes belong. XenMan supports only one server pool in this release. 

A Local node is automatically added to the pool, if prerequisites are met. XenMan
would manage Virtual machines on the local node. 

- Add Node : Additional remote managed nodes can be added by using the "Add Node" 
             operation. You are prompted for basic information: 

   * Host name : Name of the node/host to be added. 
   * Xen Port  : Port on which Xen Daemon (xend) is listening. Typically 8005
   * username  : (typically root)
   * password  : (NOT SAVED ANYWHERE ON DISK/can be left blank if 
              authentication is done using keys)  

One needs to make sure that Xen daemon (xend) listening on port 8005 on managed node.
If not, 
  - login as root
  - uncomment the following line in /etc/xen/xend-config.sxp 
    (xend-tcp-xmlrpc-server yes) 

  - and restart xend service 
     #service xend restart

Also, make sure that you can use ssh to login to the managed node.

Remove Node : A node can be removed from the list, by selecting it
               and choosing "Remove Node"

Node operations :
----------------
The following operations are allowed on a managed node.

- Start All domains : Start all domains on a selected node.

- Shutdown All domains  : Shutdown all domains on a selected node.

- Kill All domains  : Kill all domains on a selected node.

- Create Domain: Allows you to create a new domain with very few
parameters. (see section on Image Store for more details)

- 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.

- Restore domain  : Restores a domain from a file


Virtual Machine/Dom operations :
-----------------------------
start    : Start the selected domain
Pause    : Toggle button to Pause/Resume 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

Remove Domain File : Removes dom file name from the list of dom known to xenman.
Delete  : Delete domain file and associated VBD/LVMs.

XenMan and user accounts
------------------------

XenMan can be invoked from either root user or non-root user account

-- Root user : When XenMan is invoked from root user, it can manage local 
  node as well as other managed nodes for which credentials need to be 
  provided.


-- Non root user : When XenMan is invoked from non-root account, it can not
   do Xen management on local node. However, this user can manage other 
   managed nodes. Wherever necessary, XenMan prompts for credentials..


The Image Store :
----------------

XenMan allows administrators to define their images and create Virtual Machine 
configurations from them. For example, in a particular data center, four
types of machines are to be provisioned frequently. They are Red hat, CentOs, 
Suse and Ubuntu. You can configure XenMan to point to kernel and ramdisk of 
each of these distributions and install/deploy many virtual machines using 
predefined images. The collection of images (image entries) are referred to
 as Image Store.

XenMan comes with some default image store with couple of image entries 
that points to images on the net and can be used to do network installs.
These can be changed to some local images as well as new image entries can 
be added.


Here is an example of fedora image

fedora_installer = ['/net/fc5/vmlinuz.default', 
                    '/net/fc5/initrd.img.default', 
		    '',  # boot loader
                    []]  # other params for future

Instead of a mounted networked location one could have easily used image 
accessible via http or ftp too.
Once this is defined, you can use XenMan to create many VMs that would start 
the fedora installation and follow through the installation process.


XenMan config file (xenman.conf)
==============================================
XenMan's default configuration is kept in the xenman.conf file. This
file is in simple text format, so it can be easily changed to suit your environment. 

Here is a brief description of important configuration parameters: 

PATH section 
------------
This section contains default directory/file locations.

- disks_dir: This is the location where XenMan creates Virtual Block
  Devices (VBD's) for use as disks by Doms. Make sure you have plenty of space 
  available at this location. XenMan would prompt for this location if not 
  already set.

- snapshots_dir: This is the location where XenMan stores snapshots of running
  Doms for the Snapshot/Restore. XenMan would prompt for this location if not 
  already set.

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

- xenconf_dir: This is the location for storing and retrieving Dom 
  configuration files. By default, this is set to /etc/xen.


IMAGE STORE section
-------------------
The image store section contains one or more image store entries and a designated default. 

- default : the default image to use. 

Image store entries have four components: kernel, ramdisk, bootloader, other params. For example:
fedora_installer = ['/net/fc5/vmlinuz.default', 
                    '/net/fc5/initrd.img.default', 
		    '',  
                    []] 
Note that instead of a mounted networked location one can also specify images accessible via http, ftp or available on local filesystem.

APPLICATION section 
-------------------
This section keeps application specific data. 

- doms  : List of virtual machine configuration files being managed by XenMan.


ENVIRONMENT section
-------------------
This section contains node environment information.

- lvm_enabled : if the node has lvm and want XenMan to create LVM for new doms. 

Managed Node specific Sections 
------------------------------
The config file has section for each manged node. This contains information required by XenMan to connected managed nodes. This sections are relevant only on client nodes.

example :  

[192.168.0.102]
is_remote = True
login = root
xen_port = 8005


CLIENT CONFIGURATION section 
----------------------------
This section contains items specific to client/user preferences

- gnome_enabled : True/False. Set this to True if you are using XenMan on
                  Gnome desktop and have patched paramiko. See section on 
                  Remote File Browsing for more details.

 
Additional Notes:
* Upon startup, XenMan looks for xenman.conf, in order, at the 
  following locations: 
	./xenman.conf    	- (current directory)
	~/.xenman/xenman.conf 	- (user's home directory)
	/etc/xenman.conf	- (global location)
  If it doesn't find a valid, writable configuration file, XenMan creates 
  a default file under the current directory. 


Tips
====

- Always specify full path of the files, as if seen from the managed node.

- Do not add localhost or ip addresses using Add Host.

- use lower case names for images without spaces and 
  special characters

- XenMan does not allow editing DomU config files NOT generated via XenMan. It 
  looks at special header (first line) to make this determination. If the 
  config files contains simple name value pairs and are not parameterized, 
  they you may selectively choose to add the XenMan file header.



Changes since last release
===========================
- The terminal does not open until console button or show console menu item 
is used.

- The files that do not have XenMan header are not editable through XenMan.
  If the config files contains simple name value pairs and are not 
  parameterized, you may selectively choose to add XenMan file header.

- XenMan config file is now searched in the following order.
  ./xenman.conf
  ~/.xenman/xenman.conf
  /etc/xenman.conf
 
- older format xenman.conf would be upgraded to new version. (original file backed up)
  The new xenman.conf format is sufficiently different that an in-place upgrade is 
  not feasible. Thus all previous settings are lost. 


Known bugs/caveats:
==================

- To get the correct context sensitive menu for an item using right click, 
  the item must be selected. 

- You might have to enter credentials for the same node multiple times when 
  password based authentication scheme is used for managed node as opposed
  to key based authentication.

  For example : 
    - When the node is expanded
    - When terminal window is opened for selected Dom
    - When an operation requires remote file access and gnome-vfs is enabled 
      in XenMan configuration.  
    
- Sometimes, 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.

- When the Virtual machine configuration file is changed, the directives 
  may get saved in different order.

- On some platforms the password field generates gtk/pango warnings and displays "?" characters. Ignore this, the password is read correctly by XenMan.

Platforms
=========
Fedora Core 5
OpenSUSE 10.1
Xen 3.0.2 


Licensing 
=========

GNU General Public License (GPL)
For details, see: http://www.gnu.org/licenses/gpl.html


Feedback:
==========
Do drop us a line, if you download/evaluate/use XenMan. We would appreciate 
feedback on the current release as well as suggestions for future releases. 

Also, we are hoping for active community assistance in the following areas:

- packaging for more platforms and distributions. (e.g. debian, windows, etc.)
- ImageStore images (kernel/ramdisk pairs) for various pre-packaged GuestOS/DomU's.

The best way to reach us is to pop in and say hi at our (low frequency) mailing 
list. To sign up, visit http://xenman.sf.net/. We look forward to hearing 
from you!


Copyright/Acknowledgments
==========================
Xen is registered trademark of XenSource Inc
paramiko : We are thankful to paramiko author Robey Pointer for this wonderful lib.








