Merge "moving developers-guide to developer-guide for consistency"

[docs.git] / manuals / developer-guide / src / main / asciidoc / ovsdb.adoc

== OVSDB Integration\r
The Open vSwitch database (OVSDB) Plugin component for OpenDaylight implements the OVSDB  https://tools.ietf.org/html/rfc7047[RFC 7047] management protocol that allows the southbound configuration of vSwitches. The component comprises a library and various plugin usages.\r
The OVSDB protocol uses JSON/RPC calls to manipulate a physical or virtual switch that has OVSDB attached to it. Almost all vendors support OVSDB on various hardware platforms. The OpenDaylight controller uses the native OVSDB implementation to manipulate the Open vSwitch database. \r
\r
NOTE: Read the OVSDB User Guide before you begin development.\r
\r
=== OpenDaylight OVSDB integration\r
\r
For information on how the GRE-endpoint destination IP address is communicated to the controller, see https://docs.google.com/presentation/d/19ua9U6nFJSO0wtenWmJUEzUFmib8ClTkkHTgZ_BvaMk/edit?pli=1#slide=id.g17727178e_180[Neutron and ODL interactions].\r
\r
The OpenStack integration architecture uses the following technologies: +\r
\r
* https://tools.ietf.org/html/rfc7047[RFC 7047] and http://datatracker.ietf.org/doc/rfc7047/[The Open vSwitch Database Management Protocol]\r
* OpenFlow v1.3\r
* OpenStack Neutron ML2 Plugin\r
\r
==== Getting the code\r
----\r
export ODL_USERNAME=<username for the account you created at OpenDaylight>\r
git clone ssh://${ODL_USERNAME}@git.opendaylight.org:29418/ovsdb.git;(cd ovsdb; scp -p -P 29418 ${ODL_USERNAME}@git.opendaylight.org:hooks/commit-msg .git/hooks/;chmod 755 .git/hooks/commit-msg;git config remote.origin.push HEAD:refs/for/master)\r
----\r
\r
==== OpenDaylight Mechanism Driver for Openstack Neutron ML2\r
This code is a part of OpenStack and is available at: https://github.com/openstack/neutron/blob/master/neutron/plugins/ml2/drivers/mechanism_odl.py\r
\r
To make changes to this code, please read about https://wiki.openstack.org/wiki/NeutronDevelopment[Neutron Development].\r
\r
Before submitting the code, run the following tests: +\r
----\r
tox -e py27\r
tox -e pep8\r
----\r
==== Importing the code in to Eclipse or IntelliJ\r
Check out either of the following: +\r
\r
* https://wiki.opendaylight.org/view/Eclipse_Setup[Getting started with Eclipse]\r
* https://wiki.opendaylight.org/view/OpenDaylight_Controller:Developing_With_Intellij[Developing with Intellij]\r
\r
.Avoid conflicting project names\r
image::OVSDB_Eclipse.png[]\r
\r
* To ensure that a project in Eclipse does not have a conflicting name in the workspace, select Advanced > Name Template > [groupId].[artifactId] when importing the project.\r
\r
==== Browsing the code\r
The code is mirrored to https://github.com/opendaylight/ovsdb[GitHub] to make reading code online easier. \r
\r
==== Source code organization\r
\r
The OVSDB project generates 3 x Karaf Modules:\r
\r
    ovsdb  -- all ovsdb related artifacts\r
    of-nxm-extensions  -- openflow nxm extensions\r
    ovs-sfc  -- openflow service chainning function\r
\r
Both of-nxm-extensions and ovs-sfc are expected to be moved out of the ovsdb source tree in the future.\r
\r
Following are a brief descriptions on directories you will find a the root ovsdb/ directory:\r
\r
* _commons_ contains the parent POM file for Maven project which is used to get consistency of settings across the project. \r
\r
* _distribution_ contains the OVSDB distribution. For OSGI, this is the latest Virtualization Edition pulled from the Integration project with your local OVSDB artifacts added. This gives developers the ability to run the controller for testing. \r
For Karaf, this is the latest Karaf bundle pulled from the Integration project, with your local OVSDB Karaf bundles mentioned above.\r
\r
* _openstack_ contains the northbound handlers for Neutron used by OVSDB, as well as their providers.\r
\r
* _resources_ contains useful scripts, How-To's and other resources.\r
\r
* _schemas_ contains the OVSDB schemas that are implemented in ODL.\r
\r
* _utils_ contains helper functions used for handling MD-SAL OpenFlow implementation.\r
\r
=== Building and running OVSDB\r
*Prerequisites* +\r
\r
* JDK 1.7+\r
* Maven 3+\r
\r
[[ovsdbBuildSteps]]\r
==== Building a Karaf feature and deploying it in an Opendaylight Karaf distribution +\r
This is a new method for Opendaylight distribution wherein there are no defined editions such \r
as Base, Virtualization, or SP editions.  The end-customer can choose to deploy the required feature based on user deployment needs.\r
\r
. From the root ovsdb/ directory, run *mvn clean install*.\r
. Unzip the distribution-karaf-<VERSION_NUMBER>-SNAPSHOT.zip file created from step 1 in the directory ovsdb/distribution/opendaylight-karaf/target:\r
----\r
unzip distribution-karaf-<VERSION_NUMBER>-SNAPSHOT.zip\r
----\r
==== Downloading OVSDB's Karaf distribution +\r
Instead of building, you can download the latest OVSDB distribution from the Nexus server. The link for that is:\r
----\r
http://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/ovsdb/distribution.ovsdb/1.2.0-SNAPSHOT/\r
----\r
\r
==== Running Karaf feature from OVSDB's Karaf distribution +\r
\r
[[ovsdbStartingOdl]]\r
. Start ODL, from the unzipped directory\r
----\r
bin/karaf\r
----\r
. Once karaf has started, and you see the Opendaylight ascii art in the console, the last step is to start the OVSDB plugin framework with the following command in the karaf console: \r
----\r
feature:install odl-ovsdb-openstack\r
----\r
\r
For ovsdb northbound, you will also need to invoke\r
----\r
feature:install odl-ovsdb-northbound\r
----\r
===== Sample output from the Karaf console\r
----\r
opendaylight-user@root>feature:list | grep -i ovsdb \r
odl-ovsdb-all                    | 1.0.0-SNAPSHOT      |           | ovsdb-1.0.0-SNAPSHOT        \r
OpenDaylight :: OVSDB :: all \r
odl-ovsdb-library                | 1.0.0-SNAPSHOT      | x         | ovsdb-1.0.0-SNAPSHOT        \r
OVSDB :: Library \r
odl-ovsdb-schema-openvswitch     | 1.0.0-SNAPSHOT      | x         | ovsdb-1.0.0-SNAPSHOT        \r
OVSDB :: Schema :: Open_vSwitch \r
odl-ovsdb-schema-hardwarevtep    | 1.0.0-SNAPSHOT      | x         | ovsdb-1.0.0-SNAPSHOT        \r
OVSDB :: Schema :: hardware_vtep\r
odl-ovsdb-plugin                 | 1.0.0-SNAPSHOT      | x         | ovsdb-1.0.0-SNAPSHOT        \r
OpenDaylight :: OVSDB :: Plugin\r
odl-ovsdb-northbound             | 0.6.0-SNAPSHOT      |           | ovsdb-1.0.0-SNAPSHOT        \r
OpenDaylight :: OVSDB :: Northbound \r
odl-ovsdb-openstack              | 1.0.0-SNAPSHOT      | x         | ovsdb-1.0.0-SNAPSHOT        \r
OpenDaylight :: OVSDB :: OpenStack Network Virtual \r
odl-ovsdb-ovssfc                 | 0.0.1-SNAPSHOT      |           | ovsdb-0.0.1-SNAPSHOT        \r
OpenDaylight :: OVSDB :: OVS Service Function Chai\r
odl-openflow-nxm-extensions      | 0.0.3-SNAPSHOT      | x         | ovsdb-0.0.3-SNAPSHOT        \r
OpenDaylight :: Openflow :: Nicira Extensions\r
----\r
\r
==== Testing patches\r
It is recommended that you test your patches locally before submission.\r
 \r
==== Neutron integration\r
To test patches to the Neutron integration, you need a http://devstack.org/guides/multinode-lab.html[Multi-Node Devstack Setup]. The ``resources`` folder contains sample ``local.conf`` files.\r
\r
==== Open vSwitch\r
To test patches to the library, you will need a working http://openvswitch.org/[Open vSwitch]. Packages are available for most Linux distributions. If you would like to run multiple versions of Open vSwitch for testing you can use https://github.com/dave-tucker/docker-ovs[docker-ovs] to run Open vSwitch in https://www.docker.com/[Docker] containers. \r
\r
==== Mininet\r
http://mininet.org/[Mininet] is another useful resource for testing patches. Mininet creates multiple Open vSwitches connected in a configurable topology. \r
\r
==== Vagrant\r
\r
The Vagrant file in the root of the OVSDB source code provides an easy way to create VMs for tests. \r
\r
* To install Vagrant on your machine, follow the steps at: https://docs.vagrantup.com/v2/installation/[Installing Vagrant].\r
\r
*Testing with Devstack*\r
\r
. Start the controller.\r
----\r
vagrant up devstack-control\r
vagrant ssh devstack-control\r
cd devstack\r
./stack.sh\r
----\r
[start=2]\r
. Run the following:\r
----\r
vagrant up devstack-compute-1\r
vagrant ssh devstack-compute-1\r
cd devstack\r
./stack.sh\r
----\r
[start=3]\r
. To start testing, create a new VM.\r
----\r
nova boot --flavor m1.tiny --image $(nova image-list | grep 'cirros-0.3.1-x86_64-uec\s' | awk '{print $2}') --nic net-id=$(neutron net-list | grep private | awk '{print $2}') test\r
----\r
To create three, use the following:\r
----\r
nova boot --flavor m1.tiny --image $(nova image-list | grep 'cirros-0.3.1-x86_64-uec\s' | awk '{print $2}') --nic net-id=$(neutron net-list | grep private | awk '{print $2}') --num-instances 3 test\r
----\r
[start=4]\r
.To get a mininet installation for testing:\r
----\r
vagrant up mininet\r
vagrant ssh mininet\r
----\r
[start=5]\r
. Use the following to clean up when finished:\r
----\r
vagrant destroy\r
----\r
\r
=== OVSDB integration design\r
==== Resources\r
See the following: +\r
\r
* http://networkheresy.com/2012/09/15/remembering-the-management-plane/[Network Heresy]\r
\r
See the OVSDB YouTube Channel for getting started videos and other tutorials: +\r
\r
* http://www.youtube.com/channel/UCMYntfZ255XGgYFrxCNcAzA[ODL OVSDB Youtube Channel]\r
* https://wiki.opendaylight.org/view/OVSDB_Integration:Mininet_OVSDB_Tutorial[Mininet OVSDB Tutorial]\r
\r
=== OpenDaylight OVSDB southbound plugin architecture and design\r
OpenVSwitch (OVS) is generally accepted as the unofficial standard for Virtual Switching in the Open hypervisor based solutions. Every other Virtual Switch implementation, properietery or otherwise, uses OVS in some form.\r
For information on OVS, see http://openvswitch.org/[Open vSwitch].\r
\r
In Software Defined Networking (SDN), controllers and applications interact using two channels: OpenFlow and OVSDB. OpenFlow addresses the forwarding-side of the OVS functionality. OVSDB, on the other hand, addresses the management-plane. \r
A simple and concise overview of Open Virtual Switch Database(OVSDB) is available at: http://networkstatic.net/getting-started-ovsdb/\r
\r
==== Overview of OpenDaylight Controller architecture\r
The OpenDaylight controller platform is designed as a highly modular and plugin based middleware that serves various network applications in a variety of use-cases. The modularity is achieved through the Java OSGi framework. The controller consists of many Java OSGi bundles that work together to provide the required\r
 controller functionalities. \r
 \r
The bundles can be placed in the following broad categories: +\r
\r
* Network Service Functional Modules (Examples: Topology Manager, Inventory Manager, Forwarding Rules Manager,and others) \r
* NorthBound API Modules (Examples: Topology APIs, Bridge Domain APIs, Neutron APIs, Connection Manager APIs, and others) \r
* Service Abstraction Layer(SAL)- (Inventory Services, DataPath Services, Topology Services, Network Config, and others) \r
* SouthBound Plugins (OpenFlow Plugin, OVSDB Plugin, OpenDove Plugin, and others) \r
* Application Modules (Simple Forwarding, Load Balancer)\r
\r
Each layer of the Controller architecture performs specified tasks, and hence aids in modularity. \r
While the Northbound API layer addresses all the REST-Based application needs, the SAL layer takes care of abstracting the SouthBound plugin protocol specifics from the Network Service functions. \r
 \r
Each of the SouthBound Plugins serves a different purpose, with some overlapping.\r
For example, the OpenFlow plugin might serve the Data-Plane needs of an OVS element, while the OVSDB plugin can serve the management plane needs of the same OVS element.\r
As the Openflow Plugin talks OpenFlow protocol with the OVS element, the OVSDB plugin will use OVSDB schema over JSON-RPC transport.\r
\r
=== OVSDB southbound plugin\r
The http://tools.ietf.org/html/draft-pfaff-ovsdb-proto-02[Open vSwitch Database Management Protocol-draft-02] and http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf[Open vSwitch Manual] provide theoretical information about OVSDB.\r
The OVSDB protocol draft is generic enough to lay the groundwork on Wire Protocol and Database Operations, and the OVS Manual currently covers 13 tables leaving space for future OVS expansion, and vendor expansions on proprietary implementations.\r
The OVSDB Protocol is a database records transport protocol using JSON RPC1.0. For information on the protocol structure, see http://networkstatic.net/getting-started-ovsdb/[Getting Started with OVSDB].\r
The OpenDaylight OVSDB southbound plugin consists of one or more OSGi bundles addressing the following services or functionalities: +\r
\r
* Connection Service - Based on Netty \r
* Network Configuration Service \r
* Bidirectional JSON-RPC Library \r
* OVSDB Schema definitions and Object mappers \r
* Overlay Tunnel management \r
* OVSDB to OpenFlow plugin mapping service \r
* Inventory Service \r
\r
=== Connection service\r
One of the primary services that most southbound plugins provide to SAL in Opendaylight and NSF is Connection Service. The service provides protocol specific connectivity to network elements, and supports the connectivity management services as specified by the OpenDaylight Connection Manager. \r
The connectivity services include: +\r
\r
* Connection to a specified element given IP-address, L4-port, and other connectivity options (such as authentication,...) \r
* Disconnection from an element \r
* Handling Cluster Mode change notifications to support the OpenDaylight Clustering/High-Availability feature \r
\r
By default, the ovsdb-server process running on the hypervisor listens on TCP port 6632 (This is configurable.). The Connection Service takes the connectivity parameters from the connection manager, including the IP-address and TCP-Port for connections. Owing to the many benefits it provides, Connection Service will use the Netty framework (http://netty.io/) for connectivity purposes. \r
Every successful connection to a network element will result in a Node object (Refer to OpenDaylight SAL Node.java) with the type = "OVSDB" and value = User-Readable Name of the Connection as specified by the Connection Manager. This Node object is returned to the OpenDaylight Connection Manager and the application that invoked the Connect() functionality. \r
----\r
IPluginInConnectionService : public Node connect(String identifier, Map<ConnectionConstants, String> params)\r
----\r
Any subsequent interaction with this network element through any of the SAL services (Connection, Configuration, and others) will be by means of this Node Object. This Node object will be added to the Inventory maintained and managed by the Inventory Service of the plugin. The Node object will also assist with the OVSDB to Openflow mapping. \r
\r
The Node and its "Name" holds the key to the stateful Netty Socket handler maintained under the Connection Object created during the connect() call. The Channel concept of the Netty framework provides the much needed abstraction on the pipelining. With this Channel Pipelining and the asynchronous event handling, the message handling process gets better streamlined and understood. It also makes easier the replacement or manipulation of the pipeline functions in a more controlled fashion.\r
\r
.Connection to OVSDB server\r
image::ConnectionService.png[]\r
\r
.Successful connection handling\r
image::ConnectionServiceReturn.png[]\r
\r
=== Network Configuration Service\r
\r
The goal of the OpenDaylight Network Configuration services is to provide complete management plane solutions needed to successfully install, configure, and deploy the various SDN based network services. These are generic services which can be implemented in part or full by any south-bound protocol plugin. \r
The south-bound plugins can be either of the following: +\r
\r
* The new network virtualization protocol plugins such as OVSDB JSON-RPC\r
* The traditional management protocols such as SNMP or any others in the middle. \r
\r
The above definition, and more information on Network Configuration Services, is available at : https://wiki.opendaylight.org/view/OpenDaylight_Controller:NetworkConfigurationServices \r
\r
The current default OVSDB schemas support the Layer2 Bridge Domain services as defined in the Networkconfig.bridgedomain component. \r
\r
* Create Bridge Domain: createBridgeDomain(Node node, String bridgeIdentifier, Map<ConfigConstants, Object> params) \r
* Delete Bridge Domain: deleteBridgeDomain(Node node, String bridgeIdentifier) \r
* Add configurations to a Bridge Domain: addBridgeDomainConfig(Node node, String bridgeIdentifier, Map<ConfigConstants, Object> params) \r
* Delete Bridge Domain Configuration: removeBridgeDomainConfig(Node node, String bridgeIdentifier, Map<ConfigConstants, Object> params) \r
* Associate a port to a Bridge Domain: addPort(Node node, String bridgeIdentifier, String portIdentifier, Map<ConfigConstants, Object> params); \r
* Disassociate a port from a Bridge Domain: deletePort(Node node, String bridgeIdentifier, String portIdentifier) \r
* Add configurations to a Node Connector / Port: addPortConfig(Node node, String bridgeIdentifier, String portIdentifier, Map<ConfigConstants, Object> params) \r
* Remove configurations from a Node Connector: removePortConfig(Node node, String bridgeIdentifier, String portIdentifier, Map<ConfigConstants, Object> params) \r
\r
The above services are defined as generalized entities in SAL in order to ensure their compatibility with all relevant southBound plugins equally. Hence, the OVSDB plugin must derive appropriate specific configurations from a generalized request. For example: addPort() or addPortConfig() SAL service call takes in a params option which is a Map structure with a Constant Key. \r
These ConfigConstants are defined in SAL network configuration service: +\r
----\r
public enum ConfigConstants {\r
    TYPE("type"),\r
    VLAN("Vlan"),\r
    VLAN_MODE("vlan_mode"),\r
    TUNNEL_TYPE("Tunnel Type"),\r
    SOURCE_IP("Source IP"),\r
    DEST_IP("Destination IP"),\r
    MACADDRESS("MAC Address"),\r
    INTERFACE_IDENTIFIER("Interface Identifier"),\r
    MGMT("Management"),\r
    CUSTOM("Custom Configurations");\r
}\r
----\r
These are mapped to the appropriate OVSDB configurations. So, if the request is to create a VXLAN tunnel with src-ip=x.x.x.x, dst-ip=y.y.y.y, then the params Map structure may contain:\r
----\r
{\r
TYPE = "tunnel",\r
TUNNEL_TYPE = "vxlan",\r
SOURCE_IP="x.x.x.x",\r
DEST_IP="y.y.y.y"\r
}\r
----\r
NOTE: All of the APIs take in the Node parameter which is the Node value returned by the connect() method explained in <<_connection_service>>.\r
\r
==== Bidirectional JSON-RPC library\r
The OVSDB plugin implements a Bidirectional JSON-RPC library.  It is easy to design the library as a module that manages the Netty connection towards the Element. \r
\r
The main responsibilities of this Library are: +\r
\r
* Demarshal and marshal JSON Strings to JSON objects \r
* Demarshal and marshal JSON Strings from and to the Network Element.\r
\r
==== OVSDB Schema definitions and Object mappers\r
The OVSDB Schema definitions and Object Mapping layer sits above the JSON-RPC library. It maps the generic JSON objects to OVSDB schema POJOs (Plain Old Java Object) and vice-versa. This layer mostly provides the Java Object definition for the corresponding OVSDB schema (13 of them) and also will provide much more friendly API abstractions on top of these object data. This helps in hiding the JSON semantics from the functional modules such as Configuration Service and Tunnel management.\r
\r
On the demarshaling side, the mapping logic differentiates the Request and Response messages as follows : +\r
\r
* Request messages are mapped by its "method" \r
* Response messages are mapped by their IDs which were originally populated by the Request message.\r
The JSON semantics of these OVSDB schema is quite complex.\r
The following figures summarize two of the end-to-end scenarios: +\r
\r
.End-to-end handling of a Create Bridge request \r
image::ConfigurationService-example1.png[width=500]\r
\r
.End-to-end handling of a monitor response\r
image::MonitorResponse.png[width=500]\r
\r
==== Overlay tunnel management\r
\r
Network Virtualization using OVS is achieved through Overlay Tunnels. The actual Type of the Tunnel may be GRE, VXLAN, or STT. The differences in the encapsulation and configuration decide the tunnel types. Establishing a tunnel using configuration service requires just the sending of OVSDB messages towards the ovsdb-server. However, the scaling issues that would arise on the state management at the data-plane (using OpenFlow) can get challenging. Also, this module can assist in various optimizations in the presence of Gateways. It can also help in providing Service guarantees for the VMs using these overlays with the help of underlay orchestration. \r
\r
==== OVSDB to OpenFlow plugin mapping service\r
The connect() of the ConnectionService  would result in a Node that represents an ovsdb-server. The CreateBridgeDomain() Configuration on the above Node would result in creating an OVS bridge. This OVS Bridge is an OpenFlow Agent for the OpenDaylight OpenFlow plugin with its own Node represented as (example) OF|xxxx.yyyy.zzzz. \r
Without any help from the OVSDB plugin, the Node Mapping Service of the Controller platform would not be able to map the following: +\r
----\r
{OVSDB_NODE + BRIDGE_IDENTFIER} <---> {OF_NODE}.\r
----\r
Without such mapping, it would be extremely difficult for the applications to manage and maintain such nodes. This Mapping Service provided by the OVSDB plugin would essentially help in providing more value added services to the orchestration layers that sit atop the Northbound APIs (such as OpenStack). \r
\r
==== Inventory service\r
\r
Inventory Service provides a simple database of all the nodes managed and maintained by the OVSDB plugin on a given controller. For optimization purposes, it can also provide enhanced services to the OVSDB to OpenFlow mapping service by maintaining the following mapping owing to the static nature of this operation. +\r
----\r
{OVSDB_NODE + BRIDGE_IDENTFIER} <---> {OF_NODE}\r
----\r
=== OpenDaylight OVSDB Developer Getting Started Video Series\r
The video series were started to help developers bootstrap into OVSDB development.\r
\r
* http://www.youtube.com/watch?v=ieB645oCIPs[OpenDaylight OVSDB Developer Getting Started]\r
* http://www.youtube.com/watch?v=xgevyaQ12cg[OpenDaylight OVSDB Developer Getting Started - Northbound API Usage]\r
* http://www.youtube.com/watch?v=xgevyaQ12cg[OpenDaylight OVSDB Developer Getting Started - Java APIs]\r
* http://www.youtube.com/watch?v=NayuY6J-AMA[OpenDaylight OVSDB Developer Getting Started - OpenStack Integration OpenFlow v1.0]\r
\r
==== Other developer tutorials\r
\r
* https://wiki.opendaylight.org/view/OVSDB:OVSDB_OpenStack_Guide[OVSDB OpenFlow v1.3 Neutron ML2 Integration]\r
* http://networkstatic.net/getting-started-ovsdb/[Open vSwitch Database Table Explanations and Simple Jackson Tutorial]\r
\r
=== OVSDB integration: New features\r
==== Schema independent library\r
The OVS connection is a node which can have multiple databases. Each database is represented by a schema. A single connection can have multiple schemas.\r
OSVDB supports multiple schemas. Currently, these are two schemas available in the\r
OVSDB, but there is no restriction on the number of schemas. Owing to the Northbound v3 API, no code changes in ODL are needed for supporting additional schemas.\r
\r
Schemas: +\r
\r
*  openvswitch : Schema wrapper that represents http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf\r
*  hardwarevtep: Schema wrapper that represents http://openvswitch.org/docs/vtep.5.pdf\r
\r
==== Northbound API v3\r
OVSDB supports Northbound API v3 which allows external access to all ODL OVSDB databases or schemas.\r
The general syntax for that API follows this format:\r
----\r
http://{{controllerHost}}:{{controllerPort}}/ovsdb/nb/v3/node/{{OVS|HOST}}/database\r
---- \r
For more information on Northbound REST API see: +\r
https://docs.google.com/spreadsheets/d/11Rp5KSNTcrvOD4HadCnXDCUdJq_TZ5RgoQ6qSHf_xkw/edit?usp=sharing\r
 \r
The key differences between Northbound API v2 and v3 include: +\r
 \r
* Support for schema independence\r
* Formal restful style API, which includes consistent URL navigation for nodes and tables\r
* Ability to create interfaces and ports within a single rest call. To allow that, the JSON in the body can include distinct parts like interface and port\r
\r
==== Port security\r
Based on the fact that security rules can be obtained from a port object, OVSDB can apply Open Flow rules. These rules will match on what types of traffic the Openstack tenant VM is allowed to use.\r
 \r
Support for security groups is very experimental. There are limitations in determining the state of flows in the Open vSwitch. See http://%20https//www.youtube.com/watch?v=DSop2uLJZS8[Open vSwitch and the Intelligent Edge] from Justin Petit for a deep dive into the challenges we faced creating a flow based port security implementation. The current set of rules that will be installed only supports filtering of the TCP protocol. This is because via a Nicira TCP_Flag read we can match on a flows TCP_SYN flag, and permit or deny the flow based on the Neutron port security rules. If rules are requested for ICMP and UDP, they are ignored until greater visibility from the Linux kernel is available as outlined in the OpenStack presentation mentioned earlier. \r
\r
Using the port security groups of Neutron, one can add rules that restrict the network access of the tenants. The OVSDB Neutron integration checks the port security rules configured, and apply them by means of openflow rules. \r
\r
Through the ML2 interface, Neutron security rules are available in the port object, following this scope: Neutron Port -> Security Group -> Security Rules. \r
\r
The current rules are applied on the basis of the following attributes: ingress/egress, tcp protocol, port range, and prefix.\r
 \r
===== OpenStack workflow\r
\r
. Create a stack.\r
. Add the network and subnet. \r
. Add the Security Group and Rules.\r
\r
NOTE: This is no different than what users normally do in regular openstack deployments. \r
----\r
neutron security-group-create group1 --description "Group 1"\r
neutron security-group-list\r
neutron security-group-rule-create --direction ingress --protocol tcp group1\r
----\r
[start=4]\r
. Start the tenant, specifying the security-group.\r
----\r
nova boot --flavor m1.tiny \\r
--image $(nova image-list | grep 'cirros-0.3.1-x86_64-uec\s' | awk '{print $2}') \\r
--nic net-id=$(neutron net-list | grep 'vxlan2' | awk '{print $2}') vxlan2 \\r
--security-groups group1\r
----\r
===== Examples: Rules supported\r
----\r
neutron security-group-create group2 --description "Group 2"\r
neutron security-group-rule-create --direction ingress --protocol tcp --port-range-min 54 group2\r
neutron security-group-rule-create --direction ingress --protocol tcp --port-range-min 80 group2\r
neutron security-group-rule-create --direction ingress --protocol tcp --port-range-min 1633 group2\r
neutron security-group-rule-create --direction ingress --protocol tcp --port-range-min 22 group2\r
----\r
----\r
neutron security-group-create group3 --description "Group 3"\r
neutron security-group-rule-create --direction ingress --protocol tcp --remote-ip-prefix 10.200.0.0/16 group3\r
----\r
----\r
neutron security-group-create group4 --description "Group 4"\r
neutron security-group-rule-create --direction ingress --remote-ip-prefix 172.24.0.0/16 group4\r
----\r
----\r
neutron security-group-create group5 --description "Group 5"\r
neutron security-group-rule-create --direction ingress --protocol tcp group5\r
neutron security-group-rule-create --direction ingress --protocol tcp --port-range-min 54 group5\r
neutron security-group-rule-create --direction ingress --protocol tcp --port-range-min 80 group5\r
neutron security-group-rule-create --direction ingress --protocol tcp --port-range-min 1633 group5\r
neutron security-group-rule-create --direction ingress --protocol tcp --port-range-min 22 group5\r
----\r
----\r
neutron security-group-create group6 --description "Group 6"\r
neutron security-group-rule-create --direction ingress --protocol tcp --remote-ip-prefix 0.0.0.0/0 group6\r
----\r
----\r
neutron security-group-create group7 --description "Group 7"\r
neutron security-group-rule-create --direction egress --protocol tcp --port-range-min 443 --remote-ip-prefix 172.16.240.128/25 group7\r
----\r
*Reference gist*:https://gist.github.com/anonymous/1543a410d57f491352c8[Gist]\r
\r
===== Security group rules supported in ODL \r
The following rules formata are supported in the current implementation. The direction (ingress/egress) is always expected. Rules are implemented such that tcp-syn packets that do not satisfy the rules are dropped.\r
[cols="3", width="60%"]\r
|===\r
| Proto | Port | IP Prefix\r
\r
|TCP |x |x\r
|Any | Any |x\r
|TCP |x |Any\r
|TCP |Any |Any\r
|===\r
===== Limitations\r
\r
* Soon, conntrack will be supported by OVS. Until then, TCP flags are used as way of checking for connection state. Specifically, that is done by matching on the TCP-SYN flag. \r
* The param '--port-range-max' in 'security-group-rule-create' is not used until the implementation uses contrack. \r
* No UDP/ICMP specific match support is provided.\r
* No IPv6 support is provided.\r
\r
==== L3 forwarding\r
OVSDB extends support for the usage of an ODL-Neutron-driver so that OVSDB can configure OF 1.3 rules to route IPv4 packets. The driver eliminates the need for the router of the L3 Agent. In order to accomplish that, OVS 2.1 or a newer version is required.\r
OVSDB also supports inbound/outbound NAT, floating IPs.\r
\r
===== Starting OVSDB and OpenStack\r
\r
. Build or download OVSDB distribution, as mentioned in <<ovsdbBuildSteps,building a Karaf feature section>>.\r
. http://docs.vagrantup.com/v2/installation/index.html[Install Vagrant].\r
\r
[start=3]\r
. Enable the L3 Forwarding feature:\r
----\r
echo 'ovsdb.l3.fwd.enabled=yes' >> ./opendaylight/configuration/config.ini\r
echo 'ovsdb.l3gateway.mac=${GATEWAY_MAC}' >> ./configuration/config.ini\r
----\r
[start=4]\r
. Run the following commands to get the odl neutron drivers:\r
[start=5]\r
----\r
git clone https://github.com/dave-tucker/odl-neutron-drivers.git\r
cd odl-neutron-drivers\r
vagrant up devstack-control devstack-compute-1\r
----\r
[start=6]\r
. Use ssh to go to the control node, and clone odl-neutron-drivers again:\r
----\r
vagrant ssh devstack-control\r
git clone https://github.com/dave-tucker/odl-neutron-drivers.git\r
cd odl-neutron-drivers\r
sudo python setup.py install\r
*leave this shell open*\r
----\r
[start=7]\r
. Start odl, as mentioned in <<ovsdbStartingOdl,running Karaf feature section>>.\r
[start=8]\r
. To see processing of neutron event related to L3, do this from prompt:\r
----\r
log:set debug org.opendaylight.ovsdb.openstack.netvirt.impl.NeutronL3Adapter\r
----\r
[start=9]\r
. From shell, do one of the following: open on ssh into control node or vagrant ssh devstack-control.\r
----\r
cd ~/devstack && ./stack.sh\r
----\r
[start=10]\r
. From a new shell in the host system, run the following:\r
----\r
cd odl-neutron-drivers\r
vagrant ssh devstack-compute-1\r
cd ~/devstack && ./stack.sh\r
----\r
===== OpenStack workflow\r
\r
.Sample workflow\r
image::L3FwdSample.png[height=250]\r
\r
Use the following steps to set up a workflow like the one shown in figure above.\r
\r
. Set up authentication. From shell on stack control or vagrant ssh devstack-control:\r
----\r
source openrc admin admin\r
----\r
\r
----\r
rm -f id_rsa_demo* ; ssh-keygen -t rsa -b 2048 -N  -f id_rsa_demo\r
 nova keypair-add --pub-key  id_rsa_demo.pub  demo_key\r
 # nova keypair-list\r
----\r
[start=2]\r
. Create two networks and two subnets.\r
----\r
neutron net-create net1 --tenant-id $(keystone tenant-list | grep '\s'admin | awk '{print $2}') \\r
 --provider:network_type gre --provider:segmentation_id 555\r
----\r
----\r
neutron subnet-create --tenant-id $(keystone tenant-list | grep '\s'admin | awk '{print $2}') \\r
net1 10.0.0.0/16 --name subnet1 --dns-nameserver 8.8.8.8\r
----\r
----\r
neutron net-create net2 --tenant-id $(keystone tenant-list | grep '\s'admin | awk '{print $2}') \\r
 --provider:network_type gre --provider:segmentation_id 556\r
----\r
----\r
neutron subnet-create --tenant-id $(keystone tenant-list | grep '\s'admin | awk '{print $2}') \\r
 net2 20.0.0.0/16 --name subnet2 --dns-nameserver 8.8.8.8\r
----\r
[start=3]\r
. Create a router, and add an interface to each of the two subnets.\r
----\r
neutron router-create demorouter --tenant-id $(keystone tenant-list | grep '\s'admin | awk '{print $2}')\r
 neutron router-interface-add demorouter subnet1\r
 neutron router-interface-add demorouter subnet2\r
 # neutron router-port-list demorouter\r
----\r
[start=4]\r
. Create two tenant instances.\r
----\r
nova boot --poll --flavor m1.nano --image $(nova image-list | grep 'cirros-0.3.2-x86_64-uec\s' | awk '{print $2}') \\r
 --nic net-id=$(neutron net-list | grep -w net1 | awk '{print $2}'),v4-fixed-ip=10.0.0.10 \\r
 --availability-zone nova:devstack-control \\r
 --key-name demo_key host10\r
----\r
----\r
nova boot --poll --flavor m1.nano --image $(nova image-list | grep 'cirros-0.3.2-x86_64-uec\s' | awk '{print $2}') \\r
 --nic net-id=$(neutron net-list | grep -w net2 | awk '{print $2}'),v4-fixed-ip=20.0.0.20 \\r
 --availability-zone nova:devstack-compute-1 \\r
 --key-name demo_key host20\r
----\r
\r
===== Limitations\r
\r
* To use this feature, you need OVS 2.1 or newer version. \r
* Owing to OF limitations, icmp responses due to routing failures, like ttl expired or host unreacheable, are not generated.\r
* The MAC address of the default route is not automatically mapped. In order to route to L3 destinations outside the networks of the tenant, the manual configuration of the default route is necessary. To provide the MAC address of the default route, use ovsdb.l3gateway.mac in file configuration/config.ini ; \r
* This feature is Tech preview, which depends on later versions of OpenStack to be used without the provided neutron-driver. \r
* No IPv6 support is provided.\r
 \r
*More information on L3 forwarding*: +\r
\r
* odl-neutron-driver: https://github.com/dave-tucker/odl-neutron-drivers\r
* OF rules example: http://dtucker.co.uk/hack/building-a-router-with-openvswitch.html\r
\r
==== LBaaS\r
Load-Balancing-as-a-Service (LBaaS) creates an Open vSwitch powered L3-L4 stateless load-balancer in a virtualized network environment so that individual TCP connections destined to a designated virtual IP (VIP) are sent to the appropriate servers (that is to say, serving app VMs). The load-balancer works in a session-preserving, proactive manner without involving the controller during flow setup.\r
\r
A Neutron northbound interface is provided to create a VIP which will map to a pool of servers (that is to say, members) within a subnet. The pools consist of members identified by an IP address. The goal is to closely match the API to the OpenStack LBaaS v2 API: http://docs.openstack.org/api/openstack-network/2.0/content/lbaas_ext.html.\r
\r
===== Creating an OpenStack workflow\r
. Create a subnet. \r
. Create a floating VIP 'A' that maps to a private VIP 'B'. \r
. Create a Loadbalancer pool 'X'. \r
----\r
neutron lb-pool-create --name http-pool --lb-method ROUND_ROBIN --protocol HTTP --subnet-id XYZ\r
----\r
[start=4]\r
. Create a Loadbalancer pool member 'Y' and associate with pool 'X'. \r
----\r
neutron lb-member-create --address 10.0.0.10 --protocol-port 80 http-pool\r
neutron lb-member-create --address 10.0.0.11 --protocol-port 80 http-pool\r
neutron lb-member-create --address 10.0.0.12 --protocol-port 80 http-pool\r
neutron lb-member-create --address 10.0.0.13 --protocol-port 80 http-pool\r
----\r
[start=5]\r
. Create a Loadbalancer instance 'Z', and associate pool 'X' and VIP 'B' with it.\r
----\r
neutron lb-vip-create --name http-vip --protocol-port 80 --protocol HTTP --subnet-id XYZ http-pool\r
----\r
\r
===== Implementation\r
\r
The current implementation of the proactive stateless load-balancer was made using "multipath" action in the Open vSwitch. The "multipath" action takes a max_link parameter value (which is same as the number of pool members) as input, and performs a hash of the fields to get a value between (0, max_link). The value of the hash is used as an index to select a pool member to handle that session. \r
\r
==== Open vSwitch rules\r
\r
Assuming that table=20 contains all the rules to forward the traffic destined for a specific destination MAC address, the following are the rules needed to be programmed in the LBaaS service table=10. The programmed rules makes the translation from the VIP to a different pool member for every session. \r
\r
* Proactive forward rules:\r
----\r
sudo ovs-ofctl -O OpenFlow13 add-flow s1 "table=10,reg0=0,ip,nw_dst=10.0.0.5,actions=load:0x1->NXM_NX_REG0[[]],multipath(symmetric_l4, 1024, modulo_n, 4, 0, NXM_NX_REG1[0..12]),resubmit(,10)"\r
sudo ovs-ofctl -O OpenFlow13 add-flow s1 table=10,reg0=1,nw_dst=10.0.0.5,ip,reg1=0,actions=mod_dl_dst:00:00:00:00:00:10,mod_nw_dst:10.0.0.10,goto_table:20\r
sudo ovs-ofctl -O OpenFlow13 add-flow s1 table=10,reg0=1,nw_dst=10.0.0.5,ip,reg1=1,actions=mod_dl_dst:00:00:00:00:00:11,mod_nw_dst:10.0.0.11,goto_table:20\r
sudo ovs-ofctl -O OpenFlow13 add-flow s1 table=10,reg0=1,nw_dst=10.0.0.5,ip,reg1=2,actions=mod_dl_dst:00:00:00:00:00:12,mod_nw_dst:10.0.0.12,goto_table:20\r
sudo ovs-ofctl -O OpenFlow13 add-flow s1 table=10,reg0=1,nw_dst=10.0.0.5,ip,reg1=3,actions=mod_dl_dst:00:00:00:00:00:13,mod_nw_dst:10.0.0.13,goto_table:20\r
----\r
* Proactive reverse rules: \r
----\r
sudo ovs-ofctl -O OpenFlow13 add-flow s1 table=10,ip,tcp,tp_src=80,actions=mod_dl_src:00:00:00:00:00:05,mod_nw_src:10.0.0.5,goto_table:20\r
---- \r
===== OVSDB project code\r
The current implementation handles all neutron calls in the net-virt/LBaaSHandler.java code, and makes calls to the net-virt-providers/LoadBalancerService to program appropriate flowmods. The rules are updated whenever there is a change in the Neutron LBaaS settings. There is no cache of state kept in the net-virt or providers. \r
\r
===== Limitations\r
Owing to the inflexibility of the multipath action, the existing LBaaS implementation comes with some limitations: \r
\r
* TCP, HTTP or HTTPS are supported protocols for the pool. (Caution: You can lose access to the members if you assign {Proto:TCP, Port:22} to LB) \r
\r
* Member weights are ignored. \r
* The update of an LB instance is done as a delete + add, and not an actual delta. \r
* The update of an LB member is not supported (because weights are ignored). \r
* Deletion of an LB member leads to the reprogramming of the LB on all nodes (because of the way multipath does link hash).\r
* There is only a single LB instance per subnet because the pool-id is not reported in the create load-balancer call. \r
\r
\r
\r
\r
\r
\r
\r
\r
\r
                       \r
\r
\r