diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 205 |
1 files changed, 204 insertions, 1 deletions
@@ -1,5 +1,208 @@ Rumba is a Python framework that allows users to write Python scripts to define recursive internet networks and run scripted experiments. -The official documentation can be found +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. |