Homepage:
    http://www.xen-tools.org/software/xen-shell/

CVS Repository:
    http://xen-shell.cvsrepository.org/



xen-shell
---------

  The xen-shell is a simple program which is designed to be the login
 shell for a user of a Xen-based hosting account.

  For a hosting company who wishes to reduce support they may install
 and configure this shell for each of their users - reducing the amount
 of technical support which is required.

  Users of the shell may:

  * Access the serial console of their guest(s).
  * Bootup & Shutdown their guest(s).
  * Reimage their guests(s) to a new distribution. [*]
  * Control their own reverse DNS entries. [*]
  * View the bandwidth used by their guest(s). [*]

  Full help is available, and command completion provided for the
 basic commands (although not the optional arguments).

--
[*] - Requires additinal software & configuration.  See the later section
      titled "Optional Features".  See also the manpage.
--




Documentation
-------------

  Once installed you can read the manual for the xen-shell by invoking:

                xen-shell --manual

  or

                man xen-shell




Installation
------------

  To install the software run "make install" as root.

  Once installed set the login shell for each user you wish to use the
 shell to be: /usr/bin/xen-login-shell

  You'll also need to ensure that users who you wish to allow to use
 the shell have the ability to run "xm" as root with no password, via
 sudo:


# /etc/sudoers
---
User_Alias   XENUSERS = steve,nsa,grimoire,joey
Cmnd_Alias   XEN      = /usr/sbin/xm
XENUSERS     ALL      = NOPASSWD: XEN,XENIMG
---

  If you use the "reimage" system then you'll want to allow the users to
 execute "xen-create-image" if you use that too.

  Alternatively you could use something like this:

# /etc/sudoers
steve ALL = NOPASSWD: /usr/sbin/xm, /usr/bin/xen-create-image
bob   ALL = NOPASSWD: /usr/sbin/xm, /usr/bin/xen-create-image




Specifying Hosts
----------------

  The xen shell allows a user to control multiple Xen guests.  To specify
 which host a user can control you should ensure that your xen configuration
 files, (located beneat /etc/xen by default), contain the following:

   name      = 'my.host.name'
   xen_shell = 'bob, steve, skx'

  If the name of a host matches a users login name they will be allowed
 to control that instance.  Otherwise if their login name appears in the
 "xen_shell" line they will be able to control it.

  If a user is allowed to control multiple hosts then the "control" and
 "list" commands will be enabled for them.



Support
-------

  This software is released either under the terms of the GNU General Public
 License (v1 or v2) or the Perl artistic license, at your choice.

  This allows you to use it commercially with no charge - however commercial
 users are encouraged to make a donation if they're generating a profit:

    http://steve.org.uk/donate/

  If you wish to be listed as a user of the software and recieve a link
 upon the homepage please do let me know if you're using this commercially.
 As a software author it is very nice to track the spread and use of
 my software.

  Bug reports/suggestions can be sent to the author.



Optional Features
-----------------

  The shell contains several optional features which may be disabled,
 or which may not work depending upon your environtment.  These are:

   1.  Reverse DNS support.
   2.  Reimaging support.
   3.  Bandwidth display.

  Each of these things requires the support of external tools, and
 configuration.   If the shell detects that this support is not enabled
 at startup those commands will be disabled.

  If you don't want these facilities to be available to your users
 then you just need to not configure their optional features.

  If there are commands which are present in the shell which you
 wish to disable please see 'man xen-shell'.



1. Reverse DNS Support [Optional]
---------------------------------

  Whilst the shell doesn't perform any forward/reverse DNS changes by
 itself it does have a user-interface for working with reverse DNS.

  If the file ~/ips.txt exists when a user starts the shell the support
 is enabled, otherwise it is disabled.

  When the user users the 'rdns' command the only thing that changes
 is the contents of this text file.

  You are expected to process the result of these files yourself to
 actually update DNS.



2. Reimaging Support  [Optional]
--------------------------------

  The shell supports the ability to allow users to reimage their system,
 or reset it to a pristine state.  This ability isn't in the shell per se,
 instead the script will invoke:

        /home/$USER/image.sh

  The shell will prompt for confirmation before executing that script, and
 countdown to allow the user to change their mind.

  To enable reimaging you are expected to write a short shell script to 
 untar/install/fix their installation.  Using the xen-tools package you
 can allow your users to install Sarge, CentOS, or Gentoo.

  For an example of this reimaging support please run :

        xen-shell --manual



3. Bandwidth Viewing [Optional]
-------------------------------

  The shell supports the display of bandwidth used by a Xen guest
 providing you have :

   1.  The vnstat package installed.

   2.  The primary network interface for each guest named identically
      to the guest.

  For example if you have the guest named 'skx' then inside the
 Xen configuration file you should have something like this:


   vif = [ 'vifname=skx, ip=192.168.1.100, mac=00:17:31:56:BC:2D' ]

  This will ensure that once the guest is started you can run:

root@vain:~# ifconfig skx
skx       Link encap:Ethernet  HWaddr 00:17:31:56:BC:2D
          inet addr:192.168.1.30  Bcast:192.168.1.255  Mask:255.255.255.255
..




Steve
-- 
[steve@steve.org.uk]