aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSander Vrijders <sander.vrijders@ugent.be>2017-06-07 09:45:58 +0200
committerSander Vrijders <sander.vrijders@ugent.be>2017-06-07 10:05:38 +0200
commit0cb3ff13b092d6a96f60aaa4bff4d9609b067a86 (patch)
tree18b6d96e8007488a6c40a7fc2a44f3ebe1094e7c
parentacd8339aeaff05d678c3663b0a36af9e73fda618 (diff)
downloadrumba-0cb3ff13b092d6a96f60aaa4bff4d9609b067a86.tar.gz
rumba-0cb3ff13b092d6a96f60aaa4bff4d9609b067a86.zip
Update README.md
This updates the README to explain the API a bit better.
-rw-r--r--README.md68
1 files changed, 47 insertions, 21 deletions
diff --git a/README.md b/README.md
index 9bd7d38..cbe1015 100644
--- a/README.md
+++ b/README.md
@@ -3,17 +3,20 @@
Rumba is part of ARCFIRE 2020, Work Package 3. It is a framework in
Python which allows user to write a Python script to define a RINA
network. The physical graph needed for this RINA network is then
-calculated and realised on one of the supported testbeds. Next, one of
-the supported RINA prototypes is installed. After installation, the
-network is bootstrapped. For an example of such a Python script, have
-a look at the examples/ folder.
+calculated and realised on one of the supported testbeds. Next, if the
+user requests this, one of the supported RINA prototypes is
+installed. The network is then bootstrapped on the available
+nodes. Finally, the experiment can be swapped out of the testbed. For
+an example of such a Python script, have a look at the examples/
+folder.
## Workflow, both external and internal:
1. User defines the network graph, creating instances of model.Node
- and model.DIF classes
+ and model.DIF classes
- 2. User creates an instance of a Testbed class
+ 2. User creates an instance of a Testbed class. See below for
+ testbed specific configuration
3. User creates an instance of prototype.Experiment class, passing
the testbed instance and a list of Node instances
@@ -23,17 +26,19 @@ a look at the examples/ folder.
per-node IPCPs, registrations and enrollment, ready to be
used by the plugins
- 4. User calls run() on the prototype.Experiment instance:
+ 4. User calls methods on the prototype.Experiment instance:
- 1. run() calls Testbed.swap_in(), passing the Experiment, and
- filling in the missing information
+ 1. swap_in() swaps the experiment in on the testbed, and fills in
+ the missing information in the model.
- 2. run() calls a prototype-specific setup function, to create the
- required IPCPs, perform registrations, enrollments, etc.
+ 2. install_prototype() installs the chosen prototype on the
+ testbed. Currently an Ubuntu image is assumed.
- 3. Perform tests (TODO)
+ 3. bootstrap_prototype() calls a prototype-specific setup function,
+ to create the required IPCPs, perform registrations,
+ enrollments, etc.
- 4. run() calls Testbed.swap_out()
+ 4. swap_out() swaps the experiment out of the testbed.
## Installation
@@ -69,10 +74,30 @@ a look at the examples/ folder.
* [QEMU](http://wiki.qemu-project.org/Main_Page) is a generic and
open source machine emulator and virtualizer.
+ A minimal QEMU testbed is defined as follows:
+
+ tb = qemu.Testbed(exp_name = "twolayers",
+ username = "root",
+ password = "root")
+
+ A user can optionally also specify the path to a bzImage and to an
+ initramfs. If they are not specified, the latest buildroot image
+ for the specific prototype will be downloaded. (Around 40 MB in
+ size) The login to those images is root/root.
+
* [Emulab](https://www.emulab.net/) is a network testbed, giving
researchers a wide range of environments in which to develop,
debug, and evaluate their systems.
+ An emulab testbed instance is defined as follows:
+
+ tb = emulab.Testbed(exp_name = "rochefort10",
+ username = "ricksanchez")
+
+ A password can also be provided but is not necessary when an SSH
+ key has been added. Optionally, a project name, a different testbed
+ URL and a custom image can be specified.
+
* [jFed](http://jfed.iminds.be/) is a Java-based framework for
testbed federation.
@@ -89,7 +114,8 @@ a look at the examples/ folder.
Here the experiment name is rochefort10, the user's name is
ricksanchez, and the certificate can be found in
- /home/morty/cert.pem. An absolute path must be used for cert_file.
+ /home/morty/cert.pem. An absolute path must be used for
+ cert_file. Optionally a custom image can be selected.
Before running the rumba you must run an SSH agent in same terminal.
This will also avoid you having to enter the passphrase for every
@@ -102,15 +128,15 @@ a look at the examples/ folder.
$ eval `ssh-agent`
$ ssh-add /home/morty/cert.pem
- To access a node once the experiment swapped in, use the following
- command (in the same terminal where ssh-agent was run):
+ To access a node once the experiment swapped in, use the following
+ command (in the same terminal where ssh-agent was run):
- $ ssh -A -oProxyCommand="ssh -i $CERTPATH
+ $ ssh -A -oProxyCommand="ssh -i $CERTPATH
-o StrictHostKeyChecking=no $USER@bastion.test.iminds.be
nc $NODENAME.$EXP.wall2-ilabt-iminds-be.wall2.ilabt.iminds.be 22"
$USER@$NODENAME.$EXP.wall2-ilabt-iminds-be.wall2.ilabt.iminds.be
- where $CERTPATH is the absolute path of the certificate (e.g.
- /home/morty/cert.pem), $USER is the jFed username (e.g. "ricksanchez"),
- $NODENAME is the name of the node you want to access (e.g. "a"),
- and $EXP is the name of the experiment (e.g. "rochefort10").
+ where $CERTPATH is the absolute path of the certificate (e.g.
+ /home/morty/cert.pem), $USER is the jFed username (e.g. "ricksanchez"),
+ $NODENAME is the name of the node you want to access (e.g. "a"),
+ and $EXP is the name of the experiment (e.g. "rochefort10").