rumba: Add Rumba documentation website

This adds a documentation website for Rumba which is triggered
automatically after changes to master.

16 files changed, 295 insertions, 0 deletions

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 <https://www.docker.com/>`_ is a container runtime
+environment.
+
+To use the Docker testbed the Docker software needs to be installed,
+see `Install Docker <https://docs.docker.com/install/>`_ and complete
+`Post-installation steps for Linux
+<https://docs.docker.com/install/linux/linux-postinstall/>`_.
+
+.. 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 <https://www.emulab.net/>`_ 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
+<https://gitlab.com/arcfire/rumba>`_. Example scripts can be found in
+the examples/ folder.
+
+Please report any bugs or issues `here
+<https://gitlab.com/arcfire/rumba/issues>`_.
+
+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 <https://pypi.python.org/pypi/Rumba>`_ 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 <https://github.com/IRATI/stack>`_ 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 <http://jfed.iminds.be/>`_ 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
+<https://authority.ilabt.iminds.be/](https://authority.ilabt.iminds.be/>`_.
+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 <https://ouroboros.ilabt.imec.be/>`_ 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 <http://wiki.qemu-project.org/Main_Page>`_ 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 <https://github.com/vmaffione/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'.