xen-shell(1) · carta

NAME

xen-shell - Provide a console interface to control Xen guests.

SYNOPSIS

  xen-shell [options]

  Options:

   --control    Specify which instance to control by default.
   --help       Show brief help intstructions.
   --manual     Show more complete help.
   --version    Show the version of the software.

DESCRIPTION

  xen-shell provides a simple console interface to allow a user to
 control a Xen instances which are running upon the local system.

  The shell features include:

Command line completion

Command history

The ability to run within GNU Screen to allow long-running jobs to be completed "offline".

XEN SETUP

  There are two ways to setup a Xen guest which might be controlled by
 the local user "bob".

  The simplest method is to give a Xen instance the name "bob", (i.e.
 a Xen domU which has the same name as the login account of the user
 who is allowed to control it.), this has the downside that a local
 user may only control a single instance.

  The second solution is to add a line such as the following to the
 relevant Xen guest configuration file beneath /etc/xen:

  xen_shell = 'bob, steve, chris'

  This line, which will be ignored by Xen itself, will allow the Xen
 shell to be used by the three local users "bob", "steve", and "chris" -
 and each of them will be able to work with that host.

  If a user is allowed to control more than one Xen guest upon the
 current host then the two commands "control" and "list" will be made
 available to them.

COMMAND BLACKLISTING

  There are times when you might want to setup this shell such that
 some commands are not available.

  For the optional commands this is straightfoward; simply do not
 configure anything they rely upon.

  For the built-in commands such as "version", "uptime", etc, you will
 need to use the built in blacklist support.

  There are two ways you can disable commands within the shell:

Use /etc/xen-shell/xen-shell.conf

Use a per-domain blacklist

  To disable a command globally, amongst all Xen guests upon a host,
 you can simply add the following to xen-shell.conf:

  #
  #  Do not allow the following two commands
  #
  blacklist = version, uptime

  If you wish to disable a command for just a single instance, or
 only a few machines, then edit the Xen configuration file(s) to include
 this:

  xen_shell_blacklist = 'version, uptime'

REIMAGING SUPPORT

  The shell has a built-in "reimage" command which can be used by users
 to reinitialize their system.

  The reimage command itself does nothing, it merely executes the file
 "image.sh" from the users home directory, it is assumed that you will
 write your own script - perhaps to invoke "xen-create-image" to do
 the real job.

  A sample script, ~skx/image.sh, might look like this:

   #!/bin/sh
   #
   # Reimaging script for the user skx.
   #

   # the instance to be reimaged will be passed upon the command line.
   host=$1

   # The username we are.
   user=$2

   # find the IP by grepping /etc/hosts.
   ip=$(grep "$host" /etc/hosts|awk '{print $1}')

   if [ ! -z "${ip}" ]; then

      xen-create-image --hostname=$host --ip=$ip \
      --size=9.5Gb --swap=512Mb --memory=256Mb --force \
      --dist=etch --admin=$user
   else

      echo "IP address not found for guest $host - aborting"

fi

  If ~$USER/image.sh doesn't exist, or isn't executable, this command
 will be disabled.

REVERSE DNS SUPPORT

  This shell contains a built-in system for allowing a Xen-shell user to
 manipulate reverse DNS entries for IP addresses.  The shell itself doesn't
 do this directly, instead the shell will manipulate a simple text file
 in a users home directory.

  Create the file /home/$USER/ips.txt with contents of the following form:

   192.168.1.1 foo.my.flat
   192.168.1.2 bar.my.flat
   192.168.1.3 baz.my.flat

  If this file is present then the "rdns" command will be available to
 that user.  The "rdns" command, when executed with no arguments will
 simply display this file.

  When the user attempts to set reverse DNS this file will be updated.

  It is assumed you will have your own cronjob to actually read these
 files and perform the DNS updates, the shell support is just half the
 implementation.

  If the file doesn't exist, or isn't writable, then the command will
 be disabled.

BANDWIDTH TRACKING

  If you've got the 'vnstat' tool installed upon your host and the
 primary network interface of your Xen guest is given the same name
 as that of the guest you may see the bandwidth used via the 'bandwidth'
 command.

  To change the name of your interface you can configure your
 Xen guest with something like this in the configuration file:

  vif = [ 'ip=192.168.1.100,vifname=skx' ]

  Now when you run "ifconfig -a" upon the dom0 you'll see the guest
 has an interface named 'skx'.

  If the system cannot find a database for bandwidth tracking of
 a particular guest then the bandwidth command will be disabled.

AUTHOR

 Steve
 --
 http://www.steve.org.uk/

 $Id: xen-shell,v 1.110 2007-11-17 13:44:10 steve Exp $

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.

AUTHOR

 Steve
 --
 http://www.steve.org.uk/

 $Id: xen-shell,v 1.110 2007-11-17 13:44:10 steve Exp $

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.