From 0cb3ff13b092d6a96f60aaa4bff4d9609b067a86 Mon Sep 17 00:00:00 2001 From: Sander Vrijders Date: Wed, 7 Jun 2017 09:45:58 +0200 Subject: Update README.md This updates the README to explain the API a bit better. --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 47 insertions(+), 21 deletions(-) (limited to 'README.md') 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"). -- cgit v1.2.3