------------------------------------------------------------------------
                        Qemu Test Kolab Server
------------------------------------------------------------------------

This is an pre-configured, Qemu[0] based Test Kolab Server in a box.
It consists of a Qemu disk image with a ready to use Kolab Server
installation on a debian etch system and an easy to configure start
script.

The relevant ports (imap, smtp, ssh etc.) of the virtual server are
mapped to ports on the host system, so that the virtual server can be
accessed from the host system and the lan.


INSTALLATION:

A working Qemu installation is needed.[1]  The kqemu Kernel module is
recommended for best performance but not required.

Further installation is not required but see `CONVENIENCE TIPS'.


CONFIGURATION:

The start script recognizes a bunch of environment variables.  These
can be set either manually in the shell environment or in the
configuration file `qemu-kolab-server.conf'.

The most important variable is PORTOFFSET, it holds a numeric value
which is added to every forwarded port number on the host side.  This
prevents clashes with already running services and allows to run the
virtual server as non-root user by mapping all ports to non
privileged ones.  For example:

  $ PORTOFFSET="41000" ./start-qemu-kolab-server.sh

runs the server so, that the virtual system's ssh is reachable on port
41022, the virtual imap on 41143 and 41993 and so forth...

All configuration variables are listed and documented in
`qemu-kolab-server.conf'.


RUNNING:

The virtual server can be started from within the `qemu-kolab-server'
directory by simply running `./start-qemu-kolab-server.sh'.  After
that the virtual system console is accessible via VNC and all the
virtual system ports via forwarding.  The current port forwarding and
vnc configuration is printed to stout on startup:

  $ PORTOFFSET="42000" ./start-qemu-kolab-server.sh
  Starting Qemu Kolab Server
  forwarding 42022 => 22
  forwarding 42025 => 25
  forwarding 42080 => 80
  forwarding 42143 => 143
  forwarding 42443 => 443
  forwarding 42465 => 465
  forwarding 42993 => 993
  Connect to VNC display :0 for system console.

The administration interface of the virtual server can be accessed
using a browser like this:

  https://localhost:42443/admin/

The Kolab WebClient can be accessed with this URL:

  https://localhost:42443/horde/


SECURITY CONSIDERATIONS:

The forwarded ports on the host system are not only accessible locally
but on all network interfaces[2].  As the virtual system has an
insecure root and Kolab master password, with the later not easy to
change, the virtual system should not be started on hosts which are
accessible from untrusted networks.


ACCESS DATA:

The virtual Kolab Server is configured for the domain `example.com',
so the mail accounts will follow the pattern `USER@example.com'.  The
internal hostname of the virtual server is `kolab.example.com'.

The virtual system's RSA key fingerprint is
35:4e:2a:58:7f:65:e9:8d:8d:e7:06:81:be:63:fb:1a. 

The Kolab manager account (for the web administration interface) is:
User: manager
Password: nichtgeheim

The virtual system's root password is: nichtgeheim


CONVENIENCE TIPS:

The virtual server is configured to the host name `kolab.example.com',
so it might be convenient to add it to the localhost in `/etc/hosts'
like this:

  127.0.0.1	localhost kolab.example.com

For easy ssh access it is recommended to add a configuration for the
virtual host to `$HOME/.ssh/config' with the forwarded port set as
default:

  Host kolab.example.com
  User root
  Port 42022
  HostName localhost


PRESERVING AND RESTORING STATE:

The easiest way to preserve a virtual system's state is to copy the
disk-image `kolab.qcow2'.  This should only be done when the virtual
system is not running to prevent corruption of the virtual filesystem.

Further more the used virtual disk format (qcow2) allows to use Qemu's
snapshot feature to make snapshots of the whole virtual system's state
(including RAM and CPU).  Please refer to the Qemu manual on how to
use it.



[0] http://www.nongnu.org/qemu/
[1] successfully tested with the qemu package from Debian Lenny
[2] unfortunately Qemu doesn't allow for forwarded ports to only bind
    to specific interfaces.
