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/

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

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/

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

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.8 2007-11-17 XEN-SHELL(1)