xen-shell

XEN-SHELL(1)	       Perl Programmers Reference Guide		  XEN-SHELL(1)



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/

LICENSE
       Copyright (c) 2005-2007 by Steve Kemp.  All rights reserved.

       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/

LICENSE
       Copyright (c) 2005-2006 by Steve Kemp.  All rights reserved.

       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.



1.9				  2008-11-30			  XEN-SHELL(1)