OpenBACH-extra is a tool-box for OpenBACH that contains a set of additional tools that are described in this page.
openbach-extra/ ├── external_jobs/ ├── executors/ -> scripts ready to be launched from CLI: allow to run scenarios or create scenario JSONs (to be imported in the OpenBACH web interface). | ├── reference/ -> executors maintained by the OpenBACH Team | └── examples/ -> other examples of executors └── apis/ ├── data_access/ ├── auditorium_scripts/ └── scenario_builder/ ├── helpers/ -> predefined blocks of openbach functions that can be imported in scenarios. └── scenarios/ -> reference scenarios to be imported in your scenarios.
OpenBACH-extra is stored on the forge.
Cloning OpenBACH-extra on a machine can help manage multiple OpenBACH platforms.
Some jobs are installed by default on an OpenBACH platform.
The external jobs of the OpenBACH-extra project are a set of jobs that must be added to an OpenBACH controller for being used on a specific OpenBACH plateform.
This can be done through:
The executors allow you to straightforward launch scenarios from CLI or import the JSON (thanks to auditorium-scripts API). Their name should begin with executor_ (for example executor_network_delay.py).
A simple usage of the executors is described in the Simple Command Line Interface User Manual.
Three tools are available in the API:
The tools and scripts that can be found in the folders of the executors and the API can be used to pilot different OpenBACH platforms.
To use them, the OpenBACH API should be installed as follows on a machine that has access to the OpenBACH platforms it wishes to pilot.
The three tools of the OpenBACH API (scenario builder, auditorium-scripts and data-access) are part of the OpenBACH-API repository and are installed by default on the agents of any OpenBACH platform. You can also install them manually on other machines by cloning the openbach-extra repository and using the setup.py
file:
$ sudo apt-get install python3-setuptools python3-dev build-essential $ git clone https://forge.net4sat.org/openbach/openbach-extra.git $ cd openbach-extra/apis/ $ sudo python3 setup.py install
Or using pip
and asking it to install the openbach-api following wheel.
$ pip3 install https://forge.net4sat.org/openbach/openbach/raw/master/pip_mirror/python3/openbach_api-3.x.x-py3-none-any.whl
When developing new scenarios and helpers, you may want to install your latest version of the API to conduct your tests. Using python3 setup.py install
to deploy your version as suggested previously may or may not work depending on your configuration. Here are some tips to get you going:
pip
will take priority over the same package installed by setup.py
; so if you’re testing on an agent, you may want to pip uninstall openbach-api
before running python3 setup.py install
;PYTHONPATH
environment variable (e.g. PYTHONPATH=~/openbach-extra/apis/ python3 executor_network_delay.py –arguments… run
);python setup.py install
within it to always access your last version when testing (and deactivate it when done).Once your scenarios/helpers are finished and ready to be committed, you should then modify the version argument (e.g. version='3.1.4') in your setup.py, and commit/push the new scenarios/helpers as well as the setup.py.
This procedure is also recommended when you want to be sure that you are using the last version of the scenarios/helpers.
Each command must be run using Python 3 and understand the -h
flag to display the expected arguments. On top of the positional and optional arguments that are unique for each command, all have the following arguments needed by the controller:
controller
: the address of the controller to run the command on;login
or username
: the name to use to connect as on the controller. If this option is provided, the associated password will be asked on the command line when running the command. By default, the username and the password are “openbach”.Instead of arguments, you can pass these information by means of a file. For that, it is necessary to create a JSON file named “controller” (in the folder you will be running scripts from) with the controller ip, your login and your password, as follows:
{ "controller": "192.168.1.3", "login": "openbach", "password": "openbach" }
In case you don't specify a password, neither on the command-line nor in the controller
file, an echo-less prompt will ask it once you run the script.
To ease the use of the auditorium scripts with different OpenBACH platforms, it can be better to keep a separate “scripting” directory that will host the “controller” file as well. To use the API scripts, the PATH variable can be changed (in .bashrc for instance or in a particular script):
$ export PATH=$PATH:~/openbach-extra/apis/
This way, the commands can be used in any directories. The controller file is searched in the local directory where your program is launched.
Do not forget the PYTHONPATH variable either in case you didn't install the API system-wide using `setup.py`. To be able to import the `auditorium_scripts` module from the various scripts, you can:
$ export PYTHONPATH=$PYTHONPATH:~/openbach-extra/apis/
The auditorium scripts make use of a tool that understand the HTTP_PROXY
and HTTPS_PROXY
environment variables. If your platform is not accessible through your configured proxy (e.g. it is in an internal network), you can deactivate it by temporarily setting the HTTP_PROXY
variable to “”
:
$ cd ~/auditorium-scripts $ HTTP_PROXY="" ./list_projects.py --controller 192.168.1.3 --login openbach