From a1bddf0ab2cd7bee30b1f0dc1575c0b8c532e157 Mon Sep 17 00:00:00 2001 From: Sander Vrijders Date: Mon, 26 Mar 2018 16:25:14 +0200 Subject: rumba: Add Rumba documentation website This adds a documentation website for Rumba which is triggered automatically after changes to master. --- doc/conf.py | 41 +++++++++++++++++++++++++++++++++++++ doc/docker.rst | 13 ++++++++++++ doc/emulab.rst | 16 +++++++++++++++ doc/index.rst | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/installation.rst | 21 +++++++++++++++++++ doc/irati.rst | 9 +++++++++ doc/jfed.rst | 30 +++++++++++++++++++++++++++ doc/local.rst | 5 +++++ doc/log.rst | 5 +++++ doc/model.rst | 5 +++++ doc/ouroboros.rst | 9 +++++++++ doc/qemu.rst | 13 ++++++++++++ doc/rlite.rst | 9 +++++++++ doc/storyboard.rst | 5 +++++ doc/utils.rst | 13 ++++++++++++ doc/workflow.rst | 44 ++++++++++++++++++++++++++++++++++++++++ 16 files changed, 295 insertions(+) create mode 100644 doc/conf.py create mode 100644 doc/docker.rst create mode 100644 doc/emulab.rst create mode 100644 doc/index.rst create mode 100644 doc/installation.rst create mode 100644 doc/irati.rst create mode 100644 doc/jfed.rst create mode 100644 doc/local.rst create mode 100644 doc/log.rst create mode 100644 doc/model.rst create mode 100644 doc/ouroboros.rst create mode 100644 doc/qemu.rst create mode 100644 doc/rlite.rst create mode 100644 doc/storyboard.rst create mode 100644 doc/utils.rst create mode 100644 doc/workflow.rst (limited to 'doc') diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..0424dc7 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,41 @@ +from datetime import datetime + +import alabaster + + +html_theme_path = [alabaster.get_path()] +extensions = ['alabaster'] +html_theme = 'alabaster' + +html_theme_options = { + 'description': "Rumba: A framework to bootstrap a " + + "recursive internet network on a testbed." +} + +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'searchbox.html' + ] +} + +project = 'Rumba' +year = datetime.now().year +copyright = '{} imec, Nextworks S.r.l.'.format(year) +author = 'Sander Vrijders, Marco Capitani, Dimitri Staessens, Vincenzo Maffione' +master_doc = 'index' +source_suffix = '.rst' +default_role = 'obj' +language = None + +extensions.extend(['sphinx.ext.autodoc']) +autodoc_default_flags = ['members', 'special-members'] + +_locals = {} +with open('../rumba/_version.py') as fp: + exec(fp.read(), None, _locals) +version = _locals['__version__'] + +version = version +release = version diff --git a/doc/docker.rst b/doc/docker.rst new file mode 100644 index 0000000..004240d --- /dev/null +++ b/doc/docker.rst @@ -0,0 +1,13 @@ +Docker +============= + +`Docker `_ is a container runtime +environment. + +To use the Docker testbed the Docker software needs to be installed, +see `Install Docker `_ and complete +`Post-installation steps for Linux +`_. + +.. automodule:: rumba.testbeds.dockertb + :member-order: bysource diff --git a/doc/emulab.rst b/doc/emulab.rst new file mode 100644 index 0000000..376f07d --- /dev/null +++ b/doc/emulab.rst @@ -0,0 +1,16 @@ +Emulab +============= + +`Emulab `_ is a network testbed, giving +researchers a wide range of environments in which to develop, debug, +and evaluate their systems. + +Issues have been reported that Rumba asks for the password even +though a public key was added to the emulab interface. In this case +a workaround is to start an ssh-agent and add the public key there. :: + + $ eval `ssh-agent` + $ ssh-add /home/user/.ssh/id_rsa.pub + +.. automodule:: rumba.testbeds.emulab + :member-order: bysource diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..7bbea39 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,57 @@ +==================================== +Welcome to the Rumba documentation! +==================================== + +Rumba is a Python framework that allows users to write Python scripts +to define recursive internet networks and run scripted +experiments. First, Rumba creates a physical network on one of the +selected testbed plugins. If needed, Rumba can do an installation of +the selected prototype plugin on the testbed machines. The network is +then bootstrapped on the available nodes. Users can then run a +Storyboard which emulates real network traffic. Finally, the +experiment can be swapped out of the testbed. + +This site covers Rumba's usage and API documentation. The repository +holding the code can be found `here +`_. Example scripts can be found in +the examples/ folder. + +Please report any bugs or issues `here +`_. + +Rumba is developed as part of the ARCFIRE project, funded by the +European commission under the H2020 framework. + +General usage +------------------------- + +.. toctree:: + workflow + installation + +Rumba core +------------------------- + +.. toctree:: + model + log + storyboard + utils + +Testbed plugins +------------------------- + +.. toctree:: + docker + emulab + jfed + local + qemu + +Prototype plugins +------------------------- + +.. toctree:: + irati + rlite + ouroboros diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 0000000..c2038d0 --- /dev/null +++ b/doc/installation.rst @@ -0,0 +1,21 @@ +Installation +************************ + +The easiest way to install Rumba is through pip. Rumba can be found on +the `PyPi `_ and can thus be +installed through pip. :: + + $ pip install rumba + +Rumba supports both Python 2 and 3. + +For Debian and Ubuntu, the following command will ensure that the +required dependencies are installed (replace python-dev with +python3-dev if using Python 3): :: + + $ apt-get install build-essential libssl-dev libffi-dev python-dev + +To install the latest version from source, clone the repository and +install it from the command line: :: + + $ python setup.py install diff --git a/doc/irati.rst b/doc/irati.rst new file mode 100644 index 0000000..c07feb1 --- /dev/null +++ b/doc/irati.rst @@ -0,0 +1,9 @@ +IRATI +============= + +`IRATI `_ is an open source +implementation of the RINA architecture targeted at the OS/Linux +system, initially developed by the FP7-IRATI project. + +.. automodule:: rumba.prototypes.irati + :member-order: bysource diff --git a/doc/jfed.rst b/doc/jfed.rst new file mode 100644 index 0000000..7ed9e88 --- /dev/null +++ b/doc/jfed.rst @@ -0,0 +1,30 @@ +jFed +============= + + +`jFed `_ is a Java-based framework for +testbed federation. + +In order to use the jFed testbed, a user first needs to download +his/her key from the `jFed authority +`_. +After logging in, click on *Download your certificate*. Save the +contents in a file (for example cert.pem). + +Before running Rumba you must run an SSH agent in same terminal. This +will also avoid you having to enter the passphrase for every login to +a node by the framework if you are not on an IPv6 enabled network. +(Apart from asking for the passphrase to login to the nodes, the +framework will always ask for the passphrase since it is needed by the +jFed CLI as well.) In order to start an SSH agent and to add the +certificate, type the following commands: :: + + $ eval `ssh-agent` + $ ssh-add /home/morty/cert.pem + +Pay attention to run your rumba script in the same terminal used +for the previous commands, without changing the user (e.g. using su +or sudo). + +.. automodule:: rumba.testbeds.jfed + :member-order: bysource diff --git a/doc/local.rst b/doc/local.rst new file mode 100644 index 0000000..c55a275 --- /dev/null +++ b/doc/local.rst @@ -0,0 +1,5 @@ +Local +============= + +.. automodule:: rumba.testbeds.local + :member-order: bysource diff --git a/doc/log.rst b/doc/log.rst new file mode 100644 index 0000000..6084cf2 --- /dev/null +++ b/doc/log.rst @@ -0,0 +1,5 @@ +Logging +============= + +.. automodule:: rumba.log + :member-order: bysource diff --git a/doc/model.rst b/doc/model.rst new file mode 100644 index 0000000..b487263 --- /dev/null +++ b/doc/model.rst @@ -0,0 +1,5 @@ +Model +============= + +.. automodule:: rumba.model + :member-order: bysource diff --git a/doc/ouroboros.rst b/doc/ouroboros.rst new file mode 100644 index 0000000..785bf92 --- /dev/null +++ b/doc/ouroboros.rst @@ -0,0 +1,9 @@ +Ouroboros +============= + +`Ouroboros `_ is a user-space +implementation with a focus on portability. It is written in C89 and +works on any POSIX.1-2001 enabled system. + +.. automodule:: rumba.prototypes.ouroboros + :member-order: bysource diff --git a/doc/qemu.rst b/doc/qemu.rst new file mode 100644 index 0000000..ff1ede3 --- /dev/null +++ b/doc/qemu.rst @@ -0,0 +1,13 @@ +QEMU +============= + +`QEMU `_ is a generic and open +source machine emulator and virtualizer. + +In order to use the qemu testbed, the user should install the qemu and +bridge-utils packages on which the testbed depends: :: + + $ sudo apt-get install bridge-utils qemu + +.. automodule:: rumba.testbeds.qemu + :member-order: bysource diff --git a/doc/rlite.rst b/doc/rlite.rst new file mode 100644 index 0000000..f58a16a --- /dev/null +++ b/doc/rlite.rst @@ -0,0 +1,9 @@ +rlite +============= + +`rlite `_ is a lightweight Free +and Open Source implementation of the Recursive InterNetwork +Architecture (RINA) for GNU/Linux operating systems. + +.. automodule:: rumba.prototypes.rlite + :member-order: bysource diff --git a/doc/storyboard.rst b/doc/storyboard.rst new file mode 100644 index 0000000..085ea30 --- /dev/null +++ b/doc/storyboard.rst @@ -0,0 +1,5 @@ +Storyboard +============= + +.. automodule:: rumba.storyboard + :member-order: bysource diff --git a/doc/utils.rst b/doc/utils.rst new file mode 100644 index 0000000..6df8a0c --- /dev/null +++ b/doc/utils.rst @@ -0,0 +1,13 @@ +Utils +============= + +.. autoclass:: rumba.utils.ExperimentManager + :member-order: bysource + +Example usage of the class: + +.. code-block:: python + + with ExperimentManager(exp, swap_out_strategy=PROMPT_SWAPOUT): + exp.swap_in() + exp.bootstrap_prototype() diff --git a/doc/workflow.rst b/doc/workflow.rst new file mode 100644 index 0000000..04f23b1 --- /dev/null +++ b/doc/workflow.rst @@ -0,0 +1,44 @@ +Workflow +************************ + +1. Define the network graph, creating instances of model.Node and + model.DIF classes. + +2. Create an instance of a Testbed class. + +3. Create an instance of the selected prototype.Experiment class, + passing the testbed instance and a list of Node instances. + + 1. At the end of the base Experiment constructor, the + generate function is called to generate information about + per-node IPCPs, registrations and enrollment, ready to be + used by the plugins. + +4. Call methods on the prototype.Experiment instance: + + 1. swap_in() swaps the experiment in on the testbed, and fills in + the missing information in the model. + + 2. install_prototype() installs the chosen prototype on the + testbed. Currently an Ubuntu image is assumed. + + 3. bootstrap_prototype() calls a prototype-specific setup function, + to create the required IPCPs, perform registrations, + enrollments, etc. + + 4. swap_out() swaps the experiment out of the testbed. + +5. Run a Storyboard to emulate real network traffic. + + +Accessing nodes after swap-in +----------------------------- + +To access a node once the experiment swapped in, use the following +command (in the same terminal where ssh-agent was run in case of jFed): :: + + $ rumba-access $NODE_NAME + +Where $NODE_NAME is the name of the node to access. In case of the +QEMU testbed, the password of the downloaded buildroot images is +'root'. -- cgit v1.2.3