Documentation

Project Information Documentation

• Project Proposal
• IETF Drafts
• Presentations
• Mature Project Proposal

Requirements

Release Planning

Backlog

• SFC Backlog

SFC Sonar

Sonar is a static analysis tool that finds bugs and provides suggestions on how to make the code cleaner.

SFC Master Sonar

SFC TASKS

We are now (as of March 13, 2015) using Trello to track and monitor tasks.

SFC organization Trello boards

SFC Oxygen Trello board

SFC Carbon Trello board

SFC Lithium Trello board

Previous SFC Project Task Lists

SFC Installation and Testing Guide

If you want to install Ubuntu (VirtualBox) and SFC from scratch there is a guide for you:

SFC Installation and Testing Guide

Different SFC Distributions

Lithium and previous versions are no longer supported.

ODL Beryllium SR1, SFC distro

ODL Beryllium SR4, complete distro

ODL Boron SR1, complete distro

ODL Carbon Master, SFC distro

Using the distribution

$ bin/karaf
(log files located in data/log/karaf.log)

Cleaning the distribution data store from previous executions:

$ rm -rf journals snapshots
$ bin/karaf clean

The SFC Configuration in a nutshell

This is an overview of the main parts of the SFC configuration:

1. Service Functions (SFs)
   1. Service Function Type (Firewall, NAT, DPI, etc) AKA SFtype
   2. Transport details (VLAN, VxLAN, etc)
   3. IP (port if VxLAN)
   4. NSH-aware
2. Service Function Forwarders (SFFs)
   1. Transport details (VLAN, VxLAN, MPLS, etc)
   2. IP (port if VxLAN)
   3. list of SFs connected to this SFF
   4. Optionally the OVS bridge to reside on
3. Service Function Chain (SFC), Abstract, ordered list of Service Function Types.
   1. Ej [DPI, NAT, FW]
4. Service Function Path (SFP) Specify concrete details about an SFC
   1. Mandatory info: reference to an SFC, transport details to use (VxLAN, etc)
   2. Optional info: concrete details about which SFs, SFFs to use (this is usually not used)
5. Rendered Service Path (RSP), This is the actual Service Chain
   1. Reference to an SFP
   2. isSymnetric (if so, an uplink and a downlink RSP will be created)
   3. If no concrete SFs/SFFs specified in SFP, then internally the ODL-SFC will figure out the SFs/SFFs to use

Building SFC

This is the recommended way to use SFC.

Useful links, if this is your first time using OpenDaylight:

• https://wiki.opendaylight.org/view/GettingStarted:Development_Environment_Setup
• https://wiki.opendaylight.org/view/GettingStarted:Pulling,_Hacking,_and_Pushing_All_the_Code_from_the_CLI
• https://wiki.opendaylight.org/view/OpenDaylight_Controller:Gerrit_Setup
• Installing Oracle Java 8 on Ubuntu

1. Clone the git repository: (ODL GIT Cheat Sheet)

Master

git clone https://git.opendaylight.org/gerrit/p/sfc.git (master)
  -- OR --
git clone ssh://<username>@git.opendaylight.org:29418/sfc.git

Lithium

git clone https://git.opendaylight.org/gerrit/p/sfc.git  --branch stable/lithium --single-branch sfc-lithium 
-- OR --
git clone ssh://<username>@git.opendaylight.org:29418/sfc.git --branch stable/lithium --single-branch sfc-lithium

1. setup your local settings.xml file

cp -n ~/.m2/settings.xml{,.orig}

If the command above fails it is okay. It means you do not have a settings.xml, probably it is 
the first time you are trying to use ODL.

wget -q -O - https://raw.githubusercontent.com/opendaylight/odlparent/master/settings.xml > ~/.m2/settings.xml

1. export MAVEN_OPTS="-Xmx1024m"
2. export M3_HOME=/usr/share/apache-maven-3.3.9 (or whatever your path to maven is)
3. export M3=$M3_HOME/bin
4. mvn clean install –DskipTests
5. Run SFC: ./sfc-karaf/target/assembly/bin/karaf

At this point you can try the RESTConf API (http://localhost:8181/apidoc/explorer/index.html) explorer or UI (http://localhost:8181/index.html)

These are the reasons I do _not_ suggest you install and test SFC with the Karaf regular distribution:

• If you download the regular release you will not get the latest bug fixes
• If you download the regular release you will need to install features, and debug other start-up issues. This is generic problem with ODL karaf that it is not worth discussing here.
• You will not get the SFC-UI ready to go. I strongly recommend using the SFC-UI.

Using Git in ODL SFC

 # Getting started
 create a gerrit user account
 setup an ssh key
 sudo apt-get install git-review
 # More git review details: https://www.mediawiki.org/wiki/Gerrit/git-review

 git clone ssh://<username>@git.opendaylight.org:29418/sfc.git
 scp -p -P 29418 <username>@git.opendaylight.org:hooks/commit-msg .git/hooks/;chmod 755 .git/hooks/commit-msg;

 # Normal steps to create and commit changes from a topic branch
 git checkout -b topic/your_topic_branch
 <... Modify the code ...>
 git add <the modified files>
 git commit --signoff
 git review # This will provide the Gerrit link

 # Rebasing a topic branch with master
 git checkout master
 git pull --rebase
 git checkout topic/your_topic_branch
 git rebase origin/master

 # Add a patch-set to an existing commit
 git checkout topic/your_topic_branch
 <... Modify the code ..>
 git add <the modified files>
 git commit --amend
 git review # This will provide the Gerrit link

Working with the SFC Documentation

SFC User and Developer Guides

To build the documents, you will need python and the tox packages installed.

• Download the ODL documentation git repo

git clone https://git.opendaylight.org/gerrit/p/docs.git

• Update the doc submodules and build them

cd docs
git submodule update --init
cd ..
tox -e docs

• You can read the documentation using your preferred browser, and opening these files:
  • User Guide: file:///<path to ODL docs repo>/docs/_build/html/user-guide/service-function-chaining.html
  • Development Guide: file:///<path to ODL docs repo>/docs/_build/html/developer-guide/service-function-chaining.html

SFC Project documents

Since Carbon the SFC project generates project specific documentation in the docs directory. Is is use currently to publish the Specification document for every new feature added. These documents are stored within the docs folder.

• To build the SFC project documentation

cd docs
tox

The generated documentation site can be found inside the _build folder.

Building Open vSwitch with VxLAN-GPE and NSH support

Network Service Headers (NSH) is a fundamental Service Chaining encapsulation protocol for Service Function Chaining. NSH is now officially supported in OVS 2.9, which can be used with ODL Fluorine. Below are instructions to install standard OVS 2.9: (Should be installed on at least Ubuntu 16.04)

apt-get update
apt-get install -y autoconf libtool git dh-autoreconf dh-systemd software-properties-common python-software-properties \
       libssl-dev openssl build-essential fakeroot linux-image-extra-$(uname -r) graphviz python-all python-qt4 \
       python-twisted-conch dkms upstart

git clone https://github.com/openvswitch/ovs.git
cd ovs
git checkout -b ovs2.9.2 v2.9.2
sudo DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary
cd ..
mkdir -p /vagrant/ovs_debs
cp ./libopenvswitch_*.deb ./openvswitch-common*.deb ./openvswitch-switch*.deb /vagrant/ovs_debs/
sudo dpkg -i ./libopenvswitch_*.deb ./openvswitch-datapath-dkms* ./openvswitch-common* ./openvswitch-switch* ./python-openvswitch*

service openvswitch-switch restart

For ODL versions prior to Fluorine (Oxygen, Nitrogen, and Carbon), a branched version of OVS 2.6 with support for NSH and VxLAN-GPE has been prepared by Yi Yang from Intel. Below are instructions to install OVS with NSH on Ubuntu 16.04.

sudo apt-get update
sudo apt-get install git wget
mkdir -p <preferredInstallDir>/ovs
cd <preferredInstallDir>/ovs
wget https://raw.githubusercontent.com/yyang13/ovs_nsh_patches/master/start-ovs-deb-2.6.1.sh
chmod 755 start-ovs-deb-2.6.1.sh
./start-ovs-deb-2.6.1.sh

Shielding yourself from Controller build breaks

Controller build and functionality breaks are unpredictable and happen all the time. If you have a working personal clone/sandbox I suggest you to use offline builds so that new artifacts are not downloaded, unless you actually have a reason to need the new artifacts.

I consulted Thanh and he gave this suggestion:

A good way to do this is by using what's called an offline build with Maven by passing the 
parameter (-o). For example:

    mvn clean install -o

With  this method Maven will not even attempt to check online for new artifacts. However for this to 
work you must already have all the artifacts you need to build available in your Maven Local repo. A 
good way to prime your repo for offline builds is to use the dependency plugin's "go-offline" goal. 
For example:

    mvn dependency:go-offline

Or you you can just run a regular build successfully once and use offline mode after that.

Testing SFC

Testing locally

There are many cases for both unit test and integration test.

• Unit Test

Unit test cased are distributed into each component. Once the source codes are downloaded, the cases can be found in the folder

 <sfc-repo>/<component>/src/test

1. Run unit tests: mvn test
2. Run unit tests for one module: cd <module> && mvn test

If there are some cases failed, the console will show the detail of the failure.

• Integration tests

Please refer the link https://wiki.opendaylight.org/view/CrossProject:Integration_Group:Download_and_Run_System_Test to run integration tests.

If you just want to run integration tests for SFC, you can use the following commands to do so:

1. pybot -v CONTROLLER:127.0.0.1 -v MININET:127.0.0.1 -v USER_HOME:$HOME -v MININET_USER:$USER $HOME/integration/test/csit/suites/sfc/

Note that the SFC controller is running and mininet is installed in the system.

Testing on Gerrit

It is possible to run verifying jobs using Jenkins on every patch you rise to test everything is correct before merging the patch, those test are known as CSIT. This can be done by clicking the Gerrit's "reply..." button and typing one of the following keywords as any other comment:

• test-sfc-basic (it will launch sfc-rest-basic.txt test suite)
• test-sfc-full (it will launch sfc-full-deploy.txt test suite)

You can see an example of "test-sfc-full" usage in:

• [0] https://git.opendaylight.org/gerrit/#/c/53465/

SFC demos and Hackathon Documents

SFC 101 - deprecated

SFC 102 - deprecated

SFC 103 - currently stable

SFC 104 - BETA, being improved

Hackathon Guide

ODL Summit 2015 Presentation

SFC Configuration Files (Deprecated in Lithium)

You can use the SFC start-up configuration file feature. SFC allows you to create your own start-up configuration files that are loaded when SFC is started. Therefore testing and recovery is very easy. The bootstrap configuration files are found in the directory below. Feel free to modify them for your deployment.

repenno$ ls sfc-jsonconfig/src/main/resources/bootstrap/

 service-function-chains.json

 service-functions.json

 service-function-forwarders.json

 service-nodes.json

SFC UI

After running SFC distribution you can access the SFC-UI at http://localhost:8181/sfc/index.html

SFC VXLAN-GPE push/pop OpenFlow proposal

SFC VXLAN-GPE push/pop OpenFlow proposal

Meetings

Meeting minutes are now sent to the sfc-dev mailing list.

Past Meeting Minutes

Release Notes