Developer HowTo for openvim

Getting Started

Openvim is a light VIM that was born with the idea of provide underlay dataplane connectivity with a guaranteed bandwidth. The recommended Linux distribution for development is Ubuntu Sever LTS 16.04. Pycharm is a nice and easy to use tool for developing.

You can install it by: OpenVIM_installation_(Release_TWO)#Installation but usning the option "sudo ./install-openvim.sh -q --develop".

git clone https://osm.etsi.org/gerrit/osm/openvim
sudo ./scripts/install-openvim.sh --noclone --develop
# --develop option will avoid to be installed as a service, in order to run it with pycharm
# --noclone option will avoid to get sources from repository, as it is already cloned

See also and follow Workflow_with_OSM_tools#Clone_your_project

New code features must be incorporated to master:

git checkout master

Generate a ".gitignore", you can use the .gitignore-common example that skips the pycharm and eclipse files.

cp RO/.gitignore-common RO/.gitignore
#edit to include your local files to ignore

Prepare your git environment to push with a proper user/email, push to gerrit. See and configure:

Workflow_with_OSM_tools#Configure_your_Git_environment

Workflow_with_OSM_tools#Commit_changes_to_your_local_project

Workflow_with_OSM_tools#Push_your_contribution_to_Gerrit

Programming Language

The RO module uses Python2. However Python3 conventions for a possible future migration must be used. For example:

BAD Python2	OK Python2 compatible with python3
"format test string %s number %d" % (st, num)	"format test string {} number {}".format(st, num)
print a, b, c	print(a,b,c)
except Exception, e	except Exception as e
if type(x) == X:	if isinstance(x,X):

Descriptors can be YAML (prefered because more readable and allow comments) or JSON

Code Style

Please follow PEP8 style guide for all the Python code.

Logging

Use the appropriate logging levels when logging the messages. An example is shown below:

   self.logger.debug("Changing state to %s", next_state)

Logging levels (general and per module) are specified at openmanod.cfg

Try to use few useful logs, not verbose, that brings useful information. For example, in the case of failure to access the server, the complete URL should be provided.

Avoid several logs together

 WRONG:
 self.looger.debug("Entering in method A")
 self.logger.debug("Contacting server"

 RIGHT:
 self.logger.debug("method A, contacting server %s", url)

When the trace back is needed (call stack that generate the exception) , use the "exc_info=True" parameter

 self.logger.error("Exception %s when ...", exception, exc_info=True)

Exceptions

Code must be written in a way that functions and methods raise an exception when something goes wrong, instead of returning a negative or false value.

Example

 WRONG
   def get_ip_address():
       ...
       if fail:
           return False, "Fail because xxx"
       return True, ip
   
   ...
   result, ip = get_ip_address()
   if not result:
       return False, "Cannot get ip address..."

 RIGHT
   def get_ip_address():
       ...
       if fail:
           raise customException("Fail because ...")
       return ip
   
   ...
   try:
       ip = get_ip_address()
       ...
   except customException as e:
       raise customException2(str(e))

Directory Organization

(Draft) The code organized into the following high level directories:

/osm_openvim contains the openvim code. ovim.py is the main engine module in which
/test contains scripts and code for testing
/database_utils contains scripts for database creation, dumping, and migration
/scripts general scripts, as installation, execution, reporting
/scenarios examples and templates of network scnario descriptors
/ contains the entry point server openvimd and the client openvim

Openvim Architecture

(TBC)

Database changes

Database schema can be changed if needed. It is recomended to use a graphical tool (e.g. Heidy) to change database and change it back and copy the SQL commands. Follow these steps:

1. osm_openvim/ovim.py: increment '__version__', 'version_date' and 'database_version' 2. database_utils/migrate_vim_db.sh. See the three "TODO" 2a. Increment LAST_DB_VERSION 2b. Annotate comments to have a track of versions: [ $OPENVIM_VER_NUM -ge VSSS ] && DATABASE_TARGET_VER_NUM=DD #0.V.SS => DD 3c. Generate new methods like function upgrade_to_XX() and function downgrade_from_XX. Insert here the sql commands. Last SQL command over the schema_version is quite important to detect the database version.

Test several upgrades/downgrades to version 15 with "migrate_vim_db.sh" and "migrate_vim_db.sh 15"

CLI client

The openvim code contains a python CLI (openvim) that allows friendly command execution. This CLI client can run on a separate machine where openvimd server is running. "openvim config" indicates the server's deployment address/location (by default localhost).

Northbound Interface

openvim uses a REST API with YAML/JSON content. TBC

Running Unit Tests

Launching openvim

Openvim can run as systemd service. (Can be installed with ./scripts/install-openvim-service.sh -f openvim)

Or can be run inside a screen (the preferred method for developers). The script to easily launch/remove is ./scripts/service-openvim.sh. Execute with -h to see options

Tests

TBC

Creating a new SDN plugin

(DRAFT)

Openvim installs openflow pro-active rules for the known ports that must be connected among them. The port contains the information of physical port switch, mac address (if known), and VLAN tag (if any). It creates both E-LINE (two ports, mac is not used) or E-LAN (several ports, mac is used for compute destination).

The openflow rules are computed at file openflow_thread.py method. Each openflow rule is added/removed using a plugin that interacts with the concrete SDN controller. Current available plugins are ODL.py (for opendaylight), onos.py (for ONOS), floodlight.py (for floodlight). All of them create a class OF_conn derived from base class OpenflowConn (using the file openflow_conn.py).

Creating a new SDN plugin is quite easy following these steps: update_of_flows. This method gets different ports that the network must connect with it.

Create a new osm_openvim/<name>.py file (copy ODL.py or onos.py). Choose an appropriate name that will be used at SDN-create command with the optinio --<name>. Another example is the file “openvim/floodlight.py” but this is a bit more complicated because it contains extra code for auto-detecting the floodlight version 2.
Rewrite the content of the functions, but not modify the class and functions names.
Firstly test it with the osm_openvim/openflow tool. Execute "./openflow config" to see the needed variables that need to be defined at the operating system. It is a convenient to create a script to be run with source to set up this variable or put in the .bashrc. Put the right values for the ip; port, etc depending on your environment. For OF_CONTROLLER_TYPE put "<name>". At this step the OPENVIM_* variables can be ignored.
Test your file with this tool meanwhile you modify the functions. Follow these steps:
1. Make "__init__": use 'vim.OF.<name>' at logging.getLogger. Ignore user/password if not needed.
2. Make "get_of_switches" and test with "openflow switches"
3. Make "obtain_port_correspondence" and test with "openflow port-list"
4. Make "get_of_rules" and test with “openflow list --no-translate” and “openflow list”
5. Make "new_flow" and test with "openflow add <rule-name> …" and ensure is really inserted with "openflow list"
6. Make "del_flow" and test with "openflow delete <rule-name>"
7. Make "clear_all_flows" and test with "openflow clear"
Run the automatic test "test/test_openflow.sh"
Test with openvim with fake compute nodes and a real openflow controller
1. Add a new SDN controller. Modify the "openvim/openvimd.cfg" with "mode: OF only" and the proper values for "of_***" (e.g. “of_controller: <name>”)
2. In order to put the right switch port names where the NIC interfaces of the fake compute hosts are connected to, we can do one of the two options:
  1. (Suggested): Modify the value of "switch_port" and "switch_dpid" at every fake compute nodes descriptors at "/test/hosts/host-example?.json" and insert real values
  2. or : Modify the file "openvim/database_utils/of_ports_pci_correspondence.sql" and change the names 'port?/?' by valid names obtained with "openflow port-list" (the physical port names)
3. Run the script (To be completed) for testing. Openfloe rules must appear at the openflow controller, and all the networks must be ACTIVE (not ERROR) (see with "openvim net-list")