strongSwan

h1. Dynamic Uml Mesh Modeler

_Dumm_ is a framework to set up a virtual network using user mode linux guests.

It cleverly glues together some nice technologies to build networks dynamically.

To change the network topology, hosts are not required to reboot, changes apply

instantly and configuration can be done on the host (no network connection

required to change anything).

h2. Status

_Dumm_ is experimental and in development (see source:src/dumm). 

Along with the _dumm_ library, two frontends are currently usable:

* A graphical GTK client

* A console client with Ruby bindings to script scenarios in Ruby

The graphical client is incomplete. It is missing:

* Removal of added switches

* Disconnecting guests from switches

* Scenario management

The Ruby console client also misses a surrounding testing infrastructure which

will be built with ruby in the near future.

h2. Why UML?

UML is a senior in vitualization technologies, and there is a lot of new

hyped stuff about virtualization around. However, UML is lightweight, easy to

set up and allows dynamic reconfiguration (e.g. add/remove interfaces at

runtime), allows access to the hosts filesystem through hostfs and has some

other neat features.

Performance is not critical for our needs, and maybe we get hardware

virtualization support soon in UML.

It is free and fits perfectly.

h2. Requirements

* Host:

** Kernel:

*** A recent 2.6 kernel

*** "SKAS3 patch":http://www.user-mode-linux.org/~blaisorblade/patches/skas3-2.6/ recommended

*** "FUSE":http://fuse.sourceforge.net/ enabled

*** support for TAP devices

** Userland:

*** [[libstrongswan]]

*** libbridge from "bridge-utils":http://linux-net.osdl.org/index.php/Bridge

*** using the GTK client:

**** GTK+2 with developement headers

**** Gnome VteTerminal with developement headers

*** using the Ruby client:

**** Ruby 1.8 with developement headers

**** IRB

* Guest:

** Kernel:

*** hostfs

*** tuntap networking

*** our extended mconsole exec patch (see source:src/dumm/patches)

** Userland:

*** ip from iproute2

h2. Architecture

h3. Working set

Dumm needs a directory to store all its files, guest configurations and other

stuff. Inside that working directory, you'll find:

<pre>

workingdir/      - root folder containing a set of hosts and scenarios

  guests/        - contains all created guests

    alice/       - subdirectory for host "alice"

      alice/     - UML created folder (named umid) containing UML runtime files

      mem        - memory configuration file (contains amount of guest memory in MB)

      pid        - PID file if guest is running, handy to attach gdb to kernel

      linux      - symlinked UML kernel this host uses

      master/    - symlinked master root file system for this host

      diff/      - copy-on-write overlay to master this host uses

      union/     - mounted unified filesystem (master + diff + optional scenario)

    bob/

      ...        - same stuff as in alice

  templates/     - contains all scenario templates

    test1/       - a scenario folder

      diff/      - copy-on-write overlays for each guest's union folder

        alice/   - COW for alice

        bob/     - COW for bob

</pre>

h3. Networking

Network connectivity is realized through tap devices. When creating a _eth0_

network device on _alice_, a _alice-eth0_ tap device appears on the host. These

are directly connected, when _alice_ sends traffic to _eth0_, it appears on the

host at _alice-eth0_. You can see that as a small network segment (or just a

cable), where these interfaces are attached directly.

To build larger network segments, linux bridging on the host comes into play.

Segments are created by creating a bridge (as with brctl), and then attaching

our tap devices to that bridge. Routing can be done on a UML guest, or even on

the host.

This setup has some advantages over the _uml_switch_ solution. Bridging works

more reliable in the kernel, and as we see every network interface on the host,

we can sniff at every interface to get some clue what the guests are doing.

h2. HowTo

In this mini-howto, we build and boot a minimalistic debian guest on a ubuntu host.

We do everything as root here to simplify things!

h3. Host setup

* install required packages: <pre>

aptitude install libfuse-dev libgtk2.0-dev libvte-dev ruby1.8-dev irb1.8

</pre>

* install libbridge: <pre>

git clone git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/bridge-utils.git

cd bridge-utils

autoconf

./configure

cd libbridge

make

make install

</pre>

* Build and install strongSwan from Git sources: <pre>

git clone http://git.strongswan.org/strongswan.git

cd strongswan

less HACKING

./autogen

./configure --enable-dumm [other options]

make

make install

</pre>

* Ubuntu kernels almost fit our needs, they have FUSE and TAP device support. However, SKAS3 mode is missing. Build your own kernel based on the "Ubuntu Howto":https://wiki.ubuntu.com/KernelCustomBuild, patched with the "SKAS3 patch":http://www.user-mode-linux.org/~blaisorblade/patches/skas3-2.6/. SKAS3 is not required, but guests run much faster with SKAS3 enabled on the host.

h3. Guest master filesystem setup

* create a clean directory and a directory for our master filesystem in it: <pre>

mkdir umldir

cd umldir

mkdir master

</pre>

* bootstrap a debian sid system into master: <pre>

debootstrap sid master http://mirror.switch.ch/ftp/pub/debian/

</pre>

* enter chroot <pre>

chroot master

</pre>

* enable login on tty0 <pre>

echo "0:2345:respawn:/sbin/getty 38400 tty0" >> /etc/inittab

echo "tty0" >> /etc/securetty

</pre>

* Enable main repository <pre>

echo deb http://mirror.switch.ch/ftp/pub/debian sid main contrib > /etc/apt/sources.list

aptitude update

</pre>

* Install proper locales support <pre>

aptitude install locales

dpkg-reconfigure locales

</pre>

* Install some packages for strongSwan <pre>

aptitude install libgmp3c2 libsqlite3-0 libcurl3 dropbear gdb binutils

</pre>

* leave chroot <pre>

exit

</pre>

* build a vanilla UML kernel (using "my config": attachment:.config): <pre>

wget http://kernel.org/pub/linux/kernel/v2.6/linux-2.6.27.tar.bz2

tar jxvf linux-2.6.27.tar.bz2

cd linux-2.6.27

make mrproper

wget -O - http://trac.strongswan.org/browser/trunk/src/dumm/patches/mconsole-exec-2.6.27.patch?format=txt | patch -p1

wget http://trac.strongswan.org/attachment/wiki/DynamicUmlMeshModeler/.config?format=raw -O .config

ARCH=um make menuconfig

ARCH=um make

</pre>

h3. Start a network

You'll have to run the tools as root. Make sure you have a DISPLAY set, e.g. by starting it under _sudo_.

* Invoke the graphical client <pre>

sudo ipsec dumm

</pre>

Add guests, select our master filesystem and the compiled kernel. Add a bridges and connect your guests to it.

Start your guests and configure them. 

* Using the _irdumm_ ruby client <pre>

sudo ipsec irdumm

irb> sun = Guest.new("sun", "path/to/linux-2.6.27/linux", "path/to/master/", "mem=64M con0=xterm")

irb> sun.start

irb> sun.exec("echo sun > /etc/hostname")

irb> sun.add("eth0").connect(Bridge.new("br0")).add("192.168.0.1")

irb> sun.exec("ifconfig") { |line| puts line }

irb> quit

</pre>

h2. Installing strongSwan on guests

As we have full access to the master filesystem on the host, we can build strongSwan on the host and install it to the guests

<pre>

cd path/to/strongswan/

DESTDIR=/full/path/to/master make install

</pre>