Table of Contents

XenMan

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
Delete     : Delete domain file and associated VBD/LVMs.

Remove Domain File : Removes dom file name from the list of dom known to xenman.

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.