Documentation
Project Information Documentation
Requirements
Release Planning
Release | Release Plan | Release Notes | Release Review | Miscellaneous |
---|---|---|---|---|
Helium | Release Plan | Release Notes | Release Review | |
Lithium | Release Plan | Release Notes | Release Review | Lithium User Facing Features |
Beryllium | Release Plan | Release Notes | Release Review | Beryllium Feature Integration System Test |
Boron | Release Plan | Release Notes | Release Review | Boron System Test |
Carbon | Release Plan | Release Notes | ||
Nitrogen | Release Plan | Release Notes | ||
Oxygen | Release Plan | Release Notes | SFC Oxygen Release Details | |
Fluorine | Release Plan | Release Notes | SFC joining Managed Release | |
Neon | Release Plan | |||
Sodium | Release Plan |
Backlog
SFC Sonar
Sonar is a static analysis tool that finds bugs and provides suggestions on how to make the code cleaner.
SFC TASKS
We are now (as of March 13, 2015) using Trello to track and monitor tasks.
SFC organization Trello boards
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 SR4, complete distro
ODL Boron SR1, complete 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:
- Service Functions (SFs)
- Service Function Type (Firewall, NAT, DPI, etc) AKA SFtype
- Transport details (VLAN, VxLAN, etc)
- IP (port if VxLAN)
- NSH-aware
- Service Function Forwarders (SFFs)
- Transport details (VLAN, VxLAN, MPLS, etc)
- IP (port if VxLAN)
- list of SFs connected to this SFF
- Optionally the OVS bridge to reside on
- Service Function Chain (SFC), Abstract, ordered list of Service Function Types.
- Ej [DPI, NAT, FW]
- Service Function Path (SFP) Specify concrete details about an SFC
- Mandatory info: reference to an SFC, transport details to use (VxLAN, etc)
- Optional info: concrete details about which SFs, SFFs to use (this is usually not used)
- Rendered Service Path (RSP), This is the actual Service Chain
- Reference to an SFP
- isSymnetric (if so, an uplink and a downlink RSP will be created)
- 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
- 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
- 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
- export MAVEN_OPTS="-Xmx1024m"
- export M3_HOME=/usr/share/apache-maven-3.3.9 (or whatever your path to maven is)
- export M3=$M3_HOME/bin
- mvn clean install –DskipTests
- 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
- Run unit tests: mvn test
- 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:
- 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:
SFC demos and Hackathon Documents
SFC 104 - BETA, being improved
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.