strongSwan

= 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).

== Status ==

''Dumm'' is currently in [source:trunk/src/dumm heavy development] and incomplete. A prototype is running 

and a proof of concept has shown that it works.

Along with the ''dumm'' library, a console client is developed to interactively set

up and reconfigure UML networks. A test framework for strongSwan is planned around 

it, and a neat GTK GUI to click together your UML network would be just lovely (someone?).

== Terminology ==

 * Host 

   * The machine you are working on, has virtual guests in it. Mostly

    runs on bare hardware (unless you do really fancy stuff).

 * Guest

   * Virtual UML machine running on the host.

== 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 innterfaces 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.

== Requirements ==

  * Host:

    * Kernel:

      * A recent 2.6 kernel

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

      * [http://fuse.sourceforge.net/ FUSE] enabled

      * support for TAP devices

    * Userland:

      * [source:trunk/src/libstrongswan libstrongswan]

      * [http://tiswww.case.edu/php/chet/readline/rltop.html libreadline]

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

  * Guest:

    * Kernel:

      * hostfs

      * consoles?

    * Userland:

      * ip (from iproute2)/netlink proxy?

== Architecture ==

=== Working set ===

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

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

{{{

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

      boot.log   - hosts boot console log (con0)

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

      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

  scenarios/     - contains all scenarios

    test1/       - a scenario folder

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

        alice/   - COW for alice

        bob/     - COW for bob

      config     - network configuration file

}}}

=== 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.

== 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!

=== Host setup ===

  * install FUSE:

{{{

aptitude install libfuse-dev

}}}

  * install libbridge:

{{{

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

}}}

  * Build and install strongSwan from SVN sources.

{{{

svn co www.strongswan.org/ikev2/trunk strongswan

cd strongswan

less HACKING

./autogen

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

make

make install

}}}

  * 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 

    [https://wiki.ubuntu.com/KernelCustomBuild Ubuntu Howto], patched with the

    [http://www.user-mode-linux.org/~blaisorblade/patches/skas3-2.6/ SKAS3 patch].

=== Guest setup ===

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

{{{

mkdir umldir

cd umldir

mkdir master

}}}

  * debootstrap a debian etch system into master:

{{{

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

echo "proc /proc proc none 0 0" > master/etc/fstab

}}}

  * build a vanilla UML kernel

{{{

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

tar jxvf linux-2.6.22.1.tar.bz2

cd linux-2.6.22.1

make mrproper

ARCH=um make menuconfig

ARCH=um make

}}}

=== Sample session ===

  * go to our created testing directory and start ''dumm'':

{{{

cd umldir

ipsec dumm

}}}

  * create and start hosts alice and bob, each with an interface:

{{{

# guest

guest# create

guest name: alice

kernel image: linux-2.6.22.1/linux

master filesystem: master

amount of memory in MB: 128

guest 'alice' created

guest/alice# start

guest 'alice' is booting

guest/alice# addif

interface name: eth0

guest/alice# back

guest# create

guest name: bob

kernel image: linux-2.6.22.1/linux

master filesystem: master

amount of memory in MB: 128

guest 'bob' created

guest/bob# start

guest 'bob' is booting

guest/bob# addif

interface name: eth0

guest/bob# back

guest# back

#

}}}

  * create a bridge and attach guests interfaces:

{{{

# bridge

bridge# create

bridge name: br0

bridge 'br0' created

bridge/br0# addif

guest name: alice

interface name: eth0

bridge/br0# addif

guest name: bob

interface name: eth0

bridge/br0# back

bridge# back

#

}}}

  * interface manipulation on netlink is not done yet, so do it manually:

    * on master:

{{{

ifconfig alice-eth3 up

ifconfig bob-eth3 up

ifconfig br3 up

}}}

    * on alice:

{{{

ifconfig eth0 up

ifconfig eth0 192.168.1.1 netmask 255.255.255.0

ping 192.168.1.2

}}}

    * on bob:

{{{

ifconfig eth0 up

ifconfig eth0 192.168.1.1 netmask 255.255.255.0

ping 192.168.1.1

}}}