README.txt
1 $NetBSD: README.txt,v 1.1 2010/03/29 02:01:47 pooka Exp $
2
3Using rump it is possible to build a router test setup consisting
4of thousands of NetBSD IP stacks within a single host OS, one
5networking stack per application process. Each IP stack instance
6has its own set of interfaces, addresses and routing tables. These
7instances may or may not share the same code, i.e. it is possible
8to do compatibility testing of new features. The advantage over
9using full-fledged virtual OS setups (qemu, Xen, etc.) is scalability:
10the rump IP router base runtime takes less than 500kB of memory
11per instance.
12
13The code is _ONLY AN EXAMPLE_ as opposed a fully featured test kit.
14Some code tweaking is probably required to make this do what you
15want. Usage examples follow.
16
17To use one single rump networking stack instance with access to
18two real networks, you need tap and bridge on the host system (yes,
19this involves some memory copies. the resulting router setup can
20still saturate a GigE, though. it should not be difficult to bring
21performance to be ~the same as an in-kernel stack, but haven't
22managed to implement that yet).
23
24Anyway, the following can be done with the current code:
25
26/*
27 * Usage:
28 *
29 * # ifconfig yourrealif0 up
30 * # ifconfig tap0 create
31 * # ifconfig tap0 up
32 * # ifconfig bridge0 create
33 * # brconfig bridge0 add tap0 add yourrealif0
34 * # brconfig bridge0 up
35 * #
36 * # ifconfig yourrealif1 up
37 * # ifconfig tap1 create
38 * # ifconfig tap1 up
39 * # ifconfig bridge1 create
40 * # brconfig bridge1 add tap1 add yourrealif1
41 * # brconfig bridge1 up
42 * #
43 * # ./router virt0 192.168.1.1 255.255.255.0 192.168.1.255 \
44 * # virt1 192.168.2.1 255.255.255.0 192.168.2.255
45 *
46 * This will bind virtN to tapN and act as a router.
47 */
48
49As brilliant ascii art, it would look something like this:
50
51 network network
52 ^ ^
53 | |
54 /----v-------------\ /------------v----\
55 kernel | realif0 <-> tap0 | | tap1 -> realif1 |
56 \---------------^--/ \---^-------------/
57-------------------------|-------------------|--------------------
58 /----v-------------------v----\
59 user | virt0 <-> rump IP <-> virt1 |
60 \-----------------------------/
61
62(ok, no more drawing)
63
64The addresses configured to the rump virt0 and virt1 interfaces
65will be visible on the physical network, and their traffic can be
66examined with e.g. wireshark. You can also use wireshark on
67tap0/tap1.
68
69The alternate approach is to use purely internal simulation. The
70shmif rump driver uses a memory-mapped file as an ethernet "bus"
71between multiple rump networking stack instances. Just use
72rump_pub_shmif_create() in the code. This can also of course be
73combined with the tap setup, and you can have setups where border
74nodes talk to an internal mesh of shmif's. Semi-drawn, it looks
75like this:
76
77net1 <-> virt0, shm0 <-> shm1, shm2 <-> .... <-> shmN, virt1 <-> net1
78 (rump0) (rump1) .... (rumpN)
79
80Linear setups (where router n talks to exactly router n-1 and n+1)
81can be easily autogenerated. Here's a snippet of executed commands
82I used to start a few hundred routers (NOTE! the usage of the
83example code is different!):
84
85./a.out 10.0.0.1 10.0.0.255 /tmp/rumpshm_0 0 10.0.1.2 10.0.1.255 /tmp/rumpshm_1 10.0.1.1
86./a.out 10.0.1.1 10.0.1.255 /tmp/rumpshm_1 10.0.1.2 10.0.2.2 10.0.2.255 /tmp/rumpshm_2 10.0.2.1
87./a.out 10.0.2.1 10.0.2.255 /tmp/rumpshm_2 10.0.2.2 10.0.3.2 10.0.3.255 /tmp/rumpshm_3 10.0.3.1
88./a.out 10.0.3.1 10.0.3.255 /tmp/rumpshm_3 10.0.3.2 10.0.4.2 10.0.4.255 /tmp/rumpshm_4 10.0.4.1
89....
90./a.out 10.0.252.1 10.0.252.255 /tmp/rumpshm_252 10.0.252.2 10.0.253.2 10.0.253.
91255 /tmp/rumpshm_253 10.0.253.1
92./a.out 10.0.253.1 10.0.253.255 /tmp/rumpshm_253 10.0.253.2 10.0.255.1 10.0.255.
93255 /tmp/rumpshm_255 0
94
95(see startrouters.sh for a script to produce that output)
96
97Easy but slightly more interesting setups, such as a M^N matrix
98(hyper-matrix?) are also possible, but left as an exercise to the
99reader.
100
101Compiling the router depends a little on what networking domain
102and what interface you want to use for testing. The very basic
103setup with IP+virtif will get you quite far:
104
105cc rumprouter.c -lrumpnet_virtif -lrumpnet_netinet -lrumpnet_net -lrumpnet \
106 -lrump -lrumpuser -lpthread
107