1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
Rumba is a Python framework that allows users to write Python scripts
to define recursive internet networks and run scripted experiments.
The original documentation can be found
[here](https://arcfire.gitlab.io/rumba/).
This version of rumba is maintained by the Ouroboros (O7s) project.
The documentation can be found
[here](https://ouroboros.rocks/wiki/Rumba).
## Installation
To install Rumba from a local clone:
```bash
git clone https://codeberg.org/o7s/rumba.git
cd rumba
python3 -m venv .venv
source .venv/bin/activate
pip install .
```
Optional extras:
```bash
pip install rumba[NumpyAcceleration] # faster random traffic generation
pip install rumba[graphs] # PDF graph export via pydot
pip install rumba[visualizer] # interactive visualization via igraph + plotly
```
On Debian/Ubuntu you may also need:
```bash
sudo apt-get install build-essential libssl-dev libffi-dev python3-dev
```
The required dependencies (`paramiko` and `docker`) are installed
automatically.
## Defining a Topology
Rumba models recursive networks using **layers** and **nodes**. Layers
correspond to Ouroboros IPCP types. Nodes declare which layers they
belong to and how those layers are stacked via **registrations**.
The example below defines four nodes connected in a ring, with a single
unicast layer (`n1`) running over four point-to-point Ethernet links:
```
a ---e01--- b
| |
e04 e02
| |
d ---e03--- c
```
```python
from rumba.model import UnicastLayer, EthDixLayer, Node
# A unicast layer that will span all four nodes
n1 = UnicastLayer("n1")
# Four point-to-point Ethernet links (max 2 members each)
e01 = EthDixLayer("e01") # a <-> b
e02 = EthDixLayer("e02") # b <-> c
e03 = EthDixLayer("e03") # c <-> d
e04 = EthDixLayer("e04") # d <-> a
# Each node lists its layer memberships and how layers are stacked.
# registrations = {upper: [lower, ...]} means "upper registers in lower".
a = Node("a",
layers=[n1, e01, e04],
registrations={n1: [e01, e04]})
b = Node("b",
layers=[n1, e01, e02],
registrations={n1: [e01, e02]})
c = Node("c",
layers=[n1, e02, e03],
registrations={n1: [e02, e03]})
d = Node("d",
layers=[n1, e03, e04],
registrations={n1: [e03, e04]})
```
Two nodes that share an `EthDixLayer` are connected by that Ethernet
link. The `registrations` dictionary tells Rumba how to stack the
layers: `{n1: [e01, e04]}` means the unicast layer `n1` registers in
both `e01` and `e04` on that node, giving it connectivity over those
links.
Policies can be set on unicast layers:
```python
n1.add_policy("routing", "lfa")
```
Link quality (delay, loss, rate) can be configured on Ethernet layers:
```python
from rumba.model import EthDixLayer, Delay
e01 = EthDixLayer("e01")
e01.set_delay(delay=10, jitter=2) # 10 ms delay, 2 ms jitter
e01.set_loss(loss=0.1) # 0.1% packet loss
e01.set_rate(rate=100) # 100 Mbps
```
## Quick Start
A complete runnable script that deploys the ring topology above on a
local testbed:
```python
from rumba.model import *
from rumba.utils import ExperimentManager
import rumba.testbeds.local as local
import rumba.prototypes.ouroboros as our
# --- topology (from the example above) ---
n1 = UnicastLayer("n1")
e01 = EthDixLayer("e01")
e02 = EthDixLayer("e02")
e03 = EthDixLayer("e03")
e04 = EthDixLayer("e04")
a = Node("a", layers=[n1, e01, e04], registrations={n1: [e01, e04]})
b = Node("b", layers=[n1, e01, e02], registrations={n1: [e01, e02]})
c = Node("c", layers=[n1, e02, e03], registrations={n1: [e02, e03]})
d = Node("d", layers=[n1, e03, e04], registrations={n1: [e03, e04]})
# --- testbed and experiment ---
tb = local.Testbed()
exp = our.Experiment(tb, nodes=[a, b, c, d])
# --- run ---
with ExperimentManager(exp):
exp.swap_in() # provision the testbed
exp.bootstrap_prototype() # create IPCPs and enrollments
```
`swap_in()` provisions the nodes on the chosen testbed.
`bootstrap_prototype()` creates the Ouroboros IPCPs, bootstraps them,
and performs enrollments automatically. `ExperimentManager` handles
cleanup when the block exits.
## Key Concepts
- **Layer** — a network layer aligned with an Ouroboros IPCP type.
Available types: `UnicastLayer`, `BroadcastLayer`, `EthDixLayer`,
`EthLlcLayer`, `LocalLayer`, `Udp4Layer`, `Udp6Layer`.
- **Node** — a system declaring its layer memberships and
registrations (layer stacking).
- **Testbed** — the infrastructure backend that provisions nodes
(see table below).
- **Experiment** — computes IPCP placement, enrollment order, and
manages the prototype lifecycle.
- **StoryBoard** — schedules client/server traffic with support for
Poisson arrival rates.
- **CommandResult** — structured result from `node.execute_command()`
carrying exit code, stdout, and stderr.
- **Process** — a managed background process with `is_alive()`,
`wait()`, and `kill()`.
- **ExperimentManager** — context manager that handles experiment
setup and teardown.
## Supported Testbeds
| Testbed | Module | Description |
|----------|---------------------------|------------------------------------------------|
| Local | `rumba.testbeds.local` | Single machine, processes run locally |
| LocalNet | `rumba.testbeds.localnet` | Linux bridges + veth pairs, supports netem |
| Docker | `rumba.testbeds.dockertb` | Docker containers with bridge networking |
| Emulab | `rumba.testbeds.emulab` | Emulab / iMinds testbed (SSH-based) |
| jFed | `rumba.testbeds.jfed` | Virtual Wall, ExoGENI, CloudLab via jFed |
## CLI Tools
The `rumba-access` command opens an SSH session to an experiment node:
```bash
rumba-access <node-name>
```
## More Examples
See the [examples/](examples/) directory for additional topologies and
usage patterns, including multi-layer stacking, Docker deployments,
storyboard scripting, and large-scale experiments.
## Citation
If you use Rumba in your research, please cite:
> S. Vrijders, D. Staessens, M. Capitani, and V. Maffione,
> "Rumba: A Python framework for automating large-scale recursive
> internet experiments on GENI and FIRE+," *IEEE*, 2018.
## License
Rumba is licensed under the
[GNU Lesser General Public License v2.1](LICENSE).
See [AUTHORS](AUTHORS) for the list of contributors.
|
