--- /dev/null
+CAPWAP Developer Guide
+======================
+
+Overview
+--------
+
+The Control And Provisioning of Wireless Access Points (CAPWAP) plugin
+project aims to provide new southbound interface for controller to be
+able to monitor and manage CAPWAP compliant wireless termination point
+(WTP) network devices. The CAPWAP feature will provide REST based
+northbound APIs.
+
+CAPWAP Architecture
+-------------------
+
+The CAPWAP feature is implemented as an MD-SAL based provider module,
+which helps discover WTP devices and update their states in the MD-SAL
+operational datastore.
+
+CAPWAP APIs and Interfaces
+--------------------------
+
+This section describes the APIs for interacting with the CAPWAP plugin.
+
+Discovered WTPs
+~~~~~~~~~~~~~~~
+
+The CAPWAP project maintains list of discovered CAPWAP WTPs that is
+YANG-based in MD-SAL. These models are available via RESTCONF.
+
+- Name: Discovered-WTPs
+
+- URL:
+ `http://${ipaddress}:8181/restconf/operational/capwap-impl:capwap-ac-root/ <http://${ipaddress}:8181/restconf/operational/capwap-impl:capwap-ac-root/>`__
+
+- Description: Displays list of discovered WTPs and their basic
+ attributes
+
+API Reference Documentation
+---------------------------
+
+Go to
+`http://${ipaddress}:8181/apidoc/explorer/index.html <http://${ipaddress}:8181/apidoc/explorer/index.html>`__,
+sign in, and expand the capwap-impl panel. From there, users can execute
+various API calls to test their CAPWAP deployment.
+
--- /dev/null
+Cardinal: OpenDaylight Monitoring as a Service
+==============================================
+
+Overview
+--------
+
+Cardinal (OpenDaylight Monitoring as a Service) enables OpenDaylight and
+the underlying software defined network to be remotely monitored by
+deployed Network Management Systems (NMS) or Analytics suite. In the
+Boron release, Cardinal adds:
+
+1. OpenDaylight MIB.
+
+2. Enable ODL diagnostics/monitoring to be exposed across SNMP (v2c, v3)
+ and REST north-bound.
+
+3. Extend ODL System health, Karaf parameter and feature info, ODL
+ plugin scalability and network parameters.
+
+4. Support autonomous notifications (SNMP Traps).
+
+Cardinal Architecture
+---------------------
+
+The Cardinal architecture can be found at the below link:
+
+https://wiki.opendaylight.org/images/8/89/Cardinal-ODL_Monitoring_as_a_Service_V2.pdf
+
+Key APIs and Interfaces
+-----------------------
+
+There are 2 main APIs for requesting snmpget request of the Karaf info
+and System info. To expose these APIs, it assumes that you already have
+the ``odl-cardinal`` and ``odl-restconf`` features installed. You can do
+that by entering the following at the Karaf console:
+
+::
+
+ feature:install odl-cardinal
+ feature:install odl-restconf-all
+
+System Info APIs
+~~~~~~~~~~~~~~~~
+
+Open the REST interface and using the basic authentication, execute REST
+APIs for system info as:
+
+::
+
+ http://localhost:8181/restconf/operational/cardinal:CardinalSystemInfo/
+
+You should get the response code of the same as 200 OK with the
+following output as:
+
+::
+
+ {
+ "CardinalSystemInfo": {
+ "odlSystemMemUsage": " 9",
+ "odlSystemSysInfo": " OpenDaylight Node Information",
+ "odlSystemOdlUptime": " 00:29",
+ "odlSystemCpuUsage": " 271",
+ "odlSystemHostAddress": " Address of the Host should come up"
+ }
+ }
+
+Karaf Info APIs
+~~~~~~~~~~~~~~~
+
+Open the REST interface and using the basic authentication, execute REST
+APIs for system info as:
+
+::
+
+ http://localhost:8181/restconf/operational/cardinal-karaf:CardinalKarafInfo/
+
+You should get the response code of the same as 200 OK with the
+following output as:
+
+::
+
+ {
+ "CardinalKarafInfo": {
+ "odlKarafBundleListActive1": " org.ops4j.pax.url.mvn_2.4.5 [1]",
+ "odlKarafBundleListActive2": " org.ops4j.pax.url.wrap_2.4.5 [2]",
+ "odlKarafBundleListActive3": " org.ops4j.pax.logging.pax-logging-api_1.8.4 [3]",
+ "odlKarafBundleListActive4": " org.ops4j.pax.logging.pax-logging-service_1.8.4 [4]",
+ "odlKarafBundleListActive5": " org.apache.karaf.service.guard_3.0.6 [5]",
+ "odlKarafBundleListActive6": " org.apache.felix.configadmin_1.8.4 [6]",
+ "odlKarafBundleListActive7": " org.apache.felix.fileinstall_3.5.2 [7]",
+ "odlKarafBundleListActive8": " org.objectweb.asm.all_5.0.3 [8]",
+ "odlKarafBundleListActive9": " org.apache.aries.util_1.1.1 [9]",
+ "odlKarafBundleListActive10": " org.apache.aries.proxy.api_1.0.1 [10]",
+ "odlKarafBundleListInstalled1": " org.ops4j.pax.url.mvn_2.4.5 [1]",
+ "odlKarafBundleListInstalled2": " org.ops4j.pax.url.wrap_2.4.5 [2]",
+ "odlKarafBundleListInstalled3": " org.ops4j.pax.logging.pax-logging-api_1.8.4 [3]",
+ "odlKarafBundleListInstalled4": " org.ops4j.pax.logging.pax-logging-service_1.8.4 [4]",
+ "odlKarafBundleListInstalled5": " org.apache.karaf.service.guard_3.0.6 [5]",
+ "odlKarafFeatureListInstalled1": " config",
+ "odlKarafFeatureListInstalled2": " region",
+ "odlKarafFeatureListInstalled3": " package",
+ "odlKarafFeatureListInstalled4": " http",
+ "odlKarafFeatureListInstalled5": " war",
+ "odlKarafFeatureListInstalled6": " kar",
+ "odlKarafFeatureListInstalled7": " ssh",
+ "odlKarafFeatureListInstalled8": " management",
+ "odlKarafFeatureListInstalled9": " odl-netty",
+ "odlKarafFeatureListInstalled10": " odl-lmax",
+ "odlKarafBundleListResolved1": " org.ops4j.pax.url.mvn_2.4.5 [1]",
+ "odlKarafBundleListResolved2": " org.ops4j.pax.url.wrap_2.4.5 [2]",
+ "odlKarafBundleListResolved3": " org.ops4j.pax.logging.pax-logging-api_1.8.4 [3]",
+ "odlKarafBundleListResolved4": " org.ops4j.pax.logging.pax-logging-service_1.8.4 [4]",
+ "odlKarafBundleListResolved5": " org.apache.karaf.service.guard_3.0.6 [5]",
+ "odlKarafFeatureListUnInstalled1": " aries-annotation",
+ "odlKarafFeatureListUnInstalled2": " wrapper",
+ "odlKarafFeatureListUnInstalled3": " service-wrapper",
+ "odlKarafFeatureListUnInstalled4": " obr",
+ "odlKarafFeatureListUnInstalled5": " http-whiteboard",
+ "odlKarafFeatureListUnInstalled6": " jetty",
+ "odlKarafFeatureListUnInstalled7": " webconsole",
+ "odlKarafFeatureListUnInstalled8": " scheduler",
+ "odlKarafFeatureListUnInstalled9": " eventadmin",
+ "odlKarafFeatureListUnInstalled10": " jasypt-encryption"
+ }
+ }
+
--- /dev/null
+DIDM Developer Guide
+====================
+
+Overview
+--------
+
+The Device Identification and Driver Management (DIDM) project addresses
+the need to provide device-specific functionality. Device-specific
+functionality is code that performs a feature, and the code is
+knowledgeable of the capability and limitations of the device. For
+example, configuring VLANs and adjusting FlowMods are features, and
+there may be different implementations for different device types.
+Device-specific functionality is implemented as Device Drivers. Device
+Drivers need to be associated with the devices they can be used with. To
+determine this association requires the ability to identify the device
+type.
+
+DIDM Architecture
+-----------------
+
+The DIDM project creates the infrastructure to support the following
+functions:
+
+- **Discovery** - Determination that a device exists in the controller
+ management domain and connectivity to the device can be established.
+ For devices that support the OpenFlow protocol, the existing
+ discovery mechanism in OpenDaylight suffices. Devices that do not
+ support OpenFlow will be discovered through manual means such as the
+ operator entering device information via GUI or REST API.
+
+- **Identification** – Determination of the device type.
+
+- **Driver Registration** – Registration of Device Drivers as routed
+ RPCs.
+
+- **Synchronization** – Collection of device information, device
+ configuration, and link (connection) information.
+
+- **Data Models for Common Features** – Data models will be defined to
+ perform common features such as VLAN configuration. For example,
+ applications can configure a VLAN by writing the VLAN data to the
+ data store as specified by the common data model.
+
+- **RPCs for Common Features** – Configuring VLANs and adjusting
+ FlowMods are example of features. RPCs will be defined that specify
+ the APIs for these features. Drivers implement features for specific
+ devices and support the APIs defined by the RPCs. There may be
+ different Driver implementations for different device types.
+
+Key APIs and Interfaces
+-----------------------
+
+FlowObjective API
+~~~~~~~~~~~~~~~~~
+
+Following are the list of the APIs to create the flow objectives to
+install the flow rule in OpenFlow switch in pipeline agnostic way.
+Currently these APIs are getting consumed by Atrium project.
+
+Install the Forwarding Objective:
+
+`http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:forward <http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:forward>`__
+---
+
+Install the Filter Objective
+
+`http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:filter <http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:filter>`__
+---
+
+Install the Next Objective:
+
+`http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:next <http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:next>`__
+---
+
+Flow mod driver API
+~~~~~~~~~~~~~~~~~~~
+
+The Beryllium release includes a flow mod driver for the HP 3800. This
+driver adjusts the flows and push the same to the device. This API takes
+the flow to be adjusted as input and displays the adjusted flow as
+output in the REST output container. Here is the REST API to adjust and
+push flows to HP 3800 device:
+
+::
+
+ http://<CONTROLLER-IP:8181>/restconf/operations/openflow-feature:adjust-flow
+
+Here is an example of an ARP flow and how it gets adjusted and pushed to
+device HP3800:
+
+**adjust-flow input.**
+
+::
+
+ <?xml version="1.0" encoding="UTF-8" standalone="no"?>
+ <input xmlns="urn:opendaylight:params:xml:ns:yang:didm:drivers:openflow" xmlns:opendaylight-inventory="urn:opendaylight:inventory">
+ <node>/opendaylight-inventory:nodes/opendaylight-inventory:node[opendaylight-inventory:id='openflow:673249119553088']</node>
+ <flow>
+ <match>
+ <ethernet-match>
+ <ethernet-type>
+ <type>2054</type>
+ </ethernet-type>
+ </ethernet-match>
+ </match>
+ <flags>SEND_FLOW_REM</flags>
+ <priority>0</priority>
+ <flow-name>ARP_FLOW</flow-name>
+ <instructions>
+ <instruction>
+ <order>0</order>
+ <apply-actions>
+ <action>
+ <order>0</order>
+ <output-action>
+ <output-node-connector>CONTROLLER</output-node-connector>
+ <max-length>65535</max-length>
+ </output-action>
+ </action>
+ <action>
+ <order>1</order>
+ <output-action>
+ <output-node-connector>NORMAL</output-node-connector>
+ <max-length>65535</max-length>
+ </output-action>
+ </action>
+ </apply-actions>
+ </instruction>
+ </instructions>
+ <idle-timeout>180</idle-timeout>
+ <hard-timeout>1800</hard-timeout>
+ <cookie>10</cookie>
+ </flow>
+ </input>
+
+In the output, you can see that the table ID has been identified for the
+given flow and two flow mods are created as a result of adjustment. The
+first one is to catch ARP packets in Hardware table 100 with an action
+to goto table 200. The second flow mod is in table 200 with actions:
+output normal and output controller.
+
+**adjust-flow output.**
+
+::
+
+ {
+ "output": {
+ "flow": [
+ {
+ "idle-timeout": 180,
+ "instructions": {
+ "instruction": [
+ {
+ "order": 0,
+ "apply-actions": {
+ "action": [
+ {
+ "order": 1,
+ "output-action": {
+ "output-node-connector": "NORMAL",
+ "max-length": 65535
+ }
+ },
+ {
+ "order": 0,
+ "output-action": {
+ "output-node-connector": "CONTROLLER",
+ "max-length": 65535
+ }
+ }
+ ]
+ }
+ }
+ ]
+ },
+ "strict": false,
+ "table_id": 200,
+ "flags": "SEND_FLOW_REM",
+ "cookie": 10,
+ "hard-timeout": 1800,
+ "match": {
+ "ethernet-match": {
+ "ethernet-type": {
+ "type": 2054
+ }
+ }
+ },
+ "flow-name": "ARP_FLOW",
+ "priority": 0
+ },
+ {
+ "idle-timeout": 180,
+ "instructions": {
+ "instruction": [
+ {
+ "order": 0,
+ "go-to-table": {
+ "table_id": 200
+ }
+ }
+ ]
+ },
+ "strict": false,
+ "table_id": 100,
+ "flags": "SEND_FLOW_REM",
+ "cookie": 10,
+ "hard-timeout": 1800,
+ "match": {},
+ "flow-name": "ARP_FLOW",
+ "priority": 0
+ }
+ ]
+ }
+ }
+
+API Reference Documentation
+---------------------------
+
+Go to
+`http://${controller-ip}:8181/apidoc/explorer/index.html <http://${controller-ip}:8181/apidoc/explorer/index.html>`__,
+and look under DIDM section to see all the available REST calls and
+tables
+
--- /dev/null
+DLUX
+====
+
+Setup and Run
+-------------
+
+Required Technology Stack
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- AngularJS (JavaScript client-side framework, http://www.angularjs.org
+ )
+
+Run DLUX
+~~~~~~~~
+
+To turn on the DLUX UI, install DLUX core feature via running following
+command on the Karaf console -
+
+::
+
+ feature:install odl-dlux-core
+
+The above command will install odl-restconf and DLUX topology
+application internally, along with core DLUX components. Once this
+feature is successfully installed, access the UI at
+http://localhost:8181/index.html. The default credentials for login are
+admin/admin.
+
+All the applications in DLUX are Karaf features. A user can install
+other dlux applications such as node and yang-ui from Karaf console
+using commands such as -
+
+::
+
+ $ feature:install odl-dlux-node
+
+ $ feature:install odl-dlux-yangui
+
+DLUX Modules
+------------
+
+DLUX modules are the individual features such as nodes and topology.
+Each module has a defined structure and you can find all existing
+modules at
+https://github.com/opendaylight/dlux/tree/stable/lithium/modules.
+
+Module Structure
+~~~~~~~~~~~~~~~~
+
+- module\_folder
+
+ - <module\_name>.module.js
+
+ - <module\_name>.controller.js
+
+ - <module\_name>.services.js
+
+ - <module\_name>.directives.js
+
+ - <module\_name>.filter.js
+
+ - index.tpl.html
+
+ - <a\_stylesheet>.css
+
+Create New Module
+~~~~~~~~~~~~~~~~~
+
+Define the module
+^^^^^^^^^^^^^^^^^
+
+1. Create an empty maven project and create your module folder under
+ src/main/resources.
+
+2. Create an empty file with pattern <module\_name>.module.js.
+
+3. Next, you need to surround the angular module with a define function.
+ This allows RequireJs to see our module.js files. The first argument
+ is an array which contains all the module’s dependencies. The second
+ argument is a callback function, whose body contain the AngularJS
+ code base. The function parameters correspond with the order of
+ dependencies. Each dependency is injected into a parameter, if it is
+ provided.
+
+4. Finally, you will return the angular module to be able to inject it
+ as a parameter in others modules.
+
+For each new module, you must have at least these two dependencies :
+
+- angularAMD : It’s a wrapper around AngularJS to provide an AMD
+ (Asynchronous Module Definition) support, which is used by RequireJs.
+ For more information see the `AMD
+ documentation <https://github.com/amdjs/amdjs-api/blob/master/AMD.md>`__.
+
+- app/core/core.services : This one is mandatory, if you want to add
+ content in the navigation menu, the left bar or the top bar.
+
+The following are not mandatory, but very often used.
+
+- angular-ui-router : A library to provide URL routing.
+
+- routingConfig : To set the level access to a page.
+
+Your module.js file might look like this:
+
+::
+
+ define(['angularAMD','app/routingConfig', 'angular-ui-router','app/core/core.services'], function(ng) {
+ var module = angular.module('app.a_module', ['ui.router.state', 'app.core']);
+ // module configuration
+ module.config(function() {
+ [...]
+ });
+ return module;
+ });
+
+Set the register function
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+AngularJS allows lazy registration of a module’s components such as
+controller, factory etc. Once you will install your application, DLUX
+will load your module javascript, but not your angular component during
+bootstrap phase. You have to register your angular components to make
+sure they are available at the runtime.
+
+Here is how to register your module’s component for lazy initialization
+-
+
+::
+
+ module.config(function($compileProvider, $controllerProvider, $provide) {
+ module.register = {
+ controller : $controllerProvider.register,
+ directive : $compileProvider.directive,
+ factory : $provide.factory,
+ service : $provide.service
+ };
+ });
+
+Set the route
+^^^^^^^^^^^^^
+
+The next step is to set up the route for your module. This part is also
+done in the configuration method of the module. We have to add
+**$stateProvider** as a parameter.
+
+::
+
+ module.config(function($stateProvider) {
+ var access = routingConfig.accessLevels;
+ $stateProvider.state('main.module', {
+ url: 'module',
+ views : {
+ 'content' : {
+ templateUrl: 'src/app/module/module.tpl.html',
+ controller: 'ModuleCtrl'
+ }
+ }
+ });
+ });
+
+Adding element to the navigation menu
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To be able to add item to the navigation menu, the module requires the
+**NavHelperProvider** parameter in the configuration method.
+**addToMenu** method in **NavMenuHelper** helper allows an item addition
+to the menu.
+
+::
+
+ var module = angular.module('app.a_module', ['app.core']);
+ module.config(function(NavMenuHelper) {
+ NavMenuHelper.addToMenu('myFirstModule', {
+ "link" : "#/module/index",
+ "active" : "module",
+ "title" : "My First Module",
+ "icon" : "icon-sitemap",
+ "page" : {
+ "title" : "My First Module",
+ "description" : "My first module"
+ }
+ });
+ });
+
+The first parameter is an ID that refers to the level of your menu and
+the second is a object. For now, The ID parameter supports two levels of
+depth. If your ID looks like *rootNode.childNode*, the helper will look
+for a node named *rootNode* and it will append the *childNode* to it. If
+the root node doesn’t exist, it will create it.
+
+Link the AngularJS module’s controller file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To include the module’s controller file, you can use the
+NavHelperProvider. It contains a method that will load the given file.
+
+::
+
+ [...]
+ NavHelperProvider.addControllerUrl('<path_to_module_folder>/<module_name>.controller');
+
+This completes your module.js file.
+
+Create the controller, factory, directive, etc
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creating the controller and other components is similar to the module.
+
+- First, add the define method.
+
+- Second, add the relative path to the module definition.
+
+- Last, create your methods as you usually do it with AngularJS.
+
+For example -
+
+::
+
+ define(['<relative_path_to_module>/<module_name>.module'], function(module) {
+ module.register.controller('ModuleCtrl', function($rootScope, $scope) {
+ });
+ });
+
+Add new application using DLUX modularity
+-----------------------------------------
+
+DLUX works as a Karaf based UI platform, where you can create a new
+Karaf feature of your UI component and install that UI applications in
+DLUX using blueprint. This page will help you to create and load a new
+application for DLUX. You don’t have to add new module in DLUX
+repository.
+
+Add a new OSGi blueprint bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The OSGi Blueprint Container specification allows us to use dependency
+injection in our OSGi environment. Each DLUX application module
+registers itself via blueprint configuration. Each application will have
+its own blueprint.xml to place its configuration.
+
+1. Create a maven project to place blueprint configuration. For
+ reference, take a look at topology bundle, present at
+ https://github.com/opendaylight/dlux/tree/stable/lithium/bundles/topology.
+ All the existing DLUX modules' configurations are available under
+ bundles directory of DLUX code.
+
+2. In pom.xml, you have to add a maven plugin to unpack your module code
+ under generated-resources of this project. For reference, you can
+ check pom.xml of dlux/bundles/topology at
+ https://github.com/opendaylight/dlux/tree/stable/lithium/bundles/topology.
+ Your bundle will eventually get deployed in Karaf as feature, so your
+ bundle should contain all your module code. If you want to combine
+ module and bundle project, that should not be an issue either.
+
+3. Create a blueprint.xml configuration file under
+ src/main/resources/OSGI-INF/blueprint. Below is the content of the
+ blueprint.xml taken from topology bundles’s blueprint.xml. Any new
+ application should create a blueprint.xml in following format -
+
+::
+
+ <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+ <reference id="httpService" availability="mandatory" activation="eager" interface="org.osgi.service.http.HttpService"/>
+ <reference id="loader" availability="mandatory" activation="eager" interface="org.opendaylight.dlux.loader.DluxModuleLoader"/>
+
+ <bean id="bundle" init-method="initialize" destroy-method="clean" class="org.opendaylight.dlux.loader.DluxModule">
+ <property name="httpService" ref="httpService"/>
+ <property name="loader" ref="loader"/>
+ <property name="moduleName" value="topology "/>
+ <property name="url" value="/src/app/topology"/>
+ <property name="directory" value="/topology"/>
+ <property name="requireJs" value="app/topology/topology.module"/>
+ <property name="angularJs" value="app.topology"/>
+ <property name="cssDependencies">
+ <list>
+ <value>http://yui.yahooapis.com/3.18.1/build/cssreset/cssreset-min.css</value>
+ <value>src/app/topology/topology-custom.css</value>
+ </list>
+ </property>
+ </bean>
+ </blueprint>
+
+In above configuration, there are two references with id httpService and
+loader. These two beans will already be initialized by dlux-core, so any
+new application can use them. Without these two bean references, a new
+application will not be able to register.
+
+Next is the initialization of your application bean, which will be an
+instance of class org.opendaylight.dlux.loader.DluxModule. There are 5
+properties that you should provide in this bean besides the references
+of httpService and loader. Lets talk about those bean properties in
+little more detail.
+
+**moduleName** : Name of your module. This name should be unique in
+DLUX.
+
+**url**: This is the url via which RequireJS in DLUX will try to load
+your module JS/HTML files. Also, this is the url that browser will use
+to load the static HTML, JS or CSS files. RequireJS in DLUX has a base
+path of **src**, so all the url should start with /src so RequireJS and
+the browser can correctly find the files.
+
+**directory**: In your bundle’s pom.xml, you unpack your module code.
+This is the directory where your actual static files will reside. The
+above mentioned url is registered with httpService, so when browser
+makes a call to that url, it will be redirected to the directory
+mentioned here. In the above example, all the topology files are present
+under /topology directory and the browser/RequireJS can access those
+files with uri /src/app/topology.
+
+**requireJS**: This is the path to your RequireJS module. If you notice
+closely, you will see the initial path of RequireJS app/topology in the
+above example matches with the last part of url. This path will be be
+used by RequireJS. As mentioned above, we have kept **src** as base path
+in RequireJS, that is the exact reason that url start with /src.
+
+**angularJS**: name of your AngularJS module.
+
+**cssDependencies**: If the application has any external/internal css
+dependencies, then those can be added here. If you create your own css
+files, just point to those css files here. Use the url path that you
+mentioned above, so the browser can find your css file.
+
+OSGi understands blueprint.xml, once you will deploy your bundle in
+karaf (or you can create a new feature for your application), karaf will
+read your blueprint.xml and it will try to register your application
+with dlux. Once successful, if you refresh your dlux UI, you will see
+your application in left hand navigation bar of dlux.
+
+Yang Utils
+----------
+
+Yang Utils are used by UI to perform all CRUD operations. All of these
+utilities are present in yangutils.services.js file. It has following
+AngularJS factories -
+
+- **arrayUtils** – defines functions for working with arrays.
+
+- **pathUtils** – defines functions for working with xpath (paths to
+ APIs and subAPIs). It divides xpath string to array of elements, so
+ this array can be later used for search functions.
+
+- **syncFact** – provides synchronization between requests to and from
+ OpenDaylight when it’s needed.
+
+- **custFunct** – it is linked with
+ apiConnector.createCustomFunctionalityApis in yangui controller in
+ yangui.controller.js. That function makes it possible to create some
+ custom function called by the click on button in index.tpl.html. All
+ custom functions are stored in array and linked to specific subAPI.
+ When particular subAPI is expanded and clicked, its inputs (linked
+ root node with its child nodes) are displayed in the bottom part of
+ the page and its buttons with custom functionality are displayed
+ also.
+
+- **reqBuilder** – Builds object in JSON format from input fields of
+ the UI page. **Show Preview** button on Yang UI use this builder.
+ This request is sent to OpenDaylight when button PUT or POST is
+ clicked.
+
+- **yinParser** – factory for reading .xml files of yang models and
+ creating object hierarchy. Every statement from yang is represented
+ by a node.
+
+- **nodeWrapper** – adds functions to objects in tree hierarchy created
+ with yinParser. These functions provide functionality for every type
+ of node.
+
+- **apiConnector** – the main functionality is filling the main
+ structures and linking them. Structure of APIs and subAPIs which is
+ two level array - first level is filled by main APIs, second level is
+ filled by others sub APIs. Second main structure is array of root
+ nodes, which are objects including root node and its children nodes.
+ Linking these two structures is creating links between every subAPI
+ (second level of APIs array) and its root node, which must be
+ displayed like inputs when subAPI is expanded.
+
+- **yangUtils** – some top level functions which are used by yangui
+ controller for creating the main structures.
+
--- /dev/null
+L2Switch Developer Guide
+========================
+
+Overview
+--------
+
+The L2Switch project provides Layer2 switch functionality.
+
+L2Switch Architecture
+---------------------
+
+- Packet Handler
+
+ - Decodes the packets coming to the controller and dispatches them
+ appropriately
+
+- Loop Remover
+
+ - Removes loops in the network
+
+- Arp Handler
+
+ - Handles the decoded ARP packets
+
+- Address Tracker
+
+ - Learns the Addresses (MAC and IP) of entities in the network
+
+- Host Tracker
+
+ - Tracks the locations of hosts in the network
+
+- L2Switch Main
+
+ - Installs flows on each switch based on network traffic
+
+Key APIs and Interfaces
+-----------------------
+
+- Packet Handler
+
+- Loop Remover
+
+- Arp Handler
+
+- Address Tracker
+
+- Host Tracker
+
+- L2Switch Main
+
+Packet Dispatcher
+~~~~~~~~~~~~~~~~~
+
+Classes
+^^^^^^^
+
+- AbstractPacketDecoder
+
+ - Defines the methods that all decoders must implement
+
+- EthernetDecoder
+
+ - The base decoder which decodes the packet into an Ethernet packet
+
+- ArpDecoder, Ipv4Decoder, Ipv6Decoder
+
+ - Decodes Ethernet packets into the either an ARP or IPv4 or IPv6
+ packet
+
+Further development
+^^^^^^^^^^^^^^^^^^^
+
+There is a need for more decoders. A developer can write
+
+- A decoder for another EtherType, i.e. LLDP.
+
+- A higher layer decoder for the body of the IPv4 packet or IPv6
+ packet, i.e. TCP and UDP.
+
+How to write a new decoder
+
+- extends AbstractDecoder<A, B>
+
+ - A refers to the notification that the new decoder consumes
+
+ - B refers to the notification that the new decoder produces
+
+- implements xPacketListener
+
+ - The new decoder must specify which notification it is listening to
+
+- canDecode method
+
+ - This method should examine the consumed notification to see
+ whether the new decoder can decode the contents of the packet
+
+- decode method
+
+ - This method does the actual decoding of the packet
+
+Loop Remover
+~~~~~~~~~~~~
+
+Classes
+^^^^^^^
+
+- **LoopRemoverModule**
+
+ - Reads config subsystem value for *is-install-lldp-flow*
+
+ - If *is-install-lldp-flow* is true, then an
+ **InitialFlowWriter** is created
+
+ - Creates and initializes the other LoopRemover classes
+
+- **InitialFlowWriter**
+
+ - Only created when *is-install-lldp-flow* is true
+
+ - Installs a flow, which forwards all LLDP packets to the
+ controller, on each switch
+
+- **TopologyLinkDataChangeHandler**
+
+ - Listens to data change events on the Topology tree
+
+ - When these changes occur, it waits *graph-refresh-delay* seconds
+ and then tells **NetworkGraphImpl** to update
+
+ - Writes an STP (Spanning Tree Protocol) status of "forwarding" or
+ "discarding" to each link in the Topology data tree
+
+ - Forwarding links can forward packets.
+
+ - Discarding links cannot forward packets.
+
+- **NetworkGraphImpl**
+
+ - Creates a loop-free graph of the network
+
+Configuration
+^^^^^^^^^^^^^
+
+- graph-refresh-delay
+
+ - Used in TopologyLinkDataChangeHandler
+
+ - A higher value has the advantage of doing less graph updates, at
+ the potential cost of losing some packets because the graph didn’t
+ update immediately.
+
+ - A lower value has the advantage of handling network topology
+ changes quicker, at the cost of doing more computation.
+
+- is-install-lldp-flow
+
+ - Used in LoopRemoverModule
+
+ - "true" means a flow that sends all LLDP packets to the controller
+ will be installed on each switch
+
+ - "false" means this flow will not be installed
+
+- lldp-flow-table-id
+
+ - The LLDP flow will be installed on the specified flow table of
+ each switch
+
+- lldp-flow-priority
+
+ - The LLDP flow will be installed with the specified priority
+
+- lldp-flow-idle-timeout
+
+ - The LLDP flow will timeout (removed from the switch) if the flow
+ doesn’t forward a packet for *x* seconds
+
+- lldp-flow-hard-timeout
+
+ - The LLDP flow will timeout (removed from the switch) after *x*
+ seconds, regardless of how many packets it is forwarding
+
+Further development
+^^^^^^^^^^^^^^^^^^^
+
+No suggestions at the moment.
+
+Validating changes to Loop Remover
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+STP Status information is added to the Inventory data tree.
+
+- A status of "forwarding" means the link is active and packets are
+ flowing on it.
+
+- A status of "discarding" means the link is inactive and packets are
+ not sent over it.
+
+The STP status of a link can be checked through a browser or a REST
+Client.
+
+::
+
+ http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:2
+
+The STP status should still be there after changes are made.
+
+Arp Handler
+~~~~~~~~~~~
+
+Classes
+^^^^^^^
+
+- **ArpHandlerModule**
+
+ - Reads config subsystem value for *is-proactive-flood-mode*
+
+ - If *is-proactive-flood-mode* is true, then a
+ ProactiveFloodFlowWriter is created
+
+ - If *is-proactive-flood-mode* is false, then an
+ InitialFlowWriter is created
+
+- **ProactiveFloodFlowWriter**
+
+ - Only created when *is-proactive-flood-mode* is true
+
+ - Installs a flood flow on each switch. With this flood flow, a
+ packet that doesn’t match any other flows will be
+ flooded/broadcast from that switch.
+
+- **InitialFlowWriter**
+
+ - Only created when *is-proactive-flood-mode* is false
+
+ - Installs a flow, which sends all ARP packets to the controller, on
+ each switch
+
+- **ArpPacketHandler**
+
+ - Only created when *is-proactive-flood-mode* is false
+
+ - Handles and processes the controller’s incoming ARP packets
+
+ - Uses **PacketDispatcher** to send the ARP packet back into the
+ network
+
+- **PacketDispatcher**
+
+ - Only created when *is-proactive-flood-mode* is false
+
+ - Sends packets out to the network
+
+ - Uses **InventoryReader** to determine which node-connector to a
+ send a packet on
+
+- **InventoryReader**
+
+ - Only created when *is-proactive-flood-mode* is false
+
+ - Maintains a list of each switch’s node-connectors
+
+Configuration
+^^^^^^^^^^^^^
+
+- is-proactive-flood-mode
+
+ - "true" means that flood flows will be installed on each switch.
+ With this flood flow, each switch will flood a packet that doesn’t
+ match any other flows.
+
+ - Advantage: Fewer packets are sent to the controller because
+ those packets are flooded to the network.
+
+ - Disadvantage: A lot of network traffic is generated.
+
+ - "false" means the previously mentioned flood flows will not be
+ installed. Instead an ARP flow will be installed on each switch
+ that sends all ARP packets to the controller.
+
+ - Advantage: Less network traffic is generated.
+
+ - Disadvantage: The controller handles more packets (ARP requests
+ & replies) and the ARP process takes longer than if there were
+ flood flows.
+
+- flood-flow-table-id
+
+ - The flood flow will be installed on the specified flow table of
+ each switch
+
+- flood-flow-priority
+
+ - The flood flow will be installed with the specified priority
+
+- flood-flow-idle-timeout
+
+ - The flood flow will timeout (removed from the switch) if the flow
+ doesn’t forward a packet for *x* seconds
+
+- flood-flow-hard-timeout
+
+ - The flood flow will timeout (removed from the switch) after *x*
+ seconds, regardless of how many packets it is forwarding
+
+- arp-flow-table-id
+
+ - The ARP flow will be installed on the specified flow table of each
+ switch
+
+- arp-flow-priority
+
+ - The ARP flow will be installed with the specified priority
+
+- arp-flow-idle-timeout
+
+ - The ARP flow will timeout (removed from the switch) if the flow
+ doesn’t forward a packet for *x* seconds
+
+- arp-flow-hard-timeout
+
+ - The ARP flow will timeout (removed from the switch) after
+ *arp-flow-hard-timeout* seconds, regardless of how many packets it
+ is forwarding
+
+Further development
+^^^^^^^^^^^^^^^^^^^
+
+The **ProactiveFloodFlowWriter** needs to be improved. It does have the
+advantage of having less traffic come to the controller; however, it
+generates too much network traffic.
+
+Address Tracker
+~~~~~~~~~~~~~~~
+
+Classes
+^^^^^^^
+
+- AddressTrackerModule
+
+ - Reads config subsystem value for *observe-addresses-from*
+
+ - If *observe-addresses-from* contains "arp", then an
+ AddressObserverUsingArp is created
+
+ - If *observe-addresses-from* contains "ipv4", then an
+ AddressObserverUsingIpv4 is created
+
+ - If *observe-addresses-from* contains "ipv6", then an
+ AddressObserverUsingIpv6 is created
+
+- AddressObserverUsingArp
+
+ - Registers for ARP packet notifications
+
+ - Uses **AddressObservationWriter** to write address observations
+ from ARP packets
+
+- AddressObserverUsingIpv4
+
+ - Registers for IPv4 packet notifications
+
+ - Uses **AddressObservationWriter** to write address observations
+ from IPv4 packets
+
+- AddressObserverUsingIpv6
+
+ - Registers for IPv6 packet notifications
+
+ - Uses **AddressObservationWriter** to write address observations
+ from IPv6 packets
+
+- AddressObservationWriter
+
+ - Writes new Address Observations to the Inventory data tree
+
+ - Updates existing Address Observations with updated "last seen"
+ timestamps
+
+ - Uses the *timestamp-update-intervval* configuration variable to
+ determine whether or not to update
+
+Configuration
+^^^^^^^^^^^^^
+
+- timestamp-update-interval
+
+ - A last-seen timestamp is associated with each address. This
+ last-seen timestamp will only be updated after
+ *timestamp-update-interval* milliseconds.
+
+ - A higher value has the advantage of performing less writes to the
+ database.
+
+ - A lower value has the advantage of knowing how fresh an address
+ is.
+
+- observe-addresses-from
+
+ - IP and MAC addresses can be observed/learned from ARP, IPv4, and
+ IPv6 packets. Set which packets to make these observations from.
+
+Further development
+^^^^^^^^^^^^^^^^^^^
+
+Further improvements can be made to the **AddressObservationWriter** so
+that it (1) doesn’t make any unnecessary writes to the DB and (2) is
+optimized for multi-threaded environments.
+
+Validating changes to Address Tracker
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Address Observations are added to the Inventory data tree.
+
+The Address Observations on a Node Connector can be checked through a
+browser or a REST Client.
+
+::
+
+ http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
+
+The Address Observations should still be there after changes.
+
+Developer’s Guide for Host Tracker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Validationg changes to Host Tracker
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Host information is added to the Topology data tree.
+
+- Host address
+
+- Attachment point (link) to a node/switch
+
+This host information and attachment point information can be checked
+through a browser or a REST Client.
+
+::
+
+ http://10.194.126.91:8080/restconf/operational/network-topology:network-topology/topology/flow:1/
+
+Host information should still be there after changes.
+
+L2Switch Main
+~~~~~~~~~~~~~
+
+Classes
+^^^^^^^
+
+- L2SwitchMainModule
+
+ - Reads config subsystem value for *is-install-dropall-flow*
+
+ - If *is-install-dropall-flow* is true, then an
+ **InitialFlowWriter** is created
+
+ - Reads config subsystem value for *is-learning-only-mode*
+
+ - If *is-learning-only-mode* is false, then a
+ **ReactiveFlowWriter** is created
+
+- InitialFlowWriter
+
+ - Only created when *is-install-dropall-flow* is true
+
+ - Installs a flow, which drops all packets, on each switch. This
+ flow has low priority and means that packets that don’t match any
+ higher-priority flows will simply be dropped.
+
+- ReactiveFlowWriter
+
+ - Reacts to network traffic and installs MAC-to-MAC flows on
+ switches. These flows have matches based on MAC source and MAC
+ destination.
+
+ - Uses **FlowWriterServiceImpl** to write these flows to the
+ switches
+
+- FlowWriterService / FlowWriterServiceImpl
+
+ - Writes flows to switches
+
+Configuration
+^^^^^^^^^^^^^
+
+- is-install-dropall-flow
+
+ - "true" means a drop-all flow will be installed on each switch, so
+ the default action will be to drop a packet instead of sending it
+ to the controller
+
+ - "false" means this flow will not be installed
+
+- dropall-flow-table-id
+
+ - The dropall flow will be installed on the specified flow table of
+ each switch
+
+ - This field is only relevant when "is-install-dropall-flow" is set
+ to "true"
+
+- dropall-flow-priority
+
+ - The dropall flow will be installed with the specified priority
+
+ - This field is only relevant when "is-install-dropall-flow" is set
+ to "true"
+
+- dropall-flow-idle-timeout
+
+ - The dropall flow will timeout (removed from the switch) if the
+ flow doesn’t forward a packet for *x* seconds
+
+ - This field is only relevant when "is-install-dropall-flow" is set
+ to "true"
+
+- dropall-flow-hard-timeout
+
+ - The dropall flow will timeout (removed from the switch) after *x*
+ seconds, regardless of how many packets it is forwarding
+
+ - This field is only relevant when "is-install-dropall-flow" is set
+ to "true"
+
+- is-learning-only-mode
+
+ - "true" means that the L2Switch will only be learning addresses. No
+ additional flows to optimize network traffic will be installed.
+
+ - "false" means that the L2Switch will react to network traffic and
+ install flows on the switches to optimize traffic. Currently,
+ MAC-to-MAC flows are installed.
+
+- reactive-flow-table-id
+
+ - The reactive flow will be installed on the specified flow table of
+ each switch
+
+ - This field is only relevant when "is-learning-only-mode" is set to
+ "false"
+
+- reactive-flow-priority
+
+ - The reactive flow will be installed with the specified priority
+
+ - This field is only relevant when "is-learning-only-mode" is set to
+ "false"
+
+- reactive-flow-idle-timeout
+
+ - The reactive flow will timeout (removed from the switch) if the
+ flow doesn’t forward a packet for *x* seconds
+
+ - This field is only relevant when "is-learning-only-mode" is set to
+ "false"
+
+- reactive-flow-hard-timeout
+
+ - The reactive flow will timeout (removed from the switch) after *x*
+ seconds, regardless of how many packets it is forwarding
+
+ - This field is only relevant when "is-learning-only-mode" is set to
+ "false"
+
+Further development
+^^^^^^^^^^^^^^^^^^^
+
+The **ReactiveFlowWriter** needs to be improved to install the
+MAC-to-MAC flows faster. For the first ping, the ARP request and reply
+are successful. However, then the ping packets are sent out. The first
+ping packet is dropped sometimes because the MAC-to-MAC flow isn’t
+installed quickly enough. The second, third, and following ping packets
+are successful though.
+
+API Reference Documentation
+---------------------------
+
+Further documentation can be found by checking out the L2Switch project.
+
+Checking out the L2Switch project
+---------------------------------
+
+::
+
+ git clone https://git.opendaylight.org/gerrit/p/l2switch.git
+
+The above command will create a directory called "l2switch" with the
+project.
+
+Testing your changes to the L2Switch project
+--------------------------------------------
+
+Running the L2Switch project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To run the base distribution, you can use the following command
+
+::
+
+ ./distribution/base/target/distributions-l2switch-base-0.1.0-SNAPSHOT-osgipackage/opendaylight/run.sh
+
+If you need additional resources, you can use these command line
+arguments:
+
+::
+
+ -Xms1024m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=1024m'
+
+To run the karaf distribution, you can use the following command:
+
+::
+
+ ./distribution/karaf/target/assembly/bin/karaf
+
+Create a network using mininet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ sudo mn --controller=remote,ip=<Controller IP> --topo=linear,3 --switch ovsk,protocols=OpenFlow13
+ sudo mn --controller=remote,ip=127.0.0.1 --topo=linear,3 --switch ovsk,protocols=OpenFlow13
+
+The above command will create a virtual network consisting of 3
+switches. Each switch will connect to the controller located at the
+specified IP, i.e. 127.0.0.1
+
+::
+
+ sudo mn --controller=remote,ip=127.0.0.1 --mac --topo=linear,3 --switch ovsk,protocols=OpenFlow13
+
+The above command has the "mac" option, which makes it easier to
+distinguish between Host MAC addresses and Switch MAC addresses.
+
+Generating network traffic using mininet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ h1 ping h2
+
+The above command will cause host1 (h1) to ping host2 (h2)
+
+::
+
+ pingall
+
+*pingall* will cause each host to ping every other host.
+
+Miscellaneous mininet commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ link s1 s2 down
+
+This will bring the link between switch1 (s1) and switch2 (s2) down
+
+::
+
+ link s1 s2 up
+
+This will bring the link between switch1 (s1) and switch2 (s2) up
+
+::
+
+ link s1 h1 down
+
+This will bring the link between switch1 (s1) and host1 (h1) down
+
--- /dev/null
+LACP Developer Guide
+====================
+
+LACP Overview
+-------------
+
+The OpenDaylight LACP (Link Aggregation Control Protocol) project can be
+used to aggregate multiple links between OpenDaylight controlled network
+switches and LACP enabled legacy switches or hosts operating in active
+LACP mode.
+
+OpenDaylight LACP passively negotiates automatic bundling of multiple
+links to form a single LAG (Link Aggregation Group). LAGs are realised
+in the OpenDaylight controlled switches using OpenFlow 1.3+ group table
+functionality.
+
+LACP Architecture
+-----------------
+
+- **inventory**
+
+ - Maintains list of OpenDaylight controlled switches and port
+ information
+
+ - List of LAGs created and physical ports that are part of the LAG
+
+ - Interacts with MD-SAL to update LACP related information
+
+- **inventorylistener**
+
+ - This module interacts with MD-SAL for receiving
+ node/node-connector notifications
+
+- **flow**
+
+ - Programs the switch to punt LACP PDU (Protocol Data Unit) to
+ controller
+
+- **packethandler**
+
+ - Receives and transmits LACP PDUs to the LACP enabled endpoint
+
+ - Provides infrastructure services for group table programming
+
+- **core**
+
+ - Performs LACP state machine processing
+
+How LAG programming is implemented
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The LAG representing the aggregated multiple physical ports are realized
+in the OpenDaylight controlled switches by creating a group table entry
+(Group table supported from OpenFlow 1.3 onwards). The group table entry
+has a group type **Select** and action referring to the aggregated
+physical ports. Any data traffic to be sent out through the LAG can be
+sent through the **group entry** available for the LAG.
+
+Suppose there are ports P1-P8 in a node. When LACP project is installed,
+a group table entry for handling broadcast traffic is automatically
+created on all the switches that have registered to the controller.
+
++--------------------------+--------------------------+--------------------------+
+| GroupID | GroupType | EgressPorts |
++==========================+==========================+==========================+
+| <B’castgID> | ALL | P1,P2,…P8 |
++--------------------------+--------------------------+--------------------------+
+
+Now, assume P1 & P2 are now part of LAG1. The group table would be
+programmed as follows:
+
++--------------------------+--------------------------+--------------------------+
+| GroupID | GroupType | EgressPorts |
++==========================+==========================+==========================+
+| <B’castgID> | ALL | P3,P4,…P8 |
++--------------------------+--------------------------+--------------------------+
+| <LAG1> | SELECT | P1,P2 |
++--------------------------+--------------------------+--------------------------+
+
+When a second LAG, LAG2, is formed with ports P3 and P4,
+
++--------------------------+--------------------------+--------------------------+
+| GroupID | GroupType | EgressPorts |
++==========================+==========================+==========================+
+| <B’castgID> | ALL | P5,P6,…P8 |
++--------------------------+--------------------------+--------------------------+
+| <LAG1> | SELECT | P1,P2 |
++--------------------------+--------------------------+--------------------------+
+| <LAG2> | SELECT | P3,P4 |
++--------------------------+--------------------------+--------------------------+
+
+How applications can program OpenFlow flows using LACP-created LAG groups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenDaylight controller modules can get the information of LAG by
+listening/querying the LACP Aggregator datastore.
+
+When any application receives packets, it can check, if the ingress port
+is part of a LAG by verifying the LAG Aggregator reference
+(lacp-agg-ref) for the source nodeConnector that OpenFlow plugin
+provides.
+
+When applications want to add flows to egress out of the LAG, they must
+use the group entry corresponding to the LAG.
+
+From the above example, for a flow to egress out of LAG1,
+
+**add-flow eth\_type=<xxxx>,ip\_dst=<x.x.x.x>,actions=output:<LAG1>**
+
+Similarly, when applications want traffic to be broadcasted, they should
+use the group table entries **<B’castgID>,<LAG1>,<LAG2>** in output
+action.
+
+For all applications, the group table information is accessible from
+LACP Aggregator datastore.
+
--- /dev/null
+NetIDE Developer Guide
+======================
+
+Overview
+--------
+
+The NetIDE Network Engine enables portability and cooperation inside a
+single network by using a client/server multi-controller SDN
+architecture. Separate "Client SDN Controllers" host the various SDN
+Applications with their access to the actual physical network abstracted
+and coordinated through a single "Server SDN Controller", in this
+instance OpenDaylight. This allows applications written for
+Ryu/Floodlight/Pyretic to execute on OpenDaylight managed
+infrastructure.
+
+The "Network Engine" is modular by design:
+
+- An OpenDaylight plugin, "shim", sends/receives messages to/from
+ subscribed SDN Client Controllers. This consumes the ODL OpenFlow
+ Plugin
+
+- An initial suite of SDN Client Controller "Backends": Floodlight,
+ Ryu, Pyretic. Further controllers may be added over time as the
+ engine is extensible.
+
+The Network Engine provides a compatibility layer capable of translating
+calls of the network applications running on top of the client
+controllers, into calls for the server controller framework. The
+communication between the client and the server layers is achieved
+through the NetIDE intermediate protocol, which is an application-layer
+protocol on top of TCP that transmits the network control/management
+messages from the client to the server controller and vice-versa.
+Between client and server controller sits the Core Layer which also
+"speaks" the intermediate protocol. The core layer implements three main
+functions:
+
+i. interfacing with the client backends and server shim, controlling
+ the lifecycle of controllers as well as modules in them,
+
+ii. orchestrating the execution of individual modules (in one client
+ controller) or complete applications (possibly spread across
+ multiple client controllers),
+
+iii. interfacing with the tools.
+
+.. figure:: ./images/netide/arch-engine.jpg
+ :alt: NetIDE Network Engine Architecture
+
+ NetIDE Network Engine Architecture
+
+NetIDE Intermediate Protocol
+----------------------------
+
+The Intermediate Protocol serves several needs, it has to:
+
+i. carry control messages between core and shim/backend, e.g., to
+ start up/take down a particular module, providing unique
+ identifiers for modules,
+
+ii. carry event and action messages between shim, core, and backend,
+ properly demultiplexing such messages to the right module based on
+ identifiers,
+
+iii. encapsulate messages specific to a particular SBI protocol version
+ (e.g., OpenFlow 1.X, NETCONF, etc.) towards the client controllers
+ with proper information to recognize these messages as such.
+
+The NetIDE packages can be added as dependencies in Maven projects by
+putting the following code in the *pom.xml* file.
+
+::
+
+ <dependency>
+ <groupId>org.opendaylight.netide</groupId>
+ <artifactId>api</artifactId>
+ <version>${NETIDE_VERSION}</version>
+ </dependency>
+
+The current stable version for NetIDE is ``0.1.0-Beryllium``.
+
+Protocol specification
+~~~~~~~~~~~~~~~~~~~~~~
+
+Messages of the NetIDE protocol contain two basic elements: the NetIDE
+header and the data (or payload). The NetIDE header, described below, is
+placed before the payload and serves as the communication and control
+link between the different components of the Network Engine. The payload
+can contain management messages, used by the components of the Network
+Engine to exchange relevant information, or control/configuration
+messages (such as OpenFlow, NETCONF, etc.) crossing the Network Engine
+generated by either network application modules or by the network
+elements.
+
+The NetIDE header is defined as follows:
+
+::
+
+ 0 1 2 3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | netide_ver | type | length |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | xid |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | module_id |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | |
+ + datapath_id +
+ | |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+where each tick mark represents one bit position. Alternatively, in a
+C-style coding format, the NetIDE header can be represented with the
+following structure:
+
+::
+
+ struct netide_header {
+ uint8_t netide_ver ;
+ uint8_t type ;
+ uint16_t length ;
+ uint32_t xid
+ uint32_t module_id
+ uint64_t datapath_id
+ };
+
+- ``netide_ver`` is the version of the NetIDE protocol (the current
+ version is v1.2, which is identified with value 0x03).
+
+- ``length`` is the total length of the payload in bytes.
+
+- ``type`` contains a code that indicates the type of the message
+ according with the following values:
+
+ ::
+
+ enum type {
+ NETIDE_HELLO = 0x01 ,
+ NETIDE_ERROR = 0x02 ,
+ NETIDE_MGMT = 0x03 ,
+ MODULE_ANNOUNCEMENT = 0x04 ,
+ MODULE_ACKNOWLEDGE = 0x05 ,
+ NETIDE_HEARTBEAT = 0x06 ,
+ NETIDE_OPENFLOW = 0x11 ,
+ NETIDE_NETCONF = 0x12 ,
+ NETIDE_OPFLEX = 0x13
+ };
+
+- ``datapath_id`` is a 64-bit field that uniquely identifies the
+ network elements.
+
+- ``module_id`` is a 32-bits field that uniquely identifies Backends
+ and application modules running on top of each client controller. The
+ composition mechanism in the core layer leverages on this field to
+ implement the correct execution flow of these modules.
+
+- ``xid`` is the transaction identifier associated to the each message.
+ Replies must use the same value to facilitate the pairing.
+
+Module announcement
+~~~~~~~~~~~~~~~~~~~
+
+The first operation performed by a Backend is registering itself and the
+modules that it is running to the Core. This is done by using the
+``MODULE_ANNOUNCEMENT`` and ``MODULE_ACKNOWLEDGE`` message types. As a
+result of this process, each Backend and application module can be
+recognized by the Core through an identifier (the ``module_id``) placed
+in the NetIDE header. First, a Backend registers itself by using the
+following schema: backend-<platform name>-<pid>.
+
+For example,odule a Ryu Backend will register by using the following
+name in the message backend-ryu-12345 where 12345 is the process ID of
+the registering instance of the Ryu platform. The format of the message
+is the following:
+
+::
+
+ struct NetIDE_message {
+ netide_ver = 0x03
+ type = MODULE_ANNOUNCEMENT
+ length = len(" backend -< platform_name >-<pid >")
+ xid = 0
+ module_id = 0
+ datapath_id = 0
+ data = " backend -< platform_name >-<pid >"
+ }
+
+The answer generated by the Core will include a ``module_id`` number and
+the Backend name in the payload (the same indicated in the
+``MODULE_ANNOUNCEMENT`` message):
+
+::
+
+ struct NetIDE_message {
+ netide_ver = 0x03
+ type = MODULE_ACKNOWLEDGE
+ length = len(" backend -< platform_name >-<pid >")
+ xid = 0
+ module_id = MODULE_ID
+ datapath_id = 0
+ data = " backend -< platform_name >-<pid >"
+ }
+
+Once a Backend has successfully registered itself, it can start
+registering its modules with the same procedure described above by
+indicating the name of the module in the data (e.g. data="Firewall").
+From this point on, the Backend will insert its own ``module_id`` in the
+header of the messages it generates (e.g. heartbeat, hello messages,
+OpenFlow echo messages from the client controllers, etc.). Otherwise, it
+will encapsulate the control/configuration messages (e.g. FlowMod,
+PacketOut, FeatureRequest, NETCONF request, etc.) generated by network
+application modules with the specific +module\_id+s.
+
+Heartbeat
+~~~~~~~~~
+
+The heartbeat mechanism has been introduced after the adoption of the
+ZeroMQ messaging queuing library to transmit the NetIDE messages.
+Unfortunately, the ZeroMQ library does not offer any mechanism to find
+out about disrupted connections (and also completely unresponsive
+peers). This limitation of the ZeroMQ library can be an issue for the
+Core’s composition mechanism and for the tools connected to the Network
+Engine, as they cannot understand when an client controller disconnects
+or crashes. As a consequence, Backends must periodically send (let’s say
+every 5 seconds) a "heartbeat" message to the Core. If the Core does not
+receive at least one "heartbeat" message from the Backend within a
+certain timeframe, the Core considers it disconnected, removes all the
+related data from its memory structures and informs the relevant tools.
+The format of the message is the following:
+
+::
+
+ struct NetIDE_message {
+ netide_ver = 0x03
+ type = NETIDE_HEARTBEAT
+ length = 0
+ xid = 0
+ module_id = backend -id
+ datapath_id = 0
+ data = 0
+ }
+
+Handshake
+~~~~~~~~~
+
+Upon a successful connection with the Core, the client controller must
+immediately send a hello message with the list of the control and/or
+management protocols needed by the applications deployed on top of it.
+
+::
+
+ struct NetIDE_message {
+ struct netide_header header ;
+ uint8 data [0]
+ };
+
+The header contains the following values:
+
+- ``netide ver=0x03``
+
+- ``type=NETIDE_HELLO``
+
+- ``length=2*NR_PROTOCOLS``
+
+- ``data`` contains one 2-byte word (in big endian order) for each
+ protocol, with the first byte containing the code of the protocol
+ according to the above enum, while the second byte in- dictates the
+ version of the protocol (e.g. according to the ONF specification,
+ 0x01 for OpenFlow v1.0, 0x02 for OpenFlow v1.1, etc.). NETCONF
+ version is marked with 0x01 that refers to the specification in the
+ RFC6241, while OpFlex version is marked with 0x00 since this protocol
+ is still in work-in-progress stage.
+
+The Core relays hello messages to the server controller which responds
+with another hello message containing the following:
+
+- ``netide ver=0x03``
+
+- ``type=NETIDE_HELLO``
+
+- ``length=2*NR_PROTOCOLS``
+
+If at least one of the protocols requested by the client is supported.
+In particular, ``data`` contains the codes of the protocols that match
+the client’s request (2-bytes words, big endian order). If the hand-
+shake fails because none of the requested protocols is supported by the
+server controller, the header of the answer is as follows:
+
+- ``netide ver=0x03``
+
+- ``type=NETIDE_ERROR``
+
+- ``length=2*NR_PROTOCOLS``
+
+- ``data`` contains the codes of all the protocols supported by the
+ server controller (2-bytes words, big endian order). In this case,
+ the TCP session is terminated by the server controller just after the
+ answer is received by the client. \`
+
--- /dev/null
+Network Intent Composition (NIC) Developer Guide
+================================================
+
+Overview
+--------
+
+The Network Intent Composition (NIC) provides four features:
+
+- odl-nic-core-hazelcast: Provides a distributed intent mapping
+ service, implemented using hazelcast, that stores metadata needed by
+ odl-nic-core feature.
+
+- odl-nic-core-mdsal: Provides an intent rest API to external
+ applications for CRUD operations on intents, conflict resolution and
+ event handling. Uses MD-SAL as backend.
+
+- odl-nic-console: Provides a karaf CLI extension for intent CRUD
+ operations and mapping service operations.
+
+- odl-nic-renderer-of - Generic Openflow Renderer.
+
+- odl-nic-renderer-vtn - a feature that transforms an intent to a
+ network modification using the VTN project
+
+- odl-nic-renderer-gbp - a feature that transforms an intent to a
+ network modification using the Group Policy project
+
+- odl-nic-renderer-nemo - a feature that transforms an intent to a
+ network modification using the NEMO project
+
+- odl-nic-listeners - adds support for event listening. (depends on:
+ odl-nic-renderer-of)
+
+- odl-nic-neutron-integration - allow integration with openstack
+ neutron to allow coexistence between existing neutron security rules
+ and intents pushed by ODL applications.
+
+*Only a single renderer feature should be installed at a time for the
+Boron release.*
+
+odl-nic-core-mdsal XOR odl-nic-core-hazelcast
+---------------------------------------------
+
+This feature supplies the base models for the Network Intent Composition
+(NIC) capability. This includes the definition of intent as well as the
+configuration and operational data trees.
+
+This feature only provides an information model. The interface for NIC
+is to modify the information model via the configuraiton data tree,
+which will trigger the renderer to make the appropriate changes in the
+controlled network.
+
+Installation
+------------
+
+First you need to install one of the core installations:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ feature:install odl-nic-core-service-mdsal odl-nic-console
+
+*OR*
+
+::
+
+ feature:install odl-nic-core-service-hazelcast odl-nic-console
+
+Then pick a renderer:
+~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ feature:install odl-nic-listeners (will install odl-nic-renderer-of)
+
+*OR*
+
+::
+
+ feature:install odl-nic-renderer-vtn
+
+*OR*
+
+::
+
+ feature:install odl-nic-renderer-gbp
+
+*OR*
+
+::
+
+ feature:install odl-nic-renderer-nemo
+
+REST Supported operations
+-------------------------
+
+POST / PUT (configuration)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This operations create instances of an intent in the configuration data
+tree and trigger the creation or modification of an intent.
+
+GET (configuration / operational)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This operation lists all or fetches a single intent from the data tree.
+
+DELETE (configuration)
+~~~~~~~~~~~~~~~~~~~~~~
+
+This operation will cause an intent to be removed from the system and
+trigger any configuration changes on the network rendered from this
+intent to be removed.
+
+odl-nic-cli user guide
+----------------------
+
+This feature provides karaf console CLI command to manipulate the intent
+data model. The CLI essentailly invokes the equivalent data operations.
+
+intent:add
+~~~~~~~~~~
+
+Creates a new intent in the configuration data tree
+
+::
+
+ DESCRIPTION
+ intent:add
+
+ Adds an intent to the controller.
+
+ Examples: --actions [ALLOW] --from <subject> --to <subject>
+ --actions [BLOCK] --from <subject>
+
+ SYNTAX
+ intent:add [options]
+
+ OPTIONS
+ -a, --actions
+ Action to be performed.
+ -a / --actions BLOCK/ALLOW
+ (defaults to [BLOCK])
+ --help
+ Display this help message
+ -t, --to
+ Second Subject.
+ -t / --to <subject>
+ (defaults to any)
+ -f, --from
+ First subject.
+ -f / --from <subject>
+ (defaults to any)
+
+intent:delete
+~~~~~~~~~~~~~
+
+Removes an existing intent from the system
+
+::
+
+ DESCRIPTION
+ intent:remove
+
+ Removes an intent from the controller.
+
+ SYNTAX
+ intent:remove id
+
+ ARGUMENTS
+ id Intent Id
+
+intent:list
+~~~~~~~~~~~
+
+Lists all the intents in the system
+
+::
+
+ DESCRIPTION
+ intent:list
+
+ Lists all intents in the controller.
+
+ SYNTAX
+ intent:list [options]
+
+ OPTIONS
+ -c, --config
+ List Configuration Data (optional).
+ -c / --config <ENTER>
+ --help
+ Display this help message
+
+intent:show
+~~~~~~~~~~~
+
+Displays the details of a single intent
+
+::
+
+ DESCRIPTION
+ intent:show
+
+ Shows detailed information about an intent.
+
+ SYNTAX
+ intent:show id
+
+ ARGUMENTS
+ id Intent Id
+
+intent:map
+~~~~~~~~~~
+
+List/Add/Delete current state from/to the mapping service.
+
+::
+
+ DESCRIPTION
+ intent:map
+
+ List/Add/Delete current state from/to the mapping service.
+
+ SYNTAX
+ intent:map [options]
+
+ Examples: --list, -l [ENTER], to retrieve all keys.
+ --add-key <key> [ENTER], to add a new key with empty contents.
+ --del-key <key> [ENTER], to remove a key with it's values."
+ --add-key <key> --value [<value 1>, <value 2>, ...] [ENTER],
+ to add a new key with some values (json format).
+ OPTIONS
+ --help
+ Display this help message
+ -l, --list
+ List values associated with a particular key.
+ -l / --filter <regular expression> [ENTER]
+ --add-key
+ Adds a new key to the mapping service.
+ --add-key <key name> [ENTER]
+ --value
+ Specifies which value should be added/delete from the mapping service.
+ --value "key=>value"... --value "key=>value" [ENTER]
+ (defaults to [])
+ --del-key
+ Deletes a key from the mapping service.
+ --del-key <key name> [ENTER]
+
+Sample Use case: MPLS
+---------------------
+
+Description
+~~~~~~~~~~~
+
+The scope of this use-case is to add MPLS intents between two MPLS
+endpoints. The use-case tries to address the real-world scenario
+illustrated in the diagram below:
+
+.. figure:: ./images/nic/MPLS_VPN_Service_Diagram.png
+ :alt: MPLS VPN Service Diagram
+
+ MPLS VPN Service Diagram
+
+where PE (Provider Edge) and P (Provider) switches are managed by
+Opendaylight. In NIC’s terminology the endpoints are the PE switches.
+There could be many P switches between the PEs.
+
+In order for NIC to recognize endpoints as MPLS endpoints, the user is
+expected to add mapping information about the PE switches to NIC’s
+mapping service to include the below properties:
+
+1. MPLS Label to identify a PE
+
+2. IPv4 Prefix for the customer site that are connected to a PE
+
+3. Switch-Port: Ingress (or Egress) for source (or Destination) endpoint
+ of the source (or Destination) PE
+
+An intent:add between two MPLS endpoints renders Openflow rules for: 1.
+push/pop labels to the MPLS endpoint nodes after an IPv4 Prefix match.
+2. forward to port rule after MPLS label match to all the switches that
+form the shortest path between the endpoints (calculated using Dijkstra
+algorithm).
+
+Additionally, we have also added constraints to Intent model for
+protection and failover mechanism to ensure end-to-end connectivity
+between endpoints. By specifying these constraints to intent:add the
+use-case aims to reduces the risk of connectivity failure due to a
+single link or port down event on a forwarding device.
+
+- Protection constraint: Constraint that requires an end-to-end
+ connectivity to be protected by providing redundant paths.
+
+- Failover constraint: Constraint that specifies the type of failover
+ implementation. slow-reroute: Uses disjoint path calculation
+ algorithms like Suurballe to provide alternate end-to-end routes.
+ fast-reroute: Uses failure detection feature in hardware forwarding
+ device through OF group table features (Future plans) When no
+ constraint is requested by the user we default to offering a since
+ end-to-end route using Dijkstra shortest path.
+
+How to use it?
+~~~~~~~~~~~~~~
+
+1. Start Karaf and install related features:
+
+ ::
+
+ feature:install odl-nic-core-service-mdsal odl-nic-core odl-nic-console odl-nic-listeners
+ feature:install odl-dlux-all odl-dlux-core odl-dlux-yangui odl-dlux-yangvisualizer
+
+2. Start mininet topology and verify in DLUX Topology page for the nodes
+ and link.
+
+ ::
+
+ mn --controller=remote,ip=$CONTROLLER_IP --custom ~/shortest_path.py --topo shortest_path --switch ovsk,protocols=OpenFlow13
+
+ ::
+
+ cat shortest.py -->
+ from mininet.topo import Topo
+ from mininet.cli import CLI
+ from mininet.net import Mininet
+ from mininet.link import TCLink
+ from mininet.util import irange,dumpNodeConnections
+ from mininet.log import setLogLevel
+
+ ::
+
+ class Fast_Failover_Demo_Topo(Topo):
+
+ ::
+
+ def __init__(self):
+ # Initialize topology and default options
+ Topo.__init__(self)
+
+ ::
+
+ s1 = self.addSwitch('s1',dpid='0000000000000001')
+ s2a = self.addSwitch('s2a',dpid='000000000000002a')
+ s2b = self.addSwitch('s2b',dpid='000000000000002b')
+ s2c = self.addSwitch('s2c',dpid='000000000000002c')
+ s3 = self.addSwitch('s3',dpid='0000000000000003')
+ self.addLink(s1, s2a)
+ self.addLink(s1, s2b)
+ self.addLink(s2b, s2c)
+ self.addLink(s3, s2a)
+ self.addLink(s3, s2c)
+ host_1 = self.addHost('h1',ip='10.0.0.1',mac='10:00:00:00:00:01')
+ host_2 = self.addHost('h2',ip='10.0.0.2',mac='10:00:00:00:00:02')
+ self.addLink(host_1, s1)
+ self.addLink(host_2, s3)
+
+ ::
+
+ topos = { 'shortest_path': ( lambda: Demo_Topo() ) }
+
+3. Update the mapping service with required information
+
+ Sample payload:
+
+ ::
+
+ {
+ "mappings": {
+ "outer-map": [
+ {
+ "id": "uva",
+ "inner-map": [
+ {
+ "inner-key": "ip_prefix",
+ "value": "10.0.0.1/32"
+ },
+ {
+ "inner-key": "mpls_label",
+ "value": "15"
+ },
+ {
+ "inner-key": "switch_port",
+ "value": "openflow:1:1"
+ }
+ ]
+ },
+ {
+ "id": "eur",
+ "inner-map": [
+ {
+ "inner-key": "ip_prefix",
+ "value": "10.0.0.2/32"
+ },
+ {
+ "inner-key": "mpls_label",
+ "value": "16"
+ },
+ {
+ "inner-key": "switch_port",
+ "value": "openflow:3:1"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+4. Create bidirectional Intents using Karaf command line or RestCONF:
+
+ Example:
+
+ ::
+
+ intent:add -f uva -t eur -a ALLOW
+ intent:add -f eur -t uva -a ALLOW
+
+5. Verify by running ovs command on mininet if the flows were pushed
+ correctly to the nodes that form the shortest path.
+
+ Example:
+
+ ::
+
+ ovs-ofctl -O OpenFlow13 dump-flows s1
+
--- /dev/null
+Neutron Northbound
+==================
+
+How to add new API support
+--------------------------
+
+OpenStack Neutron is a moving target. It is continuously adding new
+features as new rest APIs. Here is a basic step to add new API support:
+
+In the Neutron Northbound project:
+
+- Add new YANG model for it under ``neutron/model/src/main/yang`` and
+ ``update neutron.yang``
+
+- Add northbound API for it, and neutron-spi
+
+ - Implement ``Neutron<New API>Request.java`` and
+ ``Neutron<New API>Norhtbound.java`` under
+ ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/``
+
+ - Implement ``INeutron<New API>CRUD.java`` and new data structure if
+ any under
+ ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/``
+
+ - update
+ ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/NeutronCRUDInterfaces.java``
+ to wire new CRUD interface
+
+ - Add unit tests, ``Neutron<New structure>JAXBTest.java`` under
+ ``neutron/neutron-spi/src/test/java/org/opendaylight/neutron/spi/``
+
+- update
+ ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/NeutronNorthboundRSApplication.java``
+ to wire new northbound api to ``RSApplication``
+
+- Add transcriber, ``Neutron<New API>Interface.java`` under
+ ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/``
+
+- update
+ ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/NeutronTranscriberProvider.java``
+ to wire a new transcriber
+
+ - Add integration tests ``Neutron<New API>Tests.java`` under
+ ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/``
+
+ - update
+ ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/ITNeutronE2E.java``
+ to run a newly added tests.
+
+In OpenStack networking-odl
+
+- Add new driver (or plugin) for new API with tests.
+
+In a southbound Neutron Provider
+
+- implement actual backend to realize those new API by listening
+ related YANG models.
+
+How to write transcriber
+------------------------
+
+For each Neutron data object, there is an ``Neutron*Interface`` defined
+within the transcriber artifact that will write that object to the
+MD-SAL configuration datastore.
+
+All ``Neutron*Interface`` extend ``AbstractNeutronInterface``, in which
+two methods are defined:
+
+- one takes the Neutron object as input, and will create a data object
+ from it.
+
+- one takes an uuid as input, and will create a data object containing
+ the uuid.
+
+::
+
+ protected abstract T toMd(S neutronObject);
+ protected abstract T toMd(String uuid);
+
+In addition the ``AbstractNeutronInterface`` class provides several
+other helper methods (``addMd``, ``updateMd``, ``removeMd``), which
+handle the actual writing to the configuration datastore.
+
+The semantics of the ``toMD()`` methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each of the Neutron YANG models defines structures containing data.
+Further each YANG-modeled structure has it own builder. A particular
+``toMD()`` method instantiates an instance of the correct builder, fills
+in the properties of the builder from the corresponding values of the
+Neutron object and then creates the YANG-modeled structures via the
+``build()`` method.
+
+As an example, one of the ``toMD`` code for Neutron Networks is
+presented below:
+
+::
+
+ protected Network toMd(NeutronNetwork network) {
+ NetworkBuilder networkBuilder = new NetworkBuilder();
+ networkBuilder.setAdminStateUp(network.getAdminStateUp());
+ if (network.getNetworkName() != null) {
+ networkBuilder.setName(network.getNetworkName());
+ }
+ if (network.getShared() != null) {
+ networkBuilder.setShared(network.getShared());
+ }
+ if (network.getStatus() != null) {
+ networkBuilder.setStatus(network.getStatus());
+ }
+ if (network.getSubnets() != null) {
+ List<Uuid> subnets = new ArrayList<Uuid>();
+ for( String subnet : network.getSubnets()) {
+ subnets.add(toUuid(subnet));
+ }
+ networkBuilder.setSubnets(subnets);
+ }
+ if (network.getTenantID() != null) {
+ networkBuilder.setTenantId(toUuid(network.getTenantID()));
+ }
+ if (network.getNetworkUUID() != null) {
+ networkBuilder.setUuid(toUuid(network.getNetworkUUID()));
+ } else {
+ logger.warn("Attempting to write neutron network without UUID");
+ }
+ return networkBuilder.build();
+ }
+
--- /dev/null
+Neutron Service Developer Guide
+===============================
+
+Overview
+--------
+
+This Karaf feature (``odl-neutron-service``) provides integration
+support for OpenStack Neutron via the OpenDaylight ML2 mechanism driver.
+The Neutron Service is only one of the components necessary for
+OpenStack integration. It defines YANG models for OpenStack Neutron data
+models and northbound API via REST API and YANG model RESTCONF.
+
+Those developers who want to add new provider for new OpenStack Neutron
+extensions/services (Neutron constantly adds new extensions/services and
+OpenDaylight will keep up with those new things) need to communicate
+with this Neutron Service or add models to Neutron Service. If you want
+to add new extensions/services themselves to the Neutron Service, new
+YANG data models need to be added, but that is out of scope of this
+document because this guide is for a developer who will be *using* the
+feature to build something separate, but *not* somebody who will be
+developing code for this feature itself.
+
+Neutron Service Architecture
+----------------------------
+
+.. figure:: ./images/neutron/odl-neutron-service-developer-architecture.png
+ :alt: Neutron Service Architecture
+
+ Neutron Service Architecture
+
+The Neutron Service defines YANG models for OpenStack Neutron
+integration. When OpenStack admins/users request changes
+(creation/update/deletion) of Neutron resources, e.g., Neutron network,
+Neutron subnet, Neutron port, the corresponding YANG model within
+OpenDaylight will be modified. The OpenDaylight OpenStack will subscribe
+the changes on those models and will be notified those modification
+through MD-SAL when changes are made. Then the provider will do the
+necessary tasks to realize OpenStack integration. How to realize it (or
+even not realize it) is up to each provider. The Neutron Service itself
+does not take care of it.
+
+How to Write a SB Neutron Consumer
+----------------------------------
+
+In Boron, there is only one options for SB Neutron Consumers:
+
+- Listening for changes via the Neutron YANG model
+
+Until Beryllium there was another way with the legacy I\*Aware
+interface. From Boron, the interface was eliminated. So all the SB
+Neutron Consumers have to use Neutron YANG model.
+
+Neutron YANG models
+-------------------
+
+Neutron service defines YANG models for Neutron. The details can be
+found at
+
+- https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=tree;f=model/src/main/yang;hb=refs/heads/stable/boron
+
+Basically those models are based on OpenStack Neutron API definitions.
+For exact definitions, OpenStack Neutron source code needs to be
+referred as the above documentation doesn’t always cover the necessary
+details. There is nothing special to utilize those Neutron YANG models.
+The basic procedure will be:
+
+1. subscribe for changes made to the the model
+
+2. respond on the data change notification for each models
+
+.. note::
+
+ Currently there is no way to refuse the request configuration at
+ this point. That is left to future work.
+
+.. code:: java
+
+ public class NeutronNetworkChangeListener implements DataChangeListener, AutoCloseable {
+ private ListenerRegistration<DataChangeListener> registration;
+ private DataBroker db;
+
+ public NeutronNetworkChangeListener(DataBroker db){
+ this.db = db;
+ // create identity path to register on service startup
+ InstanceIdentifier<Network> path = InstanceIdentifier
+ .create(Neutron.class)
+ .child(Networks.class)
+ .child(Network.class);
+ LOG.debug("Register listener for Neutron Network model data changes");
+ // register for Data Change Notification
+ registration =
+ this.db.registerDataChangeListener(LogicalDatastoreType.CONFIGURATION, path, this, DataChangeScope.ONE);
+
+ }
+
+ @Override
+ public void onDataChanged(
+ AsyncDataChangeEvent<InstanceIdentifier<?>, DataObject> changes) {
+ LOG.trace("Data changes : {}",changes);
+
+ // handle data change notification
+ Object[] subscribers = NeutronIAwareUtil.getInstances(INeutronNetworkAware.class, this);
+ createNetwork(changes, subscribers);
+ updateNetwork(changes, subscribers);
+ deleteNetwork(changes, subscribers);
+ }
+ }
+
+Neutron configuration
+---------------------
+
+From Boron, new models of configuration for OpenDaylight to tell
+OpenStack neutron/networking-odl its configuration/capability.
+
+hostconfig
+~~~~~~~~~~
+
+This is for OpenDaylight to tell per-node configuration to Neutron.
+Especially this is used by pseudo agent port binding heavily.
+
+The model definition can be found at
+
+- https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-hostconfig.yang;hb=refs/heads/stable/boron
+
+How to populate this for pseudo agent port binding is documented at
+
+- http://git.openstack.org/cgit/openstack/networking-odl/tree/doc/source/devref/hostconfig.rst
+
+Neutron extension config
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Boron this is experimental. The model definition can be found at
+
+- https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-extensions.yang;hb=refs/heads/stable/boron
+
+Each Neutron Service provider has its own feature set. Some support the
+full features of OpenStack, but others support only a subset. With same
+supported Neutron API, some functionality may or may not be supported.
+So there is a need for a way that OpenDaylight can tell networking-odl
+its capability. Thus networking-odl can initialize Neutron properly
+based on reported capability.
+
+Neutorn Logger
+--------------
+
+There is another small Karaf feature, ``odl-neutron-logger``, which logs
+changes of Neutron YANG models. which can be used for debug/audit.
+
+It would also help to understand how to listen the change.
+
+- https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=neutron-logger/src/main/java/org/opendaylight/neutron/logger/NeutronLogger.java;hb=refs/heads/stable/boron
+
+API Reference Documentation
+---------------------------
+
+The OpenStack Neutron API references
+
+- http://developer.openstack.org/api-ref-networking-v2.html
+
+- http://developer.openstack.org/api-ref-networking-v2-ext.html
+
--- /dev/null
+ODL Parent Developer Guide
+==========================
+
+Parent POMs
+-----------
+
+Overview
+~~~~~~~~
+
+The ODL Parent component for OpenDaylight provides a number of Maven
+parent POMs which allow Maven projects to be easily integrated in the
+OpenDaylight ecosystem. Technically, the aim of projects in OpenDaylight
+is to produce Karaf features, and these parent projects provide common
+support for the different types of projects involved.
+
+| These parent projects are:
+
+- ``odlparent-lite`` — the basic parent POM for Maven modules which
+ don’t produce artifacts (*e.g.* aggregator POMs)
+
+- ``odlparent`` — the common parent POM for Maven modules containing
+ Java code
+
+- ``bundle-parent`` — the parent POM for Maven modules producing OSGi
+ bundles
+
+- ``features-parent`` — the parent POM for Maven modules producing
+ Karaf features
+
+odlparent-lite
+~~~~~~~~~~~~~~
+
+| This is the base parent for all OpenDaylight Maven projects and
+ modules. It provides the following, notably to allow publishing
+ artifacts to Maven Central:
+
+- license information;
+
+- organization information;
+
+- issue management information (a link to our Bugzilla);
+
+- continuous integration information (a link to our Jenkins setup);
+
+- default Maven plugins (``maven-clean-plugin``,
+ ``maven-deploy-plugin``, ``maven-install-plugin``,
+ ``maven-javadoc-plugin`` with HelpMojo support,
+ ``maven-project-info-reports-plugin``, ``maven-site-plugin`` with
+ Asciidoc support, ``jdepend-maven-plugin``);
+
+- distribution management information.
+
+It also defines two profiles which help during development:
+
+- ``q`` (``-Pq``), the quick profile, which disables tests, code
+ coverage, Javadoc generation, code analysis, etc. — anything which
+ isn’t necessary to build the bundles and features (see `this blog
+ post <http://blog2.vorburger.ch/2016/06/improve-maven-build-speed-with-q.html>`__
+ for details);
+
+- ``addInstallRepositoryPath``
+ (``-DaddInstallRepositoryPath=…/karaf/system``) which can be used to
+ drop a bundle in the appropriate Karaf location, to enable
+ hot-reloading of bundles during development (see `this blog
+ post <http://blog2.vorburger.ch/2016/06/maven-install-into-additional.html>`__
+ for details).
+
+For modules which don’t produce any useful artifacts (*e.g.* aggregator
+POMs), you should add the following to avoid processing artifacts:
+
+::
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-deploy-plugin</artifactId>
+ <configuration>
+ <skip>true</skip>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-install-plugin</artifactId>
+ <configuration>
+ <skip>true</skip>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+odlparent
+~~~~~~~~~
+
+This inherits from ``odlparent-lite`` and mainly provides dependency and
+plugin management for OpenDaylight projects.
+
+| If you use any of the following libraries, you should rely on
+ ``odlparent`` to provide the appropriate versions:
+
+- Akka (and Scala)
+
+- | Apache Commons:
+
+ - ``commons-codec``
+
+ - ``commons-fileupload``
+
+ - ``commons-io``
+
+ - ``commons-lang``
+
+ - ``commons-lang3``
+
+ - ``commons-net``
+
+- Apache Shiro
+
+- Guava
+
+- JAX-RS with Jersey
+
+- | JSON processing:
+
+ - GSON
+
+ - Jackson
+
+- | Logging:
+
+ - Logback
+
+ - SLF4J
+
+- Netty
+
+- | OSGi:
+
+ - Apache Felix
+
+ - core OSGi dependencies (``core``, ``compendium``\ …)
+
+- | Testing:
+
+ - Hamcrest
+
+ - JSON assert
+
+ - JUnit
+
+ - Mockito
+
+ - Pax Exam
+
+ - PowerMock
+
+- | XML/XSL:
+
+ - Xerces
+
+ - XML APIs
+
+.. note::
+
+ This list isn’t exhaustive. It’s also not cast in stone; if you’d
+ like to add a new dependency (or migrate a dependency), please
+ contact `the mailing
+ list <https://lists.opendaylight.org/mailman/listinfo/odlparent-dev>`__.
+
+``odlparent`` also enforces some Checkstyle verification rules. In
+particular, it enforces the common license header used in all
+OpenDaylight code:
+
+::
+
+ /*
+ * Copyright © ${year} ${holder} and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+
+where “\ ``${year}``\ ” is initially the first year of publication, then
+(after a year has passed) the first and latest years of publication,
+separated by commas (*e.g.* “2014, 2016”), and “\ ``${holder}``\ ” is
+the initial copyright holder (typically, the first author’s employer).
+“All rights reserved” is optional.
+
+If you need to disable this license check, *e.g.* for files imported
+under another license (EPL-compatible of course), you can override the
+``maven-checkstyle-plugin`` configuration. ``features-test`` does this
+for its ``CustomBundleUrlStreamHandlerFactory`` class, which is
+ASL-licensed:
+
+::
+
+ <plugin>
+ <artifactId>maven-checkstyle-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>check-license</id>
+ <goals>
+ <goal>check</goal>
+ </goals>
+ <phase>process-sources</phase>
+ <configuration>
+ <configLocation>check-license.xml</configLocation>
+ <headerLocation>EPL-LICENSE.regexp.txt</headerLocation>
+ <includeResources>false</includeResources>
+ <includeTestResources>false</includeTestResources>
+ <sourceDirectory>${project.build.sourceDirectory}</sourceDirectory>
+ <excludes>
+ <!-- Skip Apache Licensed files -->
+ org/opendaylight/odlparent/featuretest/CustomBundleUrlStreamHandlerFactory.java
+ </excludes>
+ <failsOnError>false</failsOnError>
+ <consoleOutput>true</consoleOutput>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+bundle-parent
+~~~~~~~~~~~~~
+
+| This inherits from ``odlparent`` and enables functionality useful for
+ OSGi bundles:
+
+- ``maven-javadoc-plugin`` is activated, to build the Javadoc JAR;
+
+- ``maven-source-plugin`` is activated, to build the source JAR;
+
+- ``maven-bundle-plugin`` is activated (including extensions), to build
+ OSGi bundles (using the “bundle” packaging).
+
+In addition to this, JUnit is included as a default dependency in “test”
+scope.
+
+features-parent
+~~~~~~~~~~~~~~~
+
+| This inherits from ``odlparent`` and enables functionality useful for
+ Karaf features:
+
+- ``karaf-maven-plugin`` is activated, to build Karaf features — but
+ for OpenDaylight, projects need to use “jar” packaging (**not**
+ “kar”);
+
+- ``features.xml`` files are processed from templates stored in
+ ``src/main/features/features.xml``;
+
+- Karaf features are tested after build to ensure they can be activated
+ in a Karaf container.
+
+The ``features.xml`` processing allows versions to be ommitted from
+certain feature dependencies, and replaced with “\ ``{{version}}``\ ”.
+For example:
+
+::
+
+ <features name="odl-mdsal-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.2.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.2.0 http://karaf.apache.org/xmlns/features/v1.2.0">
+
+ <repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
+
+ [...]
+ <feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
+ <feature version='${yangtools.version}'>odl-yangtools-common</feature>
+ <feature version='${mdsal.version}'>odl-mdsal-binding-dom-adapter</feature>
+ <feature version='${mdsal.model.version}'>odl-mdsal-models</feature>
+ <feature version='${project.version}'>odl-mdsal-common</feature>
+ <feature version='${config.version}'>odl-config-startup</feature>
+ <feature version='${config.version}'>odl-config-netty</feature>
+ <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
+ [...]
+ <bundle>mvn:org.opendaylight.controller/sal-dom-broker-config/{{VERSION}}</bundle>
+ <bundle start-level="40">mvn:org.opendaylight.controller/blueprint/{{VERSION}}</bundle>
+ <configfile finalname="${config.configfile.directory}/${config.mdsal.configfile}">mvn:org.opendaylight.controller/md-sal-config/{{VERSION}}/xml/config</configfile>
+ </feature>
+
+As illustrated, versions can be ommitted in this way for repository
+dependencies, bundle dependencies and configuration files. They must be
+specified traditionally (either hard-coded, or using Maven properties)
+for feature dependencies.
+
+Features
+--------
+
+The ODL Parent component for OpenDaylight provides a number of Karaf
+features which can be used by other Karaf features to use certain
+third-party upstream dependencies.
+
+| These features are:
+
+- | Akka features (in the ``features-akka`` repository):
+
+ - ``odl-akka-all`` — all Akka bundles;
+
+ - ``odl-akka-scala`` — Scala runtime for OpenDaylight;
+
+ - ``odl-akka-system`` — Akka actor framework bundles;
+
+ - ``odl-akka-clustering`` — Akka clustering bundles and
+ dependencies;
+
+ - ``odl-akka-leveldb`` — LevelDB;
+
+ - ``odl-akka-persistence`` — Akka persistence;
+
+- general third-party features (in the ``features-odlparent``
+ repository):
+
+ - ``odl-netty`` — all Netty bundles;
+
+ - ``odl-guava`` — Guava;
+
+ - ``odl-lmax`` — LMAX Disruptor.
+
+To use these, you need to declare a dependency on the appropriate
+repository in your ``features.xml`` file:
+
+::
+
+ <repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
+
+and then include the feature, *e.g.*:
+
+::
+
+ <feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
+ [...]
+ <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
+ [...]
+ </feature>
+
+You also need to depend on the features repository in your POM:
+
+::
+
+ <dependency>
+ <groupId>org.opendaylight.odlparent</groupId>
+ <artifactId>features-odlparent</artifactId>
+ <classifier>features</classifier>
+ <type>xml</type>
+ </dependency>
+
+assuming the appropriate dependency management:
+
+::
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.opendaylight.odlparent</groupId>
+ <artifactId>odlparent-artifacts</artifactId>
+ <version>1.7.0-SNAPSHOT</version>
+ <scope>import</scope>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+(the version number there is appropriate for Boron). For the time being
+you also need to depend separately on the individual JARs as
+compile-time dependencies to build your dependent code; the relevant
+dependencies are managed in ``odlparent``'s dependency management.
+
+| The suggested version ranges are as follows:
+
+- ``odl-netty``: ``[4.0.37,4.1.0)`` or ``[4.0.37,5.0.0)``;
+
+- ``odl-guava``: ``[18,19)`` (if your code is ready for it, ``[19,20)``
+ is also available, but the current default version of Guava in
+ OpenDaylight is 18);
+
+- ``odl-lmax``: ``[3.3.4,4.0.0)``
+
--- /dev/null
+OF-CONFIG Developer Guide
+=========================
+
+Overview
+--------
+
+OF-CONFIG defines an OpenFlow switch as an abstraction called an
+OpenFlow Logical Switch. The OF-CONFIG protocol enables configuration of
+essential artifacts of an OpenFlow Logical Switch so that an OpenFlow
+controller can communicate and control the OpenFlow Logical switch via
+the OpenFlow protocol. OF-CONFIG introduces an operating context for one
+or more OpenFlow data paths called an OpenFlow Capable Switch for one or
+more switches. An OpenFlow Capable Switch is intended to be equivalent
+to an actual physical or virtual network element (e.g. an Ethernet
+switch) which is hosting one or more OpenFlow data paths by partitioning
+a set of OpenFlow related resources such as ports and queues among the
+hosted OpenFlow data paths. The OF-CONFIG protocol enables dynamic
+association of the OpenFlow related resources of an OpenFlow Capable
+Switch with specific OpenFlow Logical Switches which are being hosted on
+the OpenFlow Capable Switch. OF-CONFIG does not specify or report how
+the partitioning of resources on an OpenFlow Capable Switch is achieved.
+OF-CONFIG assumes that resources such as ports and queues are
+partitioned amongst multiple OpenFlow Logical Switches such that each
+OpenFlow Logical Switch can assume full control over the resources that
+is assigned to it.
+
+How to start
+------------
+
+- start OF-CONFIG feature as below:
+
+ ::
+
+ feature:install odl-of-config-all
+
+Compatible with NETCONF
+-----------------------
+
+- Config OpenFlow Capable Switch via OpenFlow Configuration Points
+
+ Method: POST
+
+ URI:
+ http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules
+
+ Headers: Content-Type" and "Accept" header attributes set to
+ application/xml
+
+ Payload:
+
+ .. code:: xml
+
+ <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">prefix:sal-netconf-connector</type>
+ <name>testtool</name>
+ <address xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">10.74.151.67</address>
+ <port xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">830</port>
+ <username xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">mininet</username>
+ <password xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">mininet</password>
+ <tcp-only xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">false</tcp-only>
+ <event-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:netty">prefix:netty-event-executor</type>
+ <name>global-event-executor</name>
+ </event-executor>
+ <binding-registry xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">prefix:binding-broker-osgi-registry</type>
+ <name>binding-osgi-broker</name>
+ </binding-registry>
+ <dom-registry xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">prefix:dom-broker-osgi-registry</type>
+ <name>dom-broker</name>
+ </dom-registry>
+ <client-dispatcher xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:config:netconf">prefix:netconf-client-dispatcher</type>
+ <name>global-netconf-dispatcher</name>
+ </client-dispatcher>
+ <processing-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:threadpool">prefix:threadpool</type>
+ <name>global-netconf-processing-executor</name>
+ </processing-executor>
+ </module>
+
+- NETCONF establishes the connections with OpenFlow Capable Switches
+ using the parameters in the previous step. NETCONF also gets the
+ information of whether the OpenFlow Switch supports NETCONF during
+ the signal handshaking. The information will be stored in the NETCONF
+ topology as prosperity of a node.
+
+- OF-CONFIG can be aware of the switches accessing and leaving by
+ monitoring the data changes in the NETCONF topology. For the detailed
+ information it can be refered to the
+ `implementation <https://git.opendaylight.org/gerrit/gitweb?p=of-config.git;a=blob_plain;f=southbound/southbound-impl/src/main/java/org/opendaylight/ofconfig/southbound/impl/OdlOfconfigApiServiceImpl.java;hb=refs/heads/stable/boron>`__.
+
+The establishment of OF-CONFIG topology
+---------------------------------------
+
+Firstly, OF-CONFIG will check whether the newly accessed switch supports
+OF-CONFIG by querying the NETCONF interface.
+
+1. During the NETCONF connection’s establishment, the NETCONF and the
+ switches will exchange the their capabilities via the "hello"
+ message.
+
+2. OF-CONFIG gets the connection information between the NETCONF and
+ switches by monitoring the data changes via the interface of
+ DataChangeListener.
+
+3. After the NETCONF connection established, the OF-CONFIG module will
+ check whether OF-CONFIG capability is in the switch’s capabilities
+ list which is got in step 1.
+
+4. If the result of step 3 is yes, the OF-CONFIG will call the following
+ processing steps to create the topology database.
+
+For the detailed information it can be referred to the
+`implementation <https://git.opendaylight.org/gerrit/gitweb?p=of-config.git;a=blob_plain;f=southbound/southbound-impl/src/main/java/org/opendaylight/ofconfig/southbound/impl/listener/OfconfigListenerHelper.java;hb=refs/heads/stable/boron>`__.
+
+Secondly, the capable switch node and logical switch node are added in
+the OF-CONFIG topology if the switch supports OF-CONFIG.
+
+OF-CONFIG’s topology compromise: Capable Switch topology (underlay) and
+logical Switch topology (overlay). Both of them are enhanced (augment)
+on
+
+/topo:network-topology/topo:topology/topo:node
+
+The NETCONF will add the nodes in the Topology via the path of
+"/topo:network-topology/topo:topology/topo:node" if it gets the
+configuration information of the switches.
+
+For the detailed information it can be referred to the
+`implementation <https://git.opendaylight.org/gerrit/gitweb?p=of-config.git;a=blob;f=southbound/southbound-api/src/main/yang/odl-ofconfig-topology.yang;h=dbdaec46ee59da3791386011f571d7434dd1e416;hb=refs/heads/stable/boron>`__.
+
--- /dev/null
+OpenFlow Protocol Library Developer Guide
+=========================================
+
+Introduction
+------------
+
+OpenFlow Protocol Library is component in OpenDaylight, that mediates
+communication between OpenDaylight controller and hardware devices
+supporting OpenFlow protocol. Primary goal is to provide user (or upper
+layers of OpenDaylight) communication channel, that can be used for
+managing network hardware devices.
+
+Features Overview
+-----------------
+
+There are three features inside openflowjava:
+
+- **odl-openflowjava-protocol** provides all openflowjava bundles, that
+ are needed for communication with openflow devices. It ensures
+ message translation and handles network connections. It also provides
+ openflow protocol specific model.
+
+- **odl-openflowjava-all** currently contains only
+ odl-openflowjava-protocol feature.
+
+- **odl-openflowjava-stats** provides mechanism for message counting
+ and reporting. Can be used for performance analysis.
+
+odl-openflowjava-protocol Architecture
+--------------------------------------
+
+Basic bundles contained in this feature are openflow-protocol-api,
+openflow-protocol-impl, openflow-protocol-spi and util.
+
+- **openflow-protocol-api** - contains openflow model, constants and
+ keys used for (de)serializer registration.
+
+- **openflow-protocol-impl** - contains message factories, that
+ translate binary messages into DataObjects and vice versa. Bundle
+ also contains network connection handlers - servers, netty pipeline
+ handlers, …
+
+- **openflow-protocol-spi** - entry point for openflowjava
+ configuration, startup and close. Basically starts implementation.
+
+- **util** - utility classes for binary-Java conversions and to ease
+ experimenter key creation
+
+odl-openflowjava-stats Feature
+------------------------------
+
+Runs over odl-openflowjava-protocol. It counts various message types /
+events and reports counts in specified time periods. Statistics
+collection can be configured in
+openflowjava-config/src/main/resources/45-openflowjava-stats.xml
+
+Key APIs and Interfaces
+-----------------------
+
+Basic API / SPI classes are ConnectionAdapter (Rpc/notifications) and
+SwitchConnectionProcider (configure, start, shutdown)
+
+Installation
+------------
+
+Pull the code and import project into your IDE.
+
+::
+
+ git clone ssh://<username>@git.opendaylight.org:29418/openflowjava.git
+
+Configuration
+-------------
+
+Current implementation allows to configure:
+
+- listening port (mandatory)
+
+- transfer protocol (mandatory)
+
+- switch idle timeout (mandatory)
+
+- TLS configuration (optional)
+
+- thread count (optional)
+
+You can find exemplary Openflow Protocol Library instance configuration
+below:
+
+::
+
+ <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <!-- default OF-switch-connection-provider (port 6633) -->
+ <module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider:impl">prefix:openflow-switch-connection-provider-impl</type>
+ <name>openflow-switch-connection-provider-default-impl</name>
+ <port>6633</port>
+ <!-- Possible transport-protocol options: TCP, TLS, UDP -->
+ <transport-protocol>TCP</transport-protocol>
+ <switch-idle-timeout>15000</switch-idle-timeout>
+ <!-- Exemplary TLS configuration:
+ - uncomment the <tls> tag
+ - copy exemplary-switch-privkey.pem, exemplary-switch-cert.pem and exemplary-cacert.pem
+ files into your virtual machine
+ - set VM encryption options to use copied keys
+ - start communication
+ Please visit OpenflowPlugin or Openflow Protocol Library#Documentation wiki pages
+ for detailed information regarding TLS -->
+ <!-- <tls>
+ <keystore>/exemplary-ctlKeystore</keystore>
+ <keystore-type>JKS</keystore-type>
+ <keystore-path-type>CLASSPATH</keystore-path-type>
+ <keystore-password>opendaylight</keystore-password>
+ <truststore>/exemplary-ctlTrustStore</truststore>
+ <truststore-type>JKS</truststore-type>
+ <truststore-path-type>CLASSPATH</truststore-path-type>
+ <truststore-password>opendaylight</truststore-password>
+ <certificate-password>opendaylight</certificate-password>
+ </tls> -->
+ <!-- Exemplary thread model configuration. Uncomment <threads> tag below to adjust default thread model -->
+ <!-- <threads>
+ <boss-threads>2</boss-threads>
+ <worker-threads>8</worker-threads>
+ </threads> -->
+ </module>
+
+::
+
+ <!-- default OF-switch-connection-provider (port 6653) -->
+ <module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider:impl">prefix:openflow-switch-connection-provider-impl</type>
+ <name>openflow-switch-connection-provider-legacy-impl</name>
+ <port>6653</port>
+ <!-- Possible transport-protocol options: TCP, TLS, UDP -->
+ <transport-protocol>TCP</transport-protocol>
+ <switch-idle-timeout>15000</switch-idle-timeout>
+ <!-- Exemplary TLS configuration:
+ - uncomment the <tls> tag
+ - copy exemplary-switch-privkey.pem, exemplary-switch-cert.pem and exemplary-cacert.pem
+ files into your virtual machine
+ - set VM encryption options to use copied keys
+ - start communication
+ Please visit OpenflowPlugin or Openflow Protocol Library#Documentation wiki pages
+ for detailed information regarding TLS -->
+ <!-- <tls>
+ <keystore>/exemplary-ctlKeystore</keystore>
+ <keystore-type>JKS</keystore-type>
+ <keystore-path-type>CLASSPATH</keystore-path-type>
+ <keystore-password>opendaylight</keystore-password>
+ <truststore>/exemplary-ctlTrustStore</truststore>
+ <truststore-type>JKS</truststore-type>
+ <truststore-path-type>CLASSPATH</truststore-path-type>
+ <truststore-password>opendaylight</truststore-password>
+ <certificate-password>opendaylight</certificate-password>
+ </tls> -->
+ <!-- Exemplary thread model configuration. Uncomment <threads> tag below to adjust default thread model -->
+ <!-- <threads>
+ <boss-threads>2</boss-threads>
+ <worker-threads>8</worker-threads>
+ </threads> -->
+ </module>
+
+::
+
+ <module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:common:config:impl">prefix:openflow-provider-impl</type>
+ <name>openflow-provider-impl</name>
+ <openflow-switch-connection-provider>
+ <type xmlns:ofSwitch="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider">ofSwitch:openflow-switch-connection-provider</type>
+ <name>openflow-switch-connection-provider-default</name>
+ </openflow-switch-connection-provider>
+ <openflow-switch-connection-provider>
+ <type xmlns:ofSwitch="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider">ofSwitch:openflow-switch-connection-provider</type>
+ <name>openflow-switch-connection-provider-legacy</name>
+ </openflow-switch-connection-provider>
+ <binding-aware-broker>
+ <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-broker-osgi-registry</type>
+ <name>binding-osgi-broker</name>
+ </binding-aware-broker>
+ </module>
+ </modules>
+
+Possible transport-protocol options:
+
+- TCP
+
+- TLS
+
+- UDP
+
+Switch-idle timeout specifies time needed to detect idle state of
+switch. When no message is received from switch within this time, upper
+layers are notified on switch idleness. To be able to use this exemplary
+TLS configuration:
+
+- uncomment the ``<tls>`` tag
+
+- copy *exemplary-switch-privkey.pem*, *exemplary-switch-cert.pem* and
+ *exemplary-cacert.pem* files into your virtual machine
+
+- set VM encryption options to use copied keys (please visit TLS
+ support wiki page for detailed information regarding TLS)
+
+- start communication
+
+Thread model configuration specifies how many threads are desired to
+perform Netty’s I/O operations.
+
+- boss-threads specifies the number of threads that register incoming
+ connections
+
+- worker-threads specifies the number of threads performing read /
+ write (+ serialization / deserialization) operations.
+
+Architecture
+------------
+
+Public API ``(openflow-protocol-api)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set of interfaces and builders for immutable data transfer objects
+representing Openflow Protocol structures.
+
+Transfer objects and service APIs are infered from several YANG models
+using code generator to reduce verbosity of definition and repeatibility
+of code.
+
+The following YANG modules are defined:
+
+- openflow-types - defines common Openflow specific types
+
+- openflow-instruction - defines base Openflow instructions
+
+- openflow-action - defines base Openflow actions
+
+- openflow-augments - defines object augmentations
+
+- openflow-extensible-match - defines Openflow OXM match
+
+- openflow-protocol - defines Openflow Protocol messages
+
+- system-notifications - defines system notification objects
+
+- openflow-configuration - defines structures used in ConfigSubsystem
+
+This modules also reuse types from following YANG modules:
+
+- ietf-inet-types - IP adresses, IP prefixes, IP-protocol related types
+
+- ietf-yang-types - Mac Address, etc.
+
+The use of predefined types is to make APIs contracts more safe, better
+readable and documented (e.g using MacAddress instead of byte array…)
+
+TCP Channel pipeline ``(openflow-protocol-impl)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creates channel processing pipeline based on configuration and support.
+
+**TCP Channel pipeline.**
+
+imageopenflowjava/500px-TCPChannelPipeline.png[width=500]
+
+**Switch Connection Provider.**
+
+Implementation of connection point for other projects. Library exposes
+its functionality through this class. Library can be configured, started
+and shutdowned here. There are also methods for custom (de)serializer
+registration.
+
+**Tcp Connection Initializer.**
+
+In order to initialize TCP connection to a device (switch), OF Plugin
+calls method ``initiateConnection()`` in ``SwitchConnectionProvider``.
+This method in turn initializes (Bootstrap) server side channel towards
+the device.
+
+**TCP Handler.**
+
+Represents single server that is handling incoming connections over TCP
+/ TLS protocol. TCP Handler creates a single instance of TCP Channel
+Initializer that will initialize channels. After that it binds to
+configured InetAddress and port. When a new device connects, TCP Handler
+registers its channel and passes control to TCP Channel Initializer.
+
+**TCP Channel Initializer.**
+
+This class is used for channel initialization / rejection and passing
+arguments. After a new channel has been registered it calls Switch
+Connection Handler’s (OF Plugin) accept method to decide if the library
+should keep the newly registered channel or if the channel should be
+closed. If the channel has been accepted, TCP Channel Initializer
+creates the whole pipeline with needed handlers and also with
+ConnectionAdapter instance. After the channel pipeline is ready, Switch
+Connection Handler is notified with ``onConnectionReady`` notification.
+OpenFlow Plugin can now start sending messages downstream.
+
+**Idle Handler.**
+
+If there are no messages received for more than time specified, this
+handler triggers idle state notification. The switch idle timeout is
+received as a parameter from ConnectionConfiguration settings. Idle
+State Handler is inactive while there are messages received within the
+switch idle timeout. If there are no messages received for more than
+timeout specified, handler creates SwitchIdleEvent message and sends it
+upstream.
+
+**TLS Handler.**
+
+It encrypts and decrypts messages over TLS protocol. Engaging TLS
+Handler into pipeline is matter of configuration (``<tls>`` tag). TLS
+communication is either unsupported or required. TLS Handler is
+represented as a Netty’s SslHandler.
+
+**OF Frame Decoder.**
+
+Parses input stream into correct length message frames for further
+processing. Framing is based on Openflow header length. If received
+message is shorter than minimal length of OpenFlow message (8 bytes), OF
+Frame Decoder waits for more data. After receiving at least 8 bytes the
+decoder checks length in OpenFlow header. If there are still some bytes
+missing, the decoder waits for them. Else the OF Frame Decoder sends
+correct length message to next handler in the channel pipeline.
+
+**OF Version Detector.**
+
+Detects version of used OpenFlow Protocol and discards unsupported
+version messages. If the detected version is supported, OF Version
+Detector creates ``VersionMessageWrapper`` object containing the
+detected version and byte message and sends this object upstream.
+
+**OF Decoder.**
+
+Chooses correct deserilization factory (based on message type) and
+deserializes messages into generated DTOs (Data Transfer Object). OF
+Decoder receives ``VersionMessageWrapper`` object and passes it to
+``DeserializationFactory`` which will return translated DTO.
+``DeserializationFactory`` creates ``MessageCodeKey`` object with
+version and type of received message and Class of object that will be
+the received message deserialized into. This object is used as key when
+searching for appropriate decoder in ``DecoderTable``. ``DecoderTable``
+is basically a map storing decoders. Found decoder translates received
+message into DTO. If there was no decoder found, null is returned. After
+returning translated DTO back to OF Decoder, the decoder checks if it is
+null or not. When the DTO is null, the decoder logs this state and
+throws an Exception. Else it passes the DTO further upstream. Finally,
+the OF Decoder releases ByteBuf containing received and decoded byte
+message.
+
+**OF Encoder.**
+
+Chooses correct serialization factory (based on type of DTO) and
+serializes DTOs into byte messages. OF Encoder does the opposite than
+the OF Decoder using the same principle. OF Encoder receives DTO, passes
+it for translation and if the result is not null, it sends translated
+DTO downstream as a ByteBuf. Searching for appropriate encoder is done
+via MessageTypeKey, based on version and class of received DTO.
+
+**Delegating Inbound Handler.**
+
+Delegates received DTOs to Connection Adapter. It also reacts on
+channelInactive and channelUnregistered events. Upon one of these events
+is triggered, DelegatingInboundHandler creates DisconnectEvent message
+and sends it upstream, notifying upper layers about switch
+disconnection.
+
+**Channel Outbound Queue.**
+
+Message flushing handler. Stores outgoing messages (DTOs) and flushes
+them. Flush is performed based on time expired and on the number of
+messages enqueued.
+
+**Connection Adapter.**
+
+Provides a facade on top of pipeline, which hides netty.io specifics.
+Provides a set of methods to register for incoming messages and to send
+messages to particular channel / session. ConnectionAdapterImpl
+basically implements three interfaces (unified in one superinterface
+ConnectionFacade):
+
+- ConnectionAdapter
+
+- MessageConsumer
+
+- OpenflowProtocolService
+
+**ConnectionAdapter** interface has methods for setting up listeners
+(message, system and connection ready listener), method to check if all
+listeners are set, checking if the channel is alive and disconnect
+method. Disconnect method clears responseCache and disables consuming of
+new messages.
+
+**MessageConsumer** interface holds only one method: ``consume()``.
+``Consume()`` method is called from DelegatingInboundHandler. This
+method processes received DTO’s based on their type. There are three
+types of received objects:
+
+- System notifications - invoke system notifications in OpenFlow Plugin
+ (systemListener set). In case of ``DisconnectEvent`` message, the
+ Connection Adapter clears response cache and disables consume()
+ method processing,
+
+- OpenFlow asynchronous messages (from switch) - invoke corresponding
+ notifications in OpenFlow Plugin,
+
+- OpenFlow symmetric messages (replies to requests) - create
+ ``RpcResponseKey`` with XID and DTO’s class set. This
+ ``RpcResponseKey`` is then used to find corresponding future object
+ in responseCache. Future object is set with success flag, received
+ message and errors (if any occurred). In case no corresponding future
+ was found in responseCache, Connection Adapter logs warning and
+ discards the message. Connection Adapter also logs warning when an
+ unknown DTO is received.
+
+**OpenflowProtocolService** interface contains all rpc-methods for
+sending messages from upper layers (OpenFlow Plugin) downstream and
+responding. Request messages return Future filled with expected reply
+message, otherwise the expected Future is of type Void.
+
+**NOTE:** MultipartRequest message is the only exception. Basically it
+is request - reply Message type, but it wouldn’t be able to process more
+following MultipartReply messages if this was implemented as rpc (only
+one Future). This is why MultipartReply is implemented as notification.
+OpenFlow Plugin takes care of correct message processing.
+
+UDP Channel pipeline (openflow-protocol-impl)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creates UDP channel processing pipeline based on configuration and
+support. **Switch Connection Provider**, **Channel Outbound Queue** and
+**Connection Adapter** fulfill the same role as in case of TCP
+connection / channel pipeline (please see above).
+
+.. figure:: ./images/openflowjava/500px-UdpChannelPipeline.png
+ :alt: UDP Channel pipeline
+
+ UDP Channel pipeline
+
+**UDP Handler.**
+
+Represents single server that is handling incoming connections over UDP
+(DTLS) protocol. UDP Handler creates a single instance of UDP Channel
+Initializer that will initialize channels. After that it binds to
+configured InetAddress and port. When a new device connects, UDP Handler
+registers its channel and passes control to UDP Channel Initializer.
+
+**UDP Channel Initializer.**
+
+This class is used for channel initialization and passing arguments.
+After a new channel has been registered (for UDP there is always only
+one channel) UDP Channel Initializer creates whole pipeline with needed
+handlers.
+
+**DTLS Handler.**
+
+Haven’t been implemented yet. Will take care of secure DTLS connections.
+
+**OF Datagram Packet Handler.**
+
+Combines functionality of OF Frame Decoder and OF Version Detector.
+Extracts messages from received datagram packets and checks if message
+version is supported. If there is a message received from yet unknown
+sender, OF Datagram Packet Handler creates Connection Adapter for this
+sender and stores it under sender’s address in ``UdpConnectionMap``.
+This map is also used for sending the messages and for correct
+Connection Adapter lookup - to delegate messages from one channel to
+multiple sessions.
+
+**OF Datagram Packet Decoder.**
+
+Chooses correct deserilization factory (based on message type) and
+deserializes messages into generated DTOs. OF Decoder receives
+``VersionMessageUdpWrapper`` object and passes it to
+``DeserializationFactory`` which will return translated DTO.
+``DeserializationFactory`` creates ``MessageCodeKey`` object with
+version and type of received message and Class of object that will be
+the received message deserialized into. This object is used as key when
+searching for appropriate decoder in ``DecoderTable``. ``DecoderTable``
+is basically a map storing decoders. Found decoder translates received
+message into DTO (DataTransferObject). If there was no decoder found,
+null is returned. After returning translated DTO back to OF Datagram
+Packet Decoder, the decoder checks if it is null or not. When the DTO is
+null, the decoder logs this state. Else it looks up appropriate
+Connection Adapter in ``UdpConnectionMap`` and passes the DTO to found
+Connection Adapter. Finally, the OF Decoder releases ``ByteBuf``
+containing received and decoded byte message.
+
+**OF Datagram Packet Encoder.**
+
+Chooses correct serialization factory (based on type of DTO) and
+serializes DTOs into byte messages. OF Datagram Packet Encoder does the
+opposite than the OF Datagram Packet Decoder using the same principle.
+OF Encoder receives DTO, passes it for translation and if the result is
+not null, it sends translated DTO downstream as a datagram packet.
+Searching for appropriate encoder is done via MessageTypeKey, based on
+version and class of received DTO.
+
+SPI (openflow-protocol-spi)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Defines interface for library’s connection point for other projects.
+Library exposes its functionality through this interface.
+
+Integration test (openflow-protocol-it)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Testing communication with simple client.
+
+Simple client(simple-client)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Lightweight switch simulator - programmable with desired scenarios.
+
+Utility (util)
+~~~~~~~~~~~~~~
+
+Contains utility classes, mainly for work with ByteBuf.
+
+Library’s lifecycle
+-------------------
+
+Steps (after the library’s bundle is started):
+
+- [1] Library is configured by ConfigSubsystem (adress, ports,
+ encryption, …)
+
+- [2] Plugin injects its SwitchConnectionHandler into the Library
+
+- [3] Plugin starts the Library
+
+- [4] Library creates configured protocol handler (e.g. TCP Handler)
+
+- [5] Protocol Handler creates Channel Initializer
+
+- [6] Channel Initializer asks plugin whether to accept incoming
+ connection on each new switch connection
+
+- [7] Plugin responds:
+
+ - true - continue building pipeline
+
+ - false - reject connection / disconnect channel
+
+- [8] Library notifies Plugin with onSwitchConnected(ConnectionAdapter)
+ notification, passing reference to ConnectionAdapter, that will
+ handle the connection
+
+- [9] Plugin registers its system and message listeners
+
+- [10] FireConnectionReadyNotification() is triggered, announcing that
+ pipeline handlers needed for communication have been created and
+ Plugin can start communication
+
+- [11] Plugin shutdowns the Library when desired
+
+.. figure:: ./images/openflowjava/Library_lifecycle.png
+ :alt: Library lifecycle
+
+ Library lifecycle
+
+Statistics collection
+---------------------
+
+Introduction
+~~~~~~~~~~~~
+
+Statistics collection collects message statistics. Current collected
+statistics (``DS`` - downstream, ``US`` - upstream):
+
+- ``DS_ENTERED_OFJAVA`` - all messages that entered openflowjava
+ (picked up from openflowplugin)
+
+- ``DS_ENCODE_SUCCESS`` - successfully encoded messages
+
+- ``DS_ENCODE_FAIL`` - messages that failed during encoding
+ (serialization) process
+
+- ``DS_FLOW_MODS_ENTERED`` - all flow-mod messages that entered
+ openflowjava
+
+- ``DS_FLOW_MODS_SENT`` - all flow-mod messages that were successfully
+ sent
+
+- ``US_RECEIVED_IN_OFJAVA`` - messages received from switch
+
+- ``US_DECODE_SUCCESS`` - successfully decoded messages
+
+- ``US_DECODE_FAIL`` - messages that failed during decoding
+ (deserialization) process
+
+- ``US_MESSAGE_PASS`` - messages handed over to openflowplugin
+
+Karaf
+~~~~~
+
+In orded to start statistics, it is needed to feature:install
+odl-openflowjava-stats. To see the logs one should use log:set DEBUG
+org.opendaylight.openflowjava.statistics and than probably log:display
+(you can log:list to see if the logging has been set). To adjust
+collection settings it is enough to modify 45-openflowjava-stats.xml.
+
+JConsole
+~~~~~~~~
+
+JConsole provides two commands for the statistics collection:
+
+- printing current statistics
+
+- resetting statistic counters
+
+After attaching JConsole to correct process, one only needs to go into
+MBeans
+``tab → org.opendaylight.controller → RuntimeBean → statistics-collection-service-impl
+→ statistics-collection-service-impl → Operations`` to be able to use
+this commands.
+
+TLS Support
+-----------
+
+ **Note**
+
+ see OpenFlow Plugin Developper Guide
+
+Extensibility
+-------------
+
+Introduction
+~~~~~~~~~~~~
+
+Entry point for the extensibility is ``SwitchConnectionProvider``.
+``SwitchConnectionProvider`` contains methods for (de)serializer
+registration. To register deserializer it is needed to use
+.register\*Deserializer(key, impl). To register serializer one must use
+.register\*Serializer(key, impl). Registration can occur either during
+configuration or at runtime.
+
+**NOTE**: In case when experimenter message is received and no
+(de)serializer was registered, the library will throw
+``IllegalArgumentException``.
+
+Basic Principle
+~~~~~~~~~~~~~~~
+
+In order to use extensions it is needed to augment existing model and
+register new (de)serializers.
+
+Augmenting the model: 1. Create new augmentation
+
+Register (de)serializers: 1. Create your (de)serializer 2. Let it
+implement ``OFDeserializer<>`` / ``OFSerializer<>`` - in case the
+structure you are (de)serializing needs to be used in Multipart
+TableFeatures messages, let it implement ``HeaderDeserializer<>`` /
+``HeaderSerializer`` 3. Implement prescribed methods 4. Register your
+deserializer under appropriate key (in our case
+``ExperimenterActionDeserializerKey``) 5. Register your serializer under
+appropriate key (in our case ``ExperimenterActionSerializerKey``) 6.
+Done, test your implementation
+
+**NOTE**: If you don’t know what key should be used with your
+(de)serializer implementation, please visit `Registration
+keys <#registration_keys>`__ page.
+
+Example
+~~~~~~~
+
+Let’s say we have vendor / experimenter action represented by this
+structure:
+
+::
+
+ struct foo_action {
+ uint16_t type;
+ uint16_t length;
+ uint32_t experimenter;
+ uint16_t first;
+ uint16_t second;
+ uint8_t pad[4];
+ }
+
+First, we have to augment existing model. We create new module, which
+imports "``openflow-types.yang``" (don’t forget to update your
+``pom.xml`` with api dependency). Now we create foo action identity:
+
+::
+
+ import openflow-types {prefix oft;}
+ identity foo {
+ description "Foo action description";
+ base oft:action-base;
+ }
+
+This will be used as type in our structure. Now we must augment existing
+action structure, so that we will have the desired fields first and
+second. In order to create new augmentation, our module has to import
+"``openflow-action.yang``". The augment should look like this:
+
+::
+
+ import openflow-action {prefix ofaction;}
+ augment "/ofaction:actions-container/ofaction:action" {
+ ext:augment-identifier "foo-action";
+ leaf first {
+ type uint16;
+ }
+ leaf second {
+ type uint16;
+ }
+ }
+
+We are finished with model changes. Run mvn clean compile to generate
+sources. After generation is done, we need to implement our
+(de)serializer.
+
+Deserializer:
+
+::
+
+ public class FooActionDeserializer extends OFDeserializer<Action> {
+ @Override
+ public Action deserialize(ByteBuf input) {
+ ActionBuilder builder = new ActionBuilder();
+ input.skipBytes(SIZE_OF_SHORT_IN_BYTES); *// we know the type of action*
+ builder.setType(Foo.class);
+ input.skipBytes(SIZE_OF_SHORT_IN_BYTES); *// we don't need length*
+ *// now create experimenterIdAugmentation - so that openflowplugin can
+ differentiate correct vendor codec*
+ ExperimenterIdActionBuilder expIdBuilder = new ExperimenterIdActionBuilder();
+ expIdBuilder.setExperimenter(new ExperimenterId(input.readUnsignedInt()));
+ builder.addAugmentation(ExperimenterIdAction.class, expIdBuilder.build());
+ FooActionBuilder fooBuilder = new FooActionBuilder();
+ fooBuilder.setFirst(input.readUnsignedShort());
+ fooBuilder.setSecond(input.readUnsignedShort());
+ builder.addAugmentation(FooAction.class, fooBuilder.build());
+ input.skipBytes(4); *// padding*
+ return builder.build();
+ }
+ }
+
+Serializer:
+
+::
+
+ public class FooActionSerializer extends OFSerializer<Action> {
+ @Override
+ public void serialize(Action action, ByteBuf outBuffer) {
+ outBuffer.writeShort(FOO_CODE);
+ outBuffer.writeShort(16);
+ *// we don't have to check for ExperimenterIdAction augmentation - our
+ serializer*
+ *// was called based on the vendor / experimenter ID, so we simply write
+ it to buffer*
+ outBuffer.writeInt(VENDOR / EXPERIMENTER ID);
+ FooAction foo = action.getAugmentation(FooAction.class);
+ outBuffer.writeShort(foo.getFirst());
+ outBuffer.writeShort(foo.getSecond());
+ outBuffer.writeZero(4); //write padding
+ }
+ }
+
+Register both deserializer and serializer:
+``SwitchConnectionProvider.registerDeserializer(new
+ExperimenterActionDeserializerKey(0x04, VENDOR / EXPERIMENTER ID),
+new FooActionDeserializer());``
+``SwitchConnectionProvider.registerSerializer(new
+ExperimenterActionSerializerKey(0x04, VENDOR / EXPERIMENTER ID),
+new FooActionSerializer());``
+
+We are ready to test our implementation.
+
+**NOTE:** Vendor / Experimenter structures define only vendor /
+experimenter ID as common distinguisher (besides action type). Vendor /
+Experimenter ID is unique for all vendor messages - that’s why vendor is
+able to register only one class under
+ExperimenterAction(De)SerializerKey. And that’s why vendor has to switch
+/ choose between his subclasses / subtypes on his own.
+
+Detailed walkthrough: Deserialization extensibility
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**External interface & class description.**
+
+**OFGeneralDeserializer:**
+
+- ``OFDeserializer<E extends DataObject>``
+
+ - *deserialize(ByteBuf)* - deserializes given ByteBuf
+
+- ``HeaderDeserializer<E extends DataObject>``
+
+ - *deserializeHeaders(ByteBuf)* - deserializes only E headers (used
+ in Multipart TableFeatures messages)
+
+**DeserializerRegistryInjector**
+
+- ``injectDeserializerRegistry(DeserializerRegistry)`` - injects
+ deserializer registry into deserializer. Useful when custom
+ deserializer needs access to other deserializers.
+
+**NOTE:** DeserializerRegistryInjector is not OFGeneralDeserializer
+descendand. It is a standalone interface.
+
+**MessageCodeKey and its descendants** These keys are used as for
+deserializer lookup in DeserializerRegistry. MessageCodeKey should is
+used in general, while its descendants are used in more special cases.
+For Example ActionDeserializerKey is used for Action deserializer lookup
+and (de)registration. Vendor is provided with special keys, which
+contain only the most necessary fields. These keys usually start with
+"Experimenter" prefix (MatchEntryDeserializerKey is an exception).
+
+MessageCodeKey has these fields:
+
+- short version - Openflow wire version number
+
+- int value - value read from byte message
+
+- Class<?> clazz - class of object being creating
+
+- [1] The scenario starts in a custom bundle which wants to extend
+ library’s functionality. The custom bundle creates deserializers
+ which implement exposed ``OFDeserializer`` / ``HeaderDeserializer``
+ interfaces (wrapped under ``OFGeneralDeserializer`` unifying super
+ interface).
+
+- [2] Created deserializers are paired with corresponding
+ ExperimenterKeys, which are used for deserializer lookup. If you
+ don’t know what key should be used with your (de)serializer
+ implementation, please visit `Registration
+ keys <#registration_keys>`__ page.
+
+- [3] Paired deserializers are passed to the OF Library via
+ **SwitchConnectionProvider**.\ *registerCustomDeserializer(key,
+ impl)*. Library registers the deserializer.
+
+ - While registering, Library checks if the deserializer is an
+ instance of **DeserializerRegistryInjector** interface. If yes,
+ the DeserializerRegistry (which stores all deserializer
+ references) is injected into the deserializer.
+
+This is particularly useful when the deserializer needs access to other
+deserializers. For example ``IntructionsDeserializer`` needs access to
+``ActionsDeserializer`` in order to be able to process
+OFPIT\_WRITE\_ACTIONS/OFPIT\_APPLY\_ACTIONS instructions.
+
+.. figure:: ./images/openflowjava/800px-Extensibility.png
+ :alt: Deserialization scenario walkthrough
+
+ Deserialization scenario walkthrough
+
+Detailed walkthrough: Serialization extensibility
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**External interface & class description.**
+
+**OFGeneralSerializer:**
+
+- OFSerializer<E extends DataObject>
+
+ - *serialize(E,ByteBuf)* - serializes E into given ByteBuf
+
+- ``HeaderSerializer<E extends DataObject>``
+
+ - *serializeHeaders(E,ByteBuf)* - serializes E headers (used in
+ Multipart TableFeatures messages)
+
+**SerializerRegistryInjector** \*
+``injectSerializerRegistry(SerializerRegistry)`` - injects serializer
+registry into serializer. Useful when custom serializer needs access to
+other serializers.
+
+**NOTE:** SerializerRegistryInjector is not OFGeneralSerializer
+descendand.
+
+**MessageTypeKey and its descendants** These keys are used as for
+serializer lookup in SerializerRegistry. MessageTypeKey should is used
+in general, while its descendants are used in more special cases. For
+Example ActionSerializerKey is used for Action serializer lookup and
+(de)registration. Vendor is provided with special keys, which contain
+only the most necessary fields. These keys usually start with
+"Experimenter" prefix (MatchEntrySerializerKey is an exception).
+
+MessageTypeKey has these fields:
+
+- *short version* - Openflow wire version number
+
+- *Class<E> msgType* - DTO class
+
+Scenario walkthrough
+
+- [1] Serialization extensbility principles are similar to the
+ deserialization principles. The scenario starts in a custom bundle.
+ The custom bundle creates serializers which implement exposed
+ OFSerializer / HeaderSerializer interfaces (wrapped under
+ OFGeneralSerializer unifying super interface).
+
+- [2] Created serializers are paired with their ExperimenterKeys, which
+ are used for serializer lookup. If you don’t know what key should be
+ used with your serializer implementation, please visit `Registration
+ keys <#registration_keys>`__ page.
+
+- [3] Paired serializers are passed to the OF Library via
+ **SwitchConnectionProvider**.\ *registerCustomSerializer(key, impl)*.
+ Library registers the serializer.
+
+- While registering, Library checks if the serializer is an instance of
+ **SerializerRegistryInjector** interface. If yes, the
+ SerializerRegistry (which stores all serializer references) is
+ injected into the serializer.
+
+This is particularly useful when the serializer needs access to other
+deserializers. For example IntructionsSerializer needs access to
+ActionsSerializer in order to be able to process
+OFPIT\_WRITE\_ACTIONS/OFPIT\_APPLY\_ACTIONS instructions.
+
+.. figure:: ./images/openflowjava/800px-Extensibility2.png
+ :alt: Serialization scenario walkthrough
+
+ Serialization scenario walkthrough
+
+Internal description
+~~~~~~~~~~~~~~~~~~~~
+
+**SwitchConnectionProvider** ``SwitchConnectionProvider`` constructs and
+initializes both deserializer and serializer registries with default
+(de)serializers. It also injects the ``DeserializerRegistry`` into the
+``DeserializationFactory``, the ``SerializerRegistry`` into the
+``SerializationFactory``. When call to register custom (de)serializer is
+made, ``SwitchConnectionProvider`` calls register method on appropriate
+registry.
+
+**DeserializerRegistry / SerializerRegistry** Both registries contain
+init() method to initialize default (de)serializers. Registration checks
+if key or (de)serializer implementation are not ``null``. If at least
+one of the is ``null``, ``NullPointerException`` is thrown. Else the
+(de)serializer implementation is checked if it is
+``(De)SerializerRegistryInjector`` instance. If it is an instance of
+this interface, the registry is injected into this (de)serializer
+implementation.
+
+``GetSerializer(key)`` or ``GetDeserializer(key)`` performs registry
+lookup. Because there are two separate interfaces that might be put into
+the registry, the registry uses their unifying super interface.
+Get(De)Serializer(key) method casts the super interface to desired type.
+There is also a null check for the (de)serializer received from the
+registry. If the deserializer wasn’t found, ``NullPointerException``
+with key description is thrown.
+
+Registration keys
+~~~~~~~~~~~~~~~~~
+
+**Deserialization.**
+
+**Possible openflow extensions and their keys**
+
+There are three vendor specific extensions in Openflow v1.0 and eight in
+Openflow v1.3. These extensions are registered under registration keys,
+that are shown in table below:
+
++----------------+---------+------------------------------+-----------------------+
+| Extension type | OpenFlo | Registration key | Utility class |
+| | w | | |
++================+=========+==============================+=======================+
+| Vendor message | 1.0 | ExperimenterIdDeserializerKe | ExperimenterDeseriali |
+| | | y(1, | zerKeyFactory |
+| | | experimenterId, | |
+| | | ExperimenterMessage.class) | |
++----------------+---------+------------------------------+-----------------------+
+| Action | 1.0 | ExperimenterActionDeserializ | . |
+| | | erKey(1, | |
+| | | experimenter ID) | |
++----------------+---------+------------------------------+-----------------------+
+| Stats message | 1.0 | ExperimenterMultipartReplyMe | ExperimenterDeseriali |
+| | | ssageDeserializerKey(1, | zerKeyFactory |
+| | | experimenter ID) | |
++----------------+---------+------------------------------+-----------------------+
+| Experimenter | 1.3 | ExperimenterIdDeserializerKe | ExperimenterDeseriali |
+| message | | y(4, | zerKeyFactory |
+| | | experimenterId, | |
+| | | ExperimenterMessage.class) | |
++----------------+---------+------------------------------+-----------------------+
+| Match entry | 1.3 | MatchEntryDeserializerKey(4, | . |
+| | | (number) ${oxm\_class}, | |
+| | | (number) ${oxm\_field}); | |
++----------------+---------+------------------------------+-----------------------+
+| | | key.setExperimenterId(experi | . |
+| | | menter | |
+| | | ID); | |
++----------------+---------+------------------------------+-----------------------+
+| Action | 1.3 | ExperimenterActionDeserializ | . |
+| | | erKey(4, | |
+| | | experimenter ID) | |
++----------------+---------+------------------------------+-----------------------+
+| Instruction | 1.3 | ExperimenterInstructionDeser | . |
+| | | ializerKey(4, | |
+| | | experimenter ID) | |
++----------------+---------+------------------------------+-----------------------+
+| Multipart | 1.3 | ExperimenterIdDeserializerKe | ExperimenterDeseriali |
+| | | y(4, | zerKeyFactory |
+| | | experimenterId, | |
+| | | MultipartReplyMessage.class) | |
++----------------+---------+------------------------------+-----------------------+
+| Multipart - | 1.3 | ExperimenterIdDeserializerKe | ExperimenterDeseriali |
+| Table features | | y(4, | zerKeyFactory |
+| | | experimenterId, | |
+| | | TableFeatureProperties.class | |
+| | | ) | |
++----------------+---------+------------------------------+-----------------------+
+| Error | 1.3 | ExperimenterIdDeserializerKe | ExperimenterDeseriali |
+| | | y(4, | zerKeyFactory |
+| | | experimenterId, | |
+| | | ErrorMessage.class) | |
++----------------+---------+------------------------------+-----------------------+
+| Queue property | 1.3 | ExperimenterIdDeserializerKe | ExperimenterDeseriali |
+| | | y(4, | zerKeyFactory |
+| | | experimenterId, | |
+| | | QueueProperty.class) | |
++----------------+---------+------------------------------+-----------------------+
+| Meter band | 1.3 | ExperimenterIdDeserializerKe | ExperimenterDeseriali |
+| type | | y(4, | zerKeyFactory |
+| | | experimenterId, | |
+| | | MeterBandExperimenterCase.cl | |
+| | | ass) | |
++----------------+---------+------------------------------+-----------------------+
+
+Table: **Deserialization**
+
+**Serialization.**
+
+**Possible openflow extensions and their keys**
+
+There are three vendor specific extensions in Openflow v1.0 and seven
+Openflow v1.3. These extensions are registered under registration keys,
+that are shown in table below:
+
++----------------+---------+------------------------------+-----------------------+
+| Extension type | OpenFlo | Registration key | Utility class |
+| | w | | |
++================+=========+==============================+=======================+
+| Vendor message | 1.0 | ExperimenterIdSerializerKey< | ExperimenterSerialize |
+| | | >(1, | rKeyFactory |
+| | | experimenterId, | |
+| | | ExperimenterInput.class) | |
++----------------+---------+------------------------------+-----------------------+
+| Action | 1.0 | ExperimenterActionSerializer | . |
+| | | Key(1, | |
+| | | experimenterId, sub-type) | |
++----------------+---------+------------------------------+-----------------------+
+| Stats message | 1.0 | ExperimenterMultipartRequest | ExperimenterSerialize |
+| | | SerializerKey(1, | rKeyFactory |
+| | | experimenter ID) | |
++----------------+---------+------------------------------+-----------------------+
+| Experimenter | 1.3 | ExperimenterIdSerializerKey< | ExperimenterSerialize |
+| message | | >(4, | rKeyFactory |
+| | | experimenterId, | |
+| | | ExperimenterInput.class) | |
++----------------+---------+------------------------------+-----------------------+
+| Match entry | 1.3 | MatchEntrySerializerKey<>(4, | . |
+| | | (class) ${oxm\_class}, | |
+| | | (class) ${oxm\_field}); | |
++----------------+---------+------------------------------+-----------------------+
+| | | key.setExperimenterId(experi | . |
+| | | menter | |
+| | | ID) | |
++----------------+---------+------------------------------+-----------------------+
+| Action | 1.3 | ExperimenterActionSerializer | . |
+| | | Key(4, | |
+| | | experimenterId, sub-type) | |
++----------------+---------+------------------------------+-----------------------+
+| Instruction | 1.3 | ExperimenterInstructionSeria | . |
+| | | lizerKey(4, | |
+| | | experimenter ID) | |
++----------------+---------+------------------------------+-----------------------+
+| Multipart | 1.3 | ExperimenterIdSerializerKey< | ExperimenterSerialize |
+| | | >(4, | rKeyFactory |
+| | | experimenterId, | |
+| | | MultipartRequestExperimenter | |
+| | | Case.class) | |
++----------------+---------+------------------------------+-----------------------+
+| Multipart - | 1.3 | ExperimenterIdSerializerKey< | ExperimenterSerialize |
+| Table features | | >(4, | rKeyFactory |
+| | | experimenterId, | |
+| | | TableFeatureProperties.class | |
+| | | ) | |
++----------------+---------+------------------------------+-----------------------+
+| Meter band | 1.3 | ExperimenterIdSerializerKey< | ExperimenterSerialize |
+| type | | >(4, | rKeyFactory |
+| | | experimenterId, | |
+| | | MeterBandExperimenterCase.cl | |
+| | | ass) | |
++----------------+---------+------------------------------+-----------------------+
+
+Table: **Serialization**
+
--- /dev/null
+OpFlex agent-ovs Developer Guide
+================================
+
+Overview
+--------
+
+agent-ovs is a policy agent that works with OVS to enforce a group-based
+policy networking model with locally attached virtual machines or
+containers. The policy agent is designed to work well with orchestration
+tools like OpenStack.
+
+agent-ovs Architecture
+----------------------
+
+agent-ovs uses libopflex to communicate with an OpFlex-based policy
+repository to enforce policy on network endpoints attached to OVS by an
+orchestration system.
+
+The key components are:
+
+- Agent - coordinates startup and configuration
+
+- Renderers - Renderers are responsible for rendering policy. This is a
+ very general mechanism but the currently-implemented renderer is the
+ stitched-mode renderer that can work along with with hardware fabrics
+ such as ACI that support policy enforcement.
+
+- EndpointManager - Keep track of network endpoints and declare them to
+ the endpoint repository
+
+- PolicyManager - Keep track of and index policies
+
+- FlowManager - render policies to OVS
+
+API Reference Documentation
+---------------------------
+
+Internal API documentation can be found here:
+https://jenkins.opendaylight.org/opflex/job/opflex-merge/ws/agent-ovs/doc/html/index.html
+
--- /dev/null
+OpFlex genie Developer Guide
+============================
+
+Overview
+--------
+
+Genie is a tool for code generation from a model. It supports generating
+C++ and Java code. C++ can be generated suitable for use with libopflex.
+C++ and Java can be generated as a plain set of objects.
+
+Group-based Policy Model
+------------------------
+
+The group-based policy model is included with the genie tool and can be
+found under the MODEL directory. By running mvn exec:java, libmodelgbp
+will be generated as a library project that, when built and installed,
+will work with libopflex. This model is used by the OVS agent.
+
+API Reference Documentation
+---------------------------
+
+Complete API documentation for the generated libmodelgbp can be found
+here:
+https://jenkins.opendaylight.org/opflex/job/opflex-merge/ws/libopflex/doc/html/index.html
+
--- /dev/null
+OpFlex libopflex Developer Guide
+================================
+
+Overview
+--------
+
+The OpFlex framework allows you to develop agents that can communicate
+using the OpFlex protocol and act as a policy element in an OpFlex-based
+distributed control system. The OpFlex architecture provides a
+distributed control system based on a declarative policy information
+model. The policies are defined at a logically centralized policy
+repository and enforced within a set of distributed policy elements. The
+policy repository communicates with the subordinate policy elements
+using the OpFlex control protocol. This protocol allows for
+bidirectional communication of policy, events, statistics, and faults.
+
+Rather than simply providing access to the OpFlex protocol, this
+framework allows you to directly manipulate a management information
+tree containing a hierarchy of managed objects. This tree is kept in
+sync as needed with other policy elements in the system, and you are
+automatically notified when important changes to the model occur.
+Additionally, we can ensure that only those managed objects that are
+important to the local policy element are synchronized locally.
+
+Object Model
+~~~~~~~~~~~~
+
+Interactions with the OpFlex framework happen through the management
+information tree. This is a tree of managed objects defined by an object
+model specific to your application. There are a few important major
+category of objects that can appear in the model.
+
+- First, there is the policy object. A policy object represents some
+ data related to a policy that describes a user intent for how the
+ system should behave. A policy object is stored in the policy
+ repository which is the source of "truth" for this object.
+
+- Second, there is an endpoint object. A endpoint represents an entity
+ in the system to which we want to apply policy, which could be a
+ network interface, a storage array, or other relevent policy
+ endpoint. Endpoints are discovered and reported by policy elements
+ locally, and are synchronized into the endpoint repository. The
+ originating policy element is the source of truth for the endpoints
+ it discovers. Policy elements can retrieve information about
+ endpoints discovered by other policy elements by resolving endpoints
+ from the endpoint repository.
+
+- Third, there is the observable object. An observable object
+ represents some state related to the operational status or health of
+ the policy element. Observable objects will be reported to the
+ observer.
+
+- Finally, there is the local-only object. This is the simplest object
+ because it exists only local to a particular policy element. These
+ objects can be used to store state specific to that policy element,
+ or as helpers to resolve other objects. Read on to learn more.
+
+You can use the genie tool that is included with the framework to
+produce your application model along with a set of generated accessor
+classes that can work with this framework library. You should refer to
+the documentation that accompanies the genie tool for information on how
+to use to to generate your object model. Later in this guide, we’ll go
+through examples of how to use the generated managed object accessor
+classes.
+
+Programming by Side Effect
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When developing software on the OpFlex framework, you’ll need to think
+in a slightly different way. Rather than calling an API function that
+would perform some specific action, you’ll need to write a managed
+object to the managed object database. Writing that object to the store
+will trigger the side effect of performing the action that you want.
+
+For example, a policy element will need to have a component responsible
+for discovering policy endpoints. When it discovers a policy endpoint,
+it would write an endpoint object into the managed object database. That
+endpoint object will contain a reference to policy that is relevant to
+the endpoint object. This will trigger a whole cascade of events. First,
+the framework will notice that an endpoint object has been created and
+it will write it to the endpoint repository. Second, the framework to
+will attempt to resolve the unresolved reference to the relevent policy
+object. There might be a whole chain of policy resolutions that will be
+automatically performed to download all the relevent policy until there
+are no longer any dangling references.
+
+As long as there is a locally-created object in the system with a
+reference to that policy, the framework will continually ensure that the
+policy and any transitive policies are kept up to date. The policy
+element can subscribe to updates to these policy classes that will be
+invoked either the first time the policy is resolved or any time the
+policy changes.
+
+A consequence of this design is that the managed object database can be
+temporarily in an inconsistent state with unresolved dangling
+references. Eventually, however, the inconsistency will be fully
+resolved. The policy element must be able to cleanly handle
+partially-resolved or inconsistent state and eventually reach the
+correct state as it receives these update notifications. Note that, in
+the OpFlex architecture, when there is no policy that specifically
+allows a particular action, that action must be prevented.
+
+Let’s cover one slightly more complex example. If a policy element needs
+to discover information about an endpoint that is not local to that
+policy element, it will need to retrieve that information from the
+endpoint repository. However, just as there is no API call to retrieve a
+policy object from the policy repository, there is no API call to
+retrieve an endpoint from the endpoint repository.
+
+To get this information, the policy element needs to create a local-only
+object that references the endpoint. Once it creates this local-only
+object, if the endpoint is not already resolved, the framework will
+notice the dangling reference and automatically resolve the endpoint
+from the endpoint respository. When the endpoint resolution completes,
+the framework deliver an update notification to the policy element. The
+policy element will continue to receive any updates related to that
+endpoint until the policy element remove the local-only reference to the
+object. Once this occurs, the framework can garbage-collect any
+unreferenced objects.
+
+Threading and Ownership
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The OpFlex framework uses a somewhat unique threading model. Each
+managed object in the system belongs to a particular owner. An owner
+would typically be a single thread that is reponsible for all updates to
+objects with that owner. Though anything can read the state of a managed
+object, only the owner of a managed object is permitted to write to it.
+Though this is not strictly required for correctness, the performance of
+the system wil be best if you ensure that only one thread at a time is
+writing to objects with a particular owner.
+
+Change notifications are delivered in a serialized fashion by a single
+thread. Blocking this thread from a notification callback will stall
+delivery of all notifications. It is therefore best practice to ensure
+that you do not block or perform long-running operations from a
+notification callback.
+
+Key APIs and Interfaces
+-----------------------
+
+Basic Usage and Initialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The primary interface point into the framework is
+opflex::ofcore::OFFramework. You can choose to instantiate your own copy
+of the framework, or you can use the static default instance.
+
+Before you can use the framework, you must initialize it by installing
+your model metadata. The model metadata is accessible through the
+generated model library. In this case, it assumes your model is called
+"mymodel":
+
+.. code:: cpp
+
+ #include <opflex/ofcore/OFFramework.h>
+ #include <mymodel/metadata/metadata.hpp>
+ // ...
+ using opflex::ofcore::OFFramework;
+ OFFramework::defaultInstance().setModel(mymodel::getMetadata());
+
+The other critical piece of information required for initialization is
+the OpFlex identity information. The identity information is required in
+order to successfully connect to OpFlex peers. In OpFlex, each component
+has a unique name within its policy domain, and each policy domain is
+identified by a globally unique domain name. You can set this identity
+information by calling:
+
+.. code:: cpp
+
+ OFFramework::defaultInstance()
+ .setOpflexIdentity("[component name]", "[unique domain]");
+
+You can then start the framework simply by calling:
+
+.. code:: cpp
+
+ OFFramework::defaultInstance().start();
+
+Finally, you can add peers after the framework is started by calling the
+``opflex::ofcore::OFFramework::addPeer`` method:
+
+.. code:: cpp
+
+ OFFramework::defaultInstance().addPeer("192.168.1.5", 1234);
+
+When connecting to the peer, that peer may provide an additional list of
+peers to connect to, which will be automatically added as peers. If the
+peer does not include itself in the list, then the framework will
+disconnect from that peer and add the peers in the list. In this way, it
+is possible to automatically bootstrap the correct set of peers using a
+known hostname or IP address or a known, fixed anycast IP address.
+
+To cleanly shut down, you can call:
+
+.. code:: cpp
+
+ OFFramework::defaultInstance().stop();
+
+Working with Data in the Tree
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Reading from the Tree
+^^^^^^^^^^^^^^^^^^^^^
+
+You can access data in the managed tree using the generated accessor
+classes. The details of exactly which classes you’ll use will depend on
+the model you’re using, but let’s assume that we have a simple model
+called "simple" with the following classes:
+
+- root - The root node. The URI for the root node is "/"
+
+- foo - A policy object, and a child of root, with a scalar string
+ property called "bar", and a unsigned 64-bit integer property called
+ baz. The bar property is the naming property for foo. The URI for a
+ foo object would be "/foo/[value of bar]/"
+
+- fooref - A local-only child of root, with a reference to a foo, and a
+ scalar string property called "bar". The bar property is the naming
+ property for foo. The URI for a fooref object would be
+ "/fooref/[value of bar]/"
+
+In this example, we’ll have a generated class for each of the objects.
+There are two main ways to get access to an object in the tree.
+
+First, we can get instantiate an accessor class to any node in the tree
+by calling one of its static resolve functions. The resolve functions
+can take either an already-built URI that represents the object, or you
+can call the version that will locate the object by its naming
+properties.
+
+Second, we can access the object also from its parent object using the
+appropriate child resolver member functions.
+
+However we read it, the object we get back is an immutable view into the
+object it references. The properties set locally on that object will not
+change even though the underlying object may have been updated in the
+store. Note, however, that its children can change between when you
+first retrieve the object and when you resolve any children.
+
+Another thing that is critical to note again is that when you attempt to
+resolve an object, you can get back nothing, even if the object actually
+does exist on another OpFlex node. You must ensure that some object in
+the managed object database references the remote managed object you
+want before it will be visible to you.
+
+To get access to the root node using the default framework instance, we
+can simply call:
+
+.. code:: cpp
+
+ using boost::shared_ptr;
+ using boost::optional;
+ optional<shared_ptr<simple::root> > r(simple::root::resolve());
+
+Note that whenever we can a resolve function, we get back our data in
+the form of an optional shared pointer to the object instance. If the
+node does not exist, then the optional will be set to boost::none. Note
+that if you dereference an optional that has not been set, you’ll
+trigger an assert, so you must check the return as follows:
+
+.. code:: cpp
+
+ if (!r) {
+ // handle missing object
+ }
+
+Now let’s get a child node of the root in three different ways:
+
+.. code:: cpp
+
+ // Get foo1 by constructing its URI from the root
+ optional<shared_ptr<simple::foo> > foo1(simple::foo::resolve("test"));
+ // get foo1 by constructing its URI relative to its parent
+ foo1 = r.get()->resolveFoo("test");
+ // get foo1 by manually building its URI
+ foo1 = simple::foo::resolve(opflex::modb::URIBuilder()
+ .addElement("foo")
+ .addElement("test")
+ .build());
+
+All three of these calls will give us the same object, which is the
+"foo" object located at "/foo/test/".
+
+The foo class has a single string property called "bar". We can easily
+access it as follows:
+
+.. code:: cpp
+
+ const std::string& barv = foo1.getBar();
+
+Writing to the Tree
+^^^^^^^^^^^^^^^^^^^
+
+Writing to the tree is nearly as easy as reading from it. The key
+concept to understand is the mutator object. If you want to make changes
+to the tree, you must allocate a mutator object. The mutator will
+register itself in some thread-local storage in the framework instance
+you’re using. The mutator is specific to a single "owner" for the data,
+so you can only make changes to data associated with that owner.
+
+Whenever you modify one of the accessor classes, the change is actually
+forwarded to the currently-active mutator. You won’t see any of the
+changes you make until you call the commit member function on the
+mutator. When you do that, all the changes you made are written into the
+store.
+
+Once the changes are written into the store, you will need to call the
+appropriate resolve function again to see the changes.
+
+Allocating a mutator is simple. To create a mutator for the default
+framework instance associated with the owner "owner1", just allocate the
+mutator on the stack. Be sure to call commit() before it goes out of
+scope or you’ll lose your changes.
+
+.. code:: cpp
+
+ {
+ opflex::modb::Mutator mutator("owner1");
+ // make changes here
+ mutator.commit();
+ }
+
+Note that if an exception is thrown while making changes but before
+committing, the mutator will go out of scope and the changes will be
+discarded.
+
+To create a new node, you must call the appropriate add[Child] member
+function on its parent. This function takes parameters for each of the
+naming properties for the object:
+
+.. code:: cpp
+
+ shared_ptr<simple::foo> newfoo(root->addFoo("test"));
+
+This will return a shared pointer to a new foo object that has been
+registered in the active mutator but not yet committed. The "bar" naming
+property will be set automatically, but if you want to set the "baz"
+property now, you can do so by calling:
+
+.. code:: cpp
+
+ newfoo->setBaz(42);
+
+Note that creating the root node requires a call to the special static
+class method createRootElement:
+
+.. code:: cpp
+
+ shared_ptr<simple::root> newroot(simple::root::createRootElement());
+
+Here’s a complete example that ties this all together:
+
+.. code:: cpp
+
+ {
+ opflex::modb::Mutator mutator("owner1");
+ shared_ptr<simple::root> newroot(simple::root::createRootElement());
+ shared_ptr<simple::root> newfoo(newroot->addFoo("test"));
+ newfoo->setBaz(42);
+
+ mutator.commit();
+ }
+
+Update Notifications
+~~~~~~~~~~~~~~~~~~~~
+
+When using the OpFlex framework, you’re likely to find that most of your
+time is spend responding to changes in the managed object database. To
+get these notifications, you’re going to need to register some number of
+listeners.
+
+You can register an object listener to see all changes related to a
+particular class by calling a static function for that class. You’ll
+then get notifications whenever any object in that class is added,
+updated, or deleted. The listener should queue a task to read the new
+state and perform appropriate processing. If this function blocks or
+peforms a long-running operation, then the dispatching of update
+notifications will be stalled, but there will not be any other
+deleterious effects.
+
+If multiple changes happen to the same URI, then at least one
+notification will be delivered but some events may be consolidated.
+
+The update you get will tell you the URI and the Class ID of the changed
+object. The class ID is a unique ID for each class. When you get the
+update, you’ll need to call the appropriate resolve function to retrieve
+the new value.
+
+You’ll need to create your own object listener derived from
+opflex::modb::ObjectListener:
+
+.. code:: cpp
+
+ class MyListener : public ObjectListener {
+ public:
+ MyListener() { }
+ virtual void objectUpdated(class_id_t class_id, const URI& uri) {
+ // Your handler here
+ }
+ };
+
+To register your listener with the default framework instance, just call
+the appropriate class static method:
+
+.. code:: cpp
+
+ MyListener listener;
+ simple::foo::registerListener(&listener);
+ // main loop
+ simple::foo::unregisterListener(&listener);
+
+The listener will now recieve notifications whenever any foo or any
+children of any foo object changes.
+
+Note that you must ensure that you unregister your listeners before
+deallocating them.
+
+API Reference Documentation
+---------------------------
+
+Complete API documentation can be found through doxygen here:
+https://jenkins.opendaylight.org/opflex/job/opflex-merge/ws/libopflex/doc/html/index.html
+
--- /dev/null
+Service Function Chaining
+=========================
+
+OpenDaylight Service Function Chaining (SFC) Overiew
+----------------------------------------------------
+
+OpenDaylight Service Function Chaining (SFC) provides the ability to
+define an ordered list of a network services (e.g. firewalls, load
+balancers). These service are then "stitched" together in the network to
+create a service chain. This project provides the infrastructure
+(chaining logic, APIs) needed for ODL to provision a service chain in
+the network and an end-user application for defining such chains.
+
+- ACE - Access Control Entry
+
+- ACL - Access Control List
+
+- SCF - Service Classifier Function
+
+- SF - Service Function
+
+- SFC - Service Function Chain
+
+- SFF - Service Function Forwarder
+
+- SFG - Service Function Group
+
+- SFP - Service Function Path
+
+- RSP - Rendered Service Path
+
+- NSH - Network Service Header
+
+SFC Classifier Control and Date plane Developer guide
+-----------------------------------------------------
+
+Overview
+~~~~~~~~
+
+Description of classifier can be found in:
+https://datatracker.ietf.org/doc/draft-ietf-sfc-architecture/
+
+Classifier manages everything from starting the packet listener to
+creation (and removal) of appropriate ip(6)tables rules and marking
+received packets accordingly. Its functionality is **available only on
+Linux** as it leverdges **NetfilterQueue**, which provides access to
+packets matched by an **iptables** rule. Classifier requires **root
+privileges** to be able to operate.
+
+So far it is capable of processing ACL for MAC addresses, ports, IPv4
+and IPv6. Supported protocols are TCP and UDP.
+
+Classifier Architecture
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Python code located in the project repository
+sfc-py/common/classifier.py.
+
+.. note::
+
+ classifier assumes that Rendered Service Path (RSP) **already
+ exists** in ODL when an ACL referencing it is obtained
+
+1. sfc\_agent receives an ACL and passes it for processing to the
+ classifier
+
+2. the RSP (its SFF locator) referenced by ACL is requested from ODL
+
+3. if the RSP exists in the ODL then ACL based iptables rules for it are
+ applied
+
+After this process is over, every packet successfully matched to an
+iptables rule (i.e. successfully classified) will be NSH encapsulated
+and forwarded to a related SFF, which knows how to traverse the RSP.
+
+Rules are created using appropriate iptables command. If the Access
+Control Entry (ACE) rule is MAC address related both iptables and
+ip6tabeles rules re issued. If ACE rule is IPv4 address related, only
+iptables rules are issued, same for IPv6.
+
+.. note::
+
+ iptables **raw** table contains all created rules
+
+Information regarding already registered RSP(s) are stored in an
+internal data-store, which is represented as a dictionary:
+
+::
+
+ {rsp_id: {'name': <rsp_name>,
+ 'chains': {'chain_name': (<ipv>,),
+ ...
+ },
+ 'sff': {'ip': <ip>,
+ 'port': <port>,
+ 'starting-index': <starting-index>,
+ 'transport-type': <transport-type>
+ },
+ },
+ ...
+ }
+
+- ``name``: name of the RSP
+
+- ``chains``: dictionary of iptables chains related to the RSP with
+ information about IP version for which the chain exists
+
+- ``SFF``: SFF forwarding parameters
+
+ - ``ip``: SFF IP address
+
+ - ``port``: SFF port
+
+ - ``starting-index``: index given to packet at first RSP hop
+
+ - ``transport-type``: encapsulation protocol
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This features exposes API to configure classifier (corresponds to
+service-function-classifier.yang)
+
+API Reference Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See: sfc-model/src/main/yang/service-function-classifier.yang
+
+SFC-OVS Plugin
+--------------
+
+Overview
+~~~~~~~~
+
+SFC-OVS provides integration of SFC with Open vSwitch (OVS) devices.
+Integration is realized through mapping of SFC objects (like SF, SFF,
+Classifier, etc.) to OVS objects (like Bridge,
+TerminationPoint=Port/Interface). The mapping takes care of automatic
+instantiation (setup) of corresponding object whenever its counterpart
+is created. For example, when a new SFF is created, the SFC-OVS plugin
+will create a new OVS bridge and when a new OVS Bridge is created, the
+SFC-OVS plugin will create a new SFF.
+
+SFC-OVS Architecture
+~~~~~~~~~~~~~~~~~~~~
+
+SFC-OVS uses the OVSDB MD-SAL Southbound API for getting/writing
+information from/to OVS devices. The core functionality consists of two
+types of mapping:
+
+a. mapping from OVS to SFC
+
+ - OVS Bridge is mapped to SFF
+
+ - OVS TerminationPoints are mapped to SFF DataPlane locators
+
+b. mapping from SFC to OVS
+
+ - SFF is mapped to OVS Bridge
+
+ - SFF DataPlane locators are mapped to OVS TerminationPoints
+
+.. figure:: ./images/sfc/sfc-ovs-architecture.png
+ :alt: SFC < — > OVS mapping flow diagram
+
+ SFC < — > OVS mapping flow diagram
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- SFF to OVS mapping API (methods to convert SFF object to OVS Bridge
+ and OVS TerminationPoints)
+
+- OVS to SFF mapping API (methods to convert OVS Bridge and OVS
+ TerminationPoints to SFF object)
+
+SFC Southbound REST Plugin
+--------------------------
+
+Overview
+~~~~~~~~
+
+The Southbound REST Plugin is used to send configuration from DataStore
+down to network devices supporting a REST API (i.e. they have a
+configured REST URI). It supports POST/PUT/DELETE operations, which are
+triggered accordingly by changes in the SFC data stores.
+
+- Access Control List (ACL)
+
+- Service Classifier Function (SCF)
+
+- Service Function (SF)
+
+- Service Function Group (SFG)
+
+- Service Function Schedule Type (SFST)
+
+- Service Function Forwader (SFF)
+
+- Rendered Service Path (RSP)
+
+Southbound REST Plugin Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **listeners** - used to listen on changes in the SFC data stores
+
+2. **JSON exporters** - used to export JSON-encoded data from
+ binding-aware data store objects
+
+3. **tasks** - used to collect REST URIs of network devices and to send
+ JSON-encoded data down to these devices
+
+.. figure:: ./images/sfc/sb-rest-architecture.png
+ :alt: Southbound REST Plugin Architecture diagram
+
+ Southbound REST Plugin Architecture diagram
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The plugin provides Southbound REST API designated to listening REST
+devices. It supports POST/PUT/DELETE operations. The operation (with
+corresponding JSON-encoded data) is sent to unique REST URL belonging to
+certain datatype.
+
+- Access Control List (ACL):
+ ``http://<host>:<port>/config/ietf-acl:access-lists/access-list/``
+
+- Service Function (SF):
+ ``http://<host>:<port>/config/service-function:service-functions/service-function/``
+
+- Service Function Group (SFG):
+ ``http://<host>:<port>/config/service-function:service-function-groups/service-function-group/``
+
+- Service Function Schedule Type (SFST):
+ ``http://<host>:<port>/config/service-function-scheduler-type:service-function-scheduler-types/service-function-scheduler-type/``
+
+- Service Function Forwarder (SFF):
+ ``http://<host>:<port>/config/service-function-forwarder:service-function-forwarders/service-function-forwarder/``
+
+- Rendered Service Path (RSP):
+ ``http://<host>:<port>/operational/rendered-service-path:rendered-service-paths/rendered-service-path/``
+
+Therefore, network devices willing to receive REST messages must listen
+on these REST URLs.
+
+.. note::
+
+ Service Classifier Function (SCF) URL does not exist, because SCF is
+ considered as one of the network devices willing to receive REST
+ messages. However, there is a listener hooked on the SCF data store,
+ which is triggering POST/PUT/DELETE operations of ACL object,
+ because ACL is referenced in ``service-function-classifier.yang``
+
+Service Function Load Balancing Developer Guide
+-----------------------------------------------
+
+Overview
+~~~~~~~~
+
+SFC Load-Balancing feature implements load balancing of Service
+Functions, rather than a one-to-one mapping between Service Function
+Forwarder and Service Function.
+
+Load Balancing Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Service Function Groups (SFG) can replace Service Functions (SF) in the
+Rendered Path model. A Service Path can only be defined using SFGs or
+SFs, but not a combination of both.
+
+Relevant objects in the YANG model are as follows:
+
+1. Service-Function-Group-Algorithm:
+
+ ::
+
+ Service-Function-Group-Algorithms {
+ Service-Function-Group-Algorithm {
+ String name
+ String type
+ }
+ }
+
+ ::
+
+ Available types: ALL, SELECT, INDIRECT, FAST_FAILURE
+
+2. Service-Function-Group:
+
+ ::
+
+ Service-Function-Groups {
+ Service-Function-Group {
+ String name
+ String serviceFunctionGroupAlgorithmName
+ String type
+ String groupId
+ Service-Function-Group-Element {
+ String service-function-name
+ int index
+ }
+ }
+ }
+
+3. ServiceFunctionHop: holds a reference to a name of SFG (or SF)
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This feature enhances the existing SFC API.
+
+REST API commands include: \* For Service Function Group (SFG): read
+existing SFG, write new SFG, delete existing SFG, add Service Function
+(SF) to SFG, and delete SF from SFG \* For Service Function Group
+Algorithm (SFG-Alg): read, write, delete
+
+Bundle providing the REST API: sfc-sb-rest \* Service Function Groups
+and Algorithms are defined in: sfc-sfg and sfc-sfg-alg \* Relevant JAVA
+API: SfcProviderServiceFunctionGroupAPI,
+SfcProviderServiceFunctionGroupAlgAPI
+
+Service Function Scheduling Algorithms
+--------------------------------------
+
+Overview
+~~~~~~~~
+
+When creating the Rendered Service Path (RSP), the earlier release of
+SFC chose the first available service function from a list of service
+function names. Now a new API is introduced to allow developers to
+develop their own schedule algorithms when creating the RSP. There are
+four scheduling algorithms (Random, Round Robin, Load Balance and
+Shortest Path) are provided as examples for the API definition. This
+guide gives a simple introduction of how to develop service function
+scheduling algorithms based on the current extensible framework.
+
+Architecture
+~~~~~~~~~~~~
+
+The following figure illustrates the service function selection
+framework and algorithms.
+
+.. figure:: ./images/sfc-sf-selection-arch.png
+ :alt: SF Scheduling Algorithm framework Architecture
+
+ SF Scheduling Algorithm framework Architecture
+
+The YANG Model defines the Service Function Scheduling Algorithm type
+identities and how they are stored in the MD-SAL data store for the
+scheduling algorithms.
+
+The MD-SAL data store stores all informations for the scheduling
+algorithms, including their types, names, and status.
+
+The API provides some basic APIs to manage the informations stored in
+the MD-SAL data store, like putting new items into it, getting all
+scheduling algorithms, etc.
+
+The RESTCONF API provides APIs to manage the informations stored in the
+MD-SAL data store through RESTful calls.
+
+The Service Function Chain Renderer gets the enabled scheduling
+algorithm type, and schedules the service functions with scheduling
+algorithm implementation.
+
+Key APIs and Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+While developing a new Service Function Scheduling Algorithm, a new
+class should be added and it should extend the base schedule class
+SfcServiceFunctionSchedulerAPI. And the new class should implement the
+abstract function:
+
+``public List<String> scheduleServiceFuntions(ServiceFunctionChain chain, int serviceIndex)``.
+
+- **``ServiceFunctionChain chain``**: the chain which will be rendered
+
+- **``int serviceIndex``**: the initial service index for this rendered
+ service path
+
+- **``List<String>``**: a list of service funtion names which scheduled
+ by the Service Function Scheduling Algorithm.
+
+API Reference Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please refer the API docs generated in the mdsal-apidocs.
+
--- /dev/null
+SNMP4SDN Developer Guide
+========================
+
+Overview
+--------
+
+We propose a southbound plugin that can control the off-the-shelf
+commodity Ethernet switches for the purpose of building SDN using
+Ethernet switches. For Ethernet switches, forwarding table, VLAN table,
+and ACL are where one can install flow configuration on, and this is
+done via SNMP and CLI in the proposed plugin. In addition, some settings
+required for Ethernet switches in SDN, e.g., disabling STP and flooding,
+are proposed.
+
+.. figure:: ./images/snmp4sdn_in_odl_architecture.jpg
+ :alt: SNMP4SDN as an OpenDaylight southbound plugin
+
+ SNMP4SDN as an OpenDaylight southbound plugin
+
+Architecture
+------------
+
+The modules in the plugin are depicted as the following figure.
+
+.. figure:: ./images/snmp4sdn_modules.jpg
+ :alt: Modules in the SNMP4SDN Plugin
+
+ Modules in the SNMP4SDN Plugin
+
+- AclService: add/remove ACL profile and rule on the switches.
+
+- FdbService: add/modify/remove FDB table entry on the switches.
+
+- VlanService: add/modify/remove VLAN table entry on the switches.
+
+- TopologyService: query and acquire the subnet topology.
+
+- InventoryService: acquire the switches and their ports.
+
+- DiscoveryService: probe and resolve the underlying switches as well
+ as the port pairs connecting the switches. The probing is realized by
+ SNMP queries. The updates from discovery will also be reflected to
+ the TopologyService.
+
+- MiscConfigService: do kinds of settings on switches
+
+ - Supported STP and ARP settings such as enable/disable STP, get
+ port’s STP state, get ARP table, set ARP entry, and others
+
+- VendorSpecificHandler: to assist the flow configuration services to
+ call the switch-talking modules with correct parameters value and
+ order.
+
+- Switch-talking modules
+
+ - For the services above, when they need to read or configure the
+ underlying switches via SNMP or CLI, these queries are dealt with
+ the modules SNMPHandler and CLIHandler which directly talk with
+ the switches. The SNMPListener is to listen to snmp trap such as
+ link up/down event or switch on/off event.
+
+Design
+------
+
+In terms of the architecture of the SNMP4SDN Plugin’s features, the
+features include flow configuration, topology discovery, and
+multi-vendor support. Their architectures please refer to Wiki
+(`Developer Guide -
+Design <https://wiki.opendaylight.org/view/SNMP4SDN:Developer_Guide#Design>`__).
+
+Installation and Configuration Guide
+------------------------------------
+
+- Please refer to the *Getting Started Guide* in
+ https://www.opendaylight.org/downloads, find the SNMP4SDN section.
+
+- For the latest full guide, please refer to Wiki (`Installation
+ Guide <https://wiki.opendaylight.org/view/SNMP4SDN:Installation_Guide>`__,
+ `User Guide -
+ Configuration <https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Configuration>`__).
+
+Tutorial
+--------
+
+- For the latest full guide, please refer to Wiki (`User Guide -
+ Tutorial <https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Tutorial_.2F_How-To>`__).
+
+Programmatic Interface(s)
+-------------------------
+
+SNMP4SDN Plugin exposes APIs via MD-SAL with YANG model. The methods
+(RPC call) and data structures for them are listed below.
+
+TopologyService
+~~~~~~~~~~~~~~~
+
+- RPC call
+
+ - get-edge-list
+
+ - get-node-list
+
+ - get-node-connector-list
+
+ - set-discovery-interval (given interval time in seconds)
+
+ - rediscover
+
+- Data structure
+
+ - node: composed of node-id, node-type
+
+ - node-connector: composed of node-connector-id,
+ node-connector-type, node
+
+ - topo-edge: composed of head-node-connector-id,
+ head-node-connector-type, head-node-id, head-node-type,
+ tail-node-connector-id, tail-node-connector-type, tail-node-id,
+ tail-node-type
+
+VlanService
+~~~~~~~~~~~
+
+- RPC call
+
+ - add-vlan (given node ID, VLAN ID, VLAN name)
+
+ - add-vlan-and-set-ports (given node ID, VLAN ID, VLAN name, tagged
+ ports, untagged ports)
+
+ - set-vlan-ports (given node ID, VLAN ID, tagged ports, untagged
+ ports)
+
+ - delete-vlan (given node ID, VLAN ID)
+
+ - get-vlan-table (given node ID)
+
+AclService
+~~~~~~~~~~
+
+- RPC call
+
+ - create-acl-profile (given node ID, acl-profile-index, acl-profile)
+
+ - del-acl-profile (given node ID, acl-profile-index)
+
+ - set-acl-rule (given node ID, acl-index, acl-rule)
+
+ - del-acl-rule (given node ID, acl-index)
+
+ - clear-acl-table (given node ID)
+
+- Data structure
+
+ - acl-profile-index: composed of profile-id, profile name
+
+ - acl-profile: composed of acl-layer, vlan-mask, src-ip-mask,
+ dst-ip-mask
+
+ - acl-layer: IP or ETHERNET
+
+ - acl-index: composed of acl-profile-index, acl-rule-index
+
+ - acl-rule-index: composed of rule-id, rule-name
+
+ - acl-rule: composed of port-list, acl-layer, acl-field, acl-action
+
+ - acl-field: composed of vlan-id, src-ip, dst-ip
+
+ - acl-action: PERMIT or DENY
+
+FdbService
+~~~~~~~~~~
+
+- RPC call
+
+ - set-fdb-entry (given fdb-entry)
+
+ - del-fdb-entry (given node-id, vlan-id, dest-mac-adddr)
+
+ - get-fdb-entry (given node-id, vlan-id, dest-mac-adddr)
+
+ - get-fdb-table (given node-id)
+
+- Data structure
+
+ - fdb-entry: composed of node-id, vlan-id, dest-mac-addr, port,
+ fdb-entry-type
+
+ - fdb-entry-type: OTHER/INVALID/LEARNED/SELF/MGMT
+
+MiscConfigService
+~~~~~~~~~~~~~~~~~
+
+- RPC call
+
+ - set-stp-port-state (given node-id, port, is\_nable)
+
+ - get-stp-port-state (given node-id, port)
+
+ - get-stp-port-root (given node-id, port)
+
+ - enable-stp (given node-id)
+
+ - disable-stp (given node-id)
+
+ - delete-arp-entry (given node-id, ip-address)
+
+ - set-arp-entry (given node-id, arp-entry)
+
+ - get-arp-entry (given node-id, ip-address)
+
+ - get-arp-table (given node-id)
+
+- Data structure
+
+ - stp-port-state:
+ DISABLE/BLOCKING/LISTENING/LEARNING/FORWARDING/BROKEN
+
+ - arp-entry: composed of ip-address and mac-address
+
+SwitchDbService
+~~~~~~~~~~~~~~~
+
+- RPC call
+
+ - reload-db (The following 4 RPC implemention is TBD)
+
+ - add-switch-entry
+
+ - delete-switch-entry
+
+ - clear-db
+
+ - update-db
+
+- Data structure
+
+ - switch-info: compose of node-ip, node-mac, community,
+ cli-user-name, cli-password, model
+
+Help
+----
+
+- `SNMP4SDN Wiki <https://wiki.opendaylight.org/view/SNMP4SDN:Main>`__
+
+- SNMP4SDN Mailing List
+ (`user <https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-users>`__,
+ `developer <https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-dev>`__)
+
+- `Latest troubleshooting in
+ Wiki <https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Troubleshooting>`__
+
--- /dev/null
+SXP Developer Guide
+===================
+
+Overview
+--------
+
+SXP (Source-Group Tag eXchange Protocol) project is an effort to enhance
+OpenDaylight platform with IP-SGT (IP Address to Source Group Tag)
+bindings that can be learned from connected SXP-aware network nodes. The
+current implementation supports SXP protocol version 4 according to the
+Smith, Kandula - SXP `IETF
+draft <https://tools.ietf.org/html/draft-smith-kandula-sxp-04>`__ and
+grouping of peers and creating filters based on ACL/Prefix-list syntax
+for filtering outbound and inbound IP-SGT bindings. All protocol legacy
+versions 1-3 are supported as well. Additionally, version 4 adds
+bidirectional connection type as an extension of a unidirectional one.
+
+SXP Architecture
+----------------
+
+The SXP Server manages all connected clients in separate threads and a
+common SXP protocol agreement is used between connected peers. Each SXP
+network peer is modelled with its pertaining class, e.g., SXP Server
+represents the SXP Speaker, SXP Listener the Client. The server program
+creates the ServerSocket object on a specified port and waits until a
+client starts up and requests connect on the IP address and port of the
+server. The client program opens a Socket that is connected to the
+server running on the specified host IP address and port.
+
+The SXP Listener maintains connection with its speaker peer. From an
+opened channel pipeline, all incoming SXP messages are processed by
+various handlers. Message must be decoded, parsed and validated.
+
+The SXP Speaker is a counterpart to the SXP Listener. It maintains a
+connection with its listener peer and sends composed messages.
+
+The SXP Binding Handler extracts the IP-SGT binding from a message and
+pulls it into the SXP-Database. If an error is detected during the
+IP-SGT extraction, an appropriate error code and sub-code is selected
+and an error message is sent back to the connected peer. All transitive
+messages are routed directly to the output queue of SXP Binding
+Dispatcher.
+
+The SXP Binding Dispatcher represents a selector that will decides how
+many data from the SXP-database will be sent and when. It is responsible
+for message content composition based on maximum message length.
+
+The SXP Binding Filters handles filtering of outgoing and incoming
+IP-SGT bindings according to BGP filtering using ACL and Prefix List
+syntax for specifying filter or based on Peer-sequence length.
+
+The SXP Domains feature provides isolation of SXP peers and bindings
+learned between them, also exchange of Bindings is possible across
+SXP-Domains by ACL, Prefix List or Peer-Sequence filters
+
+Key APIs and Interfaces
+-----------------------
+
+As this project is fairly small, it provides only few features that
+install and provide all APIs and implementations for this project.
+
+- sxp-controller
+
+- sxp-api
+
+- spx-core
+
+sxp-controller
+~~~~~~~~~~~~~~
+
+RPC request handling
+
+sxp-api
+~~~~~~~
+
+Contains data holders and entities
+
+spx-core
+~~~~~~~~
+
+Main logic and core features
+
+API Reference Documentation
+---------------------------
+
+`RESTCONF Interface and Dynamic
+Tree <https://wiki.opendaylight.org/images/9/91/SXP_Restconf_Interface_and_Dynamic_Tree.pdf>`__
+`Specification and
+Architecture <https://wiki.opendaylight.org/images/6/6e/SXP_Specification_and_Architecture_v03.pdf>`__
+
--- /dev/null
+Topology Processing Framework Developer Guide
+=============================================
+
+Overview
+--------
+
+The Topology Processing Framework allows developers to aggregate and
+filter topologies according to defined correlations. It also provides
+functionality, which you can use to make your own topology model by
+automating the translation from one model to another. For example to
+translate from the opendaylight-inventory model to only using the
+network-topology model.
+
+Architecture
+------------
+
+Chapter Overview
+~~~~~~~~~~~~~~~~
+
+In this chapter we describe the architecture of the Topology Processing
+Framework. In the first part, we provide information about available
+features and basic class relationships. In the second part, we describe
+our model specific approach, which is used to provide support for
+different models.
+
+Basic Architecture
+~~~~~~~~~~~~~~~~~~
+
+The Topology Processing Framework consists of several Karaf features:
+
+- odl-topoprocessing-framework
+
+- odl-topoprocessing-inventory
+
+- odl-topoprocessing-network-topology
+
+- odl-topoprocessing-i2rs
+
+- odl-topoprocessing-inventory-rendering
+
+The feature odl-topoprocessing-framework contains the
+topoprocessing-api, topoprocessing-spi and topoprocessing-impl bundles.
+This feature is the core of the Topology Processing Framework and is
+required by all others features.
+
+- topoprocessing-api - contains correlation definitions and definitions
+ required for rendering
+
+- topoprocessing-spi - entry point for topoprocessing service (start
+ and close)
+
+- topoprocessing-impl - contains base implementations of handlers,
+ listeners, aggregators and filtrators
+
+TopoProcessingProvider is the entry point for Topology Processing
+Framework. It requires a DataBroker instance. The DataBroker is needed
+for listener registration. There is also the TopologyRequestListener
+which listens on aggregated topology requests (placed into the
+configuration datastore) and UnderlayTopologyListeners which listen on
+underlay topology data changes (made in operational datastore). The
+TopologyRequestHandler saves toporequest data and provides a method for
+translating a path to the specified leaf. When a change in the topology
+occurs, the registered UnderlayTopologyListener processes this
+information for further aggregation and/or filtration. Finally, after an
+overlay topology is created, it is passed to the TopologyWriter, which
+writes this topology into operational datastore.
+
+.. figure:: ./images/topoprocessing/TopologyRequestHandler_classesRelationship.png
+ :alt: Class relationship
+
+ Class relationship
+
+[1] TopologyRequestHandler instantiates TopologyWriter and
+TopologyManager. Then, according to the request, initializes either
+TopologyAggregator, TopologyFiltrator or LinkCalculator.
+
+[2] It creates as many instances of UnderlayTopologyListener as there
+are underlay topologies.
+
+[3] PhysicalNodes are created for relevant incoming nodes (those having
+node ID).
+
+[4a] It performs aggregation and creates logical nodes.
+
+[4b] It performs filtration and creates logical nodes.
+
+[4c] It performs link computation and creates links between logical
+nodes.
+
+[5] Logical nodes are put into wrapper.
+
+[6] The wrapper is translated into the appropriate format and written
+into datastore.
+
+Model Specific Approach
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The Topology Processing Framework consists of several modules and Karaf
+features, which provide support for different input models. Currently we
+support the network-topology, opendaylight-inventory and i2rs models.
+For each of these input models, the Topology Processing Framework has
+one module and one Karaf feature.
+
+How it works
+^^^^^^^^^^^^
+
+**User point of view:**
+
+When you start the odl-topoprocessing-framework feature, the Topology
+Processing Framework starts without knowledge how to work with any input
+models. In order to allow the Topology Processing Framework to process
+some kind of input model, you must install one (or more) model specific
+features. Installing these features will also start
+odl-topoprocessing-framework feature if it is not already running. These
+features inject appropriate logic into the odl-topoprocessing-framework
+feature. From that point, the Topology Processing Framework is able to
+process different kinds of input models, specifically those that you
+install features for.
+
+**Developer point of view:**
+
+The topoprocessing-impl module contains (among other things) classes and
+interfaces, which are common for every model specific topoprocessing
+module. These classes and interfaces are implemented and extended by
+classes in particular model specific modules. Model specific modules
+also depend on the TopoProcessingProvider class in the
+topoprocessing-spi module. This dependency is injected during
+installation of model specific features in Karaf. When a model specific
+feature is started, it calls the registerAdapters(adapters) method of
+the injected TopoProcessingProvider object. After this step, the
+Topology Processing Framework is able to use registered model adapters
+to work with input models.
+
+To achieve the described functionality we created a ModelAdapter
+interface. It represents installed feature and provides methods for
+creating crucial structures specific to each model.
+
+.. figure:: ./images/topoprocessing/ModelAdapter.png
+ :alt: ModelAdapter interface
+
+ ModelAdapter interface
+
+Model Specific Features
+^^^^^^^^^^^^^^^^^^^^^^^
+
+- odl-topoprocessing-network-topology - this feature contains logic to
+ work with network-topology model
+
+- odl-topoprocessing-inventory - this feature contains logic to work
+ with opendaylight-inventory model
+
+- odl-topoprocessing-i2rs - this feature contains logic to work with
+ i2rs model
+
+Inventory Model Support
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The opendaylight-inventory model contains only nodes, termination
+points, information regarding these structures. This model co-operates
+with network-topology model, where other topology related information is
+stored. This means that we have to handle two input models at once. To
+support the inventory model, InventoryListener and
+NotificationInterConnector classes were introduced. Please see the flow
+diagrams below.
+
+.. figure:: ./images/topoprocessing/Network_topology_model_flow_diagram.png
+ :alt: Network topology model
+
+ Network topology model
+
+.. figure:: ./images/topoprocessing/Inventory_model_listener_diagram.png
+ :alt: Inventory model
+
+ Inventory model
+
+Here we can see the InventoryListener and NotificationInterConnector
+classes. InventoryListener listens on data changes in the inventory
+model and passes these changes wrapped as an UnderlayItem for further
+processing to NotificationInterConnector. It doesn’t contain node
+information - it contains a leafNode (node based on which aggregation
+occurs) instead. The node information is stored in the topology model,
+where UnderlayTopologyListener is registered as usual. This listener
+delivers the missing information.
+
+Then the NotificationInterConnector combines the two notifications into
+a complete UnderlayItem (no null values) and delivers this UnderlayItem
+for further processing (to next TopologyOperator).
+
+Aggregation and Filtration
+--------------------------
+
+Chapter Overview
+~~~~~~~~~~~~~~~~
+
+The Topology Processing Framework allows the creation of aggregated
+topologies and filtered views over existing topologies. Currently,
+aggregation and filtration is supported for topologies that follow
+`network-topology <https://github.com/opendaylight/yangtools/blob/master/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang>`__,
+opendaylight-inventory or i2rs model. When a request to create an
+aggregated or filtered topology is received, the framework creates one
+listener per underlay topology. Whenever any specified underlay topology
+is changed, the appropriate listener is triggered with the change and
+the change is processed. Two types of correlations (functionalities) are
+currently supported:
+
+- Aggregation
+
+ - Unification
+
+ - Equality
+
+- Filtration
+
+Terminology
+~~~~~~~~~~~
+
+We use the term underlay item (physical node) for items (nodes, links,
+termination-points) from underlay and overlay item (logical node) for
+items from overlay topologies regardless of whether those are actually
+physical network elements.
+
+Aggregation
+~~~~~~~~~~~
+
+Aggregation is an operation which creates an aggregated item from two or
+more items in the underlay topology if the aggregation condition is
+fulfilled. Requests for aggregated topologies must specify a list of
+underlay topologies over which the overlay (aggregated) topology will be
+created and a target field in the underlay item that the framework will
+check for equality.
+
+Create Overlay Node
+^^^^^^^^^^^^^^^^^^^
+
+First, each new underlay item is inserted into the proper topology
+store. Once the item is stored, the framework compares it (using the
+target field value) with all stored underlay items from underlay
+topologies. If there is a target-field match, a new overlay item is
+created containing pointers to all *equal* underlay items. The newly
+created overlay item is also given new references to its supporting
+underlay items.
+
+**Equality case:**
+
+If an item doesn’t fulfill the equality condition with any other items,
+processing finishes after adding the item into topology store. It will
+stay there for future use, ready to create an aggregated item with a new
+underlay item, with which it would satisfy the equality condition.
+
+**Unification case:**
+
+An overlay item is created for all underlay items, even those which
+don’t fulfill the equality condition with any other items. This means
+that an overlay item is created for every underlay item, but for items
+which satisfy the equality condition, an aggregated item is created.
+
+Update Node
+^^^^^^^^^^^
+
+Processing of updated underlay items depends on whether the target field
+has been modified. If yes, then:
+
+- if the underlay item belonged to some overlay item, it is removed
+ from that item. Next, if the aggregation condition on the target
+ field is satisfied, the item is inserted into another overlay item.
+ If the condition isn’t met then:
+
+ - in equality case - the item will not be present in overlay
+ topology.
+
+ - in unification case - the item will create an overlay item with a
+ single underlay item and this will be written into overlay
+ topology.
+
+- if the item didn’t belong to some overlay item, it is checked again
+ for aggregation with other underlay items.
+
+Remove Node
+^^^^^^^^^^^
+
+The underlay item is removed from the corresponding topology store, from
+it’s overlay item (if it belongs to one) and this way it is also removed
+from overlay topology.
+
+**Equality case:**
+
+If there is only one underlay item left in the overlay item, the overlay
+item is removed.
+
+**Unification case:**
+
+The overlay item is removed once it refers to no underlay item.
+
+Filtration
+~~~~~~~~~~
+
+Filtration is an operation which results in creation of overlay topology
+containing only items fulfilling conditions set in the topoprocessing
+request.
+
+Create Underlay Item
+^^^^^^^^^^^^^^^^^^^^
+
+If a newly created underlay item passes all filtrators and their
+conditions, then it is stored in topology store and a creation
+notification is delivered into topology manager. No operation otherwise.
+
+Update Underlay Item
+^^^^^^^^^^^^^^^^^^^^
+
+First, the updated item is checked for presence in topology store:
+
+- if it is present in topology store:
+
+ - if it meets the filtering conditions, then processUpdatedData
+ notification is triggered
+
+ - else processRemovedData notification is triggered
+
+- if item isn’t present in topology store
+
+ - if item meets filtering conditions, then processCreatedData
+ notification is triggered
+
+ - else it is ignored
+
+Remove Underlay Item
+^^^^^^^^^^^^^^^^^^^^
+
+If an underlay node is supporting some overlay node, the overlay node is
+simply removed.
+
+Default Filtrator Types
+^^^^^^^^^^^^^^^^^^^^^^^
+
+There are seven types of default filtrators defined in the framework:
+
+- IPv4-address filtrator - checks if specified field meets IPv4 address
+ + mask criteria
+
+- IPv6-address filtrator - checks if specified field meets IPv6 address
+ + mask criteria
+
+- Specific number filtrator - checks for specific number
+
+- Specific string filtrator - checks for specific string
+
+- Range number filtrator - checks if specified field is higher than
+ provided minimum (inclusive) and lower than provided maximum
+ (inclusive)
+
+- Range string filtrator - checks if specified field is alphabetically
+ greater than provided minimum (inclusive) and alphabetically lower
+ than provided maximum (inclusive)
+
+- Script filtrator - allows a user or application to implement their
+ own filtrator
+
+Register Custom Filtrator
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There might be some use case that cannot be achieved with the default
+filtrators. In these cases, the framework offers the possibility for a
+user or application to register a custom filtrator.
+
+Pre-Filtration / Filtration & Aggregation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This feature was introduced in order to lower memory and performance
+demands. It is a combination of the filtration and aggregation
+operations. First, uninteresting items are filtered out and then
+aggregation is performed only on items that passed filtration. This way
+the framework saves on compute time. The PreAggregationFiltrator and
+TopologyAggregator share the same TopoStoreProvider (and thus topology
+store) which results in lower memory demands (as underlay items are
+stored only in one topology store - they aren’t stored twice).
+
+Link Computation
+----------------
+
+Chapter Overview
+~~~~~~~~~~~~~~~~
+
+While processing the topology request, we create overlay nodes with
+lists of supporting underlay nodes. Because these overlay nodes have
+completely new identifiers, we lose link information. To regain this
+link information, we provide Link Computation functionality. Its main
+purpose is to create new overlay links based on the links from the
+underlay topologies and underlay items from overlay items. The required
+information for Link Computation is provided via the Link Computation
+model in
+(`topology-link-computation.yang <https://git.opendaylight.org/gerrit/gitweb?p=topoprocessing.git;a=blob;f=topoprocessing-api/src/main/yang/topology-link-computation.yang;hb=refs/heads/stable/beryllium>`__).
+
+Link Computation Functionality
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let us consider two topologies with following components:
+
+Topology 1:
+
+- Node: ``node:1:1``
+
+- Node: ``node:1:2``
+
+- Node: ``node:1:3``
+
+- Link: ``link:1:1`` (from ``node:1:1`` to ``node:1:2``)
+
+- Link: ``link:1:2`` (from ``node:1:3`` to ``node:1:2``)
+
+Topology 2:
+
+- Node: ``node:2:1``
+
+- Node: ``node:2:2``
+
+- Node: ``node:2:3``
+
+- Link: ``link:2:1`` (from ``node:2:1`` to ``node:2:3``)
+
+Now let’s say that we applied some operations over these topologies that
+results into aggregating together
+
+- ``node:1:1`` and ``node:2:3`` (``node:1``)
+
+- ``node:1:2`` and ``node:2:2`` (``node:2``)
+
+- ``node:1:3`` and ``node:2:1`` (``node:3``)
+
+At this point we can no longer use available links in new topology
+because of the node ID change, so we must create new overlay links with
+source and destination node set to new nodes IDs. It means that
+``link:1:1`` from topology 1 will create new link ``link:1``. Since
+original source (``node:1:1``) is already aggregated under ``node:1``,
+it will become source node for ``link:1``. Using same method the
+destination will be ``node:2``. And the final output will be three
+links:
+
+- ``link:1``, from ``node:1`` to ``node:2``
+
+- ``link:2``, from ``node:3`` to ``node:2``
+
+- ``link:3``, from ``node:3`` to ``node:1``
+
+.. figure:: ./images/topoprocessing/LinkComputation.png
+ :alt: Overlay topology with computed links
+
+ Overlay topology with computed links
+
+In-Depth Look
+~~~~~~~~~~~~~
+
+The main logic behind Link Computation is executed in the LinkCalculator
+operator. The required information is passed to LinkCalculator through
+the LinkComputation section of the topology request. This section is
+defined in the topology-link-computation.yang file. The main logic also
+covers cases when some underlay nodes may not pass through other
+topology operators.
+
+Link Computation Model
+^^^^^^^^^^^^^^^^^^^^^^
+
+There are three essential pieces of information for link computations.
+All of them are provided within the LinkComputation section. These
+pieces are:
+
+- output model
+
+.. code:: yang
+
+ leaf output-model {
+ type identityref {
+ base topo-corr:model;
+ }
+ description "Desired output model for computed links.";
+ }
+
+- overlay topology with new nodes
+
+.. code:: yang
+
+ container node-info {
+ leaf node-topology {
+ type string;
+ mandatory true;
+ description "Topology that contains aggregated nodes.
+ This topology will be used for storing computed links.";
+ }
+ uses topo-corr:input-model-grouping;
+ }
+
+- underlay topologies with original links
+
+.. code:: yang
+
+ list link-info {
+ key "link-topology input-model";
+ leaf link-topology {
+ type string;
+ mandatory true;
+ description "Topology that contains underlay (base) links.";
+ }
+ leaf aggregated-links {
+ type boolean;
+ description "Defines if link computation should be based on supporting-links.";
+ }
+ uses topo-corr:input-model-grouping;
+ }
+
+This whole section is augmented into ``network-topology:topology``. By
+placing this section out of correlations section, it allows us to send
+link computation request separately from topology operations request.
+
+Main Logic
+^^^^^^^^^^
+
+Taking into consideration that some of the underlay nodes may not
+transform into overlay nodes (e.g. they are filtered out), we created
+two possible states for links:
+
+- matched - a link is considered as matched when both original source
+ and destination node were transformed to overlay nodes
+
+- waiting - a link is considered as waiting if original source,
+ destination or both nodes are missing from the overlay topology
+
+All links in waiting the state are stored in waitingLinks list, already
+matched links are stored in matchedLinks list and overlay nodes are
+stored in the storedOverlayNodes list. All processing is based only on
+information in these lists. Processing created, updated and removed
+underlay items is slightly different and described in next sections
+separately.
+
+**Processing Created Items**
+
+Created items can be either nodes or links, depending on the type of
+listener from which they came. In the case of a link, it is immediately
+added to waitingLinks and calculation for possible overlay link
+creations (calculatePossibleLink) is started. The flow diagram for this
+process is shown in the following picture:
+
+.. figure:: ./images/topoprocessing/LinkComputationFlowDiagram.png
+ :alt: Flow diagram of processing created items
+
+ Flow diagram of processing created items
+
+Searching for the source and destination nodes in the
+calculatePossibleLink method runs over each node in storedOverlayNodes
+and the IDs of each supporting node is compared against IDs from the
+underlay link’s source and destination nodes. If there are any nodes
+missing, the link remains in the waiting state. If both the source and
+destination nodes are found, the corresponding overlay nodes is recorded
+as the new source and destination. The link is then removed from
+waitingLinks and a new CalculatedLink is added to the matched links. At
+the end, the new link (if it exists) is written into the datastore.
+
+If the created item is an overlayNode, this is added to
+storedOverlayNodes and we call calculatePossibleLink for every link in
+waitingLinks.
+
+**Processing Updated Items**
+
+The difference from processing created items is that we have three
+possible types of updated items: overlay nodes, waiting underlay links,
+and matched underlay links.
+
+- In the case of a change in a matched link, this must be recalculated
+ and based on the result it will either be matched with new source and
+ destination or will be returned to waiting links. If the link is
+ moved back to a waiting state, it must also be removed from the
+ datastore.
+
+- In the case of change in a waiting link, it is passed to the
+ calculation process and based on the result will either remain in
+ waiting state or be promoted to the matched state.
+
+- In the case of a change in an overlay node, storedOverlayNodes must
+ be updated properly and all links must be recalculated in case of
+ changes.
+
+**Processing Removed items**
+
+Same as for processing updated item. There can be three types of removed
+items:
+
+- In case of waiting link removal, the link is just removed from
+ waitingLinks
+
+- In case of matched link removal, the link is removed from
+ matchingLinks and datastore
+
+- In case of overlay node removal, the node must be removed form
+ storedOverlayNodes and all matching links must be recalculated
+
+Wrapper, RPC Republishing, Writing Mechanism
+--------------------------------------------
+
+Chapter Overview
+~~~~~~~~~~~~~~~~
+
+During the process of aggregation and filtration, overlay items (so
+called logical nodes) were created from underlay items (physical nodes).
+In the topology manager, overlay items are put into a wrapper. A wrapper
+is identified with unique ID and contains list of logical nodes.
+Wrappers are used to deal with transitivity of underlay items - which
+permits grouping of overlay items (into wrappers).
+
+.. figure:: ./images/topoprocessing/wrapper.png
+ :alt: Wrapper
+
+ Wrapper
+
+PN1, PN2, PN3 = physical nodes
+
+LN1, LN2 = logical nodes
+
+RPC Republishing
+~~~~~~~~~~~~~~~~
+
+All RPCs registered to handle underlay items are re-registered under
+their corresponding wrapper ID. RPCs of underlay items (belonging to an
+overlay item) are gathered, and registered under ID of their wrapper.
+
+RPC Call
+^^^^^^^^
+
+When RPC is called on overlay item, this call is delegated to it’s
+underlay items, this means that the RPC is called on all underlay items
+of this overlay item.
+
+Writing Mechanism
+~~~~~~~~~~~~~~~~~
+
+When a wrapper (containing overlay item(s) with it’s underlay item(s))
+is ready to be written into data store, it has to be converted into DOM
+format. After this translation is done, the result is written into
+datastore. Physical nodes are stored as supporting-nodes. In order to
+use resources responsibly, writing operation is divided into two steps.
+First, a set of threads registers prepared operations (deletes and puts)
+and one thread makes actual write operation in batch.
+
+Topology Rendering Guide - Inventory Rendering
+----------------------------------------------
+
+Chapter Overview
+~~~~~~~~~~~~~~~~
+
+In the most recent OpenDaylight release, the opendaylight-inventory
+model is marked as deprecated. To facilitate migration from it to the
+network-topology model, there were requests to render (translate) data
+from inventory model (whether augmented or not) to another model for
+further processing. The Topology Processing Framework was extended to
+provide this functionality by implementing several rendering-specific
+classes. This chapter is a step-by-step guide on how to implement your
+own topology rendering using our inventory rendering as an example.
+
+Use case
+~~~~~~~~
+
+For the purpose of this guide we are going to render the following
+augmented fields from the OpenFlow model:
+
+- from inventory node:
+
+ - manufacturer
+
+ - hardware
+
+ - software
+
+ - serial-number
+
+ - description
+
+ - ip-address
+
+- from inventory node-connector:
+
+ - name
+
+ - hardware-address
+
+ - current-speed
+
+ - maximum-speed
+
+We also want to preserve the node ID and termination-point ID from
+opendaylight-topology-inventory model, which is network-topology part of
+the inventory model.
+
+Implementation
+~~~~~~~~~~~~~~
+
+There are two ways to implement support for your specific topology
+rendering:
+
+- add a module to your project that depends on the Topology Processing
+ Framework
+
+- add a module to the Topology Processing Framework itself
+
+Regardless, a successful implementation must complete all of the
+following steps.
+
+Step1 - Target Model Creation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Because the network-topology node does not have fields to store all
+desired data, it is necessary to create new model to render this extra
+data in to. For this guide we created the inventory-rendering model. The
+picture below shows how data will be rendered and stored.
+
+.. figure:: ./images/topoprocessing/Inventory_Rendering_Use_case.png
+ :alt: Rendering to the inventory-rendering model
+
+ Rendering to the inventory-rendering model
+
+ **Important**
+
+ When implementing your version of the topology-rendering model in
+ the Topology Processing Framework, the source file of the model
+ (.yang) must be saved in /topoprocessing-api/src/main/yang folder so
+ corresponding structures can be generated during build and can be
+ accessed from every module through dependencies.
+
+When the target model is created you have to add an identifier through
+which you can set your new model as output model. To do that you have to
+add another identity item to topology-correlation.yang file. For our
+inventory-rendering model identity looks like this:
+
+.. code:: yang
+
+ identity inventory-rendering-model {
+ description "inventory-rendering.yang";
+ base model;
+ }
+
+After that you will be able to set inventory-rendering-model as output
+model in XML.
+
+Step2 - Module and Feature Creation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ **Important**
+
+ This and following steps are based on the `model specific
+ approach <#_model_specific_approach>`__ in the Topology Processing
+ Framework. We highly recommend that you familiarize yourself with
+ this approach in advance.
+
+To create a base module and add it as a feature to Karaf in the Topology
+Processing Framework we made the changes in following
+`commit <https://git.opendaylight.org/gerrit/#/c/26223/>`__. Changes in
+other projects will likely be similar.
+
++--------------------------------------+--------------------------------------+
+| File | Changes |
++======================================+======================================+
+| pom.xml | add new module to topoprocessing |
++--------------------------------------+--------------------------------------+
+| features.xml | add feature to topoprocessing |
++--------------------------------------+--------------------------------------+
+| features/pom.xml | add dependencies needed by features |
++--------------------------------------+--------------------------------------+
+| topoprocessing-artifacts/pom.xml | add artifact |
++--------------------------------------+--------------------------------------+
+| topoprocessing-config/pom.xml | add configuration file |
++--------------------------------------+--------------------------------------+
+| 81-topoprocessing-inventory-renderin | configuration file for new module |
+| g-config.xml | |
++--------------------------------------+--------------------------------------+
+| topoprocessing-inventory-rendering/p | main pom for new module |
+| om.xml | |
++--------------------------------------+--------------------------------------+
+| TopoProcessingProviderIR.java | contains startup method which |
+| | register new model adapter |
++--------------------------------------+--------------------------------------+
+| TopoProcessingProviderIRModule.java | generated class which contains |
+| | createInstance method. You should |
+| | call your startup method from here. |
++--------------------------------------+--------------------------------------+
+| TopoProcessingProviderIRModuleFactor | generated class. You will probably |
+| y.java | not need to edit this file |
++--------------------------------------+--------------------------------------+
+| log4j.xml | configuration file for logger |
+| | topoprocessing-inventory-rendering-p |
+| | rovider-impl.yang |
++--------------------------------------+--------------------------------------+
+
+Step3 - Module Adapters Creation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are seven mandatory interfaces or abstract classes that needs to
+be implemented in each module. They are:
+
+- TopoProcessingProvider - provides module registration
+
+- ModelAdapter - provides model specific instances
+
+- TopologyRequestListener - listens on changes in the configuration
+ datastore
+
+- TopologyRequestHandler - processes configuration datastore changes
+
+- UnderlayTopologyListener - listens for changes in the specific model
+
+- LinkTransaltor and NodeTranslator - used by OverlayItemTranslator to
+ create NormalizedNodes from OverlayItems
+
+The name convention we used was to add an abbreviation for the specific
+model to the beginning of implementing class name (e.g. the
+IRModelAdapter refers to class which implements ModelAdapter in module
+Inventory Rendering). In the case of the provider class, we put the
+abbreviation at the end.
+
+ **Important**
+
+ - In the next sections, we use the terms TopologyRequestListener,
+ TopologyRequestHandler, etc. without a prepended or appended
+ abbreviation because the steps apply regardless of which specific
+ model you are targeting.
+
+ - If you want to implement rendering from inventory to
+ network-topology, you can just copy-paste our module and
+ additional changes will be required only in the output part.
+
+**Provider part**
+
+This part is the starting point of the whole module. It is responsible
+for creating and registering TopologyRequestListeners. It is necessary
+to create three classes which will import:
+
+- **TopoProcessingProviderModule** - is a generated class from
+ topoprocessing-inventory-rendering-provider-impl.yang (created in
+ previous step, file will appear after first build). Its method
+ ``createInstance()`` is called at the feature start and must be
+ modified to create an instance of TopoProcessingProvider and call its
+ ``startup(TopoProcessingProvider topoProvider)`` function.
+
+- **TopoProcessingProvider** - in
+ ``startup(TopoProcessingProvider topoProvider)`` function provides
+ ModelAdapter registration to TopoProcessingProviderImpl.
+
+- **ModelAdapter** - provides creation of corresponding module specific
+ classes.
+
+**Input part**
+
+This includes the creation of the classes responsible for input data
+processing. In this case, we had to create five classes implementing:
+
+- **TopologyRequestListener** and **TopologyRequestHandler** - when
+ notified about a change in the configuration datastore, verify if the
+ change contains a topology request (has correlations in it) and
+ creates UnderlayTopologyListeners if needed. The implementation of
+ these classes will differ according to the model in which are
+ correlations saved (network-topology or i2rs). In the case of using
+ network-topology, as the input model, you can use our classes
+ IRTopologyRequestListener and IRTopologyRequestHandler.
+
+- **UnderlayTopologyListener** - registers underlay listeners according
+ to input model. In our case (listening in the inventory model), we
+ created listeners for the network-topology model and inventory model,
+ and set the NotificationInterConnector as the first operator and set
+ the IRRenderingOperator as the second operator (after
+ NotificationInterConnector). Same as for
+ TopologyRequestListener/Handler, if you are rendering from the
+ inventory model, you can use our class IRUnderlayTopologyListener.
+
+- **InventoryListener** - a new implementation of this class is
+ required only for inventory input model. This is because the
+ InventoryListener from topoprocessing-impl requires pathIdentifier
+ which is absent in the case of rendering.
+
+- **TopologyOperator** - replaces classic topoprocessing operator.
+ While the classic operator provides specific operations on topology,
+ the rendering operator just wraps each received UnderlayItem to
+ OverlayItem and sends them to write.
+
+ **Important**
+
+ For purposes of topology rendering from inventory to
+ network-topology, there are misused fields in UnderlayItem as
+ follows:
+
+ - item - contains node from network-topology part of inventory
+
+ - leafItem - contains node from inventory
+
+ In case of implementing UnderlayTopologyListener or
+ InventoryListener you have to carefully adjust UnderlayItem creation
+ to these terms.
+
+**Output part**
+
+The output part of topology rendering is responsible for translating
+received overlay items to normalized nodes. In the case of inventory
+rendering, this is where node information from inventory are combined
+with node information from network-topology. This combined information
+is stored in our inventory-rendering model normalized node and passed to
+the writer.
+
+The output part consists of two translators implementing the
+NodeTranslator and LinkTranslator interfaces.
+
+**NodeTranslator implementation** - The NodeTranslator interface has one
+``translate(OverlayItemWrapper wrapper)`` method. For our purposes,
+there is one important thing in wrapper - the list of OverlayItems which
+have one or more common UnderlayItems. Regardless of this list, in the
+case of rendering it will always contains only one OverlayItem. This
+item has list of UnderlayItems, but again in case of rendering there
+will be only one UnderlayItem item in this list. In NodeTranslator, the
+OverlayItem and corresponding UnderlayItem represent nodes from the
+translating model.
+
+The UnderlayItem has several attributes. How you will use these
+attributes in your rendering is up to you, as you create this item in
+your topology operator. For example, as mentioned above, in our
+inventory rendering example is an inventory node normalized node stored
+in the UnderlayItem leafNode attribute, and we also store node-id from
+network-topology model in UnderlayItem itemId attribute. You can now use
+these attributes to build a normalized node for your new model. How to
+read and create normalized nodes is out of scope of this document.
+
+**LinkTranslator implementation** - The LinkTranslator interface also
+has one ``translate(OverlayItemWrapper wrapper)`` method. In our
+inventory rendering this method returns ``null``, because the inventory
+model doesn’t have links. But if you also need links, this is the place
+where you should translate it into a normalized node for your model. In
+LinkTranslator, the OverlayItem and corresponding UnderlayItem represent
+links from the translating model. As in NodeTranslator, there will be
+only one OverlayItem and one UnderlayItem in the corresponding lists.
+
+Testing
+~~~~~~~
+
+If you want to test our implementation you must apply `this
+patch <https://git.opendaylight.org/gerrit/#/c/26612>`__. It adds an
+OpenFlow Plugin dependency so we can use it in the Karaf distribution as
+a feature. After adding patch and building the whole framework, you can
+start Karaf. Next, you have to install necessary features. In our case
+it is:
+
+``feature:install odl-restconf-noauth odl-topoprocessing-inventory-rendering odl-openflowplugin-southbound odl-openflowplugin-nsf-model``
+
+Now you can send messages to REST from any REST client (e.g. Postman in
+Chrome). Messages have to have following headers:
+
++--------------------------------------+--------------------------------------+
+| Header | Value |
++======================================+======================================+
+| Content-Type: | application/xml |
++--------------------------------------+--------------------------------------+
+| Accept: | application/xml |
++--------------------------------------+--------------------------------------+
+| username: | admin |
++--------------------------------------+--------------------------------------+
+| password: | admin |
++--------------------------------------+--------------------------------------+
+
+Firstly send topology request to
+http://localhost:8181/restconf/config/network-topology:network-topology/topology/render:1
+with method PUT. Example of simple rendering request:
+
+.. code:: xml
+
+ <topology xmlns="urn:TBD:params:xml:ns:yang:network-topology">
+ <topology-id>render:1</topology-id>
+ <correlations xmlns="urn:opendaylight:topology:correlation" >
+ <output-model>inventory-rendering-model</output-model>
+ <correlation>
+ <correlation-id>1</correlation-id>
+ <type>rendering-only</type>
+ <correlation-item>node</correlation-item>
+ <rendering>
+ <underlay-topology>und-topo:1</underlay-topology>
+ </rendering>
+ </correlation>
+ </correlations>
+ </topology>
+
+This request says that we want create topology with name render:1 and
+this topology should be stored in the inventory-rendering-model and it
+should be created from topology flow:1 by node rendering.
+
+Next we send the network-topology part of topology flow:1. So to the URL
+http://localhost:8181/restconf/config/network-topology:network-topology/topology/und-topo:1
+we PUT:
+
+.. code:: xml
+
+ <topology xmlns="urn:TBD:params:xml:ns:yang:network-topology"
+ xmlns:it="urn:opendaylight:model:topology:inventory"
+ xmlns:i="urn:opendaylight:inventory">
+ <topology-id>und-topo:1</topology-id>
+ <node>
+ <node-id>openflow:1</node-id>
+ <it:inventory-node-ref>
+ /i:nodes/i:node[i:id="openflow:1"]
+ </it:inventory-node-ref>
+ <termination-point>
+ <tp-id>tp:1</tp-id>
+ <it:inventory-node-connector-ref>
+ /i:nodes/i:node[i:id="openflow:1"]/i:node-connector[i:id="openflow:1:1"]
+ </it:inventory-node-connector-ref>
+ </termination-point>
+ </node>
+ </topology>
+
+And the last input will be inventory part of topology. To the URL
+http://localhost:8181/restconf/config/opendaylight-inventory:nodes we
+PUT:
+
+.. code:: xml
+
+ <nodes
+ xmlns="urn:opendaylight:inventory">
+ <node>
+ <id>openflow:1</id>
+ <node-connector>
+ <id>openflow:1:1</id>
+ <port-number
+ xmlns="urn:opendaylight:flow:inventory">1
+ </port-number>
+ <current-speed
+ xmlns="urn:opendaylight:flow:inventory">10000000
+ </current-speed>
+ <name
+ xmlns="urn:opendaylight:flow:inventory">s1-eth1
+ </name>
+ <supported
+ xmlns="urn:opendaylight:flow:inventory">
+ </supported>
+ <current-feature
+ xmlns="urn:opendaylight:flow:inventory">copper ten-gb-fd
+ </current-feature>
+ <configuration
+ xmlns="urn:opendaylight:flow:inventory">
+ </configuration>
+ <peer-features
+ xmlns="urn:opendaylight:flow:inventory">
+ </peer-features>
+ <maximum-speed
+ xmlns="urn:opendaylight:flow:inventory">0
+ </maximum-speed>
+ <advertised-features
+ xmlns="urn:opendaylight:flow:inventory">
+ </advertised-features>
+ <hardware-address
+ xmlns="urn:opendaylight:flow:inventory">0E:DC:8C:63:EC:D1
+ </hardware-address>
+ <state
+ xmlns="urn:opendaylight:flow:inventory">
+ <link-down>false</link-down>
+ <blocked>false</blocked>
+ <live>false</live>
+ </state>
+ <flow-capable-node-connector-statistics
+ xmlns="urn:opendaylight:port:statistics">
+ <receive-errors>0</receive-errors>
+ <receive-frame-error>0</receive-frame-error>
+ <receive-over-run-error>0</receive-over-run-error>
+ <receive-crc-error>0</receive-crc-error>
+ <bytes>
+ <transmitted>595</transmitted>
+ <received>378</received>
+ </bytes>
+ <receive-drops>0</receive-drops>
+ <duration>
+ <second>28</second>
+ <nanosecond>410000000</nanosecond>
+ </duration>
+ <transmit-errors>0</transmit-errors>
+ <collision-count>0</collision-count>
+ <packets>
+ <transmitted>7</transmitted>
+ <received>5</received>
+ </packets>
+ <transmit-drops>0</transmit-drops>
+ </flow-capable-node-connector-statistics>
+ </node-connector>
+ <node-connector>
+ <id>openflow:1:LOCAL</id>
+ <port-number
+ xmlns="urn:opendaylight:flow:inventory">4294967294
+ </port-number>
+ <current-speed
+ xmlns="urn:opendaylight:flow:inventory">0
+ </current-speed>
+ <name
+ xmlns="urn:opendaylight:flow:inventory">s1
+ </name>
+ <supported
+ xmlns="urn:opendaylight:flow:inventory">
+ </supported>
+ <current-feature
+ xmlns="urn:opendaylight:flow:inventory">
+ </current-feature>
+ <configuration
+ xmlns="urn:opendaylight:flow:inventory">
+ </configuration>
+ <peer-features
+ xmlns="urn:opendaylight:flow:inventory">
+ </peer-features>
+ <maximum-speed
+ xmlns="urn:opendaylight:flow:inventory">0
+ </maximum-speed>
+ <advertised-features
+ xmlns="urn:opendaylight:flow:inventory">
+ </advertised-features>
+ <hardware-address
+ xmlns="urn:opendaylight:flow:inventory">BA:63:87:0C:76:41
+ </hardware-address>
+ <state
+ xmlns="urn:opendaylight:flow:inventory">
+ <link-down>false</link-down>
+ <blocked>false</blocked>
+ <live>false</live>
+ </state>
+ <flow-capable-node-connector-statistics
+ xmlns="urn:opendaylight:port:statistics">
+ <receive-errors>0</receive-errors>
+ <receive-frame-error>0</receive-frame-error>
+ <receive-over-run-error>0</receive-over-run-error>
+ <receive-crc-error>0</receive-crc-error>
+ <bytes>
+ <transmitted>576</transmitted>
+ <received>468</received>
+ </bytes>
+ <receive-drops>0</receive-drops>
+ <duration>
+ <second>28</second>
+ <nanosecond>426000000</nanosecond>
+ </duration>
+ <transmit-errors>0</transmit-errors>
+ <collision-count>0</collision-count>
+ <packets>
+ <transmitted>6</transmitted>
+ <received>6</received>
+ </packets>
+ <transmit-drops>0</transmit-drops>
+ </flow-capable-node-connector-statistics>
+ </node-connector>
+ <serial-number
+ xmlns="urn:opendaylight:flow:inventory">None
+ </serial-number>
+ <manufacturer
+ xmlns="urn:opendaylight:flow:inventory">Nicira, Inc.
+ </manufacturer>
+ <hardware
+ xmlns="urn:opendaylight:flow:inventory">Open vSwitch
+ </hardware>
+ <software
+ xmlns="urn:opendaylight:flow:inventory">2.1.3
+ </software>
+ <description
+ xmlns="urn:opendaylight:flow:inventory">None
+ </description>
+ <ip-address
+ xmlns="urn:opendaylight:flow:inventory">10.20.30.40
+ </ip-address>
+ <meter-features
+ xmlns="urn:opendaylight:meter:statistics">
+ <max_bands>0</max_bands>
+ <max_color>0</max_color>
+ <max_meter>0</max_meter>
+ </meter-features>
+ <group-features
+ xmlns="urn:opendaylight:group:statistics">
+ <group-capabilities-supported
+ xmlns:x="urn:opendaylight:group:types">x:chaining
+ </group-capabilities-supported>
+ <group-capabilities-supported
+ xmlns:x="urn:opendaylight:group:types">x:select-weight
+ </group-capabilities-supported>
+ <group-capabilities-supported
+ xmlns:x="urn:opendaylight:group:types">x:select-liveness
+ </group-capabilities-supported>
+ <max-groups>4294967040</max-groups>
+ <actions>67082241</actions>
+ <actions>0</actions>
+ </group-features>
+ </node>
+ </nodes>
+
+After this, the expected result from a GET request to
+http://127.0.0.1:8181/restconf/operational/network-topology:network-topology
+is:
+
+.. code:: xml
+
+ <network-topology
+ xmlns="urn:TBD:params:xml:ns:yang:network-topology">
+ <topology>
+ <topology-id>render:1</topology-id>
+ <node>
+ <node-id>openflow:1</node-id>
+ <node-augmentation
+ xmlns="urn:opendaylight:topology:inventory:rendering">
+ <ip-address>10.20.30.40</ip-address>
+ <serial-number>None</serial-number>
+ <manufacturer>Nicira, Inc.</manufacturer>
+ <description>None</description>
+ <hardware>Open vSwitch</hardware>
+ <software>2.1.3</software>
+ </node-augmentation>
+ <termination-point>
+ <tp-id>openflow:1:1</tp-id>
+ <tp-augmentation
+ xmlns="urn:opendaylight:topology:inventory:rendering">
+ <hardware-address>0E:DC:8C:63:EC:D1</hardware-address>
+ <current-speed>10000000</current-speed>
+ <maximum-speed>0</maximum-speed>
+ <name>s1-eth1</name>
+ </tp-augmentation>
+ </termination-point>
+ <termination-point>
+ <tp-id>openflow:1:LOCAL</tp-id>
+ <tp-augmentation
+ xmlns="urn:opendaylight:topology:inventory:rendering">
+ <hardware-address>BA:63:87:0C:76:41</hardware-address>
+ <current-speed>0</current-speed>
+ <maximum-speed>0</maximum-speed>
+ <name>s1</name>
+ </tp-augmentation>
+ </termination-point>
+ </node>
+ </topology>
+ </network-topology>
+
+Key APIs and Interfaces
+-----------------------
+
+The basic provider class is TopoProcessingProvider which provides
+startup and shutdown methods. Otherwise, the framework communicates via
+requests and outputs stored in the MD-SAL datastores.
+
+API Reference Documentation
+---------------------------
+
+You can find API examples on `this wiki
+page <https://wiki.opendaylight.org/view/Topology_Processing_Framework:Developer_Guide:End_to_End_Example>`__.
+
--- /dev/null
+TTP CLI Tools Developer Guide
+=============================
+
+Overview
+--------
+
+Table Type Patterns are a specification developed by the `Open
+Networking Foundation <https://www.opennetworking.org/>`__ to enable the
+description and negotiation of subsets of the OpenFlow protocol. This is
+particularly useful for hardware switches that support OpenFlow as it
+enables the to describe what features they do (and thus also what
+features they do not) support. More details can be found in the full
+specification listed on the `OpenFlow specifications
+page <https://www.opennetworking.org/sdn-resources/onf-specifications/openflow>`__.
+
+The TTP CLI Tools provide a way for people interested in TTPs to read
+in, validate, output, and manipulate TTPs as a self-contained,
+executable jar file.
+
+TTP CLI Tools Architecture
+--------------------------
+
+The TTP CLI Tools use the TTP Model and the YANG Tools/RESTCONF codecs
+to translate between the Data Transfer Objects (DTOs) and JSON/XML.
+
+Command Line Options
+--------------------
+
+This will cover the various options for the CLI Tools. For now, there
+are no options and it merely outputs fixed data using the codecs.
+
--- /dev/null
+TTP Model Developer Guide
+=========================
+
+Overview
+--------
+
+Table Type Patterns are a specification developed by the `Open
+Networking Foundation <https://www.opennetworking.org/>`__ to enable the
+description and negotiation of subsets of the OpenFlow protocol. This is
+particularly useful for hardware switches that support OpenFlow as it
+enables the to describe what features they do (and thus also what
+features they do not) support. More details can be found in the full
+specification listed on the `OpenFlow specifications
+page <https://www.opennetworking.org/sdn-resources/onf-specifications/openflow>`__.
+
+TTP Model Architecture
+----------------------
+
+The TTP Model provides a YANG-modeled type for a TTP and allows them to
+be associated with a master list of known TTPs, as well as active and
+supported TTPs with nodes in the MD-SAL inventory model.
+
+Key APIs and Interfaces
+-----------------------
+
+The key API provided by the TTP Model feature is the ability to store a
+set of TTPs in the MD-SAL as well as associate zero or one active TTPs
+and zero or more supported TTPs along with a given node in the MD-SAL
+inventory model.
+
+API Reference Documentation
+---------------------------
+
+RESTCONF
+~~~~~~~~
+
+See the generated RESTCONF API documentation at:
+http://localhost:8181/apidoc/explorer/index.html
+
+Look for the onf-ttp module to expand and see the various RESTCONF APIs.
+
+Java Bindings
+~~~~~~~~~~~~~
+
+As stated above there are 3 locations where a Table Type Pattern can be
+placed into the MD-SAL Data Store. They correspond to 3 different REST
+API URIs:
+
+1. ``restconf/config/onf-ttp:opendaylight-ttps/onf-ttp:table-type-patterns/``
+
+2. ``restconf/config/opendaylight-inventory:nodes/node/{id}/ttp-inventory-node:active_ttp/``
+
+3. ``restconf/config/opendaylight-inventory:nodes/node/{id}/ttp-inventory-node:supported_ttps/``
+
+.. note::
+
+ Typically, these URIs are running on the machine the controller is
+ on at port 8181. If you are on the same machine they can thus be
+ accessed at ``http://localhost:8181/<uri>``
+
+Using the TTP Model RESTCONF APIs
+---------------------------------
+
+Setting REST HTTP Headers
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Authentication
+^^^^^^^^^^^^^^
+
+The REST API calls require authentication by default. The default method
+is to use basic auth with a user name and password of ‘admin’.
+
+Content-Type and Accept
+^^^^^^^^^^^^^^^^^^^^^^^
+
+RESTCONF supports both xml and json. This example focuses on JSON, but
+xml can be used just as easily. When doing a PUT or POST be sure to
+specify the appropriate ``Conetnt-Type`` header: either
+``application/json`` or ``application/xml``.
+
+When doing a GET be sure to specify the appropriate ``Accept`` header:
+again, either ``application/json`` or ``application/xml``.
+
+Content
+~~~~~~~
+
+The contents of a PUT or POST should be a OpenDaylight Table Type
+Pattern. An example of one is provided below. The example can also be
+found at ```parser/sample-TTP-from-tests.ttp`` in the TTP git
+repository <https://git.opendaylight.org/gerrit/gitweb?p=ttp.git;a=blob;f=parser/sample-TTP-from-tests.ttp;h=45130949b25c6f86b750959d27d04ec2208935fb;hb=HEAD>`__.
+
+**Sample Table Type Pattern (json).**
+
+::
+
+ {
+ "table-type-patterns": {
+ "table-type-pattern": [
+ {
+ "security": {
+ "doc": [
+ "This TTP is not published for use by ONF. It is an example and for",
+ "illustrative purposes only.",
+ "If this TTP were published for use it would include",
+ "guidance as to any security considerations in this doc member."
+ ]
+ },
+ "NDM_metadata": {
+ "authority": "org.opennetworking.fawg",
+ "OF_protocol_version": "1.3.3",
+ "version": "1.0.0",
+ "type": "TTPv1",
+ "doc": [
+ "Example of a TTP supporting L2 (unicast, multicast, flooding), L3 (unicast only),",
+ "and an ACL table."
+ ],
+ "name": "L2-L3-ACLs"
+ },
+ "identifiers": [
+ {
+ "doc": [
+ "The VLAN ID of a locally attached L2 subnet on a Router."
+ ],
+ "var": "<subnet_VID>"
+ },
+ {
+ "doc": [
+ "An OpenFlow group identifier (integer) identifying a group table entry",
+ "of the type indicated by the variable name"
+ ],
+ "var": "<<group_entry_types/name>>"
+ }
+ ],
+ "features": [
+ {
+ "doc": [
+ "Flow entry notification Extension – notification of changes in flow entries"
+ ],
+ "feature": "ext187"
+ },
+ {
+ "doc": [
+ "Group notifications Extension – notification of changes in group or meter entries"
+ ],
+ "feature": "ext235"
+ }
+ ],
+ "meter_table": {
+ "meter_types": [
+ {
+ "name": "ControllerMeterType",
+ "bands": [
+ {
+ "type": "DROP",
+ "rate": "1000..10000",
+ "burst": "50..200"
+ }
+ ]
+ },
+ {
+ "name": "TrafficMeter",
+ "bands": [
+ {
+ "type": "DSCP_REMARK",
+ "rate": "10000..500000",
+ "burst": "50..500"
+ },
+ {
+ "type": "DROP",
+ "rate": "10000..500000",
+ "burst": "50..500"
+ }
+ ]
+ }
+ ],
+ "built_in_meters": [
+ {
+ "name": "ControllerMeter",
+ "meter_id": 1,
+ "type": "ControllerMeterType",
+ "bands": [
+ {
+ "rate": 2000,
+ "burst": 75
+ }
+ ]
+ },
+ {
+ "name": "AllArpMeter",
+ "meter_id": 2,
+ "type": "ControllerMeterType",
+ "bands": [
+ {
+ "rate": 1000,
+ "burst": 50
+ }
+ ]
+ }
+ ]
+ },
+ "table_map": [
+ {
+ "name": "ControlFrame",
+ "number": 0
+ },
+ {
+ "name": "IngressVLAN",
+ "number": 10
+ },
+ {
+ "name": "MacLearning",
+ "number": 20
+ },
+ {
+ "name": "ACL",
+ "number": 30
+ },
+ {
+ "name": "L2",
+ "number": 40
+ },
+ {
+ "name": "ProtoFilter",
+ "number": 50
+ },
+ {
+ "name": "IPv4",
+ "number": 60
+ },
+ {
+ "name": "IPv6",
+ "number": 80
+ }
+ ],
+ "parameters": [
+ {
+ "doc": [
+ "documentation"
+ ],
+ "name": "Showing-curt-how-this-works",
+ "type": "type1"
+ }
+ ],
+ "flow_tables": [
+ {
+ "doc": [
+ "Filters L2 control reserved destination addresses and",
+ "may forward control packets to the controller.",
+ "Directs all other packets to the Ingress VLAN table."
+ ],
+ "name": "ControlFrame",
+ "flow_mod_types": [
+ {
+ "doc": [
+ "This match/action pair allows for flow_mods that match on either",
+ "ETH_TYPE or ETH_DST (or both) and send the packet to the",
+ "controller, subject to metering."
+ ],
+ "name": "Frame-To-Controller",
+ "match_set": [
+ {
+ "field": "ETH_TYPE",
+ "match_type": "all_or_exact"
+ },
+ {
+ "field": "ETH_DST",
+ "match_type": "exact"
+ }
+ ],
+ "instruction_set": [
+ {
+ "doc": [
+ "This meter may be used to limit the rate of PACKET_IN frames",
+ "sent to the controller"
+ ],
+ "instruction": "METER",
+ "meter_name": "ControllerMeter"
+ },
+ {
+ "instruction": "APPLY_ACTIONS",
+ "actions": [
+ {
+ "action": "OUTPUT",
+ "port": "CONTROLLER"
+ }
+ ]
+ }
+ ]
+ }
+ ],
+ "built_in_flow_mods": [
+ {
+ "doc": [
+ "Mandatory filtering of control frames with C-VLAN Bridge reserved DA."
+ ],
+ "name": "Control-Frame-Filter",
+ "priority": "1",
+ "match_set": [
+ {
+ "field": "ETH_DST",
+ "mask": "0xfffffffffff0",
+ "value": "0x0180C2000000"
+ }
+ ]
+ },
+ {
+ "doc": [
+ "Mandatory miss flow_mod, sends packets to IngressVLAN table."
+ ],
+ "name": "Non-Control-Frame",
+ "priority": "0",
+ "instruction_set": [
+ {
+ "instruction": "GOTO_TABLE",
+ "table": "IngressVLAN"
+ }
+ ]
+ }
+ ]
+ }
+ ],
+ "group_entry_types": [
+ {
+ "doc": [
+ "Output to a port, removing VLAN tag if needed.",
+ "Entry per port, plus entry per untagged VID per port."
+ ],
+ "name": "EgressPort",
+ "group_type": "INDIRECT",
+ "bucket_types": [
+ {
+ "name": "OutputTagged",
+ "action_set": [
+ {
+ "action": "OUTPUT",
+ "port": "<port_no>"
+ }
+ ]
+ },
+ {
+ "name": "OutputUntagged",
+ "action_set": [
+ {
+ "action": "POP_VLAN"
+ },
+ {
+ "action": "OUTPUT",
+ "port": "<port_no>"
+ }
+ ]
+ },
+ {
+ "opt_tag": "VID-X",
+ "name": "OutputVIDTranslate",
+ "action_set": [
+ {
+ "action": "SET_FIELD",
+ "field": "VLAN_VID",
+ "value": "<local_vid>"
+ },
+ {
+ "action": "OUTPUT",
+ "port": "<port_no>"
+ }
+ ]
+ }
+ ]
+ }
+ ],
+ "flow_paths": [
+ {
+ "doc": [
+ "This object contains just a few examples of flow paths, it is not",
+ "a comprehensive list of the flow paths required for this TTP. It is",
+ "intended that the flow paths array could include either a list of",
+ "required flow paths or a list of specific flow paths that are not",
+ "required (whichever is more concise or more useful."
+ ],
+ "name": "L2-2",
+ "path": [
+ "Non-Control-Frame",
+ "IV-pass",
+ "Known-MAC",
+ "ACLskip",
+ "L2-Unicast",
+ "EgressPort"
+ ]
+ },
+ {
+ "name": "L2-3",
+ "path": [
+ "Non-Control-Frame",
+ "IV-pass",
+ "Known-MAC",
+ "ACLskip",
+ "L2-Multicast",
+ "L2Mcast",
+ "[EgressPort]"
+ ]
+ },
+ {
+ "name": "L2-4",
+ "path": [
+ "Non-Control-Frame",
+ "IV-pass",
+ "Known-MAC",
+ "ACL-skip",
+ "VID-flood",
+ "VIDflood",
+ "[EgressPort]"
+ ]
+ },
+ {
+ "name": "L2-5",
+ "path": [
+ "Non-Control-Frame",
+ "IV-pass",
+ "Known-MAC",
+ "ACLskip",
+ "L2-Drop"
+ ]
+ },
+ {
+ "name": "v4-1",
+ "path": [
+ "Non-Control-Frame",
+ "IV-pass",
+ "Known-MAC",
+ "ACLskip",
+ "L2-Router-MAC",
+ "IPv4",
+ "v4-Unicast",
+ "NextHop",
+ "EgressPort"
+ ]
+ },
+ {
+ "name": "v4-2",
+ "path": [
+ "Non-Control-Frame",
+ "IV-pass",
+ "Known-MAC",
+ "ACLskip",
+ "L2-Router-MAC",
+ "IPv4",
+ "v4-Unicast-ECMP",
+ "L3ECMP",
+ "NextHop",
+ "EgressPort"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+Making a REST Call
+~~~~~~~~~~~~~~~~~~
+
+In this example we’ll do a PUT to install the sample TTP from above into
+OpenDaylight and then retrieve it both as json and as xml. We’ll use the
+`Postman - REST
+Client <https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm>`__
+for Chrome in the examples, but any method of accessing REST should
+work.
+
+First, we’ll fill in the basic information:
+
+.. figure:: ./images/ttp-screen1-basic-auth.png
+ :alt: Filling in URL, content, Content-Type and basic auth
+
+ Filling in URL, content, Content-Type and basic auth
+
+1. Set the URL to
+ ``http://localhost:8181/restconf/config/onf-ttp:opendaylight-ttps/onf-ttp:table-type-patterns/``
+
+2. Set the action to ``PUT``
+
+3. Click Headers and
+
+4. Set a header for ``Content-Type`` to ``application/json``
+
+5. Make sure the content is set to raw and
+
+6. Copy the sample TTP from above into the content
+
+7. Click the Basic Auth tab and
+
+8. Set the username and password to admin
+
+9. Click Refresh headers
+
+.. figure:: ./images/ttp-screen2-applied-basic-auth.png
+ :alt: Refreshing basic auth headers
+
+ Refreshing basic auth headers
+
+After clicking Refresh headers, we can see that a new header
+(``Authorization``) has been created and this will allow us to
+authenticate to make the REST call.
+
+.. figure:: ./images/ttp-screen3-sent-put.png
+ :alt: PUTting a TTP
+
+ PUTting a TTP
+
+At this point, clicking send should result in a Status response of ``200
+OK`` indicating we’ve successfully PUT the TTP into OpenDaylight.
+
+.. figure:: ./images/ttp-screen4-get-json.png
+ :alt: Retrieving the TTP as json via a GET
+
+ Retrieving the TTP as json via a GET
+
+We can now retrieve the TTP by:
+
+1. Changing the action to ``GET``
+
+2. Setting an ``Accept`` header to ``application/json`` and
+
+3. Pressing send
+
+.. figure:: ./images/ttp-screen5-get-xml.png
+ :alt: Retrieving the TTP as xml via a GET
+
+ Retrieving the TTP as xml via a GET
+
+The same process can retrieve the content as xml by setting the
+``Accept`` header to ``application/xml``.
+
--- /dev/null
+Virtual Tenant Network (VTN)
+============================
+
+OpenDaylight Virtual Tenant Network (VTN) Overview
+--------------------------------------------------
+
+OpenDaylight Virtual Tenant Network (VTN) is an application that
+provides multi-tenant virtual network on an SDN controller.
+
+Conventionally, huge investment in the network systems and operating
+expenses are needed because the network is configured as a silo for each
+department and system. Therefore various network appliances must be
+installed for each tenant and those boxes cannot be shared with others.
+It is a heavy work to design, implement and operate the entire complex
+network.
+
+The uniqueness of VTN is a logical abstraction plane. This enables the
+complete separation of logical plane from physical plane. Users can
+design and deploy any desired network without knowing the physical
+network topology or bandwidth restrictions.
+
+VTN allows the users to define the network with a look and feel of
+conventional L2/L3 network. Once the network is designed on VTN, it will
+automatically be mapped into underlying physical network, and then
+configured on the individual switch leverage SDN control protocol. The
+definition of logical plane makes it possible not only to hide the
+complexity of the underlying network but also to better manage network
+resources. It achieves reducing reconfiguration time of network services
+and minimizing network configuration errors. OpenDaylight Virtual Tenant
+Network (VTN) is an application that provides multi-tenant virtual
+network on an SDN controller. It provides API for creating a common
+virtual network irrespective of the physical network.
+
+.. figure:: ./images/vtn/vtn-overview.png
+ :alt: VTN Architecture
+
+ VTN Architecture
+
+It is implemented as two major components
+
+- `VTN Manager <#_vtn_manager>`__
+
+- `VTN Coordinator <#_vtn_coordinator>`__
+
+VTN Manager
+~~~~~~~~~~~
+
+An OpenDaylight Plugin that interacts with other modules to implement
+the components of the VTN model. It also provides a REST interface to
+configure VTN components in OpenDaylight. VTN Manager is implemented as
+one plugin to the OpenDaylight. This provides a REST interface to
+create/update/delete VTN components. The user command in VTN Coordinator
+is translated as REST API to VTN Manager by the OpenDaylight Driver
+component. In addition to the above mentioned role, it also provides an
+implementation to the OpenStack L2 Network Functions API.
+
+Function Outline
+^^^^^^^^^^^^^^^^
+
+The table identifies the functions and the interface used by VTN
+Components:
+
++--------------------------+--------------------------+--------------------------+
+| Component | Interface | Purpose |
++==========================+==========================+==========================+
+| VTN Manager | RESTful API | Configure VTN |
+| | | Virtualization model |
+| | | components in |
+| | | OpenDaylight |
++--------------------------+--------------------------+--------------------------+
+| VTN Manager | Neutron API | Handle Networks API from |
+| | implementation | OpenStack (Neutron |
+| | | Interface) |
++--------------------------+--------------------------+--------------------------+
+| VTN Coordinator | RESTful API | (1) Uses the RESTful |
+| | | interface of VTN |
+| | | Manager and configures |
+| | | VTN Virtualization |
+| | | model components in |
+| | | OpenDaylight. |
+| | | (2) Handles multiple |
+| | | OpenDaylight |
+| | | orchestration. |
+| | | (3) Provides API to |
+| | | read the physical |
+| | | network details. See |
+| | | `samples <https://wiki |
+| | | .OpenDaylight.org/view/O |
+| | | penDaylight_Virtual_Tena |
+| | | nt_Network_(VTN):VTN_Coo |
+| | | rdinator:RestApi:L2_Netw |
+| | | ork_Example_Using_VTN_Vi |
+| | | rtualization>`__ |
+| | | for usage. |
++--------------------------+--------------------------+--------------------------+
+
+Feature Overview
+^^^^^^^^^^^^^^^^
+
+There are three features
+
+- **odl-vtn-manager** provides VTN Manager’s JAVA API.
+
+- **odl-vtn-manager-rest** provides VTN Manager’s REST API.
+
+- **odl-vtn-manager-neutron** provides the integration with Neutron
+ interface.
+
+REST API documentation for VTN Manager, please refer to:
+https://jenkins.opendaylight.org/releng/view/vtn/job/vtn-merge-beryllium/lastSuccessfulBuild/artifact/manager/model/target/site/models/
+
+For VTN Java API documentation, please refer to:
+https://jenkins.opendaylight.org/releng/view/vtn/job/vtn-merge-beryllium/lastSuccessfulBuild/artifact/target/apidocs/index.html
+
+Once the Karaf distribution is up, install dlux and apidocs.
+
+::
+
+ feature:install odl-dlux-all odl-mdsal-apidocs
+
+Logging In
+''''''''''
+
+To Log in to DLUX, after installing the application:
+
+- Open a browser and enter the login URL as
+ `http://<OpenDaylight-IP>:8181/index.html <http://<OpenDaylight-IP>:8181/index.html>`__.
+
+.. note::
+
+ Replace "<OpenDaylight-IP>" with the IP address of OpenDaylight
+ based on your environment.
+
+- Login to the application with user ID and password credentials as
+ admin.
+
+.. note::
+
+ admin is the only default user available for DLUX in this release.
+
+- In the right hand side frame, click "Yang UI".
+
+YANG documentation for VTN Manager, please refer to:
+https://jenkins.opendaylight.org/releng/view/vtn/job/vtn-merge-beryllium/lastSuccessfulBuild/artifact/manager/model/target/site/models/
+
+VTN Coordinator
+~~~~~~~~~~~~~~~
+
+The VTN Coordinator is an external application that provides a REST
+interface for an user to use OpenDaylight VTN Virtualization. It
+interacts with the VTN Manager plugin to implement the user
+configuration. It is also capable of multiple OpenDaylight
+orchestration. It realizes VTN provisioning in OpenDaylight instances.
+In the OpenDaylight architecture VTN Coordinator is part of the network
+application, orchestration and services layer. VTN Coordinator will use
+the REST interface exposed by the VTN Manger to realize the virtual
+network using OpenDaylight. It uses OpenDaylight APIs (REST) to
+construct the virtual network in OpenDaylight instances. It provides
+REST APIs for northbound VTN applications and supports virtual networks
+spanning across multiple OpenDaylight by coordinating across
+OpenDaylight.
+
+VTN Coordinator Components:
+
+- Transaction Coordinator
+
+- Unified Provider Physical Layer (UPPL)
+
+- Unified Provider Logical LAyer (UPLL)
+
+- OpenDaylight Controller Diver (ODC Driver)
+
+OpenDaylight Virtual Tenant Network (VTN) API Overview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The VTN API module is a sub component of the VTN Coordinator and
+provides the northbound REST API interface for VTN applications. It
+consists of two subcomponents:
+
+- Web Server
+
+- VTN service Java API Library
+
+.. figure:: ./images/vtn/vtn-coordinator-api-architecture.png
+ :alt: VTN-Coordinator\_api-architechture
+
+ VTN-Coordinator\_api-architechture
+
+Web Server
+''''''''''
+
+The Web Server module handles the REST APIs received from the VTN
+applications. It translates the REST APIs to the appropriate Java APIs.
+
+The main functions of this module are:
+
+- Starts via the startup script ``catalina.sh``.
+
+- VTN Application sends HTTP request to Web server in XML or JSON
+ format.
+
+- Creates a session and acquire a read/write lock.
+
+- Invokes the VTN Service Java API Library corresponding to the
+ specified URI.
+
+- Returns the response to the VTN Application.
+
+WebServer Class Details
+'''''''''''''''''''''''
+
+The list below shows the classes available for Web Server module and
+their descriptions:
+
+Init Manager
+ It is a singleton class for executing the acquisition of
+ configuration information from properties file, log initialization,
+ initialization of VTN Service Java API Library. Executed by init()
+ of VtnServiceWebAPIServlet.
+
+Configuration Manager
+ Maintains the configuration information acquired from properties
+ file.
+
+VtnServiceCommonUtil
+ Utility class
+
+VtnServiceWebUtil
+ Utility class
+
+VtnServiceWebAPIServlet
+ Receives HTTP request from VTN Application and calls the method of
+ corresponding VtnServiceWebAPIHandler. herits class HttpServlet, and
+ overrides doGet(), doPut(), doDelete(), doPost().
+
+VtnServiceWebAPIHandler
+ Creates JsonObject(com.google.gson) from HTTP request, and calls
+ method of corresponding VtnServiceWebAPIController.
+
+VtnServiceWebAPIController
+ Creates RestResource() class and calls UPLL API/UPPL API through
+ Java API. the time of calling UPLL API/UPPL API, performs the
+ creation/deletion of session, acquisition/release of configuration
+ mode, acquisition/release of read lock by TC API through Java API.
+
+Data Converter
+ Converts HTTP request to JsonObject and JsonXML to JSON.
+
+VTN Service Java API Library
+''''''''''''''''''''''''''''
+
+It provides the Java API library to communicate with the lower layer
+modules in the VTN Coordinator. The main functions of this library are:
+
+- Creates an IPC client session to the lower layer.
+
+- Converts the request to IPC framework format.
+
+- Invokes the lower layer API (i.e. UPPL API, UPLL API, TC API).
+
+- Returns the response from the lower layer to the web server
+
+- VTN Service Java API Library Class Details
+
+Feature Overview
+^^^^^^^^^^^^^^^^
+
+VTN Coordinator doesn’t have Karaf features.
+
+For VTN Coordinator REST API, please refer to:
+https://wiki.opendaylight.org/view/OpenDaylight_Virtual_Tenant_Network_%28VTN%29:VTN_Coordinator:RestApi
+
+Usage Examples
+~~~~~~~~~~~~~~
+
+- `L2 Network using Single
+ Controller <https://wiki.OpenDaylight.org/view/OpenDaylight_Virtual_Tenant_Network_(VTN):VTN_Coordinator:RestApi:How_to_configure_L2_Network_with_Single_Controller>`__
+
--- /dev/null
+YANG Tools
+==========
+
+Overview
+--------
+
+YANG Tools is set of libraries and tooling providing support for use
+`YANG <https://tools.ietf.org/html/rfc6020>`__ for Java (or other
+JVM-based language) projects and applications.
+
+YANG Tools provides following features in OpenDaylight:
+
+- parsing of YANG sources and semantic inference of relationship across
+ YANG models as defined in
+ `RFC6020 <https://tools.ietf.org/html/rfc6020>`__
+
+- representation of YANG-modeled data in Java
+
+ - **Normalized Node** representation - DOM-like tree model, which
+ uses conceptual meta-model more tailored to YANG and OpenDaylight
+ use-cases than a standard XML DOM model allows for.
+
+ - **Java Binding** - concrete data model and classes generated from
+ YANG models, designed to provide compile-time safety when working
+ with YANG-modeled data.
+
+- serialization / deserialization of YANG-modeled data driven by YANG
+ models
+
+ - XML - as defined in
+ `RFC6020 <https://tools.ietf.org/html/rfc6020>`__
+
+ - JSON - as defined in
+ `draft-lhotka-netmod-yang-json-01 <https://tools.ietf.org/html/rfc6020>`__
+
+ - Java Binding to Normalized Node and vice-versa
+
+- Integration of YANG model parsing into Maven build lifecycle and
+ support for third-party generators processing YANG models.
+
+YANG Tools project consists of following logical subsystems:
+
+- **Commons** - Set of general purpose code, which is not specific to
+ YANG, but is also useful outside YANG Tools implementation.
+
+- **YANG Model and Parser** - YANG semantic model and lexical and
+ semantic parser of YANG models, which creates in-memory
+ cross-referenced represenation of YANG models, which is used by other
+ components to determine their behaviour based on the model.
+
+- **YANG Data** - Definition of Normalized Node APIs and Data Tree
+ APIs, reference implementation of these APIs and implementation of
+ XML and JSON codecs for Normalized Nodes.
+
+- **YANG Maven Plugin** - Maven plugin which integrates YANG parser
+ into Maven build lifecycle and provides code-generation framework for
+ components, which wants to generate code or other artefacts based on
+ YANG model.
+
+- **YANG Java Binding** - Mapping of YANG model to generated Java APIs.
+ Java Binding also references to set of compile-time and runtime
+ components which implements this mapping, provides generation of
+ classes and APIs based on YANG models and integrate these Java
+ Binding objects with **YANG Data** APIs and components.
+
+ - **Models** - Set of **IETF** and **YANG Tools** models, with
+ generated Java Bindings so they could be simply consumed outside
+ of **YANG Tools**.
+
+YANG Java Binding: Mapping rules
+--------------------------------
+
+This chapter covers the details of mapping YANG to Java.
+
+.. note::
+
+ The following source code examples does not show canonical generated
+ code, but rather illustrative example. Generated classes and
+ interfaces may differ from this examples, but APIs are preserved.
+
+General conversion rules
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Package names of YANG models
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| The package name consists of the following parts:
+
+- **Opendaylight prefix** - Specifies the opendaylight prefix. Every
+ package name starts with the prefix ``org.opendaylight.yang.gen.v``.
+
+- **Java Binding version** - Specifies the YANG Java Binding version.
+ Curent Binding version is ``1``.
+
+- **Namespace** - Specified by the value of ``namespace`` substatement.
+ URI is converted to package name structure.
+
+- **Revision** - Specifies the concatenation of word ``rev`` and value
+ of ``module`` substatements ``revision`` argument value without
+ leading zeros before month and day. For example: ``rev201379``
+
+After the package name is generated, we check if it contains any Java
+keywords or starts with a digit. If so, then we add an underscore before
+the offending token.
+
+The following is a list of keywords which are prefixed with underscore:
+
+abstract, assert, boolean, break, byte, case, catch, char, class, const,
+continue, default, double, do, else, enum, extends, false, final,
+finally, float, for, goto, if, implements, import, instanceof, int,
+interface, long, native, new, null, package, private, protected, public,
+return, short, static, strictfp, super, switch, synchronized, this,
+throw, throws, transient, true, try, void, volatile, while
+
+As an example suppose following yang model:
+
+.. code:: yang
+
+ module module {
+ namespace "urn:2:case#module";
+ prefix "sbd";
+ organization "OPEN DAYLIGHT";
+ contact "http://www.example.com/";
+ revision 2013-07-09 {
+ }
+ }
+
+After applying rules (replacing digits and Java keywords) the resulting
+package name is
+``org.opendaylight.yang.gen.v1.urn._2._case.module.rev201379``
+
+Additional Packages
+^^^^^^^^^^^^^^^^^^^
+
+In cases when YANG statement contain some of specific YANG statements
+additional packages are generated to designate this containment. Table
+below provides details of parent statement and nested statements, which
+yields additional package generation:
+
++--------------------------------------+--------------------------------------+
+| Parent statement | Substatement |
++======================================+======================================+
+| ``list`` | list, container, choice |
++--------------------------------------+--------------------------------------+
+| ``container`` | list, container, choice |
++--------------------------------------+--------------------------------------+
+| ``choice`` | leaf, list, leaf-list, container, |
+| | case |
++--------------------------------------+--------------------------------------+
+| ``case`` | list, container, choice |
++--------------------------------------+--------------------------------------+
+| rpc ``input`` or ``output`` | list, container, (choice isn’t |
+| | supported) |
++--------------------------------------+--------------------------------------+
+| ``notification`` | list, container, (choice isn’t |
+| | supported) |
++--------------------------------------+--------------------------------------+
+| ``augment`` | list, container, choice, case |
++--------------------------------------+--------------------------------------+
+
+Substatements are not only mapped to Java setter methods in the
+interface representing the parent statement, but they also generate
+packages with names consisting of the parent statement package name with
+the parent statement name appended.
+
+For example, this YANG model considers the container statement ``cont``
+as the direct substatement of the module.
+
+.. code:: yang
+
+ container cont {
+ container cont-inner {
+ }
+ list outter-list {
+ list list-in-list {
+ }
+ }
+ }
+
+Container ``cont`` is the parent statement for the substatements
+``cont-inner`` and ``outter-list``. ``list outter-list`` is the parent
+statement for substatement ``list-in-list``.
+
+| Java code is generated in the following structure:
+
+- ``org.opendaylight.yang.gen.v1.urn.module.rev201379`` - package
+ contains direct substatements of module statement
+
+ - ``Cont.java``
+
+- ``org.opendaylight.yang.gen.v1.urn.module.rev201379.cont`` - package
+ contains substatements of ``cont`` container statement
+
+ - ``ContInner.java`` - interface representing container
+ ``cont-inner``
+
+ - ``OutterList.java`` - interface representing list ``outer-list``
+
+- ``org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.outter.list``
+ - package contains substatements of outter-list list element
+
+ - ``ListInList.java``
+
+Class and interface names
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some YANG statements are mapped to Java classes and interfaces. The name
+of YANG element may contain various characters which aren’t permitted in
+Java class names. Firstly whitespaces are trimmed from YANG name. Next
+the characters space, -, \` are deleted and the subsequent letter is
+capitalized. At the end, first letter is capitalized.
+
+For example, ``example-name_ without_capitalization`` would map to
+``ExampleNameWithoutCapitalization``.
+
+Getter and setter names
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In some cases, YANG statements are converted to getter and/or setter
+methods. The process for getter is:
+
+1. the name of YANG statement is converted to Java class name style as
+ `explained above <#_class_and_interface_names>`__.
+
+2. the word ``get`` is added as prefix, if resulting type is
+ ``Boolean``, the name is prefixed with ``is`` prefix instead of
+ ``get``.
+
+3. the return type of the getter method is set to Java type representing
+ substatement
+
+The process for setter is:
+
+1. the name of YANG statement is converted to Java class name style as
+ `explained above <#_class_and_interface_names>`__.
+
+2. the word ``set`` is added as prefix
+
+3. the input parameter name is set to element’s name converted to Java
+ parameter style
+
+4. the return parameter is set to builder type
+
+Statement specific mapping
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+module statement
+^^^^^^^^^^^^^^^^
+
+YANG ``module`` statement is converted to Java as two Java classes. Each
+of the classes is in the separate Java file. The names of Java files are
+composed as follows: ``<module name><suffix>.java`` where ``<suffix>``
+is either data or service.
+
+Data Interface
+''''''''''''''
+
+Data Interface has a mapping similar to container, but contains only top
+level nodes defined in module.
+
+Data interface serves only as marker interface for type-safe APIs of
+``InstanceIdentifier``.
+
+Service Interface
+'''''''''''''''''
+
+Service Interface serves to describe RPC contract defined in the module.
+This RPC contract is defined by ``rpc`` statements.
+
+RPC implementation usually implement this interface and users of the
+RPCs use this interface to invoke RPCs.
+
+container statement
+^^^^^^^^^^^^^^^^^^^
+
+YANG containers are mapped to Java interfaces which extend the Java
+DataObject and Augmentable<container-interface>, where
+container-interface is the name of the mapped interface.
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ container cont {
+
+ }
+
+is converted into this Java:
+
+**Cont.java.**
+
+.. code:: java
+
+ public interface Cont extends ChildOf<...>, Augmentable<Cont> {
+ }
+
+Leaf statement
+^^^^^^^^^^^^^^
+
+Each leaf has to contain at least one type substatement. The leaf is
+mapped to getter method of parent statement with return type equal to
+type substatement value.
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ container cont {
+ leaf lf {
+ type string;
+ }
+ }
+
+is converted into this Java:
+
+**Cont.java.**
+
+.. code:: java
+
+ public interface Cont extends DataObject, Augmentable<Cont> {
+ String getLf();
+ }
+
+- Represents ``leaf lf``
+
+leaf-list statement
+^^^^^^^^^^^^^^^^^^^
+
+Each leaf-list has to contain one type substatement. The leaf-list is
+mapped to getter method of parent statement with return type equal to
+List of type substatement value.
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ container cont {
+ leaf-list lf-lst {
+ type string;
+ }
+ }
+
+is converted into this Java:
+
+**Cont.java.**
+
+.. code:: java
+
+ public interface Cont extends DataObject, Augmentable<Cont> {
+ List<String> getLfLst();
+ }
+
+list statement
+^^^^^^^^^^^^^^
+
+``list`` statements are mapped to Java interfaces and a getter method is
+generated in the interface associated with it’s parent statement. The
+return type of getter the method is a Java List of objects implementing
+the interface generated corresponding to the ``list statement.
+Mapping of `list`` substatement to Java:
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ container cont {
+ list outter-list {
+ key "leaf-in-list";
+ leaf number {
+ type uint64;
+ }
+ }
+ }
+
+The list statement ``example-list`` is mapped to the Java interface
+``ExampleList`` and the ``Cont`` interface (parent of ``ExampleList``)
+contains getter method with return type ``List<ExampleList>``. The
+presence of a ``key`` statement, triggers generation of
+``ExampleListKey``, which may be used to identify item in list.
+
+The end result is this Java:
+
+**OutterList.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont;
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+ import org.opendaylight.yangtools.yang.binding.Augmentable;
+ import Java.util.List;
+ import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.outter.list.ListInList;
+
+ public interface OutterList extends DataObject, Augmentable<OutterList> {
+
+ List<String> getLeafListInList();
+
+ List<ListInList> getListInList();
+
+ /*
+ Returns Primary Key of Yang List Type
+ */
+ OutterListKey getOutterListKey();
+
+ }
+
+**OutterListKey.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont;
+
+ import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.OutterListKey;
+ import Java.math.BigInteger;
+
+ public class OutterListKey {
+
+ private BigInteger _leafInList;
+
+ public OutterListKey(BigInteger _leafInList) {
+ super();
+ this_leafInList = _leafInList;
+ }
+
+ public BigInteger getLeafInList() {
+ return _leafInList;
+ }
+
+ @Override
+ public int hashCode() {
+ final int prime = 31;
+ int result = 1;
+ result = prime * result + ((_leafInList == null) ? 0 : _leafInList.hashCode());
+ return result;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj == null) {
+ return false;
+ }
+ if (getClass() != obj.getClass()) {
+ return false;
+ }
+ OutterListKey other = (OutterListKey) obj;
+ if (_leafInList == null) {
+ if (other._LeafInList != null) {
+ return false;
+ }
+ } else if(!_leafInList.equals(other._leafInList)) {
+ return false;
+ }
+ return true;
+ }
+
+ @Override
+ public String toString() {
+ StringBuilder builder = new StringBuilder();
+ builder.append("OutterListKey [_leafInList=");
+ builder.append(_leafInList);
+ builder.append("]");
+ return builder.toString();
+ }
+ }
+
+choice and case statements
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``choice`` element is mapped in mostly the same way a ``list`` element
+is. The ``choice`` element is mapped to and interface (marker interface)
+and a new getter method with the return type of a Java ``List`` of this
+marker interfaces is added to the interface corresponding to the parent
+statement. Any ``case`` substatements are mapped to Java interfaces
+which extend the marker interface.
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ container cont {
+ choice example-choice {
+ case foo-case {
+ leaf foo {
+ type string;
+ }
+ }
+ case bar-case {
+ leaf bar {
+ type string;
+ }
+ }
+ }
+ }
+
+is converted into this Java:
+
+**Cont.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379;
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+ import org.opendaylight.yangtools.yang.binding.Augmentable;
+ import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.ChoiceTest;
+
+ public interface Cont extends DataObject, Augmentable<Cont> {
+
+ ExampleChoice getExampleChoice();
+
+ }
+
+**ExampleChoice.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont;
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+
+ public interface ExampleChoice extends DataContainer {
+ }
+
+**FooCase.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.example.choice;
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+ import org.opendaylight.yangtools.yang.binding.Augmentable;
+ import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.ChoiceTest;
+
+ public interface FooCase extends ExampleChoice, DataObject, Augmentable<FooCase> {
+
+ String getFoo();
+
+ }
+
+**BarCase.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.example.choice;
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+ import org.opendaylight.yangtools.yang.binding.Augmentable;
+ import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.ChoiceTest;
+
+ public interface BarCase extends ExampleChoice, DataObject, Augmentable<BarCase> {
+
+ String getBar();
+
+ }
+
+grouping and uses statements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``grouping`s are mapped to Java interfaces. `uses`` statements in some
+element (using of concrete grouping) are mapped as extension of
+interface for this element with the interface which represents grouping.
+
+For example, the following YANG:
+
+**YANG Model.**
+
+.. code:: yang
+
+ grouping grp {
+ leaf foo {
+ type string;
+ }
+ }
+
+ container cont {
+ uses grp;
+ }
+
+is converted into this Java:
+
+**Grp.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379;
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+
+ public interface Grp extends DataObject {
+
+ String getFoo();
+
+ }
+
+**Cont.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379;
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+ import org.opendaylight.yangtools.yang.binding.Augmentable;
+
+ public interface Cont extends DataObject, Augmentable<Cont>, Grp {
+ }
+
+rpc, input and output statements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An ``rpc`` statement is mapped to Java as method of class
+``ModuleService.java``. Any substatements of an ``rpc`` are mapped as
+follows:
+
++--------------------------------------+--------------------------------------+
+| Rpc Substatement | Mapping |
++======================================+======================================+
+| input | presence of input statement triggers |
+| | generation of interface |
++--------------------------------------+--------------------------------------+
+| output | presence of output statement |
+| | triggers generation of interface |
++--------------------------------------+--------------------------------------+
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ rpc rpc-test1 {
+ output {
+ leaf lf-output {
+ type string;
+ }
+ }
+ input {
+ leaf lf-input {
+ type string;
+ }
+ }
+ }
+
+is converted into this Java:
+
+**ModuleService.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379;
+
+ import Java.util.concurrent.Future;
+ import org.opendaylight.yangtools.yang.common.RpcResult;
+
+ public interface ModuleService {
+
+ Future<RpcResult<RpcTest1Output>> rpcTest1(RpcTest1Input input);
+
+ }
+
+**RpcTest1Input.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379;
+
+ public interface RpcTest1Input {
+
+ String getLfInput();
+
+ }
+
+**RpcTest1Output.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379;
+
+ public interface RpcTest1Output {
+
+ String getLfOutput();
+
+ }
+
+notification statement
+^^^^^^^^^^^^^^^^^^^^^^
+
+``notification`` statements are mapped to Java interfaces which extend
+the Notification interface.
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ notification notif {
+ }
+
+is converted into this Java:
+
+**Notif.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379;
+
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+ import org.opendaylight.yangtools.yang.binding.Augmentable;
+ import org.opendaylight.yangtools.yang.binding.Notification;
+
+ public interface Notif extends DataObject, Augmentable<Notif>, Notification {
+ }
+
+augment statement
+~~~~~~~~~~~~~~~~~
+
+``augment`` statements are mapped to Java interfaces. The interface
+starts with the same name as the name of augmented interface with a
+suffix corresponding to the order number of augmenting interface. The
+augmenting interface also extends ``Augmentation<>`` with actual type
+parameter equal to augmented interface.
+
+For example, the following YANG:
+
+**YANG Model.**
+
+.. code:: yang
+
+ container cont {
+ }
+
+ augment "/cont" {
+ leaf additional-value {
+ type string;
+ }
+ }
+
+is converted into this Java:
+
+**Cont.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379;
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+ import org.opendaylight.yangtools.yang.binding.Augmentable;
+
+ public interface Cont extends DataObject, Augmentable<Cont> {
+
+ }
+
+**Cont1.java.**
+
+.. code:: java
+
+ package org.opendaylight.yang.gen.v1.urn.module.rev201379;
+
+ import org.opendaylight.yangtools.yang.binding.DataObject;
+ import org.opendaylight.yangtools.yang.binding.Augmentation;
+
+ public interface Cont1 extends DataObject, Augmentation<Cont> {
+
+ }
+
+YANG Type mapping
+~~~~~~~~~~~~~~~~~
+
+typedef statement
+^^^^^^^^^^^^^^^^^
+
+YANG ``typedef`` statements are mapped to Java classes. A ``typedef``
+may contain following substatements:
+
++--------------------------------------+--------------------------------------+
+| Substatement | Behaviour |
++======================================+======================================+
+| type | determines wrapped type and how |
+| | class will be generated |
++--------------------------------------+--------------------------------------+
+| descripton | Javadoc description |
++--------------------------------------+--------------------------------------+
+| units | is not mapped |
++--------------------------------------+--------------------------------------+
+| default | is not mapped |
++--------------------------------------+--------------------------------------+
+
+Valid Arguments Type
+''''''''''''''''''''
+
+Simple values of type argument are mapped as follows:
+
++--------------------------------------+--------------------------------------+
+| YANG Type | Java type |
++======================================+======================================+
+| boolean | Boolean |
++--------------------------------------+--------------------------------------+
+| empty | Boolean |
++--------------------------------------+--------------------------------------+
+| int8 | Byte |
++--------------------------------------+--------------------------------------+
+| int16 | Short |
++--------------------------------------+--------------------------------------+
+| int32 | Integer |
++--------------------------------------+--------------------------------------+
+| int64 | Long |
++--------------------------------------+--------------------------------------+
+| string | String or, wrapper class (if pattern |
+| | substatement is specified) |
++--------------------------------------+--------------------------------------+
+| decimal64 | Double |
++--------------------------------------+--------------------------------------+
+| uint8 | Short |
++--------------------------------------+--------------------------------------+
+| uint16 | Integer |
++--------------------------------------+--------------------------------------+
+| uint32 | Long |
++--------------------------------------+--------------------------------------+
+| uint64 | BigInteger |
++--------------------------------------+--------------------------------------+
+| binary | byte[] |
++--------------------------------------+--------------------------------------+
+
+Complex values of type argument are mapped as follows:
+
++--------------------------------------+--------------------------------------+
+| Argument Type | Java type |
++======================================+======================================+
+| enumeration | generated java enum |
++--------------------------------------+--------------------------------------+
+| bits | generated class for bits |
++--------------------------------------+--------------------------------------+
+| leafref | same type as referenced leaf |
++--------------------------------------+--------------------------------------+
+| identityref | Class |
++--------------------------------------+--------------------------------------+
+| union | generated java class |
++--------------------------------------+--------------------------------------+
+| instance-identifier | ``org.opendaylight.yangtools.yang.bi |
+| | nding.InstanceIdentifier`` |
++--------------------------------------+--------------------------------------+
+
+Enumeration Substatement Enum
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The YANG ``enumeration`` type has to contain some ``enum``
+substatements. An ``enumeration`` is mapped as Java enum type
+(standalone class) and every YANG enum substatements is mapped to Java
+enum’s predefined values.
+
+An ``enum`` statement can have following substatements:
+
++--------------------------------------+--------------------------------------+
+| Enum’s Substatement | Java mapping |
++======================================+======================================+
+| description | is not mapped in API |
++--------------------------------------+--------------------------------------+
+| value | mapped as input parameter for every |
+| | predefined value of enum |
++--------------------------------------+--------------------------------------+
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ typedef typedef-enumeration {
+ type enumeration {
+ enum enum1 {
+ description "enum1 description";
+ value 18;
+ }
+ enum enum2 {
+ value 16;
+ }
+ enum enum3 {
+ }
+ }
+ }
+
+is converted into this Java:
+
+**TypedefEnumeration.java.**
+
+.. code:: java
+
+ public enum TypedefEnumeration {
+ Enum1(18),
+ Enum2(16),
+ Enum3(19);
+
+ int value;
+
+ private TypedefEnumeration(int value) {
+ this.value = value;
+ }
+ }
+
+Bits’s Substatement Bit
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The YANG ``bits`` type has to contain some bit substatements. YANG
+``bits`` is mapped to a Java class (standalone class) and every YANG
+``bits`` substatements is mapped to a boolean attribute of that class.
+In addition, the class provides overridden versions of the Object
+methods ``hashCode``, ``toString``, and ``equals``.
+
+For example, the following YANG:
+
+**YANG Model.**
+
+.. code:: yang
+
+ typedef typedef-bits {
+ type bits {
+ bit first-bit {
+ description "first-bit description";
+ position 15;
+ }
+ bit second-bit;
+ }
+ }
+
+is converted into this Java:
+
+**TypedefBits.java.**
+
+.. code:: java
+
+ public class TypedefBits {
+
+ private Boolean firstBit;
+ private Boolean secondBit;
+
+ public TypedefBits() {
+ super();
+ }
+
+ public Boolean getFirstBit() {
+ return firstBit;
+ }
+
+ public void setFirstBit(Boolean firstBit) {
+ this.firstBit = firstBit;
+ }
+
+ public Boolean getSecondBit() {
+ return secondBit;
+ }
+
+ public void setSecondBit(Boolean secondBit) {
+ this.secondBit = secondBit;
+ }
+
+ @Override
+ public int hashCode() {
+ final int prime = 31;
+ int result = 1;
+ result = prime * result +
+ ((firstBit == null) ? 0 : firstBit.hashCode());
+ result = prime * result +
+ ((secondBit == null) ? 0 : secondBit.hashCode());
+ return result;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj == null) {
+ return false;
+ }
+ if (getClass() != obj.getClass()) {
+ return false;
+ }
+ TypedefBits other = (TypedefBits) obj;
+ if (firstBit == null) {
+ if (other.firstBit != null) {
+ return false;
+ }
+ } else if(!firstBit.equals(other.firstBit)) {
+ return false;
+ }
+ if (secondBit == null) {
+ if (other.secondBit != null) {
+ return false;
+ }
+ } else if(!secondBit.equals(other.secondBit)) {
+ return false;
+ }
+ return true;
+ }
+
+ @Override
+ public String toString() {
+ StringBuilder builder = new StringBuilder();
+ builder.append("TypedefBits [firstBit=");
+ builder.append(firstBit);
+ builder.append(", secondBit=");
+ builder.append(secondBit);
+ builder.append("]");
+ return builder.toString();
+ }
+ }
+
+Union’s Substatement Type
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the type of a ``typedef`` is ``union``, it has to contain ``type``
+substatements. The ``union typedef`` is mapped to class and its ``type``
+substatements are mapped to private class members. Every YANG union
+subtype gets its own Java constructor with a parameter which represent
+just that one attribute.
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ typedef typedef-union {
+ type union {
+ type int32;
+ type string;
+ }
+ }
+
+is converted into this Java:
+
+**TypdefUnion.java.**
+
+.. code:: java
+
+ public class TypedefUnion {
+
+ private Integer int32;
+ private String string;
+
+ public TypedefUnion(Integer int32) {
+ super();
+ this.int32 = int32;
+ }
+
+ public TypedefUnion(String string) {
+ super();
+ this.string = string;
+ }
+
+ public Integer getInt32() {
+ return int32;
+ }
+
+ public String getString() {
+ return string;
+ }
+
+ @Override
+ public int hashCode() {
+ final int prime = 31;
+ int result = 1;
+ result = prime * result + ((int32 == null) ? 0 : int32.hashCode());
+ result = prime * result + ((string == null) ? 0 : string.hashCode());
+ return result;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj == null) {
+ return false;
+ }
+ if (getClass() != obj.getClass()) {
+ return false;
+ }
+ TypedefUnion other = (TypedefUnion) obj;
+ if (int32 == null) {
+ if (other.int32 != null) {
+ return false;
+ }
+ } else if(!int32.equals(other.int32)) {
+ return false;
+ }
+ if (string == null) {
+ if (other.string != null) {
+ return false;
+ }
+ } else if(!string.equals(other.string)) {
+ return false;
+ }
+ return true;
+ }
+
+ @Override
+ public String toString() {
+ StringBuilder builder = new StringBuilder();
+ builder.append("TypedefUnion [int32=");
+ builder.append(int32);
+ builder.append(", string=");
+ builder.append(string);
+ builder.append("]");
+ return builder.toString();
+ }
+ }
+
+String Mapping
+^^^^^^^^^^^^^^
+
+The YANG ``string`` type can contain the substatements ``length`` and
+``pattern`` which are mapped as follows:
+
++--------------------------------------+--------------------------------------+
+| Type substatements | Mapping to Java |
++======================================+======================================+
+| length | not mapped |
++--------------------------------------+--------------------------------------+
+| pattern | | . list of string constants = list |
+| | of patterns |
+| | | . list of Pattern objects |
+| | | . static initialization block |
+| | where list of Patterns is |
+| | initialized from list of string of |
+| | constants |
++--------------------------------------+--------------------------------------+
+
+For example, the following YANG:
+
+**YANG model.**
+
+.. code:: yang
+
+ typedef typedef-string {
+ type string {
+ length 44;
+ pattern "[a][.]*"
+ }
+ }
+
+is converted into this Java:
+
+**TypedefString.java.**
+
+.. code:: java
+
+ public class TypedefString {
+
+ private static final List<Pattern> patterns = new ArrayList<Pattern>();
+ public static final List<String> PATTERN`CONSTANTS = Arrays.asList("[a][.]*");
+
+ static {
+ for (String regEx : PATTERN`CONSTANTS) {
+ patterns.add(Pattern.compile(regEx));
+ }
+ }
+
+ private String typedefString;
+
+ public TypedefString(String typedefString) {
+ super();
+ // Pattern validation
+ this.typedefString = typedefString;
+ }
+
+ public String getTypedefString() {
+ return typedefString;
+ }
+
+ @Override
+ public int hashCode() {
+ final int prime = 31;
+ int result = 1;
+ result = prime * result + ((typedefString == null) ? 0 : typedefString.hashCode());
+ return result;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj == null) {
+ return false;
+ }
+ if (getClass() != obj.getClass()) {
+ return false;
+ }
+ TypedefString other = (TypedefString) obj;
+ if (typedefString == null) {
+ if (other.typedefString != null) {
+ return false;
+ }
+ } else if(!typedefString.equals(other.typedefString)) {
+ return false;
+ }
+ return true;
+ }
+
+ @Override
+ public String toString() {
+ StringBuilder builder = new StringBuilder();
+ builder.append("TypedefString [typedefString=");
+ builder.append(typedefString);
+ builder.append("]");
+ return builder.toString();
+ }
+ }
+
+identity statement
+~~~~~~~~~~~~~~~~~~
+
+The purpose of the ``identity`` statement is to define a new globally
+unique, abstract, and untyped value.
+
+The ``base`` substatement argument is the name of existing identity from
+which the new identity is derived.
+
+Given that, an ``identity`` statement is mapped to Java abstract class
+and any ``base`` substatements are mapped as ``extends`` Java keyword.
+The identity name is translated to class name.
+
+For example, the following YANG:
+
+**YANG Model.**
+
+.. code:: yang
+
+ identity toast-type {
+
+ }
+
+ identity white-bread {
+ base toast-type;
+ }
+
+is converted into this Java:
+
+**ToastType.java.**
+
+.. code:: java
+
+ public abstract class ToastType extends BaseIdentity {
+ protected ToastType() {
+ super();
+ }
+ }
+
+**WhiteBread.java.**
+
+.. code:: java
+
+ public abstract class WhiteBread extends ToastType {
+ protected WhiteBread() {
+ super();
+ }
+ }
+
--- /dev/null
+############
+Gerrit Guide
+############
+
+How to push to Gerrit
+=====================
+
+It is highly recommended to use ssh to push to Gerrit to push code to Gerrit.
+In the event that you cannot use ssh such as corporate firewall blocking you
+then falling back to pushing via https should work.
+
+Using ssh to push to Gerrit
+---------------------------
+
+# TODO
+
+Using https to push to Gerrit
+-----------------------------
+
+Gerrit does not allow you to use your regular account credentials when pushing
+via https. Instead it requires you to first generate a http password via the
+Web U and use that as the password when pushing via https.
+
+.. figure:: images/gerrit-https-password-setup.png
+
+ Setting up an https password to push using https instead of ssh.
+
+To do this:
+
+1. navigate to https://git.opendaylight.org/gerrit/#/settings/http-password
+ (Steps 1, 2 and 3 in the image above.)
+2. click the **Generate Password** button.
+
+Gerrit will then generate a random password which you will need to use as your
+password when using git to push code to Gerrit via https.
+
+Signing Gerrit Commits
+======================
+
+1. Generate your GPG key.
+
+ The following instructions work on a Mac, but the general approach
+ should be the same on other OSes.
+
+ .. code-block:: bash
+
+ brew install gpg2 # if you don't have homebrew, get that here: http://brew.sh/
+ gpg2 --gen-key
+ # pick 1 for "RSA and RSA"
+ # enter 4096 to creat a 4096-bit key
+ # enter an expiration time, I picked 2y for 2 years
+ # enter y to accept the expiration time
+ # pick O or Q to accept your name/email/comment
+ # enter a pass phrase twice. it seems like backspace doesn't work, so type carefully
+ gpg2 --fingerprint
+ # you'll get something like this:
+ # spectre:~ ckd$ gpg2 --fingerprint
+ # /Users/ckd/.gnupg/pubring.gpg
+ # -----------------------------
+ # pub 4096R/F566C9B1 2015-04-06 [expires: 2017-04-05]
+ # Key fingerprint = 7C37 02AC D651 1FA7 9209 48D3 5DD5 0C4B F566 C9B1
+ # uid [ultimate] Colin Dixon <colin at colindixon.com>
+ # sub 4096R/DC1497E1 2015-04-06 [expires: 2017-04-05]
+ # you're looking for the part after 4096R, which is your key ID
+ gpg2 --send-keys <key-id>
+ # in the above example, the key-id would be F566C9B1
+ # you should see output like this:
+ # gpg: sending key F566C9B1 to hkp server keys.gnupg.net
+
+ If you're trying to participate in an OpenDaylight keysigning, then
+ send the output of ``gpg2 --fingerprint <key-id>`` to
+ keysigning@opendaylight.org
+
+ .. code-block:: bash
+
+ gpg2 --fingerprint <key-id>
+ # in the above example, the key-id would be F566C9B1
+ # in my case, the output was:
+ # pub 4096R/F566C9B1 2015-04-06 [expires: 2017-04-05]
+ # Key fingerprint = 7C37 02AC D651 1FA7 9209 48D3 5DD5 0C4B F566 C9B1
+ # uid [ultimate] Colin Dixon <colin at colindixon.com>
+ # sub 4096R/DC1497E1 2015-04-06 [expires: 2017-04-05]
+
+2. Install gpg, instead of or addition to gpg2. It appears as though
+ gpg2 has annoying things that it does when asking for your
+ passphrase, which I haven't debugged yet.
+
+ .. note:: you can tell git to use gpg by doing:
+ ``git config --global gpg.program gpg2``
+ but that then will seem to struggle asking for your
+ passphrase unless you have your gpg-agent set up right.
+
+3. Add you GPG to Gerrit
+
+ a. Run the following at the CLI:
+
+ .. code-block:: bash
+
+ gpg --export -a <fingerprint>
+ # e.g., gpg --export -a F566C9B1
+ # in my case the output looked like:
+ # -----BEGIN PGP PUBLIC KEY BLOCK-----
+ # Version: GnuPG v2
+ #
+ # mQINBFUisGABEAC/DkcjNUhxQkRLdfbfdlq9NlfDusWri0cXLVz4YN1cTUTF5HiW
+ # ...
+ # gJT+FwDvCGgaE+JGlmXgjv0WSd4f9cNXkgYqfb6mpji0F3TF2HXXiVPqbwJ1V3I2
+ # NA+l+/koCW0aMReK
+ # =A/ql
+ # -----END PGP PUBLIC KEY BLOCK-----
+
+ b. Browse to https://git.opendaylight.org/gerrit/#/settings/gpg-keys
+ c. Click Add Key...
+ d. Copy the output from the above command, paste it into the box,
+ and click Add
+
+3. Set up your git to sign commits and push signatures
+
+ .. code-block:: bash
+
+ git config commit.gpgsign true
+ git config push.gpgsign true
+ git config user.signingkey <fingerprint>
+ # e.g., git config user.signingkey F566C9B1
+
+ .. note:: you can do this instead with ``git commit -S``
+ You can use ``git commit -S`` and ``git push --signed``
+ on the CLI instead of configuring it in config if you
+ want to control which commits use your signature.
+
+4. Commit and push a change
+
+ a. change a file
+ b. ``git commit -asm "test commit"``
+
+ .. note:: this should result in git asking you for your passphrase
+
+ c. ``git review``
+
+ .. note:: this should result in git asking you for your passphrase
+
+ .. note:: annoyingly, the presence of a gpgp signature or pushing
+ of a gpg signature isn't recognized as a "change" by
+ Gerrit, so if you forget to do either, you need to change
+ something about the commit to get Gerrit to accept the
+ patch again. Slightly tweaking the commit message is a
+ good way.
+
+ .. note:: this assumes you have git review set up and push.gpgsign
+ set to true. Otherwise:
+
+ ``git push --signed gerrit HEAD:refs/for/master``
+
+ .. note:: this assumes you have your gerrit remote set up, if
+ not it's something like:
+ ``ssh://ckd@git.opendaylight.org:29418/<repo>.git``
+ where repo is something like docs or controller
+
+5. Verify that your commit is signed by going to the change in Gerrit
+ and checking for a green check (instead of a blue ?) next to your
+ name.
+
+
+Setting up gpg-agent on a Mac
+-----------------------------
+
+#. Install ``gpg-agent`` and ``pinentry-mac`` using ``brew``::
+
+ brew install gpg-agent pinentry-mac
+
+#. Edit your ``~/.gnupg/gpg.conf`` contain the line::
+
+ use-agent
+
+#. Edit your ``~/.gnupg/gpg-agent.conf`` to something like::
+
+ use-standard-socket
+ enable-ssh-support
+ default-cache-ttl 600
+ max-cache-ttl 7200
+ pinentry-program /usr/local/bin/pinentry-mac
+
+#. Edit your ``.bash_profile`` or equivalent file to contain the
+ following:
+
+ .. code-block:: bash
+
+ [ -f ~/.gpg-agent-info ] && source ~/.gpg-agent-info
+ if [ -S "${GPG_AGENT_INFO%%:*}" ]; then
+ export GPG_AGENT_INFO
+ else
+ eval $( gpg-agent --daemon --write-env-file ~/.gpg-agent-info )
+ fi
+
+#. Kill any stray ``gpg-agent`` daemons running::
+
+ sudo killall gpg-agent
+
+#. Restart your terminal (or log in and out) to reload the your
+ ``.bash_profile`` or equivalent file
+
+#. The next time a git operation makes a call to gpg, it should use
+ your gpg-agent to run a GUI window to ask for your passphrase and
+ give you an option to save your passphrase in the keychain.
+
+ .. image:: images/pinentry-mac.png
:maxdepth: 1
getting-started-guide/index
+ user-guide/index
opendaylight-with-openstack/index
.. toctree::
:maxdepth: 1
+ gerrit
submodules/releng/builder/docs/index
submodules/integration/test/docs/index
documentation
openstack-with-ovsdb
openstack-with-gbp
+ openstack-with-gbp-vpp
openstack-with-vtn
.. _OpenStack: https://www.openstack.org/
--- /dev/null
+Using Groupbasedpolicy's Neutron VPP Mapper
+===========================================
+
+Overview
+--------
+Neutron VPP Mapper implements features for support policy-based routing for OpenStack Neutron interface involving VPP devices.
+It allows using of policy-based schemes defined in GBP controller in a network consisting of OpenStack-provided nodes routed by a VPP node.
+
+Architecture
+------------
+Neutron VPP Mapper listens to Neutron data store change events, as well as being able to access directly the store.
+If the data changed match certain criteria (see `Processing Neutron Configuration`_),
+Neutron VPP Mapper converts Neutron data specifically required to render a VPP node configuration with a given End Point,
+e.g., the virtual host interface name assigned to a ``vhostuser`` socket.
+Then the mapped data is stored in the VPP info data store.
+
+Administering Neutron VPP Mapper
+--------------------------------
+To use the Neutron VPP Mapper in Karaf, at least the following Karaf features must be installed:
+
+* odl-groupbasedpolicy-neutron-vpp-mapper
+* odl-vbd-ui
+
+Initial pre-requisites
+----------------------
+A topology should exist in config datastore, it is necessary to define a node with a particular ``node-id``.
+Later, ``node-id`` will be used as a physical location reference in VPP renderer's bridge domain::
+
+ GET http://localhost:8181/restconf/config/network-topology:network-topology/
+
+ {
+ "network-topology":{
+ "topology":[
+ {
+ "topology-id":"datacentre",
+ "node":[
+ {
+ "node-id":"dut2",
+ "vlan-tunnel:super-interface":"GigabitEthernet0/9/0",
+ "termination-point":[
+ {
+ "tp-id":"GigabitEthernet0/9/0",
+ "neutron-provider-topology:physical-interface":{
+ "interface-name":"GigabitEthernet0/9/0"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+
+Processing Neutron Configuration
+--------------------------------
+``NeutronListener`` listens to the changes in Neutron datatree in config datastore. It filters the changes, processing only ``network`` and ``port`` entities.
+
+For a ``network`` entity it is checked that it has ``physical-network`` parameter set (i.e., it is backed-up by a physical network),
+and that ``network-type`` is ``vlan-network`` or ``"flat"``, and if this check has passed, a related bridge domain is created
+in VPP Renderer config datastore
+(``http://{{controller}}:{{port}}/restconf/config/vpp-renderer:config``), referenced to network by ``vlan`` field.
+
+In case of ``"vlan-network"``, the ``vlan`` field contains the same value as ``neutron-provider-ext:segmentation-id`` of network created by Neutron.
+
+In case of ``"flat"``, the VLAN specific parameters are not filled out.
+
+.. note:: In case of VXLAN network (i.e. ``network-type`` is ``"vxlan-network"``), no information is actually written
+into VPP Renderer datastore, as VXLAN is used for tenant-network (so no packets are going outside). Instead, VPP Renderer looks up GBP flood domains corresponding to existing VPP bridge domains trying to establish a VXLAN tunnel between them.
+
+For a ``port`` entity it is checked that ``vif-type`` contains ``"vhostuser"`` substring, and that ``device-owner`` contains a specific substring, namely ``"compute"``, ``"router"`` or ``"dhcp"``.
+
+In case of ``"compute"`` substring, a ``vhost-user`` is written to VPP Renderer config datastore.
+
+In case of ``"dhcp"`` or ``"router"``, a ``tap`` is written to VPP Renderer config datastore.
+
+Input/output examples
+---------------------
+
+OpenStack is creating network, and these data are being put into the data store::
+
+ PUT http://{{controller}}:{{port}}/restconf/config/neutron:neutron/networks
+
+ {
+ "networks": {
+ "network": [
+ {
+ "uuid": "43282482-a677-4102-87d6-90708f30a115",
+ "tenant-id": "94836b88-0e56-4150-aaa7-60f1c2b67faa",
+ "neutron-provider-ext:segmentation-id": "2016",
+ "neutron-provider-ext:network-type": "neutron-networks:network-type-vlan",
+ "neutron-provider-ext:physical-network": "datacentre",
+ "neutron-L3-ext:external": true,
+ "name": "drexternal",
+ "shared": false,
+ "admin-state-up": true,
+ "status": "ACTIVE"
+ }
+ ]
+ }
+ }
+
+Checking bridge domain in VPP Renderer config data store.
+Note that ``physical-location-ref`` is referring to ``"dut2"``, paired by ``neutron-provider-ext:physical-network`` -> ``topology-id``::
+
+ GET http://{{controller}}:{{port}}/restconf/config/vpp-renderer:config
+
+ {
+ "config": {
+ "bridge-domain": [
+ {
+ "id": "43282482-a677-4102-87d6-90708f30a115",
+ "type": "vpp-renderer:vlan-network",
+ "description": "drexternal",
+ "vlan": 2016,
+ "physical-location-ref": [
+ {
+ "node-id": "dut2",
+ "interface": [
+ "GigabitEthernet0/9/0"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+Port (compute)::
+
+ PUT http://{{controller}}:{{port}}/restconf/config/neutron:neutron/ports
+
+ {
+ "ports": {
+ "port": [
+ {
+ "uuid": "3d5dff96-25f5-4d4b-aa11-dc03f7f8d8e0",
+ "tenant-id": "94836b88-0e56-4150-aaa7-60f1c2b67faa",
+ "device-id": "dhcp58155ae3-f2e7-51ca-9978-71c513ab02ee-a91437c0-8492-47e2-b9d0-25c44aef6cda",
+ "neutron-binding:vif-details": [
+ {
+ "details-key": "somekey"
+ }
+ ],
+ "neutron-binding:host-id": "devstack-control",
+ "neutron-binding:vif-type": "vhostuser",
+ "neutron-binding:vnic-type": "normal",
+ "mac-address": "fa:16:3e:4a:9f:c0",
+ "name": "",
+ "network-id": "a91437c0-8492-47e2-b9d0-25c44aef6cda",
+ "neutron-portsecurity:port-security-enabled": false,
+ "device-owner": "network:compute",
+ "fixed-ips": [
+ {
+ "subnet-id": "0a5834ed-ed31-4425-832d-e273cac26325",
+ "ip-address": "10.1.1.3"
+ }
+ ],
+ "admin-state-up": true
+ }
+ ]
+ }
+ }
+
+ GET http://{{controller}}:{{port}}/restconf/config/vpp-renderer:config
+
+ {
+ "config": {
+ "vpp-endpoint": [
+ {
+ "context-type": "l2-l3-forwarding:l2-bridge-domain",
+ "context-id": "a91437c0-8492-47e2-b9d0-25c44aef6cda",
+ "address-type": "l2-l3-forwarding:mac-address-type",
+ "address": "fa:16:3e:4a:9f:c0",
+ "vpp-node-path": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='topology-netconf']/network-topology:node[network-topology:node-id='devstack-control']",
+ "vpp-interface-name": "neutron_port_3d5dff96-25f5-4d4b-aa11-dc03f7f8d8e0",
+ "socket": "/tmp/socket_3d5dff96-25f5-4d4b-aa11-dc03f7f8d8e0",
+ "description": "neutron port"
+ }
+ ]
+ }
+ }
+
+Port (dhcp)::
+
+ PUT http://{{controller}}:{{port}}/restconf/config/neutron:neutron/ports
+
+ {
+ "ports": {
+ "port": [
+ {
+ "uuid": "3d5dff96-25f5-4d4b-aa11-dc03f7f8d8e0",
+ "tenant-id": "94836b88-0e56-4150-aaa7-60f1c2b67faa",
+ "device-id": "dhcp58155ae3-f2e7-51ca-9978-71c513ab02ee-a91437c0-8492-47e2-b9d0-25c44aef6cda",
+ "neutron-binding:vif-details": [
+ {
+ "details-key": "somekey"
+ }
+ ],
+ "neutron-binding:host-id": "devstack-control",
+ "neutron-binding:vif-type": "vhostuser",
+ "neutron-binding:vnic-type": "normal",
+ "mac-address": "fa:16:3e:4a:9f:c0",
+ "name": "",
+ "network-id": "a91437c0-8492-47e2-b9d0-25c44aef6cda",
+ "neutron-portsecurity:port-security-enabled": false,
+ "device-owner": "network:dhcp",
+ "fixed-ips": [
+ {
+ "subnet-id": "0a5834ed-ed31-4425-832d-e273cac26325",
+ "ip-address": "10.1.1.3"
+ }
+ ],
+ "admin-state-up": true
+ }
+ ]
+ }
+ }
+
+ GET http://{{controller}}:{{port}}/restconf/config/vpp-renderer:config
+
+ {
+ "config": {
+ "vpp-endpoint": [
+ {
+ "context-type": "l2-l3-forwarding:l2-bridge-domain",
+ "context-id": "a91437c0-8492-47e2-b9d0-25c44aef6cda",
+ "address-type": "l2-l3-forwarding:mac-address-type",
+ "address": "fa:16:3e:4a:9f:c0",
+ "vpp-node-path": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='topology-netconf']/network-topology:node[network-topology:node-id='devstack-control']",
+ "vpp-interface-name": "neutron_port_3d5dff96-25f5-4d4b-aa11-dc03f7f8d8e0",
+ "physical-address": "fa:16:3e:4a:9f:c0",
+ "name": "tap3d5dff96-25",
+ "description": "neutron port"
+ }
+ ]
+ }
+ }
-Subproject commit b8410b1299b7ee1e1b843850a558e68609575fa1
+Subproject commit d94bd13f7e025f10ae7416026a835156590a1869
-Subproject commit 3a464941f84541fb3193c92cff6b8c5fcf80808f
+Subproject commit b87f6fa515871466e515dd6aec05e8733aeabe08
-Subproject commit 1a0bece17ca76ee1e887d1e66992df63774d1f9b
+Subproject commit a713249be961be184644f4fbce7914a4014cb68b
-Subproject commit e714b02ea6f1ab2adc04140dfe8d5a6a75462268
+Subproject commit ca11928e7924eec6b43bdaca3fd4fa6b015f3a75
-Subproject commit 8fb9f39b806b94c392c4bb5b7c23826198000498
+Subproject commit 620c4dc69a97dcbeb63fec372f1b10002a35c346
--- /dev/null
+Atrium User Guide
+=================
+
+Overview
+--------
+
+Project Atrium is an open source SDN distribution - a vertically
+integrated set of open source components which together form a complete
+SDN stack. It’s goals are threefold:
+
+- Close the large integration-gap of the elements that are needed to
+ build an SDN stack - while there are multiple choices at each layer,
+ there are missing pieces with poor or no integration.
+
+- Overcome a massive gap in interoperability - This exists both at the
+ switch level, where existing products from different vendors have
+ limited compatibility, making it difficult to connect an arbitrary
+ switch and controller and at an API level, where its difficult to
+ write a portable application across multiple controller platforms.
+
+- Work closely with network operators on deployable use-cases, so that
+ they could download near production quality code from one location,
+ and get started with functioning software defined networks on real
+ hardware.
+
+Architecture
+------------
+
+The key components of Atrium BGP Peering Router Application are as
+follows:
+
+- Data Plane Switch - Data plane switch is the entity that uses flow
+ table entries installed by BGP Routing Application through SDN
+ controller. In the simplest form data plane switch with the installed
+ flows act like a BGP Router.
+
+- OpenDaylight Controller - OpenDaylight SDN controller has many
+ utility applications or plugins which are leveraged by the BGP Router
+ application to manage the control plane information.
+
+- BGP Routing Application - An application running within the
+ OpenDaylight runtime environment to handle I-BGP updates.
+
+- `DIDM <#_didm_user_guide>`__ - DIDM manages the drivers specific to
+ each data plane switch connected to the controller. The drivers are
+ created primarily to hide the underlying complexity of the devices
+ and to expose a uniform API to applications.
+
+- Flow Objectives API - The driver implementation provides a pipeline
+ abstraction and exposes Flow Objectives API. This means applications
+ need to be aware of only the Flow Objectives API without worrying
+ about the Table IDs or the pipelines.
+
+- Control Plane Switch - This component is primarily used to connect
+ the OpenDaylight SDN controller with the Quagga Soft-Router and
+ establish a path for forwarding E-BGP packets to and from Quagga.
+
+- Quagga soft router - An open source routing software that handles
+ E-BGP updates.
+
+Running Atrium
+--------------
+
+- To run the Atrium BGP Routing Application in OpenDaylight
+ distribution, simply install the ``odl-atrium-all`` feature.
+
+ ::
+
+ feature:install odl-atrium-all
+
--- /dev/null
+DIDM User Guide
+===============
+
+Overview
+--------
+
+The Device Identification and Driver Management (DIDM) project addresses
+the need to provide device-specific functionality. Device-specific
+functionality is code that performs a feature, and the code is
+knowledgeable of the capability and limitations of the device. For
+example, configuring VLANs and adjusting FlowMods are features, and
+there may be different implementations for different device types.
+Device-specific functionality is implemented as Device Drivers. Device
+Drivers need to be associated with the devices they can be used with. To
+determine this association requires the ability to identify the device
+type.
+
+DIDM Architecture
+-----------------
+
+The DIDM project creates the infrastructure to support the following
+functions:
+
+- **Discovery** - Determination that a device exists in the controller
+ management domain and connectivity to the device can be established.
+ For devices that support the OpenFlow protocol, the existing
+ discovery mechanism in OpenDaylight suffices. Devices that do not
+ support OpenFlow will be discovered through manual means such as the
+ operator entering device information via GUI or REST API.
+
+- **Identification** – Determination of the device type.
+
+- **Driver Registration** – Registration of Device Drivers as routed
+ RPCs.
+
+- **Synchronization** – Collection of device information, device
+ configuration, and link (connection) information.
+
+- **Data Models for Common Features** – Data models will be defined to
+ perform common features such as VLAN configuration. For example,
+ applications can configure a VLAN by writing the VLAN data to the
+ data store as specified by the common data model.
+
+- **RPCs for Common Features** – Configuring VLANs and adjusting
+ FlowMods are example of features. RPCs will be defined that specify
+ the APIs for these features. Drivers implement features for specific
+ devices and support the APIs defined by the RPCs. There may be
+ different Driver implementations for different device types.
+
+Atrium Support
+--------------
+
+The Atrium implements an open source router that speaks BGP to other
+routers, and forwards packets received on one port/vlan to another,
+based on the next-hop learnt via BGP peering. A BGP peering application
+for the Open Daylight Controller and a new model for flow objective
+drivers for switches integrated with the Open Daylight Atrium
+distribution was developed for this project. The implementation has the
+same level of feature partly that was introduced by the Atrium 2015/A
+distribution on the ONOS controller. An overview of the architecture is
+available at here
+(https://github.com/onfsdn/atrium-docs/wiki/ODL-Based-Atrium-Router-16A).
+
+Atrium stack is implemented in OpenDaylight using Atrium and DIDM
+project. Atrium project provides the application implementation for BGP
+peering and the DIDM project provides implementation for FlowObjectives.
+FlowObjective provides an abstraction layer and present the pipeline
+agnostic api to application to consume.
+
+FlowObjective
+~~~~~~~~~~~~~
+
+Flow Objectives describe an SDN application’s objective (or intention)
+behind a flow it is sending to a device.
+
+Application communicates the flow installation requirement using Flow
+Objectives. DIDM drivers translates the Flow Objectives to device
+specific flows as per the device pipeline.
+
+There are three FlowObjectives (already implemented in ONOS controller)
+:
+
+- Filtering Objective
+
+- Next Objective
+
+- Forwarding Objective
+
+Installing DIDM
+---------------
+
+To install DIDM, download OpenDaylight and use the Karaf console to
+install the following features:
+
+- odl-openflowplugin-all
+
+- odl-didm-all
+
+odl-didm-all installs the following required features:
+
+- odl-didm-ovs-all
+
+- odl-didm-ovs-impl
+
+- odl-didm-util
+
+- odl-didm-identification
+
+- odl-didm-drivers
+
+- odl-didm-hp-all
+
+Configuring DIDM
+----------------
+
+This section shows an example configuration steps for installing a
+driver (HP 3800 OpenFlow switch driver).
+
+Install DIDM features:
+----------------------
+
+::
+
+ feature:install odl-didm-identification-api
+ feature:install odl-didm-drivers
+
+In order to identify the device, device driver needs to be installed
+first. Identification Manager will be notified when a new device
+connects to the controller.
+
+Install HP driver
+-----------------
+
+feature:install odl-didm-hp-all installs the following features
+
+- odl-didm-util
+
+- odl-didm-identification
+
+- odl-didm-drivers
+
+- odl-didm-hp-all
+
+- odl-didm-hp-impl
+
+Now at this point, the driver has written all of the identification
+information in to the MD-SAL datastore. The identification manager
+should have that information so that it can try to identify the HP 3800
+device when it connects to the controller.
+
+Configure the switch and connect it to the controller from the switch
+CLI.
+
+Run REST GET command to verify the device details:
+--------------------------------------------------
+
+`http://<CONTROLLER-IP:8181>/restconf/operational/opendaylight-inventory:nodes <http://<CONTROLLER-IP:8181>/restconf/operational/opendaylight-inventory:nodes>`__
+
+Run REST adjust-flow command to adjust flows and push to the device
+-------------------------------------------------------------------
+
+**Flow mod driver for HP 3800 device is added in Beryllium release.**
+
+This driver adjusts the flows and push the same to the device. This API
+takes the flow to be adjusted as input and displays the adjusted flow as
+output in the REST output container. Here is the REST API to adjust and
+push flows to HP 3800 device:
+
+`http://<CONTROLLER-IP:8181>/restconf/operations/openflow-feature:adjust-flow <http://<CONTROLLER-IP:8181>/restconf/operations/openflow-feature:adjust-flow>`__
+
+FlowObjectives API
+------------------
+
+FlowObjective presents the OpenFlow pipeline agnostic API to Application
+to consume. Application communicate their intent behind installation of
+flow to Drivers using the FlowObjective. Driver translates the
+FlowObjective in device specific flows and uses the OpenFlowPlugin to
+install the flows to the device.
+
+Filter Objective
+~~~~~~~~~~~~~~~~
+
+`http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:filter <http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:filter>`__
+
+Next Objective
+~~~~~~~~~~~~~~
+
+`http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:next <http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:next>`__
+
+Forward Objective
+~~~~~~~~~~~~~~~~~
+
+`http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:forward <http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:forward>`__
+
--- /dev/null
+Group Based Policy User Guide
+=============================
+
+Overview
+--------
+
+OpenDaylight Group Based Policy allows users to express network
+configuration in a declarative versus imperative way.
+
+This is often described as asking for **"what you want"**, rather than
+**"how to do it"**.
+
+In order to achieve this Group Based Policy (herein referred to as
+**GBP**) is an implementation of an **Intent System**.
+
+An **Intent System**:
+
+- is a process around an intent driven data model
+
+- contains no domain specifics
+
+- is capable of addressing multiple semantic definitions of intent
+
+To this end, **GBP** Policy views an **Intent System** visually as:
+
+.. figure:: ./images/groupbasedpolicy/IntentSystemPolicySurfaces.png
+ :alt: Intent System Process and Policy Surfaces
+
+ Intent System Process and Policy Surfaces
+
+- **expressed intent** is the entry point into the system.
+
+- **operational constraints** provide policy for the usage of the
+ system which modulates how the system is consumed. For instance *"All
+ Financial applications must use a specific encryption standard"*.
+
+- **capabilities and state** are provided by *renderers*. *Renderers*
+ dynamically provide their capabilities to the core model, allowing
+ the core model to remain non-domain specific.
+
+- **governance** provides feedback on the delivery of the *expressed
+ intent*. i.e. *"Did we do what you asked us?"*
+
+In summary **GBP is about the Automation of Intent**.
+
+By thinking of **Intent Systems** in this way, it enables:
+
+- **automation of intent**
+
+ By focusing on **Model. Process. Automation**, a consistent policy
+ resolution process enables for mapping between the **expressed
+ intent** and renderers responsible for providing the capabilities of
+ implementing that intent.
+
+- recursive/intent level-independent behaviour.
+
+ Where *one person’s concrete is another’s abstract*, intent can be
+ fulfilled through a hierarchical implementation of non-domain
+ specific policy resolution. Domain specifics are provided by the
+ *renderers*, and exposed via the API, at each policy resolution
+ instance. For example:
+
+ - To DNS: The name "www.foo.com" is *abstract*, and it’s IPv4
+ address 10.0.0.10 is *concrete*,
+
+ - To an IP stack: 10.0.0.10 is *abstract* and the MAC
+ 08:05:04:03:02:01 is *concrete*,
+
+ - To an Ethernet switch: The MAC 08:05:04:03:02:01 is *abstract*,
+ the resolution to a port in it’s CAM table is *concrete*,
+
+ - To an optical network: The port maybe *abstract*, yet the optical
+ wavelength is *concrete*.
+
+ **Note**
+
+ *This is a very domain specific analogy, tied to something most
+ readers will understand. It in no way implies the **GBP** should be
+ implemented in an OSI type fashion. The premise is that by
+ implementing a full **Intent System**, the user is freed from a lot
+ of the constraints of how the expressed intent is realised.*
+
+It is important to show the overall philosophy of **GBP** as it sets the
+project’s direction.
+
+In the Beryllium release of OpenDaylight, **GBP** focused on **expressed
+intent**, **refactoring of how renderers consume and publish Subject
+Feature Definitions for multi-renderer support**.
+
+GBP Base Architecture and Value Proposition
+-------------------------------------------
+
+Terminology
+~~~~~~~~~~~
+
+In order to explain the fundamental value proposition of **GBP**, an
+illustrated example is given. In order to do that some terminology must
+be defined.
+
+The Access Model is the core of the **GBP** Intent System policy
+resolution process.
+
+.. figure:: ./images/groupbasedpolicy/GBPTerminology1.png
+ :alt: GBP Access Model Terminology - Endpoints, EndpointGroups,
+ Contract
+
+ GBP Access Model Terminology - Endpoints, EndpointGroups, Contract
+
+.. figure:: ./images/groupbasedpolicy/GBPTerminology2.png
+ :alt: GBP Access Model Terminology - Subject, Classifier, Action
+
+ GBP Access Model Terminology - Subject, Classifier, Action
+
+.. figure:: ./images/groupbasedpolicy/GBPTerminology3.png
+ :alt: GBP Forwarding Model Terminology - L3 Context, L2 Bridge
+ Context, L2 Flood Context/Domain, Subnet
+
+ GBP Forwarding Model Terminology - L3 Context, L2 Bridge Context, L2
+ Flood Context/Domain, Subnet
+
+- Endpoints:
+
+ Define concrete uniquely identifiable entities. In Beryllium,
+ examples could be a Docker container, or a Neutron port
+
+- EndpointGroups:
+
+ EndpointGroups are sets of endpoints that share a common set of
+ policies. EndpointGroups can participate in contracts that determine
+ the kinds of communication that are allowed. EndpointGroups *consume*
+ and *provide* contracts. They also expose both *requirements and
+ capabilities*, which are labels that help to determine how contracts
+ will be applied. An EndpointGroup can specify a parent EndpointGroup
+ from which it inherits.
+
+- Contracts:
+
+ Contracts determine which endpoints can communicate and in what way.
+ Contracts between pairs of EndpointGroups are selected by the
+ contract selectors defined by the EndpointGroup. Contracts expose
+ qualities, which are labels that can help EndpointGroups to select
+ contracts. Once the contract is selected, contracts have clauses that
+ can match against requirements and capabilities exposed by
+ EndpointGroups, as well as any conditions that may be set on
+ endpoints, in order to activate subjects that can allow specific
+ kinds of communication. A contract is allowed to specify a parent
+ contract from which it inherits.
+
+- Subject
+
+ Subjects describe some aspect of how two endpoints are allowed to
+ communicate. Subjects define an ordered list of rules that will match
+ against the traffic and perform any necessary actions on that
+ traffic. No communication is allowed unless a subject allows that
+ communication.
+
+- Clause
+
+ Clauses are defined as part of a contract. Clauses determine how a
+ contract should be applied to particular endpoints and
+ EndpointGroups. Clauses can match against requirements and
+ capabilities exposed by EndpointGroups, as well as any conditions
+ that may be set on endpoints. Matching clauses define some set of
+ subjects which can be applied to the communication between the pairs
+ of endpoints.
+
+Architecture and Value Proposition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**GBP** offers an intent based interface, accessed via the `UX <#UX>`__,
+via the `REST API <#REST>`__ or directly from a domain-specific-language
+such as `Neutron <#Neutron>`__ through a mapping interface.
+
+There are two models in **GBP**:
+
+- the access (or core) model
+
+- the forwarding model
+
+.. figure:: ./images/groupbasedpolicy/GBP_AccessModel_simple.png
+ :alt: GBP Access (or Core) Model
+
+ GBP Access (or Core) Model
+
+The *classifier* and *action* portions of the model can be thought of as
+hooks, with their definition provided by each *renderer* about its
+domain specific capabilities. In **GBP** Beryllium, there is one
+renderer, the *`OpenFlow Overlay renderer (OfOverlay). <#OfOverlay>`__*
+
+These hooks are filled with *definitions* of the types of *features* the
+renderer can provide the *subject*, and are called
+**subject-feature-definitions**.
+
+This means an *expressed intent* can be fulfilled by, and across,
+multiple renderers simultaneously, without any specific provisioning
+from the consumer of **GBP**.
+
+Since **GBP** is implemented in OpenDaylight, which is an SDN
+controller, it also must address networking. This is done via the
+*forwarding model*, which is domain specific to networking, but could be
+applied to many different *types* of networking.
+
+.. figure:: ./images/groupbasedpolicy/GBP_ForwardingModel_simple.png
+ :alt: GBP Forwarding Model
+
+ GBP Forwarding Model
+
+Each endpoint is provisioned with a *network-containment*. This can be
+a:
+
+- subnet
+
+ - normal IP stack behaviour, where ARP is performed in subnet, and
+ for out of subnet, traffic is sent to default gateway.
+
+ - a subnet can be a child of any of the below forwarding model
+ contexts, but typically would be a child of a flood-domain
+
+- L2 flood-domain
+
+ - allows flooding behaviour.
+
+ - is a n:1 child of a bridge-domain
+
+ - can have multiple children
+
+- L2 bridge-domain
+
+ - is a layer2 namespace
+
+ - is the realm where traffic can be sent at layer 2
+
+ - is a n:1 child of a L3 context
+
+ - can have multiple children
+
+- L3 context
+
+ - is a layer3 namespace
+
+ - is the realm where traffic is passed at layer 3
+
+ - is a n:1 child of a tenant
+
+ - can have multiple children
+
+A simple example of how the access and forwarding models work is as
+follows:
+
+.. figure:: ./images/groupbasedpolicy/GBP_Endpoint_EPG_Contract.png
+ :alt: GBP Endpoints, EndpointGroups and Contracts
+
+ GBP Endpoints, EndpointGroups and Contracts
+
+In this example, the **EPG:webservers** is *providing* the *web* and
+*ssh* contracts. The **EPG:client** is consuming those contracts.
+**EPG:client** is providing the *any* contract, which is consumed by
+**EPG:webservers**.
+
+The *direction* keyword is always from the perspective of the *provider*
+of the contract. In this case contract *web*, being *provided* by
+**EPG:webservers**, with the classifier to match TCP destination port
+80, means:
+
+- packets with a TCP destination port of 80
+
+- sent to (*in*) endpoints in the **EPG:webservers**
+
+- will be *allowed*.
+
+.. figure:: ./images/groupbasedpolicy/GBP_Endpoint_EPG_Forwarding.png
+ :alt: GBP Endpoints and the Forwarding Model
+
+ GBP Endpoints and the Forwarding Model
+
+When the forwarding model is considered in the figure above, it can be
+seen that even though all endpoints are communicating using a common set
+of contracts, their forwarding is *contained* by the forwarding model
+contexts or namespaces. In the example shown, the endpoints associated
+with a *network-containment* that has an ultimate parent of
+*L3Context:Sales* can only communicate with other endpoints within this
+L3Context. In this way L3VPN services can be implemented without any
+impact to the **Intent** of the contract.
+
+High-level implementation Architecture
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The overall architecture, including *`Neutron <#Neutron>`__* domain
+specific mapping, and the `OpenFlow Overlay renderer <#OfOverlay>`__
+looks as so:
+
+.. figure:: ./images/groupbasedpolicy/GBP_High-levelBerylliumArchitecture.png
+ :alt: GBP High Level Beryllium Architecture
+
+ GBP High Level Beryllium Architecture
+
+The major benefit of this architecture is that the mapping of the
+domain-specific-language is completely separate and independent of the
+underlying renderer implementation.
+
+For instance, using the `Neutron Mapper <#Neutron>`__, which maps the
+Neutron API to the **GBP** core model, any contract automatically
+generated from this mapping can be augmented via the `UX <#UX>`__ to use
+`Service Function Chaining <#SFC>`__, a capability not currently
+available in OpenStack Neutron.
+
+When another renderer is added, for instance, NetConf, the same policy
+can now be leveraged across NetConf devices simultaneously:
+
+.. figure:: ./images/groupbasedpolicy/GBP_High-levelExtraRenderer.png
+ :alt: GBP High Level Beryllium Architecture - adding a renderer
+
+ GBP High Level Beryllium Architecture - adding a renderer
+
+As other domain-specific mappings occur, they too can leverage the same
+renderers, as the renderers only need to implement the **GBP** access
+and forwarding models, and the domain-specific mapping need only manage
+mapping to the access and forwarding models. For instance:
+
+.. figure:: ./images/groupbasedpolicy/High-levelBerylliumArchitectureEvolution2.png
+ :alt: GBP High Level Beryllium Architecture - adding a renderer
+
+ GBP High Level Beryllium Architecture - adding a renderer
+
+In summary, the **GBP** architecture:
+
+- separates concerns: the Expressed Intent is kept completely separated
+ from the underlying renderers.
+
+- is cohesive: each part does it’s part and it’s part only
+
+- is scalable: code can be optimised around model
+ mapping/implementation, and functionality re-used
+
+Policy Resolution
+~~~~~~~~~~~~~~~~~
+
+Contract Selection
+^^^^^^^^^^^^^^^^^^
+
+The first step in policy resolution is to select the contracts that are
+in scope.
+
+EndpointGroups participate in contracts either as a *provider* or as a
+*consumer* of a contract. Each EndpointGroup can participate in many
+contracts at the same time, but for each contract it can be in only one
+role at a time. In addition, there are two ways for an EndpointGroup to
+select a contract: either with either a:
+
+- *named selector*
+
+ Named selectors simply select a specific contract by its contract ID.
+
+- target selector.
+
+ Target selectors allow for additional flexibility by matching against
+ *qualities* of the contract’s *target.*
+
+Thus, there are a total of 4 kinds of contract selector:
+
+- provider named selector
+
+ Select a contract by contract ID, and participate as a provider.
+
+- provider target selector
+
+ Match against a contract’s target with a quality matcher, and
+ participate as a provider.
+
+- consumer named selector
+
+ Select a contract by contract ID, and participate as a consumer.
+
+- consumer target selector
+
+ Match against a contract’s target with a quality matcher, and
+ participate as a consumer.
+
+To determine which contracts are in scope, contracts are found where
+either the source EndpointGroup selects a contract as either a provider
+or consumer, while the destination EndpointGroup matches against the
+same contract in the corresponding role. So if endpoint *x* in
+EndpointGroup *X* is communicating with endpoint *y* in EndpointGroup
+*Y*, a contract *C* is in scope if either *X* selects *C* as a provider
+and *Y* selects *C* as a consumer, or vice versa.
+
+The details of how quality matchers work are described further in
+`Matchers <#Matchers>`__. Quality matchers provide a flexible mechanism
+for contract selection based on labels.
+
+The end result of the contract selection phase can be thought of as a
+set of tuples representing selected contract scopes. The fields of the
+tuple are:
+
+- Contract ID
+
+- The provider EndpointGroup ID
+
+- The name of the selector in the provider EndpointGroup that was used
+ to select the contract, called the *matching provider selector.*
+
+- The consumer EndpointGroup ID
+
+- The name of the selector in the consumer EndpointGroup that was used
+ to select the contract, called the *matching consumer selector.*
+
+The result is then stored in the datastore under **Resolved Policy**.
+
+Subject Selection
+^^^^^^^^^^^^^^^^^
+
+The second phase in policy resolution is to determine which subjects are
+in scope. The subjects define what kinds of communication are allowed
+between endpoints in the EndpointGroups. For each of the selected
+contract scopes from the contract selection phase, the subject selection
+procedure is applied.
+
+Labels called, capabilities, requirements and conditions are matched
+against to bring a Subject *into scope*. EndpointGroups have
+capabilities and requirements, while endpoints have conditions.
+
+Requirements and Capabilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When acting as a *provider*, EndpointGroups expose *capabilities,* which
+are labels representing specific pieces of functionality that can be
+exposed to other EndpointGroups that may meet functional requirements of
+those EndpointGroups.
+
+When acting as a *consumer*, EndpointGroups expose *requirements*, which
+are labels that represent that the EndpointGroup requires some specific
+piece of functionality.
+
+As an example, we might create a capability called "user-database" which
+indicates that an EndpointGroup contains endpoints that implement a
+database of users.
+
+We might create a requirement also called "user-database" to indicate an
+EndpointGroup contains endpoints that will need to communicate with the
+endpoints that expose this service.
+
+Note that in this example the requirement and capability have the same
+name, but the user need not follow this convention.
+
+The matching provider selector (that was used by the provider
+EndpointGroup to select the contract) is examined to determine the
+capabilities exposed by the provider EndpointGroup for this contract
+scope.
+
+The provider selector will have a list of capabilities either directly
+included in the provider selector or inherited from a parent selector or
+parent EndpointGroup. (See `Inheritance <#Inheritance>`__).
+
+Similarly, the matching consumer selector will expose a set of
+requirements.
+
+Conditions
+^^^^^^^^^^
+
+Endpoints can have *conditions*, which are labels representing some
+relevant piece of operational state related to the endpoint.
+
+An example of a condition might be "malware-detected," or
+"authentication-succeeded." Conditions are used to affect how that
+particular endpoint can communicate.
+
+To continue with our example, the "malware-detected" condition might
+cause an endpoint’s connectivity to be cut off, while
+"authentication-succeeded" might open up communication with services
+that require an endpoint to be first authenticated and then forward its
+authentication credentials.
+
+Clauses
+^^^^^^^
+
+Clauses perform the actual selection of subjects. A clause has lists of
+matchers in two categories. In order for a clause to become active, all
+lists of matchers must match. A matching clause will select all the
+subjects referenced by the clause. Note that an empty list of matchers
+counts as a match.
+
+The first category is the consumer matchers, which match against the
+consumer EndpointGroup and endpoints. The consumer matchers are:
+
+- Group Idenfication Constraint: Requirement matchers
+
+ Matches against requirements in the matching consumer selector.
+
+- Group Identification Constraint: GroupName
+
+ Matches against the group name
+
+- Consumer condition matchers
+
+ Matches against conditions on endpoints in the consumer EndpointGroup
+
+- Consumer Endpoint Identification Constraint
+
+ Label based criteria for matching against endpoints. In Beryllium
+ this can be used to label endpoints based on IpPrefix.
+
+The second category is the provider matchers, which match against the
+provider EndpointGroup and endpoints. The provider matchers are:
+
+- Group Idenfication Constraint: Capability matchers
+
+ Matches against capabilities in the matching provider selector.
+
+- Group Identification Constraint: GroupName
+
+ Matches against the group name
+
+- Consumer condition matchers
+
+ Matches against conditions on endpoints in the provider EndpointGroup
+
+- Consumer Endpoint Identification Constraint
+
+ Label based criteria for matching against endpoints. In Beryllium
+ this can be used to label endpoints based on IpPrefix.
+
+Clauses have a list of subjects that apply when all the matchers in the
+clause match. The output of the subject selection phase logically is a
+set of subjects that are in scope for any particular pair of endpoints.
+
+Rule Application
+^^^^^^^^^^^^^^^^
+
+Now subjects have been selected that apply to the traffic between a
+particular set of endpoints, policy can be applied to allow endpoints to
+communicate. The applicable subjects from the previous step will each
+contain a set of rules.
+
+Rules consist of a set of *classifiers* and a set of *actions*.
+Classifiers match against traffic between two endpoints. An example of a
+classifier would be something that matches against all TCP traffic on
+port 80, or one that matches against HTTP traffic containing a
+particular cookie. Actions are specific actions that need to be taken on
+the traffic before it reaches its destination. Actions could include
+tagging or encapsulating the traffic in some way, redirecting the
+traffic, or applying a `service function chain <#SFC>`__.
+
+Rules, subjects, and actions have an *order* parameter, where a lower
+order value means that a particular item will be applied first. All
+rules from a particular subject will be applied before the rules of any
+other subject, and all actions from a particular rule will be applied
+before the actions from another rule. If more than item has the same
+order parameter, ties are broken with a lexicographic ordering of their
+names, with earlier names having logically lower order.
+
+Matchers
+''''''''
+
+Matchers specify a set of labels (which include requirements,
+capabilities, conditions, and qualities) to match against. There are
+several kinds of matchers that operate similarly:
+
+- Quality matchers
+
+ used in target selectors during the contract selection phase. Quality
+ matchers provide a more advanced and flexible way to select contracts
+ compared to a named selector.
+
+- Requirement and capability matchers
+
+ used in clauses during the subject selection phase to match against
+ requirements and capabilities on EndpointGroups
+
+- Condition matchers
+
+ used in clauses during the subject selection phase to match against
+ conditions on endpoints
+
+A matcher is, at its heart, fairly simple. It will contain a list of
+label names, along with a *match type*. The match type can be either:
+
+- "all"
+
+ which means the matcher matches when all of its labels match
+
+- "any"
+
+ which means the matcher matches when any of its labels match,
+
+- "none"
+
+ which means the matcher matches when none of its labels match.
+
+Note a *match all* matcher can be made by matching against an empty set
+of labels with a match type of "all."
+
+Additionally each label to match can optionally include a relevant name
+field. For quality matchers, this is a target name. For capability and
+requirement matchers, this is a selector name. If the name field is
+specified, then the matcher will only match against targets or selectors
+with that name, rather than any targets or selectors.
+
+Inheritance
+^^^^^^^^^^^
+
+Some objects in the system include references to parents, from which
+they will inherit definitions. The graph of parent references must be
+loop free. When resolving names, the resolution system must detect loops
+and raise an exception. Objects that are part of these loops may be
+considered as though they are not defined at all. Generally, inheritance
+works by simply importing the objects in the parent into the child
+object. When there are objects with the same name in the child object,
+then the child object will override the parent object according to rules
+which are specific to the type of object. We’ll next explore the
+detailed rules for inheritance for each type of object
+
+**EndpointGroups**
+
+EndpointGroups will inherit all their selectors from their parent
+EndpointGroups. Selectors with the same names as selectors in the parent
+EndpointGroups will inherit their behavior as defined below.
+
+**Selectors**
+
+Selectors include provider named selectors, provider target selectors,
+consumer named selectors, and consumer target selectors. Selectors
+cannot themselves have parent selectors, but when selectors have the
+same name as a selector of the same type in the parent EndpointGroup,
+then they will inherit from and override the behavior of the selector in
+the parent EndpointGroup.
+
+**Named Selectors**
+
+Named selectors will add to the set of contract IDs that are selected by
+the parent named selector.
+
+**Target Selectors**
+
+A target selector in the child EndpointGroup with the same name as a
+target selector in the parent EndpointGroup will inherit quality
+matchers from the parent. If a quality matcher in the child has the same
+name as a quality matcher in the parent, then it will inherit as
+described below under Matchers.
+
+**Contracts**
+
+Contracts will inherit all their targets, clauses and subjects from
+their parent contracts. When any of these objects have the same name as
+in the parent contract, then the behavior will be as defined below.
+
+**Targets**
+
+Targets cannot themselves have a parent target, but it may inherit from
+targets with the same name as the target in a parent contract. Qualities
+in the target will be inherited from the parent. If a quality with the
+same name is defined in the child, then this does not have any semantic
+effect except if the quality has its inclusion-rule parameter set to
+"exclude." In this case, then the label should be ignored for the
+purpose of matching against this target.
+
+**Subjects**
+
+Subjects cannot themselves have a parent subject, but it may inherit
+from a subject with the same name as the subject in a parent contract.
+The order parameter in the child subject, if present, will override the
+order parameter in the parent subject. The rules in the parent subject
+will be added to the rules in the child subject. However, the rules will
+not override rules of the same name. Instead, all rules in the parent
+subject will be considered to run with a higher order than all rules in
+the child; that is all rules in the child will run before any rules in
+the parent. This has the effect of overriding any rules in the parent
+without the potentially-problematic semantics of merging the ordering.
+
+**Clauses**
+
+Clauses cannot themselves have a parent clause, but it may inherit from
+a clause with the same name as the clause in a parent contract. The list
+of subject references in the parent clause will be added to the list of
+subject references in the child clause. This is just a union operation.
+A subject reference that refers to a subject name in the parent contract
+might have that name overridden in the child contract. Each of the
+matchers in the clause are also inherited by the child clause. Matchers
+in the child of the same name and type as a matcher from the parent will
+inherit from and override the parent matcher. See below under Matchers
+for more information.
+
+**Matchers**
+
+Matchers include quality matchers, condition matchers, requirement
+matchers, and capability matchers. Matchers cannot themselves have
+parent matchers, but when there is a matcher of the same name and type
+in the parent object, then the matcher in the child object will inherit
+and override the behavior of the matcher in the parent object. The match
+type, if specified in the child, overrides the value specified in the
+parent. Labels are also inherited from the parent object. If there is a
+label with the same name in the child object, this does not have any
+semantic effect except if the label has its inclusion-rule parameter set
+to "exclude." In this case, then the label should be ignored for the
+purpose of matching. Otherwise, the label with the same name will
+completely override the label from the parent.
+
+Using the GBP UX interface
+--------------------------
+
+Overview
+~~~~~~~~
+
+These following components make up this application and are described in
+more detail in following sections:
+
+- Basic view
+
+- Governance view
+
+- Policy Expression view
+
+- Wizard view
+
+The **GBP** UX is access via:
+
+::
+
+ http://<odl controller>:8181/index.html
+
+Basic view
+~~~~~~~~~~
+
+Basic view contains 5 navigation buttons which switch user to the
+desired section of application:
+
+- Governance – switch to the Governance view (middle of graphic has the
+ same function)
+
+- Renderer configuration – switch to the Policy expression view with
+ Renderers section expanded
+
+- Policy expression – switch to the Policy expression view with Policy
+ section expanded
+
+- Operational constraints – placeholder for development in next release
+
+.. figure:: ./images/groupbasedpolicy/ui-1-basicview.png
+ :alt: Basic view
+
+ Basic view
+
+Governance view
+~~~~~~~~~~~~~~~
+
+Governance view consists from three columns.
+
+.. figure:: ./images/groupbasedpolicy/ui-2-governanceview.png
+ :alt: Governance view
+
+ Governance view
+
+**Governance view – Basic view – Left column**
+
+In the left column is Health section with Exception and Conflict buttons
+with no functionality yet. This is a placeholder for development in
+further releases.
+
+**Governance view – Basic view – Middle column**
+
+In the top half of this section is select box with list of tenants for
+select. Once the tenant is selected, all sub sections in application
+operate and display data with actual selected tenant.
+
+Below the select box are buttons which display Expressed or Delivered
+policy of Governance section. In the bottom half of this section is
+select box with list of renderers for select. There is currently only
+`OfOverlay <#OfOverlay>`__ renderer available.
+
+Below the select box is Renderer configuration button, which switch the
+app into the Policy expression view with Renderers section expanded for
+performing CRUD operations. Renderer state button display Renderer state
+view.
+
+**Governance view – Basic view – Right column**
+
+In the bottom part of the right section of Governance view is Home
+button which switch the app to the Basic view.
+
+In the top part is situated navigation menu with four main sections.
+
+Policy expression button expand/collapse sub menu with three main parts
+of Policy expression. By clicking on sub menu buttons, user will be
+switched into the Policy expressions view with appropriate section
+expanded for performing CRUD operations.
+
+Renderer configuration button switches user into the Policy expressions
+view.
+
+Governance button expand/collapse sub menu with four main parts of
+Governance section. Sub menu buttons of Governance section display
+appropriate section of Governance view.
+
+Operational constraints have no functionality yet, and is a placeholder
+for development in further releases.
+
+Below the menu is place for view info section which displays info about
+actual selected element from the topology (explained below).
+
+**Governance view – Expressed policy**
+
+In this view are displayed contracts with their consumed and provided
+EndpointGroups of actual selected tenant, which can be changed in select
+box in the upper left corner.
+
+By single-clicking on any contract or EPG, the data of actual selected
+element will be shown in the right column below the menu. A Manage
+button launches a display wizard window for managing configuration of
+items such as `Service Function Chaining <#SFC>`__.
+
+.. figure:: ./images/groupbasedpolicy/ui-3-governanceview-expressed.png
+ :alt: Expressed policy
+
+ Expressed policy
+
+**Governance view – Delivered policy** In this view are displayed
+subjects with their consumed and provided EndpointGroups of actual
+selected tenant, which can be changed in select box in the upper left
+corner.
+
+By single-clicking on any subject or EPG, the data of actual selected
+element will be shown in the right column below the menu.
+
+By double-click on subject the subject detail view will be displayed
+with subject’s rules of actual selected subject, which can be changed in
+select box in the upper left corner.
+
+By single-clicking on rule or subject, the data of actual selected
+element will be shown in the right column below the menu.
+
+By double-clicking on EPG in Delivered policy view, the EPG detail view
+will be displayed with EPG’s endpoints of actual selected EPG, which can
+be changed in select box in the upper left corner.
+
+By single-clicking on EPG or endpoint the data of actual selected
+element will be shown in the right column below the menu.
+
+.. figure:: ./images/groupbasedpolicy/ui-4-governanceview-delivered-0.png
+ :alt: Delivered policy
+
+ Delivered policy
+
+.. figure:: ./images/groupbasedpolicy/ui-4-governanceview-delivered-1-subject.png
+ :alt: Subject detail
+
+ Subject detail
+
+.. figure:: ./images/groupbasedpolicy/ui-4-governanceview-delivered-2-epg.png
+ :alt: EPG detail
+
+ EPG detail
+
+**Governance view – Renderer state**
+
+In this part are displayed Subject feature definition data with two main
+parts: Action definition and Classifier definition.
+
+By clicking on the down/right arrow in the circle is possible to
+expand/hide data of appropriate container or list. Next to the list node
+are displayed names of list’s elements where one is always selected and
+element’s data are shown (blue line under the name).
+
+By clicking on names of children nodes is possible to select desired
+node and node’s data will be displayed.
+
+.. figure:: ./images/groupbasedpolicy/ui-4-governanceview-renderer.png
+ :alt: Renderer state
+
+ Renderer state
+
+Policy expression view
+~~~~~~~~~~~~~~~~~~~~~~
+
+In the left part of this view is placed topology of actual selected
+elements with the buttons for switching between types of topology at the
+bottom.
+
+Right column of this view contains four parts. At the top of this column
+are displayed breadcrumbs with actual position in the application.
+
+Below the breadcrumbs is select box with list of tenants for select. In
+the middle part is situated navigation menu, which allows switch to the
+desired section for performing CRUD operations.
+
+At the bottom is quick navigation menu with Access Model Wizard button
+which display Wizard view, Home button which switch application to the
+Basic view and occasionally Back button, which switch application to the
+upper section.
+
+**Policy expression - Navigation menu**
+
+To open Policy expression, select Policy expression from the GBP Home
+screen.
+
+In the top of navigation box you can select the tenant from the tenants
+list to activate features addicted to selected tenant.
+
+In the right menu, by default, the Policy menu section is expanded.
+Subitems of this section are modules for CRUD (creating, reading,
+updating and deleting) of tenants, EndpointGroups, contracts, L2/L3
+objects.
+
+- Section Renderers contains CRUD forms for Classifiers and Actions.
+
+- Section Endpoints contains CRUD forms for Endpoint and L3 prefix
+ endpoint.
+
+.. figure:: ./images/groupbasedpolicy/ui-5-expresssion-1.png
+ :alt: Navigation menu
+
+ Navigation menu
+
+.. figure:: ./images/groupbasedpolicy/ui-5-expresssion-2.png
+ :alt: CRUD operations
+
+ CRUD operations
+
+**Policy expression - Types of topology**
+
+There are three different types of topology:
+
+- Configured topology - EndpointGroups and contracts between them from
+ CONFIG datastore
+
+- Operational topology - displays same information but is based on
+ operational data.
+
+- L2/L3 - displays relationships between L3Contexts, L2 Bridge domains,
+ L2 Flood domains and Subnets.
+
+.. figure:: ./images/groupbasedpolicy/ui-5-expresssion-3.png
+ :alt: L2/L3 Topology
+
+ L2/L3 Topology
+
+.. figure:: ./images/groupbasedpolicy/ui-5-expresssion-4.png
+ :alt: Config Topology
+
+ Config Topology
+
+**Policy expression - CRUD operations**
+
+In this part are described basic flows for viewing, adding, editing and
+deleting system elements like tenants, EndpointGroups etc.
+
+Tenants
+~~~~~~~
+
+To edit tenant objects click the Tenants button in the right menu. You
+can see the CRUD form containing tenants list and control buttons.
+
+To add new tenant, click the Add button This will display the form for
+adding a new tenant. After filling tenant attributes Name and
+Description click Save button. Saving of any object can be performed
+only if all the object attributes are filled correctly. If some
+attribute doesn’t have correct value, exclamation mark with mouse-over
+tooltip will be displayed next to the label for the attribute. After
+saving of tenant the form will be closed and the tenants list will be
+set to default value.
+
+To view an existing tenant, select the tenant from the select box
+Tenants list. The view form is read-only and can be closed by clicking
+cross mark in the top right of the form.
+
+To edit selected tenant, click the Edit button, which will display the
+edit form for selected tenant. After editing the Name and Description of
+selected tenant click the Save button to save selected tenant. After
+saving of tenant the edit form will be closed and the tenants list will
+be set to default value.
+
+To delete tenant select the tenant from the Tenants list and click
+Delete button.
+
+To return to the Policy expression click Back button on the bottom of
+window.
+
+**EndpointGroups**
+
+For managing EndpointGroups (EPG) the tenant from the top Tenants list
+must be selected.
+
+To add new EPG click Add button and after filling required attributes
+click Save button. After adding the EPG you can edit it and assign
+Consumer named selector or Provider named selector to it.
+
+To edit EPG click the Edit button after selecting the EPG from Group
+list.
+
+To add new Consumer named selector (CNS) click the Add button next to
+the Consumer named selectors list. While CNS editing you can set one or
+more contracts for current CNS pressing the Plus button and selecting
+the contract from the Contracts list. To remove the contract, click on
+the cross mark next to the contract. Added CNS can be viewed, edited or
+deleted by selecting from the Consumer named selectors list and clicking
+the Edit and Delete buttons like with the EPG or tenants.
+
+To add new Provider named selector (PNS) click the Add button next to
+the Provider named selectors list. While PNS editing you can set one or
+more contracts for current PNS pressing the Plus button and selecting
+the contract from the Contracts list. To remove the contract, click on
+the cross mark next to the contract. Added PNS can be viewed, edited or
+deleted by selecting from the Provider named selectors list and clicking
+the Edit and Delete buttons like with the EPG or tenants.
+
+To delete EPG, CNS or PNS select it in selectbox and click the Delete
+button next to the selectbox.
+
+**Contracts**
+
+For managing contracts the tenant from the top Tenants list must be
+selected.
+
+To add new Contract click Add button and after filling required fields
+click Save button.
+
+After adding the Contract user can edit it by selecting in the Contracts
+list and clicking Edit button.
+
+To add new Clause click Add button next to the Clause list while editing
+the contract. While editing the Clause after selecting clause from the
+Clause list user can assign clause subjects by clicking the Plus button
+next to the Clause subjects label. Adding and editing action must be
+submitted by pressing Save button. To manage Subjects you can use CRUD
+form like with the Clause list.
+
+**L2/L3**
+
+For managing L2/L3 the tenant from the top Tenants list must be
+selected.
+
+To add L3 Context click the Add button next to the L3 Context list
+,which will display the form for adding a new L3 Context. After filling
+L3 Context attributes click Save button. After saving of L3 Context,
+form will be closed and the L3 Context list will be set to default
+value.
+
+To view an existing L3 Context, select the L3 Context from the select
+box L3 Context list. The view form is read-only and can be closed by
+clicking cross mark in the top right of the form.
+
+If user wants to edit selected L3 Context, click the Edit button, which
+will display the edit form for selected L3 Context. After editing click
+the Save button to save selected L3 Context. After saving of L3 Context,
+the edit form will be closed and the L3 Context list will be set to
+default value.
+
+To delete L3 Context, select it from the L3 Context list and click
+Delete button.
+
+To add L2 Bridge Domain, click the Add button next to the L2 Bridge
+Domain list. This will display the form for adding a new L2 Bridge
+Domain. After filling L2 Bridge Domain attributes click Save button.
+After saving of L2 Bridge Domain, form will be closed and the L2 Bridge
+Domain list will be set to default value.
+
+To view an existing L2 Bridge Domain, select the L2 Bridge Domain from
+the select box L2 Bridge Domain list. The view form is read-only and can
+be closed by clicking cross mark in the top right of the form.
+
+If user wants to edit selected L2 Bridge Domain, click the Edit button,
+which will display the edit form for selected L2 Bridge Domain. After
+editing click the Save button to save selected L2 Bridge Domain. After
+saving of L2 Bridge Domain the edit form will be closed and the L2
+Bridge Domain list will be set to default value.
+
+To delete L2 Bridge Domain select it from the L2 Bridge Domain list and
+click Delete button.
+
+To add L3 Flood Domain, click the Add button next to the L3 Flood Domain
+list. This will display the form for adding a new L3 Flood Domain. After
+filling L3 Flood Domain attributes click Save button. After saving of L3
+Flood Domain, form will be closed and the L3 Flood Domain list will be
+set to default value.
+
+To view an existing L3 Flood Domain, select the L3 Flood Domain from the
+select box L3 Flood Domain list. The view form is read-only and can be
+closed by clicking cross mark in the top right of the form.
+
+If user wants to edit selected L3 Flood Domain, click the Edit button,
+which will display the edit form for selected L3 Flood Domain. After
+editing click the Save button to save selected L3 Flood Domain. After
+saving of L3 Flood Domain the edit form will be closed and the L3 Flood
+Domain list will be set to default value.
+
+To delete L3 Flood Domain select it from the L3 Flood Domain list and
+click Delete button.
+
+To add Subnet click the Add button next to the Subnet list. This will
+display the form for adding a new Subnet. After filling Subnet
+attributes click Save button. After saving of Subnet, form will be
+closed and the Subnet list will be set to default value.
+
+To view an existing Subnet, select the Subnet from the select box Subnet
+list. The view form is read-only and can be closed by clicking cross
+mark in the top right of the form.
+
+If user wants to edit selected Subnet, click the Edit button, which will
+display the edit form for selected Subnet. After editing click the Save
+button to save selected Subnet. After saving of Subnet the edit form
+will be closed and the Subnet list will be set to default value.
+
+To delete Subnet select it from the Subnet list and click Delete button.
+
+**Classifiers**
+
+To add Classifier, click the Add button next to the Classifier list.
+This will display the form for adding a new Classifier. After filling
+Classifier attributes click Save button. After saving of Classifier,
+form will be closed and the Classifier list will be set to default
+value.
+
+To view an existing Classifier, select the Classifier from the select
+box Classifier list. The view form is read-only and can be closed by
+clicking cross mark in the top right of the form.
+
+If you want to edit selected Classifier, click the Edit button, which
+will display the edit form for selected Classifier. After editing click
+the Save button to save selected Classifier. After saving of Classifier
+the edit form will be closed and the Classifier list will be set to
+default value.
+
+To delete Classifier select it from the Classifier list and click Delete
+button.
+
+**Actions**
+
+To add Action, click the Add button next to the Action list. This will
+display the form for adding a new Action. After filling Action
+attributes click Save button. After saving of Action, form will be
+closed and the Action list will be set to default value.
+
+To view an existing Action, select the Action from the select box Action
+list. The view form is read-only and can be closed by clicking cross
+mark in the top right of the form.
+
+If user wants to edit selected Action, click the Edit button, which will
+display the edit form for selected Action. After editing click the Save
+button to save selected Action. After saving of Action the edit form
+will be closed and the Action list will be set to default value.
+
+To delete Action select it from the Action list and click Delete button.
+
+**Endpoint**
+
+To add Endpoint, click the Add button next to the Endpoint list. This
+will display the form for adding a new Endpoint. To add EndpointGroup
+assignment click the Plus button next to the label EndpointGroups. To
+add Condition click Plus button next to the label Condition. To add L3
+Address click the Plus button next to the L3 Addresses label. After
+filling Endpoint attributes click Save button. After saving of Endpoint,
+form will be closed and the Endpoint list will be set to default value.
+
+To view an existing Endpoint just, the Endpoint from the select box
+Endpoint list. The view form is read-only and can be closed by clicking
+cross mark in the top right of the form.
+
+If you want to edit selected Endpoint, click the Edit button, which will
+display the edit form for selected Endpoint. After editing click the
+Save button to save selected Endpoint. After saving of Endpoint the edit
+form will be closed and the Endpoint list will be set to default value.
+
+To delete Endpoint select it from the Endpoint list and click Delete
+button.
+
+**L3 prefix endpoint**
+
+To add L3 prefix endpoint, click the Add button next to the L3 prefix
+endpoint list. This will display the form for adding a new Endpoint. To
+add EndpointGroup assignment, click the Plus button next to the label
+EndpointGroups. To add Condition, click Plus button next to the label
+Condition. To add L2 gateway click the Plus button next to the L2
+gateways label. To add L3 gateway, click the Plus button next to the L3
+gateways label. After filling L3 prefix endpoint attributes click Save
+button. After saving of L3 prefix endpoint, form will be closed and the
+Endpoint list will be set to default value.
+
+To view an existing L3 prefix endpoint, select the Endpoint from the
+select box L3 prefix endpoint list. The view form is read-only and can
+be closed by clicking cross mark in the top right of the form.
+
+If you want to edit selected L3 prefix endpoint, click the Edit button,
+which will display the edit form for selected L3 prefix endpoint. After
+editing click the Save button to save selected L3 prefix endpoint. After
+saving of Endpoint the edit form will be closed and the Endpoint list
+will be set to default value.
+
+To delete Endpoint select it from the L3 prefix endpoint list and click
+Delete button.
+
+Wizard
+~~~~~~
+
+Wizard provides quick method to send basic data to controller necessary
+for basic usage of GBP application. It is useful in the case that there
+aren’t any data in controller. In the first tab is form for create
+tenant. The second tab is for CRUD operations with contracts and their
+sub elements such as subjects, rules, clauses, action refs and
+classifier refs. The last tab is for CRUD operations with EndpointGroups
+and their CNS and PNS. Created structure of data is possible to send by
+clicking on Submit button.
+
+.. figure:: ./images/groupbasedpolicy/ui-6-wizard.png
+ :alt: Wizard
+
+ Wizard
+
+Using the GBP API
+-----------------
+
+Please see:
+
+- `Using the GBP OpenFlow Overlay (OfOverlay) renderer <#OfOverlay>`__
+
+- `Policy Resolution <#policyresolution>`__
+
+- `Forwarding Model <#forwarding>`__
+
+- `the **GBP** demo and development environments for tips <#demo>`__
+
+It is recommended to use either:
+
+- `Neutron mapper <#Neutron>`__
+
+- `the UX <#UX>`__
+
+If the REST API must be used, and the above resources are not
+sufficient:
+
+- feature:install odl-dlux-yangui
+
+- browse to:
+ `http://<odl-controller>:8181/index.html <http://<odl-controller>:8181/index.html>`__
+ and select YangUI from the left menu.
+
+to explore the various **GBP** REST options
+
+Using OpenStack with GBP
+------------------------
+
+Overview
+~~~~~~~~
+
+This section is for Application Developers and Network Administrators
+who are looking to integrate Group Based Policy with OpenStack.
+
+To enable the **GBP** Neutron Mapper feature, at the Karaf console:
+
+::
+
+ feature:install odl-groupbasedpolicy-neutronmapper
+
+Neutron Mapper has the following dependencies that are automatically
+loaded:
+
+::
+
+ odl-neutron-service
+
+Neutron Northbound implementing REST API used by OpenStack
+
+::
+
+ odl-groupbasedpolicy-base
+
+Base **GBP** feature set, such as policy resolution, data model etc.
+
+::
+
+ odl-groupbasedpolicy-ofoverlay
+
+REST calls from OpenStack Neutron are by the Neutron NorthBound project.
+
+**GBP** provides the implementation of the `Neutron V2.0
+API <http://developer.openstack.org/api-ref-networking-v2.html>`__.
+
+Features
+~~~~~~~~
+
+List of supported Neutron entities:
+
+- Port
+
+- Network
+
+ - Standard Internal
+
+ - External provider L2/L3 network
+
+- Subnet
+
+- Security-groups
+
+- Routers
+
+ - Distributed functionality with local routing per compute
+
+ - External gateway access per compute node (dedicated port required)
+
+ - Multiple routers per tenant
+
+- FloatingIP NAT
+
+- IPv4/IPv6 support
+
+The mapping of Neutron entities to **GBP** entities is as follows:
+
+**Neutron Port**
+
+.. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-port.png
+ :alt: Neutron Port
+
+ Neutron Port
+
+The Neutron port is mapped to an endpoint.
+
+The current implementation supports one IP address per Neutron port.
+
+An endpoint and L3-endpoint belong to multiple EndpointGroups if the
+Neutron port is in multiple Neutron Security Groups.
+
+The key for endpoint is L2-bridge-domain obtained as the parent of
+L2-flood-domain representing Neutron network. The MAC address is from
+the Neutron port. An L3-endpoint is created based on L3-context (the
+parent of the L2-bridge-domain) and IP address of Neutron Port.
+
+**Neutron Network**
+
+.. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-network.png
+ :alt: Neutron Network
+
+ Neutron Network
+
+A Neutron network has the following characteristics:
+
+- defines a broadcast domain
+
+- defines a L2 transmission domain
+
+- defines a L2 name space.
+
+To represent this, a Neutron Network is mapped to multiple **GBP**
+entities. The first mapping is to an L2 flood-domain to reflect that the
+Neutron network is one flooding or broadcast domain. An L2-bridge-domain
+is then associated as the parent of L2 flood-domain. This reflects both
+the L2 transmission domain as well as the L2 addressing namespace.
+
+The third mapping is to L3-context, which represents the distinct L3
+address space. The L3-context is the parent of L2-bridge-domain.
+
+**Neutron Subnet**
+
+.. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet.png
+ :alt: Neutron Subnet
+
+ Neutron Subnet
+
+Neutron subnet is associated with a Neutron network. The Neutron subnet
+is mapped to a **GBP** subnet where the parent of the subnet is
+L2-flood-domain representing the Neutron network.
+
+**Neutron Security Group**
+
+.. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-securitygroup.png
+ :alt: Neutron Security Group and Rules
+
+ Neutron Security Group and Rules
+
+**GBP** entity representing Neutron security-group is EndpointGroup.
+
+**Infrastructure EndpointGroups**
+
+Neutron-mapper automatically creates EndpointGroups to manage key
+infrastructure items such as:
+
+- DHCP EndpointGroup - contains endpoints representing Neutron DHCP
+ ports
+
+- Router EndpointGroup - contains endpoints representing Neutron router
+ interfaces
+
+- External EndpointGroup - holds L3-endpoints representing Neutron
+ router gateway ports, also associated with FloatingIP ports.
+
+**Neutron Security Group Rules**
+
+This is the most involved amongst all the mappings because Neutron
+security-group-rules are mapped to contracts with clauses, subjects,
+rules, action-refs, classifier-refs, etc. Contracts are used between
+EndpointGroups representing Neutron Security Groups. For simplification
+it is important to note that Neutron security-group-rules are similar to
+a **GBP** rule containing:
+
+- classifier with direction
+
+- action of **allow**.
+
+**Neutron Routers**
+
+.. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-router.png
+ :alt: Neutron Router
+
+ Neutron Router
+
+Neutron router is represented as a L3-context. This treats a router as a
+Layer3 namespace, and hence every network attached to it a part of that
+Layer3 namespace.
+
+This allows for multiple routers per tenant with complete isolation.
+
+The mapping of the router to an endpoint represents the router’s
+interface or gateway port.
+
+The mapping to an EndpointGroup represents the internal infrastructure
+EndpointGroups created by the **GBP** Neutron Mapper
+
+When a Neutron router interface is attached to a network/subnet, that
+network/subnet and its associated endpoints or Neutron Ports are
+seamlessly added to the namespace.
+
+**Neutron FloatingIP**
+
+When associated with a Neutron Port, this leverages the
+`OfOverlay <#OfOverlay>`__ renderer’s NAT capabilities.
+
+A dedicated *external* interface on each Nova compute host allows for
+disitributed external access. Each Nova instance associated with a
+FloatingIP address can access the external network directly without
+having to route via the Neutron controller, or having to enable any form
+of Neutron distributed routing functionality.
+
+Assuming the gateway provisioned in the Neutron Subnet command for the
+external network is reachable, the combination of **GBP** Neutron Mapper
+and `OfOverlay renderer <#OfOverlay>`__ will automatically ARP for this
+default gateway, requiring no user intervention.
+
+**Troubleshooting within GBP**
+
+Logging level for the mapping functionality can be set for package
+org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling
+TRACE logging level on Karaf console:
+
+::
+
+ log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
+
+**Neutron mapping example**
+
+As an example for mapping can be used creation of Neutron network,
+subnet and port. When a Neutron network is created 3 **GBP** entities
+are created: l2-flood-domain, l2-bridge-domain, l3-context.
+
+.. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-network-example.png
+ :alt: Neutron network mapping
+
+ Neutron network mapping
+
+After an subnet is created in the network mapping looks like this.
+
+.. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet-example.png
+ :alt: Neutron subnet mapping
+
+ Neutron subnet mapping
+
+If an Neutron port is created in the subnet an endpoint and l3-endpoint
+are created. The endpoint has key composed from l2-bridge-domain and MAC
+address from Neutron port. A key of l3-endpoint is compesed from
+l3-context and IP address. The network containment of endpoint and
+l3-endpoint points to the subnet.
+
+.. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-port-example.png
+ :alt: Neutron port mapping
+
+ Neutron port mapping
+
+Configuring GBP Neutron
+~~~~~~~~~~~~~~~~~~~~~~~
+
+No intervention passed initial OpenStack setup is required by the user.
+
+More information about configuration can be found in our DevStack demo
+environment on the `**GBP**
+wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`__.
+
+Administering or Managing GBP Neutron
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For consistencies sake, all provisioning should be performed via the
+Neutron API. (CLI or Horizon).
+
+The mapped policies can be augmented via the **GBP** `UX <#UX>`__, to:
+
+- Enable `Service Function Chaining <#SFC>`__
+
+- Add endpoints from outside of Neutron i.e. VMs/containers not
+ provisioned in OpenStack
+
+- Augment policies/contracts derived from Security Group Rules
+
+- Overlay additional contracts or groupings
+
+Tutorials
+~~~~~~~~~
+
+A DevStack demo environment can be found on the `**GBP**
+wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`__.
+
+Using the GBP OpenFlow Overlay (OfOverlay) renderer
+---------------------------------------------------
+
+Overview
+~~~~~~~~
+
+The OpenFlow Overlay (OfOverlay) feature enables the OpenFlow Overlay
+renderer, which creates a network virtualization solution across nodes
+that host Open vSwitch software switches.
+
+Installing and Pre-requisites
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From the Karaf console in OpenDaylight:
+
+::
+
+ feature:install odl-groupbasedpolicy-ofoverlay
+
+This renderer is designed to work with OpenVSwitch (OVS) 2.1+ (although
+2.3 is strongly recommended) and OpenFlow 1.3.
+
+When used in conjunction with the `Neutron Mapper feature <#Neutron>`__
+no extra OfOverlay specific setup is required.
+
+When this feature is loaded "standalone", the user is required to
+configure infrastructure, such as
+
+- instantiating OVS bridges,
+
+- attaching hosts to the bridges,
+
+- and creating the VXLAN/VXLAN-GPE tunnel ports on the bridges.
+
+The **GBP** OfOverlay renderer also supports a table offset option, to
+offset the pipeline post-table 0. The value of table offset is stored in
+the config datastore and it may be rewritten at runtime.
+
+::
+
+ PUT http://{{controllerIp}}:8181/restconf/config/ofoverlay:of-overlay-config
+ {
+ "of-overlay-config": {
+ "gbp-ofoverlay-table-offset": 6
+ }
+ }
+
+The default value is set by changing:
+<gbp-ofoverlay-table-offset>0</gbp-ofoverlay-table-offset>
+
+in file:
+distribution-karaf/target/assembly/etc/opendaylight/karaf/15-groupbasedpolicy-ofoverlay.xml
+
+To avoid overwriting runtime changes, the default value is used only
+when the OfOverlay renderer starts and no other value has been written
+before.
+
+OpenFlow Overlay Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These are the primary components of **GBP**. The OfOverlay components
+are highlighted in red.
+
+.. figure:: ./images/groupbasedpolicy/ofoverlay-1-components.png
+ :alt: OfOverlay within **GBP**
+
+ OfOverlay within **GBP**
+
+In terms of the inner components of the **GBP** OfOverlay renderer:
+
+.. figure:: ./images/groupbasedpolicy/ofoverlay-2-components.png
+ :alt: OfOverlay expanded view:
+
+ OfOverlay expanded view:
+
+**OfOverlay Renderer**
+
+Launches components below:
+
+**Policy Resolver**
+
+Policy resolution is completely domain independent, and the OfOverlay
+leverages process policy information internally. See `Policy Resolution
+process <#policyresolution>`__.
+
+It listens to inputs to the *Tenants* configuration datastore, validates
+tenant input, then writes this to the Tenants operational datastore.
+
+From there an internal notification is generated to the PolicyManager.
+
+In the next release, this will be moving to a non-renderer specific
+location.
+
+**Endpoint Manager**
+
+The endpoint repository operates in **orchestrated** mode. This means
+the user is responsible for the provisioning of endpoints via:
+
+- `UX/GUI <#UX>`__
+
+- REST API
+
+ **Note**
+
+ When using the `Neutron mapper <#Neutron>`__ feature, everything is
+ managed transparently via Neutron.
+
+The Endpoint Manager is responsible for listening to Endpoint repository
+updates and notifying the Switch Manager when a valid Endpoint has been
+registered.
+
+It also supplies utility functions to the flow pipeline process.
+
+**Switch Manager**
+
+The Switch Manager is purely a state manager.
+
+Switches are in one of 3 states:
+
+- DISCONNECTED
+
+- PREPARING
+
+- READY
+
+**Ready** is denoted by a connected switch:
+
+- having a tunnel interface
+
+- having at least one endpoint connected.
+
+In this way **GBP** is not writing to switches it has no business to.
+
+**Preparing** simply means the switch has a controller connection but is
+missing one of the above *complete and necessary* conditions
+
+**Disconnected** means a previously connected switch is no longer
+present in the Inventory operational datastore.
+
+.. figure:: ./images/groupbasedpolicy/ofoverlay-3-flowpipeline.png
+ :alt: OfOverlay Flow Pipeline
+
+ OfOverlay Flow Pipeline
+
+The OfOverlay leverages Nicira registers as follows:
+
+- REG0 = Source EndpointGroup + Tenant ordinal
+
+- REG1 = Source Conditions + Tenant ordinal
+
+- REG2 = Destination EndpointGroup + Tenant ordinal
+
+- REG3 = Destination Conditions + Tenant ordinal
+
+- REG4 = Bridge Domain + Tenant ordinal
+
+- REG5 = Flood Domain + Tenant ordinal
+
+- REG6 = Layer 3 Context + Tenant ordinal
+
+**Port Security**
+
+Table 0 of the OpenFlow pipeline. Responsible for ensuring that only
+valid connections can send packets into the pipeline:
+
+::
+
+ cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
+ cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
+ cookie=0x0, <snip> , priority=121,arp,in_port=5,dl_src=fa:16:3e:d5:b9:8d,arp_spa=10.1.1.3 actions=goto_table:2
+ cookie=0x0, <snip> , priority=120,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_src=10.1.1.3 actions=goto_table:2
+ cookie=0x0, <snip> , priority=115,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_dst=255.255.255.255 actions=goto_table:2
+ cookie=0x0, <snip> , priority=112,ipv6 actions=drop
+ cookie=0x0, <snip> , priority=111, ip actions=drop
+ cookie=0x0, <snip> , priority=110,arp actions=drop
+ cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
+ cookie=0x0, <snip> , priority=1 actions=drop
+
+Ingress from tunnel interface, go to Table *Source Mapper*:
+
+::
+
+ cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
+
+Ingress from outside, goto Table *Ingress NAT Mapper*:
+
+::
+
+ cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
+
+ARP from Endpoint, go to Table *Source Mapper*:
+
+::
+
+ cookie=0x0, <snip> , priority=121,arp,in_port=5,dl_src=fa:16:3e:d5:b9:8d,arp_spa=10.1.1.3 actions=goto_table:2
+
+IPv4 from Endpoint, go to Table *Source Mapper*:
+
+::
+
+ cookie=0x0, <snip> , priority=120,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_src=10.1.1.3 actions=goto_table:2
+
+DHCP DORA from Endpoint, go to Table *Source Mapper*:
+
+::
+
+ cookie=0x0, <snip> , priority=115,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_dst=255.255.255.255 actions=goto_table:2
+
+Series of DROP tables with priority set to capture any non-specific
+traffic that should have matched above:
+
+::
+
+ cookie=0x0, <snip> , priority=112,ipv6 actions=drop
+ cookie=0x0, <snip> , priority=111, ip actions=drop
+ cookie=0x0, <snip> , priority=110,arp actions=drop
+
+"L2" catch all traffic not identified above:
+
+::
+
+ cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
+
+Drop Flow:
+
+::
+
+ cookie=0x0, <snip> , priority=1 actions=drop
+
+**Ingress NAT Mapper**
+
+Table `*offset* <#offset>`__\ +1.
+
+ARP responder for external NAT address:
+
+::
+
+ cookie=0x0, <snip> , priority=150,arp,arp_tpa=192.168.111.51,arp_op=1 actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],set_field:fa:16:3e:58:c3:dd->eth_src,load:0x2->NXM_OF_ARP_OP[],move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],load:0xfa163e58c3dd->NXM_NX_ARP_SHA[],move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],load:0xc0a86f33->NXM_OF_ARP_SPA[],IN_PORT
+
+Translate from Outside to Inside and perform same functions as
+SourceMapper.
+
+::
+
+ cookie=0x0, <snip> , priority=100,ip,nw_dst=192.168.111.51 actions=set_field:10.1.1.2->ip_dst,set_field:fa:16:3e:58:c3:dd->eth_dst,load:0x2->NXM_NX_REG0[],load:0x1->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],load:0x3->NXM_NX_TUN_ID[0..31],goto_table:3
+
+**Source Mapper**
+
+Table `*offset* <#offset>`__\ +2.
+
+Determines based on characteristics from the ingress port, which:
+
+- EndpointGroup(s) it belongs to
+
+- Forwarding context
+
+- Tunnel VNID ordinal
+
+Establishes tunnels at valid destination switches for ingress.
+
+Ingress Tunnel established at remote node with VNID Ordinal that maps to
+Source EPG, Forwarding Context etc:
+
+::
+
+ cookie=0x0, <snip>, priority=150,tun_id=0xd,in_port=3 actions=load:0xc->NXM_NX_REG0[],load:0xffffff->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],goto_table:3
+
+Maps endpoint to Source EPG, Forwarding Context based on ingress port,
+and MAC:
+
+::
+
+ cookie=0x0, <snip> , priority=100,in_port=5,dl_src=fa:16:3e:b4:b4:b1 actions=load:0xc->NXM_NX_REG0[],load:0x1->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],load:0xd->NXM_NX_TUN_ID[0..31],goto_table:3
+
+Generic drop:
+
+::
+
+ cookie=0x0, duration=197.622s, table=2, n_packets=0, n_bytes=0, priority=1 actions=drop
+
+**Destination Mapper**
+
+Table `*offset* <#offset>`__\ +3.
+
+Determines based on characteristics of the endpoint:
+
+- EndpointGroup(s) it belongs to
+
+- Forwarding context
+
+- Tunnel Destination value
+
+Manages routing based on valid ingress nodes ARP’ing for their default
+gateway, and matches on either gateway MAC or destination endpoint MAC.
+
+ARP for default gateway for the 10.1.1.0/24 subnet:
+
+::
+
+ cookie=0x0, <snip> , priority=150,arp,reg6=0x7,arp_tpa=10.1.1.1,arp_op=1 actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],set_field:fa:16:3e:28:4c:82->eth_src,load:0x2->NXM_OF_ARP_OP[],move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],load:0xfa163e284c82->NXM_NX_ARP_SHA[],move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],load:0xa010101->NXM_OF_ARP_SPA[],IN_PORT
+
+Broadcast traffic destined for GroupTable:
+
+::
+
+ cookie=0x0, <snip> , priority=140,reg5=0x5,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00 actions=load:0x5->NXM_NX_TUN_ID[0..31],group:5
+
+Layer3 destination matching flows, where priority=100+masklength. Since
+**GBP** now support L3Prefix endpoint, we can set default routes etc:
+
+::
+
+ cookie=0x0, <snip>, priority=132,ip,reg6=0x7,dl_dst=fa:16:3e:b4:b4:b1,nw_dst=10.1.1.3 actions=load:0xc->NXM_NX_REG2[],load:0x1->NXM_NX_REG3[],load:0x5->NXM_NX_REG7[],set_field:fa:16:3e:b4:b4:b1->eth_dst,dec_ttl,goto_table:4
+
+Layer2 destination matching flows, designed to be caught only after last
+IP flow (lowest priority IP flow is 100):
+
+::
+
+ cookie=0x0, duration=323.203s, table=3, n_packets=4, n_bytes=168, priority=50,reg4=0x4,dl_dst=fa:16:3e:58:c3:dd actions=load:0x2->NXM_NX_REG2[],load:0x1->NXM_NX_REG3[],load:0x2->NXM_NX_REG7[],goto_table:4
+
+General drop flow: cookie=0x0, duration=323.207s, table=3, n\_packets=6,
+n\_bytes=588, priority=1 actions=drop
+
+**Policy Enforcer**
+
+Table `*offset* <#offset>`__\ +4.
+
+Once the Source and Destination EndpointGroups are assigned, policy is
+enforced based on resolved rules.
+
+In the case of `Service Function Chaining <#SFC>`__, the encapsulation
+and destination for traffic destined to a chain, is discovered and
+enforced.
+
+Policy flow, allowing IP traffic between EndpointGroups:
+
+::
+
+ cookie=0x0, <snip> , priority=64998,ip,reg0=0x8,reg1=0x1,reg2=0xc,reg3=0x1 actions=goto_table:5
+
+**Egress NAT Mapper**
+
+Table `*offset* <#offset>`__\ +5.
+
+Performs NAT function before Egressing OVS instance to the underlay
+network.
+
+Inside to Outside NAT translation before sending to underlay:
+
+::
+
+ cookie=0x0, <snip> , priority=100,ip,reg6=0x7,nw_src=10.1.1.2 actions=set_field:192.168.111.51->ip_src,goto_table:6
+
+**External Mapper**
+
+Table `*offset* <#offset>`__\ +6.
+
+Manages post-policy enforcement for endpoint specific destination
+effects. Specifically for `Service Function Chaining <#SFC>`__, which is
+why we can support both symmetric and asymmetric chains and distributed
+ingress/egress classification.
+
+Generic allow:
+
+::
+
+ cookie=0x0, <snip>, priority=100 actions=output:NXM_NX_REG7[]
+
+Configuring OpenFlow Overlay via REST
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ **Note**
+
+ Please see the `UX <#UX>`__ section on how to configure **GBP** via
+ the GUI.
+
+**Endpoint**
+
+::
+
+ POST http://{{controllerIp}}:8181/restconf/operations/endpoint:register-endpoint
+ {
+ "input": {
+ "endpoint-group": "<epg0>",
+ "endpoint-groups" : ["<epg1>","<epg2>"],
+ "network-containment" : "<fowarding-model-context1>",
+ "l2-context": "<bridge-domain1>",
+ "mac-address": "<mac1>",
+ "l3-address": [
+ {
+ "ip-address": "<ipaddress1>",
+ "l3-context": "<l3_context1>"
+ }
+ ],
+ "*ofoverlay:port-name*": "<ovs port name>",
+ "tenant": "<tenant1>"
+ }
+ }
+
+ **Note**
+
+ The usage of "port-name" preceded by "ofoverlay". In OpenDaylight,
+ base datastore objects can be *augmented*. In **GBP**, the base
+ endpoint model has no renderer specifics, hence can be leveraged
+ across multiple renderers.
+
+**OVS Augmentations to Inventory**
+
+::
+
+ PUT http://{{controllerIp}}:8181/restconf/config/opendaylight-inventory:nodes/
+ {
+ "opendaylight-inventory:nodes": {
+ "node": [
+ {
+ "id": "openflow:123456",
+ "ofoverlay:tunnel": [
+ {
+ "tunnel-type": "overlay:tunnel-type-vxlan",
+ "ip": "<ip_address_of_ovs>",
+ "port": 4789,
+ "node-connector-id": "openflow:123456:1"
+ }
+ ]
+ },
+ {
+ "id": "openflow:654321",
+ "ofoverlay:tunnel": [
+ {
+ "tunnel-type": "overlay:tunnel-type-vxlan",
+ "ip": "<ip_address_of_ovs>",
+ "port": 4789,
+ "node-connector-id": "openflow:654321:1"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+**Tenants** see `Policy Resolution <#policyresolution>`__ and
+`Forwarding Model <#forwarding>`__ for details:
+
+::
+
+ {
+ "policy:tenant": {
+ "contract": [
+ {
+ "clause": [
+ {
+ "name": "allow-http-clause",
+ "subject-refs": [
+ "allow-http-subject",
+ "allow-icmp-subject"
+ ]
+ }
+ ],
+ "id": "<id>",
+ "subject": [
+ {
+ "name": "allow-http-subject",
+ "rule": [
+ {
+ "classifier-ref": [
+ {
+ "direction": "in",
+ "name": "http-dest"
+ },
+ {
+ "direction": "out",
+ "name": "http-src"
+ }
+ ],
+ "action-ref": [
+ {
+ "name": "allow1",
+ "order": 0
+ }
+ ],
+ "name": "allow-http-rule"
+ }
+ ]
+ },
+ {
+ "name": "allow-icmp-subject",
+ "rule": [
+ {
+ "classifier-ref": [
+ {
+ "name": "icmp"
+ }
+ ],
+ "action-ref": [
+ {
+ "name": "allow1",
+ "order": 0
+ }
+ ],
+ "name": "allow-icmp-rule"
+ }
+ ]
+ }
+ ]
+ }
+ ],
+ "endpoint-group": [
+ {
+ "consumer-named-selector": [
+ {
+ "contract": [
+ "<id>"
+ ],
+ "name": "<name>"
+ }
+ ],
+ "id": "<id>",
+ "provider-named-selector": []
+ },
+ {
+ "consumer-named-selector": [],
+ "id": "<id>",
+ "provider-named-selector": [
+ {
+ "contract": [
+ "<id>"
+ ],
+ "name": "<name>"
+ }
+ ]
+ }
+ ],
+ "id": "<id>",
+ "l2-bridge-domain": [
+ {
+ "id": "<id>",
+ "parent": "<id>"
+ }
+ ],
+ "l2-flood-domain": [
+ {
+ "id": "<id>",
+ "parent": "<id>"
+ },
+ {
+ "id": "<id>",
+ "parent": "<id>"
+ }
+ ],
+ "l3-context": [
+ {
+ "id": "<id>"
+ }
+ ],
+ "name": "GBPPOC",
+ "subject-feature-instances": {
+ "classifier-instance": [
+ {
+ "classifier-definition-id": "<id>",
+ "name": "http-dest",
+ "parameter-value": [
+ {
+ "int-value": "6",
+ "name": "proto"
+ },
+ {
+ "int-value": "80",
+ "name": "destport"
+ }
+ ]
+ },
+ {
+ "classifier-definition-id": "<id>",
+ "name": "http-src",
+ "parameter-value": [
+ {
+ "int-value": "6",
+ "name": "proto"
+ },
+ {
+ "int-value": "80",
+ "name": "sourceport"
+ }
+ ]
+ },
+ {
+ "classifier-definition-id": "<id>",
+ "name": "icmp",
+ "parameter-value": [
+ {
+ "int-value": "1",
+ "name": "proto"
+ }
+ ]
+ }
+ ],
+ "action-instance": [
+ {
+ "name": "allow1",
+ "action-definition-id": "<id>"
+ }
+ ]
+ },
+ "subnet": [
+ {
+ "id": "<id>",
+ "ip-prefix": "<ip_prefix>",
+ "parent": "<id>",
+ "virtual-router-ip": "<ip address>"
+ },
+ {
+ "id": "<id>",
+ "ip-prefix": "<ip prefix>",
+ "parent": "<id>",
+ "virtual-router-ip": "<ip address>"
+ }
+ ]
+ }
+ }
+
+Tutorials
+~~~~~~~~~
+
+Comprehensive tutorials, along with a demonstration environment
+leveraging Vagrant can be found on the `**GBP**
+wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`__
+
+Using the GBP eBPF IO Visor Agent renderer
+------------------------------------------
+
+Overview
+~~~~~~~~
+
+The IO Visor renderer feature enables container endpoints (e.g. Docker,
+LXC) to leverage GBP policies.
+
+The renderer interacts with a IO Visor module from the Linux Foundation
+IO Visor project.
+
+Installing and Pre-requisites
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From the Karaf console in OpenDaylight:
+
+::
+
+ feature:install odl-groupbasedpolicy-iovisor odl-restconf
+
+Installation details, usage, and other information for the IO Visor GBP
+module can be found here: `**IO Visor** github repo for IO
+Modules <https://github.com/iovisor/iomodules>`__
+
+Using the GBP FaaS renderer
+---------------------------
+
+Overview
+~~~~~~~~
+
+The FaaS renderer feature enables leveraging the FaaS project as a GBP
+renderer.
+
+Installing and Pre-requisites
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From the Karaf console in OpenDaylight:
+
+::
+
+ feature:install odl-groupbasedpolicy-faas
+
+More information about FaaS can be found here:
+https://wiki.opendaylight.org/view/FaaS:GBPIntegration
+
+Using Service Function Chaining (SFC) with GBP Neutron Mapper and OfOverlay
+---------------------------------------------------------------------------
+
+Overview
+~~~~~~~~
+
+Please refer to the Service Function Chaining project for specifics on
+SFC provisioning and theory.
+
+**GBP** allows for the use of a chain, by name, in policy.
+
+This takes the form of an *action* in **GBP**.
+
+Using the `**GBP** demo and development environment <#demo>`__ as an
+example:
+
+.. figure:: ./images/groupbasedpolicy/sfc-1-topology.png
+ :alt: GBP and SFC integration environment
+
+ GBP and SFC integration environment
+
+In the topology above, a symmetrical chain between H35\_2 and H36\_3
+could take path:
+
+H35\_2 to sw1 to sff1 to sf1 to sff1 to sff2 to sf2 to sff2 to sw6 to
+H36\_3
+
+If symmetric chaining was desired, the return path is:
+
+.. figure:: ./images/groupbasedpolicy/sfc-2-symmetric.png
+ :alt: GBP and SFC symmetric chain environment
+
+ GBP and SFC symmetric chain environment
+
+If asymmetric chaining was desired, the return path could be direct, or
+an **entirely different chain**.
+
+.. figure:: ./images/groupbasedpolicy/sfc-3-asymmetric.png
+ :alt: GBP and SFC assymmetric chain environment
+
+ GBP and SFC assymmetric chain environment
+
+All these scenarios are supported by the integration.
+
+In the **Subject Feature Instance** section of the tenant config, we
+define the instances of the classifier definitions for ICMP and HTTP:
+
+::
+
+ "subject-feature-instances": {
+ "classifier-instance": [
+ {
+ "name": "icmp",
+ "parameter-value": [
+ {
+ "name": "proto",
+ "int-value": 1
+ }
+ ]
+ },
+ {
+ "name": "http-dest",
+ "parameter-value": [
+ {
+ "int-value": "6",
+ "name": "proto"
+ },
+ {
+ "int-value": "80",
+ "name": "destport"
+ }
+ ]
+ },
+ {
+ "name": "http-src",
+ "parameter-value": [
+ {
+ "int-value": "6",
+ "name": "proto"
+ },
+ {
+ "int-value": "80",
+ "name": "sourceport"
+ }
+ ]
+ }
+ ],
+
+Then the action instances to associate to traffic that matches
+classifiers are defined.
+
+Note the *SFC chain name* must exist in SFC, and is validated against
+the datastore once the tenant configuration is entered, before entering
+a valid tenant configuration into the operational datastore (which
+triggers policy resolution).
+
+::
+
+ "action-instance": [
+ {
+ "name": "chain1",
+ "parameter-value": [
+ {
+ "name": "sfc-chain-name",
+ "string-value": "SFCGBP"
+ }
+ ]
+ },
+ {
+ "name": "allow1",
+ }
+ ]
+ },
+
+When ICMP is matched, allow the traffic:
+
+::
+
+ "contract": [
+ {
+ "subject": [
+ {
+ "name": "icmp-subject",
+ "rule": [
+ {
+ "name": "allow-icmp-rule",
+ "order" : 0,
+ "classifier-ref": [
+ {
+ "name": "icmp"
+ }
+ ],
+ "action-ref": [
+ {
+ "name": "allow1",
+ "order": 0
+ }
+ ]
+ }
+
+ ]
+ },
+
+When HTTP is matched, **in** to the provider of the contract with a TCP
+destination port of 80 (HTTP) or the HTTP request. The chain action is
+triggered, and similarly **out** from the provider for traffic with TCP
+source port of 80 (HTTP), or the HTTP response.
+
+::
+
+ {
+ "name": "http-subject",
+ "rule": [
+ {
+ "name": "http-chain-rule-in",
+ "classifier-ref": [
+ {
+ "name": "http-dest",
+ "direction": "in"
+ }
+ ],
+ "action-ref": [
+ {
+ "name": "chain1",
+ "order": 0
+ }
+ ]
+ },
+ {
+ "name": "http-chain-rule-out",
+ "classifier-ref": [
+ {
+ "name": "http-src",
+ "direction": "out"
+ }
+ ],
+ "action-ref": [
+ {
+ "name": "chain1",
+ "order": 0
+ }
+ ]
+ }
+ ]
+ }
+
+To enable asymmetrical chaining, for instance, the user desires that
+HTTP requests traverse the chain, but the HTTP response does not, the
+HTTP response is set to *allow* instead of chain:
+
+::
+
+ {
+ "name": "http-chain-rule-out",
+ "classifier-ref": [
+ {
+ "name": "http-src",
+ "direction": "out"
+ }
+ ],
+ "action-ref": [
+ {
+ "name": "allow1",
+ "order": 0
+ }
+ ]
+ }
+
+Demo/Development environment
+----------------------------
+
+The **GBP** project for Beryllium has two demo/development environments.
+
+- Docker based GBP and GBP+SFC integration Vagrant environment
+
+- DevStack based GBP+Neutron integration Vagrant environment
+
+`Demo @ GBP
+wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)/Consumability/Demo>`__
+
--- /dev/null
+OpenDaylight User Guide
+=======================
+
+Overview
+--------
+
+This first part of the user guide covers the basic user operations of
+the OpenDaylight Release using the generic base functionality.
+
+.. toctree::
+ :maxdepth: 1
+
+ opendaylight-controller-overview
+ using-the-opendaylight-user-interface-(dlux)
+ running-xsql-console-commands-and-queries
+ ../getting-started-guide/common-features/clustering.rst
+
+Project-specific User Guides
+----------------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ alto-user-guide
+ authentication-and-authorization-services
+ atrium-user-guide
+ bgp-user-guide
+ bgp-monitoring-protocol-user-guide
+ capwap-user-guide
+ cardinal_-opendaylight-monitoring-as-a-service
+ centinel-user-guide
+ didm-user-guide
+ group-based-policy-user-guide
+ l2switch-user-guide
+ l3vpn-service_-user-guide
+ link-aggregation-control-protocol-user-guide
+ lisp-flow-mapping-user-guide
+ network-modeling-(nemo)
+ netconf-user-guide
+ netide-user-guide
+ neutron-service-user-guide
+ network-intent-composition-(nic)-user-guide
+ ocp-plugin-user-guide
+ odl-sdni-user-guide
+ of-config-user-guide
+ openflow-plugin-project-user-guide
+ opflex-agent-ovs-user-guide
+ ovsdb-netvirt
+ pcep-user-guide
+ packetcable-user-guide
+ service-function-chaining
+ snmp-plugin-user-guide
+ snmp4sdn-user-guide
+ sxp-user-guide
+ tsdr-user-guide
+ ttp-cli-tools-user-guide
+ uni-manager-plug-in-project
+ unified-secure-channel
+ virtual-tenant-network-(vtn)
+ yang-ide-user-guide
+ yang-push
--- /dev/null
+L2Switch User Guide
+===================
+
+Overview
+--------
+
+The L2Switch project provides Layer2 switch functionality.
+
+L2Switch Architecture
+---------------------
+
+- Packet Handler
+
+ - Decodes the packets coming to the controller and dispatches them
+ appropriately
+
+- Loop Remover
+
+ - Removes loops in the network
+
+- Arp Handler
+
+ - Handles the decoded ARP packets
+
+- Address Tracker
+
+ - Learns the Addresses (MAC and IP) of entities in the network
+
+- Host Tracker
+
+ - Tracks the locations of hosts in the network
+
+- L2Switch Main
+
+ - Installs flows on each switch based on network traffic
+
+Configuring L2Switch
+--------------------
+
+This sections below give details about the configuration settings for
+the components that can be configured.
+
+Configuring Loop Remover
+------------------------
+
+- 52-loopremover.xml
+
+ - is-install-lldp-flow
+
+ - "true" means a flow that sends all LLDP packets to the
+ controller will be installed on each switch
+
+ - "false" means this flow will not be installed
+
+ - lldp-flow-table-id
+
+ - The LLDP flow will be installed on the specified flow table of
+ each switch
+
+ - This field is only relevant when "is-install-lldp-flow" is set
+ to "true"
+
+ - lldp-flow-priority
+
+ - The LLDP flow will be installed with the specified priority
+
+ - This field is only relevant when "is-install-lldp-flow" is set
+ to "true"
+
+ - lldp-flow-idle-timeout
+
+ - The LLDP flow will timeout (removed from the switch) if the
+ flow doesn’t forward a packet for *x* seconds
+
+ - This field is only relevant when "is-install-lldp-flow" is set
+ to "true"
+
+ - lldp-flow-hard-timeout
+
+ - The LLDP flow will timeout (removed from the switch) after *x*
+ seconds, regardless of how many packets it is forwarding
+
+ - This field is only relevant when "is-install-lldp-flow" is set
+ to "true"
+
+ - graph-refresh-delay
+
+ - A graph of the network is maintained and gets updated as
+ network elements go up/down (i.e. links go up/down and switches
+ go up/down)
+
+ - After a network element going up/down, it waits
+ *graph-refresh-delay* seconds before recomputing the graph
+
+ - A higher value has the advantage of doing less graph updates,
+ at the potential cost of losing some packets because the graph
+ didn’t update immediately.
+
+ - A lower value has the advantage of handling network topology
+ changes quicker, at the cost of doing more computation.
+
+Configuring Arp Handler
+-----------------------
+
+- 54-arphandler.xml
+
+ - is-proactive-flood-mode
+
+ - "true" means that flood flows will be installed on each switch.
+ With this flood flow, each switch will flood a packet that
+ doesn’t match any other flows.
+
+ - Advantage: Fewer packets are sent to the controller because
+ those packets are flooded to the network.
+
+ - Disadvantage: A lot of network traffic is generated.
+
+ - "false" means the previously mentioned flood flows will not be
+ installed. Instead an ARP flow will be installed on each switch
+ that sends all ARP packets to the controller.
+
+ - Advantage: Less network traffic is generated.
+
+ - Disadvantage: The controller handles more packets (ARP
+ requests & replies) and the ARP process takes longer than if
+ there were flood flows.
+
+ - flood-flow-table-id
+
+ - The flood flow will be installed on the specified flow table of
+ each switch
+
+ - This field is only relevant when "is-proactive-flood-mode" is
+ set to "true"
+
+ - flood-flow-priority
+
+ - The flood flow will be installed with the specified priority
+
+ - This field is only relevant when "is-proactive-flood-mode" is
+ set to "true"
+
+ - flood-flow-idle-timeout
+
+ - The flood flow will timeout (removed from the switch) if the
+ flow doesn’t forward a packet for *x* seconds
+
+ - This field is only relevant when "is-proactive-flood-mode" is
+ set to "true"
+
+ - flood-flow-hard-timeout
+
+ - The flood flow will timeout (removed from the switch) after *x*
+ seconds, regardless of how many packets it is forwarding
+
+ - This field is only relevant when "is-proactive-flood-mode" is
+ set to "true"
+
+ - arp-flow-table-id
+
+ - The ARP flow will be installed on the specified flow table of
+ each switch
+
+ - This field is only relevant when "is-proactive-flood-mode" is
+ set to "false"
+
+ - arp-flow-priority
+
+ - The ARP flow will be installed with the specified priority
+
+ - This field is only relevant when "is-proactive-flood-mode" is
+ set to "false"
+
+ - arp-flow-idle-timeout
+
+ - The ARP flow will timeout (removed from the switch) if the flow
+ doesn’t forward a packet for *x* seconds
+
+ - This field is only relevant when "is-proactive-flood-mode" is
+ set to "false"
+
+ - arp-flow-hard-timeout
+
+ - The ARP flow will timeout (removed from the switch) after
+ *arp-flow-hard-timeout* seconds, regardless of how many packets
+ it is forwarding
+
+ - This field is only relevant when "is-proactive-flood-mode" is
+ set to "false"
+
+Configuring Address Tracker
+---------------------------
+
+- 56-addresstracker.xml
+
+ - timestamp-update-interval
+
+ - A last-seen timestamp is associated with each address. This
+ last-seen timestamp will only be updated after
+ *timestamp-update-interval* milliseconds.
+
+ - A higher value has the advantage of performing less writes to
+ the database.
+
+ - A lower value has the advantage of knowing how fresh an address
+ is.
+
+ - observe-addresses-from
+
+ - IP and MAC addresses can be observed/learned from ARP, IPv4,
+ and IPv6 packets. Set which packets to make these observations
+ from.
+
+Configuring L2Switch Main
+-------------------------
+
+- 58-l2switchmain.xml
+
+ - is-install-dropall-flow
+
+ - "true" means a drop-all flow will be installed on each switch,
+ so the default action will be to drop a packet instead of
+ sending it to the controller
+
+ - "false" means this flow will not be installed
+
+ - dropall-flow-table-id
+
+ - The dropall flow will be installed on the specified flow table
+ of each switch
+
+ - This field is only relevant when "is-install-dropall-flow" is
+ set to "true"
+
+ - dropall-flow-priority
+
+ - The dropall flow will be installed with the specified priority
+
+ - This field is only relevant when "is-install-dropall-flow" is
+ set to "true"
+
+ - dropall-flow-idle-timeout
+
+ - The dropall flow will timeout (removed from the switch) if the
+ flow doesn’t forward a packet for *x* seconds
+
+ - This field is only relevant when "is-install-dropall-flow" is
+ set to "true"
+
+ - dropall-flow-hard-timeout
+
+ - The dropall flow will timeout (removed from the switch) after
+ *x* seconds, regardless of how many packets it is forwarding
+
+ - This field is only relevant when "is-install-dropall-flow" is
+ set to "true"
+
+ - is-learning-only-mode
+
+ - "true" means that the L2Switch will only be learning addresses.
+ No additional flows to optimize network traffic will be
+ installed.
+
+ - "false" means that the L2Switch will react to network traffic
+ and install flows on the switches to optimize traffic.
+ Currently, MAC-to-MAC flows are installed.
+
+ - reactive-flow-table-id
+
+ - The reactive flow will be installed on the specified flow table
+ of each switch
+
+ - This field is only relevant when "is-learning-only-mode" is set
+ to "false"
+
+ - reactive-flow-priority
+
+ - The reactive flow will be installed with the specified priority
+
+ - This field is only relevant when "is-learning-only-mode" is set
+ to "false"
+
+ - reactive-flow-idle-timeout
+
+ - The reactive flow will timeout (removed from the switch) if the
+ flow doesn’t forward a packet for *x* seconds
+
+ - This field is only relevant when "is-learning-only-mode" is set
+ to "false"
+
+ - reactive-flow-hard-timeout
+
+ - The reactive flow will timeout (removed from the switch) after
+ *x* seconds, regardless of how many packets it is forwarding
+
+ - This field is only relevant when "is-learning-only-mode" is set
+ to "false"
+
+Running the L2Switch project
+----------------------------
+
+To run the L2 Switch inside the Lithium OpenDaylight distribution simply
+install the ``odl-l2switch-switch-ui`` feature;
+
+::
+
+ feature:install odl-l2switch-switch-ui
+
+Create a network using mininet
+------------------------------
+
+::
+
+ sudo mn --controller=remote,ip=<Controller IP> --topo=linear,3 --switch ovsk,protocols=OpenFlow13
+ sudo mn --controller=remote,ip=127.0.0.1 --topo=linear,3 --switch ovsk,protocols=OpenFlow13
+
+The above command will create a virtual network consisting of 3
+switches. Each switch will connect to the controller located at the
+specified IP, i.e. 127.0.0.1
+
+::
+
+ sudo mn --controller=remote,ip=127.0.0.1 --mac --topo=linear,3 --switch ovsk,protocols=OpenFlow13
+
+The above command has the "mac" option, which makes it easier to
+distinguish between Host MAC addresses and Switch MAC addresses.
+
+Generating network traffic using mininet
+----------------------------------------
+
+::
+
+ h1 ping h2
+
+The above command will cause host1 (h1) to ping host2 (h2)
+
+::
+
+ pingall
+
+*pingall* will cause each host to ping every other host.
+
+Checking Address Observations
+-----------------------------
+
+Address Observations are added to the Inventory data tree.
+
+The Address Observations on a Node Connector can be checked through a
+browser or a REST Client.
+
+::
+
+ http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
+
+.. figure:: ./images/l2switch-address-observations.png
+ :alt: Address Observations
+
+ Address Observations
+
+Checking Hosts
+--------------
+
+Host information is added to the Topology data tree.
+
+- Host address
+
+- Attachment point (link) to a node/switch
+
+This host information and attachment point information can be checked
+through a browser or a REST Client.
+
+::
+
+ http://10.194.126.91:8080/restconf/operational/network-topology:network-topology/topology/flow:1/
+
+.. figure:: ./images/l2switch-hosts.png
+ :alt: Hosts
+
+ Hosts
+
+Checking STP status of each link
+--------------------------------
+
+STP Status information is added to the Inventory data tree.
+
+- A status of "forwarding" means the link is active and packets are
+ flowing on it.
+
+- A status of "discarding" means the link is inactive and packets are
+ not sent over it.
+
+The STP status of a link can be checked through a browser or a REST
+Client.
+
+::
+
+ http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:2
+
+.. figure:: ./images/l2switch-stp-status.png
+ :alt: STP status
+
+ STP status
+
+Miscellaneous mininet commands
+------------------------------
+
+::
+
+ link s1 s2 down
+
+This will bring the link between switch1 (s1) and switch2 (s2) down
+
+::
+
+ link s1 s2 up
+
+This will bring the link between switch1 (s1) and switch2 (s2) up
+
+::
+
+ link s1 h1 down
+
+This will bring the link between switch1 (s1) and host1 (h1) down
+
--- /dev/null
+L3VPN Service: User Guide
+=========================
+
+Overview
+--------
+
+L3VPN Service in OpenDaylight provides a framework to create L3VPN based
+on BGP-MP. It also helps to create Network Virtualization for DC Cloud
+environment.
+
+Modules & Interfaces
+--------------------
+
+L3VPN service can be realized using the following modules -
+
+VPN Service Modules
+~~~~~~~~~~~~~~~~~~~
+
+1. **VPN Manager** : Creates and manages VPNs and VPN Interfaces
+
+2. **BGP Manager** : Configures BGP routing stack and provides interface
+ to routing services
+
+3. **FIB Manager** : Provides interface to FIB, creates and manages
+ forwarding rules in Dataplane
+
+4. **Nexthop Manager** : Creates and manages nexthop egress pointer,
+ creates egress rules in Dataplane
+
+5. **Interface Manager** : Creates and manages different type of network
+ interfaces, e.g., VLAN, l3tunnel etc.,
+
+6. **Id Manager** : Provides cluster-wide unique ID for a given key.
+ Used by different modules to get unique IDs for different entities.
+
+7. **MD-SAL Util** : Provides interface to MD-SAL. Used by service
+ modules to access MD-SAL Datastore and services.
+
+All the above modules can function independently and can be utilized by
+other services as well.
+
+Configuration Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following modules expose configuration interfaces through which user
+can configure L3VPN Service.
+
+1. BGP Manager
+
+2. VPN Manager
+
+3. Interface Manager
+
+4. FIB Manager
+
+Configuration Interface Details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Data Node Path : */config/bgp:bgp-router/*
+
+ a. Fields :
+
+ i. local-as-identifier
+
+ ii. local-as-number
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+2. Data Node Path : */config/bgp:bgp-neighbors/*
+
+ a. Fields :
+
+ i. List of bgp-neighbor
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+3. Data Node Path :
+ */config/bgp:bgp-neighbors/bgp-neighbor/``{as-number}``/*
+
+ a. Fields :
+
+ i. as-number
+
+ ii. ip-address
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+1. Data Node Path : */config/l3vpn:vpn-instances/*
+
+ a. Fields :
+
+ i. List of vpn-instance
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+2. Data Node Path : */config/l3vpn:vpn-interfaces/vpn-instance*
+
+ a. Fields :
+
+ i. name
+
+ ii. route-distinguisher
+
+ iii. import-route-policy
+
+ iv. export-route-policy
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+3. Data Node Path : */config/l3vpn:vpn-interfaces/*
+
+ a. Fields :
+
+ i. List of vpn-interface
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+4. Data Node Path : */config/l3vpn:vpn-interfaces/vpn-interface*
+
+ a. Fields :
+
+ i. name
+
+ ii. vpn-instance-name
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+5. Data Node Path :
+ */config/l3vpn:vpn-interfaces/vpn-interface/``{name}``/adjacency*
+
+ a. Fields :
+
+ i. ip-address
+
+ ii. mac-address
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+1. Data Node Path : */config/if:interfaces/interface*
+
+ a. Fields :
+
+ i. name
+
+ ii. type
+
+ iii. enabled
+
+ iv. of-port-id
+
+ v. tenant-id
+
+ vi. base-interface
+
+ b. type specific fields
+
+ i. when type = *l2vlan*
+
+ A. vlan-id
+
+ ii. when type = *stacked\_vlan*
+
+ A. stacked-vlan-id
+
+ iii. when type = *l3tunnel*
+
+ A. tunnel-type
+
+ B. local-ip
+
+ C. remote-ip
+
+ D. gateway-ip
+
+ iv. when type = *mpls*
+
+ A. list labelStack
+
+ B. num-labels
+
+ c. REST Methods : GET, PUT, DELETE, POST
+
+1. Data Node Path : */config/odl-fib:fibEntries/vrfTables*
+
+ a. Fields :
+
+ i. List of vrfTables
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+2. Data Node Path :
+ */config/odl-fib:fibEntries/vrfTables/``{routeDistinguisher}``/*
+
+ a. Fields :
+
+ i. route-distinguisher
+
+ ii. list vrfEntries
+
+ A. destPrefix
+
+ B. label
+
+ C. nexthopAddress
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+3. Data Node Path : */config/odl-fib:fibEntries/ipv4Table*
+
+ a. Fields :
+
+ i. list ipv4Entry
+
+ A. destPrefix
+
+ B. nexthopAddress
+
+ b. REST Methods : GET, PUT, DELETE, POST
+
+Provisioning Sequence & Sample Configurations
+---------------------------------------------
+
+Installation
+~~~~~~~~~~~~
+
+1. Edit *etc/custom.properties* and set the following property:
+ *vpnservice.bgpspeaker.host.name = <bgpserver-ip>* *<bgpserver-ip>*
+ here refers to the IP address of the host where BGP is running.
+
+2. Run ODL and install VPN Service *feature:install odl-vpnservice-core*
+
+Use REST interface to configure L3VPN service
+
+Pre-requisites:
+~~~~~~~~~~~~~~~
+
+1. BGP stack with VRF support needs to installed and configured
+
+ a. *Configure BGP as specified in Step 1 below.*
+
+2. Create pairs of GRE/VxLAN Tunnels (using ovsdb/ovs-vsctl) between
+ each switch and between each switch to the Gateway node
+
+ a. *Create *l3tunnel* interfaces corresponding to each tunnel in
+ interfaces DS as specified in Step 2 below.*
+
+Step 1 : Configure BGP
+~~~~~~~~~~~~~~~~~~~~~~
+
+1. Configure BGP Router
+^^^^^^^^^^^^^^^^^^^^^^^
+
+**REST API** : *PUT /config/bgp:bgp-router/*
+
+**Sample JSON Data**
+
+.. code:: json
+
+ {
+ "bgp-router": {
+ "local-as-identifier": "10.10.10.10",
+ "local-as-number": 108
+ }
+ }
+
+2. Configure BGP Neighbors
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**REST API** : *PUT /config/bgp:bgp-neighbors/*
+
+**Sample JSON Data**
+
+.. code:: json
+
+ {
+ "bgp-neighbor" : [
+ {
+ "as-number": 105,
+ "ip-address": "169.144.42.168"
+ }
+ ]
+ }
+
+Step 2 : Create Tunnel Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create l3tunnel interfaces corresponding to all GRE/VxLAN tunnels
+created with ovsdb (`refer Prerequisites <#prer>`__). Use following REST
+Interface -
+
+**REST API** : *PUT /config/if:interfaces/if:interfacce*
+
+**Sample JSON Data**
+
+.. code:: json
+
+ {
+ "interface": [
+ {
+ "name" : "GRE_192.168.57.101_192.168.57.102",
+ "type" : "odl-interface:l3tunnel",
+ "odl-interface:tunnel-type": "odl-interface:tunnel-type-gre",
+ "odl-interface:local-ip" : "192.168.57.101",
+ "odl-interface:remote-ip" : "192.168.57.102",
+ "odl-interface:portId" : "openflow:1:3",
+ "enabled" : "true"
+ }
+ ]
+ }
+
+Following is expected as a result of these configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Unique If-index is generated
+
+2. *Interface-state* operational DS is updated
+
+3. Corresponding Nexthop Group Entry is created
+
+Step 3 : OS Create Neutron Ports and attach VMs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At this step user creates VMs.
+
+Step 4 : Create VM Interfaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create l2vlan interfaces corresponding to VM created in step 3
+
+**REST API** : *PUT /config/if:interfaces/if:interface*
+
+**Sample JSON Data**
+
+.. code:: json
+
+ {
+ "interface": [
+ {
+ "name" : "dpn1-dp1.2",
+ "type" : "l2vlan",
+ "odl-interface:of-port-id" : "openflow:1:2",
+ "odl-interface:vlan-id" : "1",
+ "enabled" : "true"
+ }
+ ]
+ }
+
+Step 5: Create VPN Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**REST API** : *PUT /config/l3vpn:vpn-instances/l3vpn:vpn-instance/*
+
+**Sample JSON Data**
+
+.. code:: json
+
+ {
+ "vpn-instance": [
+ {
+ "description": "Test VPN Instance 1",
+ "vpn-instance-name": "testVpn1",
+ "ipv4-family": {
+ "route-distinguisher": "4000:1",
+ "export-route-policy": "4000:1,5000:1",
+ "import-route-policy": "4000:1,5000:1",
+ }
+ }
+ ]
+ }
+
+Following is expected as a result of these configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. VPN ID is allocated and updated in data-store
+
+2. Corresponding VRF is created in BGP
+
+3. If there are vpn-interface configurations for this VPN, corresponding
+ action is taken as defined in step 5
+
+Step 5 : Create VPN-Interface and Local Adjacency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*this can be done in two steps as well*
+
+1. Create vpn-interface
+^^^^^^^^^^^^^^^^^^^^^^^
+
+**REST API** : *PUT /config/l3vpn:vpn-interfaces/l3vpn:vpn-interface/*
+
+**Sample JSON Data**
+
+.. code:: json
+
+ {
+ "vpn-interface": [
+ {
+ "vpn-instance-name": "testVpn1",
+ "name": "dpn1-dp1.2",
+ }
+ ]
+ }
+
+.. note::
+
+ name here is the name of VM interface created in step 3, 4
+
+2. Add Adjacencies on vpn-interafce
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**REST API** : *PUT
+/config/l3vpn:vpn-interfaces/l3vpn:vpn-interface/dpn1-dp1.3/adjacency*
+
+**Sample JSON Data**
+
+.. code:: json
+
+ {
+ "adjacency" : [
+ {
+ "ip-address" : "169.144.42.168",
+ "mac-address" : "11:22:33:44:55:66"
+ }
+ ]
+ }
+
+ its a list, user can define more than one adjacency on a
+ vpn\_interface
+
+Above steps can be carried out in a single step as following
+
+.. code:: json
+
+ {
+ "vpn-interface": [
+ {
+ "vpn-instance-name": "testVpn1",
+ "name": "dpn1-dp1.3",
+ "odl-l3vpn:adjacency": [
+ {
+ "odl-l3vpn:mac_address": "11:22:33:44:55:66",
+ "odl-l3vpn:ip_address": "11.11.11.2",
+ }
+ ]
+ }
+ ]
+ }
+
+Following is expected as a result of these configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Prefix label is generated and stored in DS
+
+2. Ingress table is programmed with flow corresponding to interface
+
+3. Local Egress Group is created
+
+4. Prefix is added to BGP for advertisement
+
+5. BGP pushes route update to FIB YANG Interface
+
+6. FIB Entry flow is added to FIB Table in OF pipeline
+
--- /dev/null
+Link Aggregation Control Protocol User Guide
+============================================
+
+Overview
+--------
+
+This section contains information about how to use the LACP plugin
+project with OpenDaylight, including configurations.
+
+Link Aggregation Control Protocol Architecture
+----------------------------------------------
+
+The LACP Project within OpenDaylight implements Link Aggregation Control
+Protocol (LACP) as an MD-SAL service module and will be used to
+auto-discover and aggregate multiple links between an OpenDaylight
+controlled network and LACP-enabled endpoints or switches. The result is
+the creation of a logical channel, which represents the aggregation of
+the links. Link aggregation provides link resiliency and bandwidth
+aggregation. This implementation adheres to IEEE Ethernet specification
+`802.3ad <http://www.ieee802.org/3/hssg/public/apr07/frazier_01_0407.pdf>`__.
+
+Configuring Link Aggregation Control Protocol
+---------------------------------------------
+
+This feature can be enabled in the Karaf console of the OpenDaylight
+Karaf distribution by issuing the following command:
+
+::
+
+ feature:install odl-lacp-ui
+
+.. note::
+
+ 1. Ensure that legacy (non-OpenFlow) switches are configured with
+ LACP mode active with a long timeout to allow for the LACP plugin
+ in OpenDaylight to respond to its messages.
+
+ 2. Flows that want to take advantage of LACP-configured Link
+ Aggregation Groups (LAGs) must explicitly use a OpenFlow group
+ table entry created by the LACP plugin. The plugin only creates
+ group table entries, it does not program any flows on its own.
+
+Administering or Managing Link Aggregation Control Protocol
+-----------------------------------------------------------
+
+LACP-discovered network inventory and network statistics can be viewed
+using the following REST APIs.
+
+1. List of aggregators available for a node:
+
+ ::
+
+ http://<ControllerIP>:8181/restconf/operational/opendaylight-inventory:nodes/node/<node-id>
+
+ Aggregator information will appear within the ``<lacp-aggregators>``
+ XML tag.
+
+2. To view only the information of an aggregator:
+
+ ::
+
+ http://<ControllerIP>:8181/restconf/operational/opendaylight-inventory:nodes/node/<node-id>/lacp-aggregators/<agg-id>
+
+ The group ID associated with the aggregator can be found inside the
+ ``<lag-groupid>`` XML tag.
+
+ The group table entry information for the ``<lag-groupid>`` added for
+ the aggregator is also available in the ``opendaylight-inventory``
+ node database.
+
+3. To view physical port information.
+
+ ::
+
+ http://<ControllerIP>:8181/restconf/operational/opendaylight-inventory:nodes/node/<node-id>/node-connector/<node-connector-id>
+
+ Ports that are associated with an aggregator will have the tag
+ ``<lacp-agg-ref>`` updated with valid aggregator information.
+
+Tutorials
+---------
+
+The below tutorial demonstrates LACP LAG creation for a sample mininet
+topology.
+
+Sample LACP Topology creation on Mininet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ sudo mn --controller=remote,ip=<Controller IP> --topo=linear,1 --switch ovsk,protocols=OpenFlow13
+
+The above command will create a virtual network consisting of a switch
+and a host. The switch will be connected to the controller.
+
+Once the topology is discovered, verify the presence of a flow entry
+with "dl\_type" set to "0x8809" to handle LACP packets using the below
+ovs-ofctl command:
+
+::
+
+ ovs-ofctl -O OpenFlow13 dump-flows s1
+ OFPST_FLOW reply (OF1.3) (xid=0x2):
+ cookie=0x300000000000001e, duration=60.067s, table=0, n_packets=0, n_bytes=0, priority=5,dl_dst=01:80:c2:00:00:02,dl_type=0x8809 actions=CONTROLLER:65535
+
+Configure an additional link between the switch (s1) and host (h1) using
+the below command on mininet shell to aggregate 2 links:
+
+::
+
+ mininet> py net.addLink(s1, net.get('h1'))
+ mininet> py s1.attach('s1-eth2')
+
+The LACP module will listen for LACP control packets that are generated
+from legacy switch (non-OpenFlow enabled). In our example, host (h1)
+will act as a LACP packet generator. In order to generate the LACP
+control packets, a bond interface has to be created on the host (h1)
+with mode type set to LACP with long-timeout. To configure bond
+interface, create a new file bonding.conf under the /etc/modprobe.d/
+directory and insert the below lines in this new file:
+
+::
+
+ alias bond0 bonding
+ options bonding mode=4
+
+Here mode=4 is referred to LACP and the default timeout is set to long.
+
+Enable bond interface and associate both physical interface h1-eth0 &
+h1-eth1 as members of the bond interface on host (h1) using the below
+commands on the mininet shell:
+
+::
+
+ mininet> py net.get('h1').cmd('modprobe bonding')
+ mininet> py net.get('h1').cmd('ip link add bond0 type bond')
+ mininet> py net.get('h1').cmd('ip link set bond0 address <bond-mac-address>')
+ mininet> py net.get('h1').cmd('ip link set h1-eth0 down')
+ mininet> py net.get('h1').cmd('ip link set h1-eth0 master bond0')
+ mininet> py net.get('h1').cmd('ip link set h1-eth1 down')
+ mininet> py net.get('h1').cmd('ip link set h1-eth1 master bond0')
+ mininet> py net.get('h1').cmd('ip link set bond0 up')
+
+Once the bond0 interface is up, the host (h1) will send LACP packets to
+the switch (s1). The LACP Module will then create a LAG through exchange
+of LACP packets between the host (h1) and switch (s1). To view the bond
+interface output on the host (h1) side:
+
+::
+
+ mininet> py net.get('h1').cmd('cat /proc/net/bonding/bond0')
+ Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011)
+ Bonding Mode: IEEE 802.3ad Dynamic link aggregation
+ Transmit Hash Policy: layer2 (0)
+ MII Status: up
+ MII Polling Interval (ms): 100
+ Up Delay (ms): 0
+ Down Delay (ms): 0
+ 802.3ad info
+ LACP rate: slow
+ Min links: 0
+ Aggregator selection policy (ad_select): stable
+ Active Aggregator Info:
+ Aggregator ID: 1
+ Number of ports: 2
+ Actor Key: 33
+ Partner Key: 27
+ Partner Mac Address: 00:00:00:00:01:01
+
+::
+
+ Slave Interface: h1-eth0
+ MII Status: up
+ Speed: 10000 Mbps
+ Duplex: full
+ Link Failure Count: 0
+ Permanent HW addr: 00:00:00:00:00:11
+ Aggregator ID: 1
+ Slave queue ID: 0
+
+::
+
+ Slave Interface: h1-eth1
+ MII Status: up
+ Speed: 10000 Mbps
+ Duplex: full
+ Link Failure Count: 0
+ Permanent HW addr: 00:00:00:00:00:12
+ Aggregator ID: 1
+ Slave queue ID: 0
+
+A corresponding group table entry would be created on the OpenFlow
+switch (s1) with "type" set to "select" to perform the LAG
+functionality. To view the group entries:
+
+::
+
+ mininet>ovs-ofctl -O Openflow13 dump-groups s1
+ OFPST_GROUP_DESC reply (OF1.3) (xid=0x2):
+ group_id=60169,type=select,bucket=weight:0,actions=output:1,output:2
+
+To apply the LAG functionality on the switches, the flows should be
+configured with action set to GroupId instead of output port. A sample
+add-flow configuration with output action set to GroupId:
+
+::
+
+ sudo ovs-ofctl -O Openflow13 add-flow s1 dl_type=0x0806,dl_src=SRC_MAC,dl_dst=DST_MAC,actions=group:60169
+
--- /dev/null
+LISP Flow Mapping User Guide
+============================
+
+Overview
+--------
+
+Locator/ID Separation Protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Locator/ID Separation Protocol
+(LISP) <http://tools.ietf.org/html/rfc6830>`__ is a technology that
+provides a flexible map-and-encap framework that can be used for overlay
+network applications such as data center network virtualization and
+Network Function Virtualization (NFV).
+
+LISP provides the following name spaces:
+
+- `Endpoint Identifiers
+ (EIDs) <http://tools.ietf.org/html/rfc6830#page-6>`__
+
+- `Routing Locators
+ (RLOCs) <http://tools.ietf.org/html/rfc6830#section-3>`__
+
+In a virtualization environment EIDs can be viewed as virtual address
+space and RLOCs can be viewed as physical network address space.
+
+The LISP framework decouples network control plane from the forwarding
+plane by providing:
+
+- A data plane that specifies how the virtualized network addresses are
+ encapsulated in addresses from the underlying physical network.
+
+- A control plane that stores the mapping of the virtual-to-physical
+ address spaces, the associated forwarding policies and serves this
+ information to the data plane on demand.
+
+Network programmability is achieved by programming forwarding policies
+such as transparent mobility, service chaining, and traffic engineering
+in the mapping system; where the data plane elements can fetch these
+policies on demand as new flows arrive. This chapter describes the LISP
+Flow Mapping project in OpenDaylight and how it can be used to enable
+advanced SDN and NFV use cases.
+
+LISP data plane Tunnel Routers are available at
+`LISPmob.org <http://LISPmob.org/>`__ in the open source community on
+the following platforms:
+
+- Linux
+
+- Android
+
+- OpenWRT
+
+For more details and support for LISP data plane software please visit
+`the LISPmob web site <http://LISPmob.org/>`__.
+
+LISP Flow Mapping Service
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The LISP Flow Mapping service provides LISP Mapping System services.
+This includes LISP Map-Server and LISP Map-Resolver services to store
+and serve mapping data to data plane nodes as well as to OpenDaylight
+applications. Mapping data can include mapping of virtual addresses to
+physical network address where the virtual nodes are reachable or hosted
+at. Mapping data can also include a variety of routing policies
+including traffic engineering and load balancing. To leverage this
+service, OpenDaylight applications and services can use the northbound
+REST API to define the mappings and policies in the LISP Mapping
+Service. Data plane devices capable of LISP control protocol can
+leverage this service through a southbound LISP plugin. LISP-enabled
+devices must be configured to use this OpenDaylight service as their Map
+Server and/or Map Resolver.
+
+The southbound LISP plugin supports the LISP control protocol
+(Map-Register, Map-Request, Map-Reply messages), and can also be used to
+register mappings in the OpenDaylight mapping service.
+
+LISP Flow Mapping Architecture
+------------------------------
+
+The following figure shows the various LISP Flow Mapping modules.
+
+.. figure:: ./images/ODL_lfm_Be_component.jpg
+ :alt: LISP Mapping Service Internal Architecture
+
+ LISP Mapping Service Internal Architecture
+
+A brief description of each module is as follows:
+
+- **DAO (Data Access Object):** This layer separates the LISP logic
+ from the database, so that we can separate the map server and map
+ resolver from the specific implementation of the mapping database.
+ Currently we have an implementation of this layer with an in-memory
+ HashMap, but it can be switched to any other key/value store and you
+ only need to implement the ILispDAO interface.
+
+- **Map Server:** This module processes the adding or registration of
+ authentication tokens (keys) and mappings. For a detailed
+ specification of LISP Map Server, see
+ `LISP <http://tools.ietf.org/search/rfc6830>`__.
+
+- **Map Resolver:** This module receives and processes the mapping
+ lookup queries and provides the mappings to requester. For a detailed
+ specification of LISP Map Server, see
+ `LISP <http://tools.ietf.org/search/rfc6830>`__.
+
+- **RPC/RESTCONF:** This is the auto-generated RESTCONF-based
+ northbound API. This module enables defining key-EID associations as
+ well as adding mapping information through the Map Server. Key-EID
+ associations and mappings can also be queried via this API.
+
+- **GUI:** This module enables adding and querying the mapping service
+ through a GUI based on ODL DLUX.
+
+- **Neutron:** This module implements the OpenDaylight Neutron Service
+ APIs. It provides integration between the LISP service and the
+ OpenDaylight Neutron service, and thus OpenStack.
+
+- **Java API:** The API module exposes the Map Server and Map Resolver
+ capabilities via a Java API.
+
+- **LISP Proto:** This module includes LISP protocol dependent data
+ types and associated processing.
+
+- **In Memory DB:** This module includes the in memory database
+ implementation of the mapping service.
+
+- **LISP Southbound Plugin:** This plugin enables data plane devices
+ that support LISP control plane protocol (see
+ `LISP <http://tools.ietf.org/search/rfc6830>`__) to register and
+ query mappings to the LISP Flow Mapping via the LISP control plane
+ protocol.
+
+Configuring LISP Flow Mapping
+-----------------------------
+
+In order to use the LISP mapping service for registering EID to RLOC
+mappings from northbound or southbound, keys have to be defined for the
+EID prefixes first. Once a key is defined for an EID prefix, it can be
+used to add mappings for that EID prefix multiple times. If the service
+is going to be used to process Map-Register messages from the southbound
+LISP plugin, the same key must be used by the data plane device to
+create the authentication data in the Map-Register messages for the
+associated EID prefix.
+
+The ``etc/custom.properties`` file in the Karaf distribution allows
+configuration of several OpenDaylight parameters. The LISP service has
+the following properties that can be adjusted:
+
+**lisp.mappingOverwrite** (default: *true*)
+ Configures handling of mapping updates. When set to *true* (default)
+ a mapping update (either through the southbound plugin via a
+ Map-Register message or through a northbound API PUT REST call) the
+ existing RLOC set associated to an EID prefix is overwritten. When
+ set to *false*, the RLOCs of the update are merged to the existing
+ set.
+
+**lisp.smr** (default: *false*)
+ Enables/disables the `Solicit-Map-Request
+ (SMR) <http://tools.ietf.org/html/rfc6830#section-6.6.2>`__
+ functionality. SMR is a method to notify changes in an EID-to-RLOC
+ mapping to "subscribers". The LISP service considers all
+ Map-Request’s source RLOC as a subscriber to the requested EID
+ prefix, and will send an SMR control message to that RLOC if the
+ mapping changes.
+
+**lisp.elpPolicy** (default: *default*)
+ Configures how to build a Map-Reply southbound message from a
+ mapping containing an Explicit Locator Path (ELP) RLOC. It is used
+ for compatibility with dataplane devices that don’t understand the
+ ELP LCAF format. The *default* setting doesn’t alter the mapping,
+ returning all RLOCs unmodified. The *both* setting adds a new RLOC
+ to the mapping, with a lower priority than the ELP, that is the next
+ hop in the service chain. To determine the next hop, it searches the
+ source RLOC of the Map-Request in the ELP, and chooses the next hop,
+ if it exists, otherwise it chooses the first hop. The *replace*
+ setting adds a new RLOC using the same algorithm as the *both*
+ setting, but using the origin priority of the ELP RLOC, which is
+ removed from the mapping.
+
+**lisp.lookupPolicy** (default: *northboundFirst*)
+ Configures the mapping lookup algorithm. When set to
+ *northboundFirst* mappings programmed through the northbound API
+ will take precedence. If no northbound programmed mappings exist,
+ then the mapping service will return mappings registered through the
+ southbound plugin, if any exists. When set to
+ *northboundAndSouthbound* the mapping programmed by the northbound
+ is returned, updated by the up/down status of these mappings as
+ reported by the southbound (if existing).
+
+**lisp.mappingMerge** (default: *false*)
+ Configures the merge policy on the southbound registrations through
+ the LISP SB Plugin. When set to *false*, only the latest mapping
+ registered through the SB plugin is valid in the southbound mapping
+ database, independent of which device it came from. When set to
+ *true*, mappings for the same EID registered by different devices
+ are merged together and a union of the locators is maintained as the
+ valid mapping for that EID.
+
+Textual Conventions for LISP Address Formats
+--------------------------------------------
+
+In addition to the more common IPv4, IPv6 and MAC address data types,
+the LISP control plane supports arbitrary `Address Family
+Identifiers <http://www.iana.org/assignments/address-family-numbers>`__
+assigned by IANA, and in addition to those the `LISP Canoncal Address
+Format (LCAF) <https://tools.ietf.org/html/draft-ietf-lisp-lcaf>`__.
+
+The LISP Flow Mapping project in OpenDaylight implements support for
+many of these different address formats, the full list being summarized
+in the following table. While some of the address formats have well
+defined and widely used textual representation, many don’t. It became
+necessary to define a convention to use for text rendering of all
+implemented address types in logs, URLs, input fields, etc. The below
+table lists the supported formats, along with their AFI number and LCAF
+type, including the prefix used for disambiguation of potential overlap,
+and examples output.
+
++------------------+----------+----------+----------+----------------------------------+
+| Name | AFI | LCAF | Prefix | Text Rendering |
++==================+==========+==========+==========+==================================+
+| **No Address** | 0 | - | no: | No Address Present |
++------------------+----------+----------+----------+----------------------------------+
+| **IPv4 Prefix** | 1 | - | ipv4: | 192.0.2.0/24 |
++------------------+----------+----------+----------+----------------------------------+
+| **IPv6 Prefix** | 2 | - | ipv6: | 2001:db8::/32 |
++------------------+----------+----------+----------+----------------------------------+
+| **MAC Address** | 16389 | - | mac: | 00:00:5E:00:53:00 |
++------------------+----------+----------+----------+----------------------------------+
+| **Distinguished | 17 | - | dn: | stringAsIs |
+| Name** | | | | |
++------------------+----------+----------+----------+----------------------------------+
+| **AS Number** | 18 | - | as: | AS64500 |
++------------------+----------+----------+----------+----------------------------------+
+| **AFI List** | 16387 | 1 | list: | {192.0.2.1,192.0.2.2,2001:db8::1 |
+| | | | | } |
++------------------+----------+----------+----------+----------------------------------+
+| **Instance ID** | 16387 | 2 | - | [223] 192.0.2.0/24 |
++------------------+----------+----------+----------+----------------------------------+
+| **Application | 16387 | 4 | appdata: | 192.0.2.1!128!17!80-81!6667-7000 |
+| Data** | | | | |
++------------------+----------+----------+----------+----------------------------------+
+| **Explicit | 16387 | 10 | elp: | {192.0.2.1→192.0.2.2\|lps→192.0. |
+| Locator Path** | | | | 2.3} |
++------------------+----------+----------+----------+----------------------------------+
+| **Source/Destina | 16387 | 12 | srcdst: | 192.0.2.1/32\|192.0.2.2/32 |
+| tion | | | | |
+| Key** | | | | |
++------------------+----------+----------+----------+----------------------------------+
+| **Key/Value | 16387 | 15 | kv: | 192.0.2.1⇒192.0.2.2 |
+| Address Pair** | | | | |
++------------------+----------+----------+----------+----------------------------------+
+| **Service Path** | 16387 | N/A | sp: | 42(3) |
++------------------+----------+----------+----------+----------------------------------+
+
+Table: LISP Address Formats
+
+Please note that the forward slash character ``/`` typically separating
+IPv4 and IPv6 addresses from the mask length is transformed into ``%2f``
+when used in a URL.
+
+Karaf commands
+--------------
+
+In this section we will discuss two types of Karaf commands: built-in,
+and LISP specific. Some built-in commands are quite useful, and are
+needed for the tutorial, so they will be discussed here. A reference of
+all LISP specific commands, added by the LISP Flow Mapping project is
+also included. They are useful mostly for debugging.
+
+Useful built-in commands
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``help``
+ Lists all available command, with a short description of each.
+
+``help <command_name>``
+ Show detailed help about a specific command.
+
+``feature:list [-i]``
+ Show all locally available features in the Karaf container. The
+ ``-i`` option lists only features that are currently installed. It
+ is possible to use ``| grep`` to filter the output (for all
+ commands, not just this one).
+
+``feature:install <feature_name>``
+ Install feature ``feature_name``.
+
+``log:set <level> <class>``
+ Set the log level for ``class`` to ``level``. The default log level
+ for all classes is INFO. For debugging, or learning about LISP
+ internals it is useful to run
+ ``log:set TRACE org.opendaylight.lispflowmapping`` right after Karaf
+ starts up.
+
+``log:display``
+ Outputs the log file to the console, and returns control to the
+ user.
+
+``log:tail``
+ Continuously shows log output, requires ``Ctrl+C`` to return to the
+ console.
+
+LISP specific commands
+~~~~~~~~~~~~~~~~~~~~~~
+
+The available lisp commands can always be obtained by
+``help mappingservice``. Currently they are:
+
+``mappingservice:addkey``
+ Add the default password ``password`` for the IPv4 EID prefix
+ 0.0.0.0/0 (all addresses). This is useful when experimenting with
+ southbound devices, and using the REST interface would be combersome
+ for whatever reason.
+
+``mappingservice:mappings``
+ Show the list of all mappings stored in the internal non-persistent
+ data store (the DAO), listing the full data structure. The output is
+ not human friendly, but can be used for debugging.
+
+LISP Flow Mapping Karaf Features
+--------------------------------
+
+LISP Flow Mapping has the following Karaf features that can be installed
+from the Karaf console:
+
+``odl-lispflowmapping-msmr``
+ This includes the core features required to use the LISP Flow
+ Mapping Service such as mapping service and the LISP southbound
+ plugin.
+
+``odl-lispflowmapping-ui``
+ This includes the GUI module for the LISP Mapping Service.
+
+``odl-lispflowmapping-neutron``
+ This is the experimental Neutron provider module for LISP mapping
+ service.
+
+Tutorials
+---------
+
+This section provides a tutorial demonstrating various features in this
+service.
+
+Creating a LISP overlay
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This section provides instructions to set up a LISP network of three
+nodes (one "client" node and two "server" nodes) using LISPmob as data
+plane LISP nodes and the LISP Flow Mapping project from OpenDaylight as
+the LISP programmable mapping system for the LISP network.
+
+Overview
+^^^^^^^^
+
+The steps shown below will demonstrate setting up a LISP network between
+a client and two servers, then performing a failover between the two
+"server" nodes.
+
+Prerequisites
+^^^^^^^^^^^^^
+
+- **OpenDaylight Beryllium**
+
+- **The Postman Chrome App**: the most convenient way to follow along
+ this tutorial is to use the `Postman Chrome
+ App <https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en>`__
+ to edit and send the requests. The project git repository hosts a
+ collection of the requests that are used in this tutorial in the
+ ``resources/tutorial/Beryllium_Tutorial.json.postman_collection``
+ file. You can import this file to Postman by clicking *Import* at the
+ top, choosing *Download from link* and then entering the following
+ URL:
+ ``https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/Beryllium_Tutorial.json.postman_collection;hb=refs/heads/stable/beryllium``.
+ Alternatively, you can save the file on your machine, or if you have
+ the repository checked out, you can import from there. You will need
+ to create a new Postman Environment and define some variables within:
+ ``controllerHost`` set to the hostname or IP address of the machine
+ running the ODL instance, and ``restconfPort`` to 8181, if you didn’t
+ modify the default controller settings.
+
+- **LISPmob version 0.5.x** The README.md lists the dependencies needed
+ to build it from source.
+
+- **A virtualization platform**
+
+Target Environment
+^^^^^^^^^^^^^^^^^^
+
+The three LISP data plane nodes and the LISP mapping system are assumed
+to be running in Linux virtual machines, which have the ``eth0``
+interface in NAT mode to allow outside internet access and ``eth1``
+connected to a host-only network, with the following IP addresses
+(please adjust configuration files, JSON examples, etc. accordingly if
+you’re using another addressing scheme):
+
++--------------------------+--------------------------+--------------------------+
+| Node | Node Type | IP Address |
++==========================+==========================+==========================+
+| **controller** | OpenDaylight | 192.168.16.11 |
++--------------------------+--------------------------+--------------------------+
+| **client** | LISPmob | 192.168.16.30 |
++--------------------------+--------------------------+--------------------------+
+| **server1** | LISPmob | 192.168.16.31 |
++--------------------------+--------------------------+--------------------------+
+| **server2** | LISPmob | 192.168.16.32 |
++--------------------------+--------------------------+--------------------------+
+| **service-node** | LISPmob | 192.168.16.33 |
++--------------------------+--------------------------+--------------------------+
+
+Table: Nodes in the tutorial
+
+.. note::
+
+ While the tutorial uses LISPmob as the data plane, it could be any
+ LISP-enabled hardware or software router (commercial/open source).
+
+Instructions
+^^^^^^^^^^^^
+
+The below steps use the command line tool cURL to talk to the LISP Flow
+Mapping RPC REST API. This is so that you can see the actual request
+URLs and body content on the page.
+
+1. Install and run OpenDaylight Beryllium release on the controller VM.
+ Please follow the general OpenDaylight Beryllium Installation Guide
+ for this step. Once the OpenDaylight controller is running install
+ the *odl-lispflowmapping-msmr* feature from the Karaf CLI:
+
+ ::
+
+ feature:install odl-lispflowmapping-msmr
+
+ It takes quite a while to load and initialize all features and their
+ dependencies. It’s worth running the command ``log:tail`` in the
+ Karaf console to see when the log output is winding down, and
+ continue with the tutorial after that.
+
+2. Install LISPmob on the **client**, **server1**, **server2**, and
+ **service-node** VMs following the installation instructions `from
+ the LISPmob README
+ file <https://github.com/LISPmob/lispmob#software-prerequisites>`__.
+
+3. Configure the LISPmob installations from the previous step. Starting
+ from the ``lispd.conf.example`` file in the distribution, set the
+ EID in each ``lispd.conf`` file from the IP address space selected
+ for your virtual/LISP network. In this tutorial the EID of the
+ **client** is set to 1.1.1.1/32, and that of **server1** and
+ **server2** to 2.2.2.2/32.
+
+4. Set the RLOC interface to ``eth1`` in each ``lispd.conf`` file. LISP
+ will determine the RLOC (IP address of the corresponding VM) based
+ on this interface.
+
+5. Set the Map-Resolver address to the IP address of the
+ **controller**, and on the **client** the Map-Server too. On
+ **server1** and **server2** set the Map-Server to something else, so
+ that it doesn’t interfere with the mappings on the controller, since
+ we’re going to program them manually.
+
+6. Modify the "key" parameter in each ``lispd.conf`` file to a
+ key/password of your choice (*password* in this tutorial).
+
+ .. note::
+
+ The ``resources/tutorial`` directory in the *stable/beryllium*
+ branch of the project git repository has the files used in the
+ tutorial `checked
+ in <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial;hb=refs/heads/stable/beryllium>`__,
+ so you can just copy the files to ``/root/lispd.conf`` on the
+ respective VMs. You will also find the JSON files referenced
+ below in the same directory.
+
+7. Define a key and EID prefix association in OpenDaylight using the
+ RPC REST API for the **client** EID (1.1.1.1/32) to allow
+ registration from the southbound. Since the mappings for the server
+ EID will be configured from the REST API, no such association is
+ necessary. Run the below command on the **controller** (or any
+ machine that can reach **controller**, by replacing *localhost* with
+ the IP address of **controller**).
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:add-key \
+ --data @add-key.json
+
+ where the content of the *add-key.json* file is the following:
+
+ .. code:: json
+
+ {
+ "input": {
+ "eid": {
+ "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
+ "ipv4-prefix": "1.1.1.1/32"
+ },
+ "mapping-authkey": {
+ "key-string": "password",
+ "key-type": 1
+ }
+ }
+ }
+
+8. Verify that the key is added properly by requesting the following
+ URL:
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:get-key \
+ --data @get1.json
+
+ where the content of the *get1.json* file can be derived from the
+ *add-key.json* file by removing the *mapping-authkey* field. The
+ output the above invocation should look like this:
+
+ ::
+
+ {"output":{"mapping-authkey":{"key-type":1,"key-string":"password"}}}
+
+9. Run the ``lispd`` LISPmob daemon on all VMs:
+
+ ::
+
+ lispd -f /root/lispd.conf
+
+10. The **client** LISPmob node should now register its EID-to-RLOC
+ mapping in OpenDaylight. To verify you can lookup the corresponding
+ EIDs via the REST API
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
+ --data @get1.json
+
+ An alternative way for retrieving mappings from ODL using the
+ southbound interface is using the
+ ```lig`` <https://github.com/davidmeyer/lig>`__ open source tool.
+
+11. Register the EID-to-RLOC mapping of the server EID 2.2.2.2/32 to the
+ controller, pointing to **server1** and **server2** with a higher
+ priority for **server1**
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
+ --data @mapping.json
+
+ where the *mapping.json* file looks like this:
+
+ .. code:: json
+
+ {
+ "input": {
+ "mapping-record": {
+ "recordTtl": 1440,
+ "action": "NoAction",
+ "authoritative": true,
+ "eid": {
+ "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
+ "ipv4-prefix": "2.2.2.2/32"
+ },
+ "LocatorRecord": [
+ {
+ "locator-id": "server1",
+ "priority": 1,
+ "weight": 1,
+ "multicastPriority": 255,
+ "multicastWeight": 0,
+ "localLocator": true,
+ "rlocProbed": false,
+ "routed": true,
+ "rloc": {
+ "address-type": "ietf-lisp-address-types:ipv4-afi",
+ "ipv4": "192.168.16.31"
+ }
+ },
+ {
+ "locator-id": "server2",
+ "priority": 2,
+ "weight": 1,
+ "multicastPriority": 255,
+ "multicastWeight": 0,
+ "localLocator": true,
+ "rlocProbed": false,
+ "routed": true,
+ "rloc": {
+ "address-type": "ietf-lisp-address-types:ipv4-afi",
+ "ipv4": "192.168.16.32"
+ }
+ }
+ ]
+ }
+ }
+ }
+
+ Here the priority of the second RLOC (192.168.16.32 - **server2**)
+ is 2, a higher numeric value than the priority of 192.168.16.31,
+ which is 1. This policy is saying that **server1** is preferred to
+ **server2** for reaching EID 2.2.2.2/32. Note that lower priority
+ value has higher preference in LISP.
+
+12. Verify the correct registration of the 2.2.2.2/32 EID:
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
+ --data @get2.json
+
+ where *get2.json* can be derived from *get1.json* by changing the
+ content of the *Ipv4Address* field from *1.1.1.1* to *2.2.2.2*.
+
+13. Now the LISP network is up. To verify, log into the **client** VM
+ and ping the server EID:
+
+ ::
+
+ ping 2.2.2.2
+
+14. Let’s test fail-over now. Suppose you had a service on **server1**
+ which became unavailable, but **server1** itself is still reachable.
+ LISP will not automatically fail over, even if the mapping for
+ 2.2.2.2/32 has two locators, since both locators are still reachable
+ and uses the one with the higher priority (lowest priority value).
+ To force a failover, we need to set the priority of **server2** to a
+ lower value. Using the file mapping.json above, swap the priority
+ values between the two locators (lines 14 and 28 in *mapping.json*)
+ and repeat the request from step 11. You can also repeat step 12 to
+ see if the mapping is correctly registered. If you leave the ping
+ on, and monitor the traffic using wireshark, you can see that the
+ ping traffic to 2.2.2.2 will be diverted from the **server1** RLOC
+ to the **server2** RLOC.
+
+ With the default OpenDaylight configuration the failover should be
+ near instantaneous (we observed 3 lost pings in the worst case),
+ because of the LISP `Solicit-Map-Request (SMR)
+ mechanism <http://tools.ietf.org/html/rfc6830#section-6.6.2>`__ that
+ can ask a LISP data plane element to update its mapping for a
+ certain EID (enabled by default). It is controlled by the
+ ``lisp.smr`` variable in ``etc/custom.porperties``. When enabled,
+ any mapping change from the RPC interface will trigger an SMR packet
+ to all data plane elements that have requested the mapping in the
+ last 24 hours (this value was chosen because it’s the default TTL of
+ Cisco IOS xTR mapping registrations). If disabled, ITRs keep their
+ mappings until the TTL specified in the Map-Reply expires.
+
+15. To add a service chain into the path from the client to the server,
+ we can use an Explicit Locator Path, specifying the **service-node**
+ as the first hop and **server1** (or **server2**) as the second hop.
+ The following will achieve that:
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
+ --data @elp.json
+
+ where the *elp.json* file is as follows:
+
+ .. code:: json
+
+ {
+ "input": {
+ "mapping-record": {
+ "recordTtl": 1440,
+ "action": "NoAction",
+ "authoritative": true,
+ "eid": {
+ "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
+ "ipv4-prefix": "2.2.2.2/32"
+ },
+ "LocatorRecord": [
+ {
+ "locator-id": "ELP",
+ "priority": 1,
+ "weight": 1,
+ "multicastPriority": 255,
+ "multicastWeight": 0,
+ "localLocator": true,
+ "rlocProbed": false,
+ "routed": true,
+ "rloc": {
+ "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
+ "explicit-locator-path": {
+ "hop": [
+ {
+ "hop-id": "service-node",
+ "address": "192.168.16.33",
+ "lrs-bits": "strict"
+ },
+ {
+ "hop-id": "server1",
+ "address": "192.168.16.31",
+ "lrs-bits": "strict"
+ }
+ ]
+ }
+ }
+ }
+ ]
+ }
+ }
+ }
+
+ After the mapping for 2.2.2.2/32 is updated with the above, the ICMP
+ traffic from **client** to **server1** will flow through the
+ **service-node**. You can confirm this in the LISPmob logs, or by
+ sniffing the traffic on either the **service-node** or **server1**.
+ Note that service chains are unidirectional, so unless another ELP
+ mapping is added for the return traffic, packets will go from
+ **server1** to **client** directly.
+
+16. Suppose the **service-node** is actually a firewall, and traffic is
+ diverted there to support access control lists (ACLs). In this
+ tutorial that can be emulated by using ``iptables`` firewall rules
+ in the **service-node** VM. To deny traffic on the service chain
+ defined above, the following rule can be added:
+
+ ::
+
+ iptables -A OUTPUT --dst 192.168.16.31 -j DROP
+
+ The ping from the **client** should now have stopped.
+
+ In this case the ACL is done on the destination RLOC. There is an
+ effort underway in the LISPmob community to allow filtering on EIDs,
+ which is the more logical place to apply ACLs.
+
+17. To delete the rule and restore connectivity on the service chain,
+ delete the ACL by issuing the following command:
+
+ ::
+
+ iptables -D OUTPUT --dst 192.168.16.31 -j DROP
+
+ which should restore connectivity.
+
+LISP Flow Mapping Support
+-------------------------
+
+For support the lispflowmapping project can be reached by emailing the
+developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on
+the #opendaylight-lispflowmapping IRC channel on irc.freenode.net.
+
+Additional information is also available on the `Lisp Flow Mapping
+wiki <https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main>`__
+
+Clustering in LISP Flow Mapping
+-------------------------------
+
+Documentation regarding setting up a 3-node OpenDaylight cluster is
+described at following `odl wiki
+page <https://wiki.opendaylight.org/view/Running_and_testing_an_OpenDaylight_Cluster#Three-node_cluster>`__.
+
+To turn on clustering in LISP Flow Mapping it is necessary:
+
+- run script **deploy.py** script. This script is in
+ `integration-test <https://git.opendaylight.org/gerrit/integration/test>`__
+ project placed at *tools/clustering/cluster-deployer/deploy.py*. A
+ whole deploy.py command can looks like:
+
+.. raw:: html
+
+ <div class="informalexample">
+
+| {path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/**deploy.py**
+| --**distribution** {path\_to\_distribution\_in\_zip\_format}
+| --**rootdir** {dir\_at\_remote\_host\_where\_copy\_odl\_distribution}
+| --**hosts** {ip1},{ip2},{ip3}
+| --**clean**
+| --**template** lispflowmapping
+| --**rf** 3
+| --**user** {user\_name\_of\_remote\_hosts}
+| --**password** {password\_to\_remote\_hosts}
+
+.. raw:: html
+
+ </div>
+
+| Running this script will cause that specified **distribution** to be
+ deployed to remote **hosts** specified through their IP adresses with
+ using credentials (**user** and **password**). The distribution will
+ be copied to specified **rootdir**. As part of the deployment, a
+ **template** which contains a set of controller files which are
+ different from standard ones. In this case it is specified in
+| *{path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/lispflowmapping*
+ directory.
+| Lispflowmapping templates are part of integration-test project. There
+ are 5 template files:
+
+- akka.conf.template
+
+- jolokia.xml.template
+
+- module-shards.conf.template
+
+- modules.conf.template
+
+- org.apache.karaf.features.cfg.template
+
+After copying the distribution, it is unzipped and started on all of
+specified **hosts** in cluster aware manner.
+
+Remarks
+~~~~~~~
+
+It is necessary to have:
+
+- **unzip** program installed on all of the host
+
+- set all remote hosts /etc/sudoers files to not **requiretty** (should
+ only matter on debian hosts)
+
--- /dev/null
+Network Intent Composition (NIC) User Guide
+===========================================
+
+Overview
+--------
+
+Network Intent Composition (NIC) is an interface that allows clients to
+express a desired state in an implementation-neutral form that will be
+enforced via modification of available resources under the control of
+the OpenDaylight system.
+
+This description is purposely abstract as an intent interface might
+encompass network services, virtual devices, storage, etc.
+
+The intent interface is meant to be a controller-agnostic interface so
+that "intents" are portable across implementations, such as OpenDaylight
+and ONOS. Thus an intent specification should not contain implementation
+or technology specifics.
+
+The intent specification will be implemented by decomposing the intent
+and augmenting it with implementation specifics that are driven by local
+implementation rules, policies, and/or settings.
+
+Network Intent Composition (NIC) Architecture
+---------------------------------------------
+
+The core of the NIC architecture is the intent model, which specifies
+the details of the desired state. It is the responsibility of the NIC
+implementation transforms this desired state to the resources under the
+control of OpenDaylight. The component that transforms the intent to the
+implementation is typically referred to as a renderer.
+
+For the Boron release, multiple, simultaneous renderers will not be
+supported. Instead either the VTN or GBP renderer feature can be
+installed, but not both.
+
+For the Boron release, the only actions supported are "ALLOW" and
+"BLOCK". The "ALLOW" action indicates that traffic can flow between the
+source and destination end points, while "BLOCK" prevents that flow;
+although it is possible that an given implementation may augment the
+available actions with additional actions.
+
+Besides transforming a desired state to an actual state it is the
+responsibility of a renderer to update the operational state tree for
+the NIC data model in OpenDaylight to reflect the intent which the
+renderer implemented.
+
+Configuring Network Intent Composition (NIC)
+--------------------------------------------
+
+For the Boron release there is no default implementation of a renderer,
+thus without an additional module installed the NIC will not function.
+
+Administering or Managing Network Intent Composition (NIC)
+----------------------------------------------------------
+
+There is no additional administration of management capabilities related
+to the Network Intent Composition features.
+
+Interactions
+------------
+
+A user can interact with the Network Intent Composition (NIC) either
+through the RESTful interface using standard RESTCONF operations and
+syntax or via the Karaf console CLI.
+
+REST
+~~~~
+
+Configuration
+^^^^^^^^^^^^^
+
+The Network Intent Composition (NIC) feature supports the following REST
+operations against the configuration data store.
+
+- POST - creates a new instance of an intent in the configuration
+ store, which will trigger the realization of that intent. An ID
+ *must* be specified as part of this request as an attribute of the
+ intent.
+
+- GET - fetches a list of all configured intents or a specific
+ configured intent.
+
+- DELETE - removes a configured intent from the configuration store,
+ which triggers the removal of the intent from the network.
+
+Operational
+^^^^^^^^^^^
+
+The Network Intent Composition (NIC) feature supports the following REST
+operations against the operational data store.
+
+- GET - fetches a list of all operational intents or a specific
+ operational intent.
+
+Karaf Console CLI
+~~~~~~~~~~~~~~~~~
+
+This feature provides karaf console CLI command to manipulate the intent
+data model. The CLI essentailly invokes the equivalent data operations.
+
+intent:add
+^^^^^^^^^^
+
+Creates a new intent in the configuration data tree
+
+::
+
+ DESCRIPTION
+ intent:add
+
+ Adds an intent to the controller.
+
+ Examples: --actions [ALLOW] --from <subject> --to <subject>
+ --actions [BLOCK] --from <subject>
+
+ SYNTAX
+ intent:add [options]
+
+ OPTIONS
+ -a, --actions
+ Action to be performed.
+ -a / --actions BLOCK/ALLOW
+ (defaults to [BLOCK])
+ --help
+ Display this help message
+ -t, --to
+ Second Subject.
+ -t / --to <subject>
+ (defaults to any)
+ -f, --from
+ First subject.
+ -f / --from <subject>
+ (defaults to any)
+
+intent:delete
+^^^^^^^^^^^^^
+
+Removes an existing intent from the system
+
+::
+
+ DESCRIPTION
+ intent:remove
+
+ Removes an intent from the controller.
+
+ SYNTAX
+ intent:remove id
+
+ ARGUMENTS
+ id Intent Id
+
+intent:list
+^^^^^^^^^^^
+
+Lists all the intents in the system
+
+::
+
+ DESCRIPTION
+ intent:list
+
+ Lists all intents in the controller.
+
+ SYNTAX
+ intent:list [options]
+
+ OPTIONS
+ -c, --config
+ List Configuration Data (optional).
+ -c / --config <ENTER>
+ --help
+ Display this help message
+
+intent:show
+^^^^^^^^^^^
+
+Displayes the details of a single intent
+
+::
+
+ DESCRIPTION
+ intent:show
+
+ Shows detailed information about an intent.
+
+ SYNTAX
+ intent:show id
+
+ ARGUMENTS
+ id Intent Id
+
+intent:map
+^^^^^^^^^^
+
+List/Add/Delete current state from/to the mapping service.
+
+::
+
+ DESCRIPTION
+ intent:map
+
+ List/Add/Delete current state from/to the mapping service.
+
+ SYNTAX
+ intent:map [options]
+
+ Examples: --list, -l [ENTER], to retrieve all keys.
+ --add-key <key> [ENTER], to add a new key with empty contents.
+ --del-key <key> [ENTER], to remove a key with it's values."
+ --add-key <key> --value [<value 1>, <value 2>, ...] [ENTER],
+ to add a new key with some values (json format).
+ OPTIONS
+ --help
+ Display this help message
+ -l, --list
+ List values associated with a particular key.
+ -l / --filter <regular expression> [ENTER]
+ --add-key
+ Adds a new key to the mapping service.
+ --add-key <key name> [ENTER]
+ --value
+ Specifies which value should be added/delete from the mapping service.
+ --value "key=>value"... --value "key=>value" [ENTER]
+ (defaults to [])
+ --del-key
+ Deletes a key from the mapping service.
+ --del-key <key name> [ENTER]
+
+NIC Usage Examples
+------------------
+
+Default Requirements
+~~~~~~~~~~~~~~~~~~~~
+
+Start mininet, and create three switches (s1, s2, and s3) and four hosts
+(h1, h2, h3, and h4) in it.
+
+Replace <Controller IP> based on your environment.
+
+::
+
+ $ sudo mn --mac --topo single,2 --controller=remote,ip=<Controller IP>
+
+::
+
+ mininet> net
+ h1 h1-eth0:s2-eth1
+ h2 h2-eth0:s2-eth2
+ h3 h3-eth0:s3-eth1
+ h4 h4-eth0:s3-eth2
+ s1 lo: s1-eth1:s2-eth3 s1-eth2:s3-eth3
+ s2 lo: s2-eth1:h1-eth0 s2-eth2:h2-eth0 s2-eth3:s1-eth1
+ s3 lo: s3-eth1:h3-eth0 s3-eth2:h4-eth0 s3-eth3:s1-eth2
+
+Downloading and deploy Karaf distribution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Get the Beryllium distribution.
+
+- Unzip the downloaded zip distribution.
+
+- To run the Karaf.
+
+::
+
+ ./bin/karaf
+
+- Once the console is up, type as below to install feature.
+
+::
+
+ feature:install odl-nic-core-mdsal odl-nic-console odl-nic-listeners
+
+Simple Mininet topology
+-----------------------
+
+.. code:: python
+
+ !/usr/bin/python
+
+ from mininet.topo import Topo
+
+ class SimpleTopology( Topo ):
+ "Simple topology example."
+
+ def __init__( self ):
+ "Create custom topo."
+
+
+ Topo.__init__( self )
+
+
+ Switch1 = self.addSwitch( 's1' )
+ Switch2 = self.addSwitch( 's2' )
+ Switch3 = self.addSwitch( 's3' )
+ Switch4 = self.addSwitch( 's4' )
+ Host11 = self.addHost( 'h1' )
+ Host12 = self.addHost( 'h2' )
+ Host21 = self.addHost( 'h3' )
+ Host22 = self.addHost( 'h4' )
+ Host23 = self.addHost( 'h5' )
+ Service1 = self.addHost( 'srvc1' )
+
+
+ self.addLink( Host11, Switch1 )
+ self.addLink( Host12, Switch1 )
+ self.addLink( Host21, Switch2 )
+ self.addLink( Host22, Switch2 )
+ self.addLink( Host23, Switch2 )
+ self.addLink( Switch1, Switch2 )
+ self.addLink( Switch2, Switch4 )
+ self.addLink( Switch4, Switch3 )
+ self.addLink( Switch3, Switch1 )
+ self.addLink( Switch3, Service1 )
+ self.addLink( Switch4, Service1 )
+
+
+ topos = { 'simpletopology': ( lambda: SimpleTopology() ) }
+
+- Initialize topology
+
+- Add hosts and switches
+
+- Host used to represent the service
+
+- Add links
+
+ Source: https://gist.github.com/vinothgithub15/315d0a427d5afc39f2d7
+
+How to configure VTN Renderer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The section demonstrates allow or block packets of the traffic within a
+VTN Renderer, according to the specified flow conditions.
+
+The table below lists the actions to be applied when a packet matches
+the condition:
+
++----------------+-----------------------------------------------------------+
+| Action | Function |
++================+===========================================================+
+| Allow | Permits the packet to be forwarded normally. |
++----------------+-----------------------------------------------------------+
+| Block | Discards the packet preventing it from being forwarded. |
++----------------+-----------------------------------------------------------+
+
+Requirement
+^^^^^^^^^^^
+
+- Before execute the follow steps, please, use default requirements.
+ See section `Default Requirements <#_default_requirements>`__.
+
+Configuration
+^^^^^^^^^^^^^
+
+Please execute the following curl commands to test network intent using
+mininet:
+
+Create Intent
+'''''''''''''
+
+To provision the network for the two hosts(h1 and h2) and demonstrates
+the action allow.
+
+::
+
+ curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X PUT http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436034 -d '{ "intent:intent" : { "intent:id": "b9a13232-525e-4d8c-be21-cd65e3436034", "intent:actions" : [ { "order" : 2, "allow" : {} } ], "intent:subjects" : [ { "order":1 , "end-point-group" : {"name":"10.0.0.1"} }, { "order":2 , "end-point-group" : {"name":"10.0.0.2"}} ] } }'
+
+To provision the network for the two hosts(h2 and h3) and demonstrates
+the action allow.
+
+::
+
+ curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X PUT http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436035 -d '{ "intent:intent" : { "intent:id": "b9a13232-525e-4d8c-be21-cd65e3436035", "intent:actions" : [ { "order" : 2, "allow" : {} } ], "intent:subjects" : [ { "order":1 , "end-point-group" : {"name":"10.0.0.2"} }, { "order":2 , "end-point-group" : {"name":"10.0.0.3"}} ] } }'
+
+Verification
+''''''''''''
+
+As we have applied action type allow now ping should happen between
+hosts (h1 and h2) and (h2 and h3).
+
+::
+
+ mininet> pingall
+ Ping: testing ping reachability
+ h1 -> h2 X X
+ h2 -> h1 h3 X
+ h3 -> X h2 X
+ h4 -> X X X
+
+Update the intent
+'''''''''''''''''
+
+To provision block action that indicates traffic is not allowed between
+h1 and h2.
+
+::
+
+ curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X PUT http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436034 -d '{ "intent:intent" : { "intent:id": "b9a13232-525e-4d8c-be21-cd65e3436034", "intent:actions" : [ { "order" : 2, "block" : {} } ], "intent:subjects" : [ { "order":1 , "end-point-group" : {"name":"10.0.0.1"} }, { "order":2 , "end-point-group" : {"name":"10.0.0.2"}} ] } }'
+
+Verification
+''''''''''''
+
+As we have applied action type block now ping should not happen between
+hosts (h1 and h2).
+
+::
+
+ mininet> pingall
+ Ping: testing ping reachability
+ h1 -> X X X
+ h2 -> X h3 X
+ h3 -> X h2 X
+ h4 -> X X X
+
+.. note::
+
+ Old actions and hosts are replaced by the new action and hosts.
+
+Delete the intent
+'''''''''''''''''
+
+Respective intent and the traffics will be deleted.
+
+::
+
+ curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X DELETE http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436035
+
+Verification
+''''''''''''
+
+Deletion of intent and flow.
+
+::
+
+ mininet> pingall
+ Ping: testing ping reachability
+ h1 -> X X X
+ h2 -> X X X
+ h3 -> X X X
+ h4 -> X X X
+
+.. note::
+
+ Ping between two hosts can also be done using MAC Address
+
+To provision the network for the two hosts(h1 MAC address and h2 MAC
+address).
+
+::
+
+ curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X PUT http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436035 -d '{ "intent:intent" : { "intent:id": "b9a13232-525e-4d8c-be21-cd65e3436035", "intent:actions" : [ { "order" : 2, "allow" : {} } ], "intent:subjects" : [ { "order":1 , "end-point-group" : {"name":"6e:4f:f7:27:15:c9"} }, { "order":2 , "end-point-group" : {"name":"aa:7d:1f:4a:70:81"}} ] } }'
+
+How to configure Redirect Action
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The section explains the redirect action supported in NIC. The redirect
+functionality supports forwarding (to redirect) the traffic to a service
+configured in SFC before forwarding it to the destination.
+
+.. figure:: ./images/nic/Service_Chaining.png
+ :alt: REDIRECT SERVICE
+
+ REDIRECT SERVICE
+
+Following steps explain Redirect action function:
+
+- Configure the service in SFC using the SFC APIs.
+
+- Configure the intent with redirect action and the service information
+ where the traffic needs to be redirected.
+
+- The flows are computed as below
+
+ 1. First flow entry between the source host connected node and the
+ ingress node of the configured service.
+
+ 2. Second flow entry between the egress Node id the configured
+ service and the ID and destination host connected host.
+
+ 3. Third flow entry between the destination host node and the source
+ host node.
+
+Requirement
+^^^^^^^^^^^
+
+- Save the mininet `Simple Mininet
+ topology <#_simple_mininet_topology>`__ script as redirect\_test.py
+
+- Start mininet, and create switches in it.
+
+Replace <Controller IP> based on your environment.
+
+::
+
+ sudo mn --controller=remote,ip=<Controller IP>--custom redirect_test.py --topo mytopo2
+
+::
+
+ mininet> net
+ h1 h1-eth0:s1-eth1
+ h2 h2-eth0:s1-eth2
+ h3 h3-eth0:s2-eth1
+ h4 h4-eth0:s2-eth2
+ h5 h5-eth0:s2-eth3
+ srvc1 srvc1-eth0:s3-eth3 srvc1-eth1:s4-eth3
+ s1 lo: s1-eth1:h1-eth0 s1-eth2:h2-eth0 s1-eth3:s2-eth4 s1-eth4:s3-eth2
+ s2 lo: s2-eth1:h3-eth0 s2-eth2:h4-eth0 s2-eth3:h5-eth0 s2-eth4:s1-eth3 s2-eth5:s4-eth1
+ s3 lo: s3-eth1:s4-eth2 s3-eth2:s1-eth4 s3-eth3:srvc1-eth0
+ s4 lo: s4-eth1:s2-eth5 s4-eth2:s3-eth1 s4-eth3:srvc1-eth1
+ c0
+
+Starting the Karaf
+^^^^^^^^^^^^^^^^^^
+
+- Before execute the following steps, please, use the default
+ requirements. See section `Downloading and deploy Karaf
+ distribution <#_default_requirements>`__.
+
+Configuration
+^^^^^^^^^^^^^
+
+Mininet
+'''''''
+
+.. figure:: ./images/nic/Redirect_flow.png
+ :alt: CONFIGURATION THE NETWORK IN MININET
+
+ CONFIGURATION THE NETWORK IN MININET
+
+- Configure srvc1 as service node in the mininet environment.
+
+Please execute the following commands in the mininet console (where
+mininet script is executed).
+
+::
+
+ srvc1 ip addr del 10.0.0.6/8 dev srvc1-eth0
+ srvc1 brctl addbr br0
+ srvc1 brctl addif br0 srvc1-eth0
+ srvc1 brctl addif br0 srvc1-eth1
+ srvc1 ifconfig br0 up
+ srvc1 tc qdisc add dev srvc1-eth1 root netem delay 200ms
+
+Configure service in SFC
+''''''''''''''''''''''''
+
+The service (srvc1) is configured using SFC REST API. As part of the
+configuration the ingress and egress node connected the service is
+configured.
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{
+ "service-functions": {
+ "service-function": [
+ {
+ "name": "srvc1",
+ "sf-data-plane-locator": [
+ {
+ "name": "Egress",
+ "service-function-forwarder": "openflow:4"
+ },
+ {
+ "name": "Ingress",
+ "service-function-forwarder": "openflow:3"
+ }
+ ],
+ "nsh-aware": false,
+ "type": "delay"
+ }
+ ]
+ }
+ }' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function:service-functions/
+
+**SFF RESTCONF Request**
+
+Configuring switch and port information for the service functions.
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{
+ "service-function-forwarders": {
+ "service-function-forwarder": [
+ {
+ "name": "openflow:3",
+ "service-node": "OVSDB2",
+ "sff-data-plane-locator": [
+ {
+ "name": "Ingress",
+ "data-plane-locator":
+ {
+ "vlan-id": 100,
+ "mac": "11:11:11:11:11:11",
+ "transport": "service-locator:mac"
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "port-id" : "3"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "name": "srvc1",
+ "sff-sf-data-plane-locator":
+ {
+ "sf-dpl-name" : "openflow:3",
+ "sff-dpl-name" : "Ingress"
+ }
+ }
+ ]
+ },
+ {
+ "name": "openflow:4",
+ "service-node": "OVSDB3",
+ "sff-data-plane-locator": [
+ {
+ "name": "Egress",
+ "data-plane-locator":
+ {
+ "vlan-id": 200,
+ "mac": "44:44:44:44:44:44",
+ "transport": "service-locator:mac"
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "port-id" : "3"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "name": "srvc1",
+ "sff-sf-data-plane-locator":
+ {
+ "sf-dpl-name" : "openflow:4",
+ "sff-dpl-name" : "Egress"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ }' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-forwarder:service-function-forwarders/
+
+CLI Command
+'''''''''''
+
+To provision the network for the two hosts (h1 and h5).
+
+Demonstrates the redirect action with service name srvc1.
+
+::
+
+ intent:add -f <SOURCE_MAC> -t <DESTINATION_MAC> -a REDIRECT -s <SERVICE_NAME>
+
+Example:
+
+::
+
+ intent:add -f 32:bc:ec:65:a7:d1 -t c2:80:1f:77:41:ed -a REDIRECT -s srvc1
+
+Verification
+''''''''''''
+
+- As we have applied action type redirect now ping should happen
+ between hosts h1 and h5.
+
+::
+
+ mininet> h1 ping h5
+ PING 10.0.0.5 (10.0.0.5) 56(84) bytes of data.
+ 64 bytes from 10.0.0.5: icmp_seq=2 ttl=64 time=201 ms
+ 64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=200 ms
+ 64 bytes from 10.0.0.5: icmp_seq=4 ttl=64 time=200 ms
+
+The redirect functionality can be verified by the time taken by the ping
+operation (200ms). The service srvc1 configured using SFC introduces
+200ms delay. As the traffic from h1 to h5 is redirected via the srvc1,
+the time taken by the traffic from h1 to h5 will take about 200ms.
+
+- Flow entries added to nodes for the redirect action.
+
+::
+
+ mininet> dpctl dump-flows
+ *** s1 ------------------------------------------------------------------------
+ NXST_FLOW reply (xid=0x4):
+ cookie=0x0, duration=9.406s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=1,dl_src=32:bc:ec:65:a7:d1, dl_dst=c2:80:1f:77:41:ed actions=output:4
+ cookie=0x0, duration=9.475s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=3,dl_src=c2:80:1f:77:41:ed, dl_dst=32:bc:ec:65:a7:d1 actions=output:1
+ cookie=0x1, duration=362.315s, table=0, n_packets=144, n_bytes=12240, idle_age=4, priority=9500,dl_type=0x88cc actions=CONTROLLER:65535
+ cookie=0x1, duration=362.324s, table=0, n_packets=4, n_bytes=168, idle_age=3, priority=10000,arp actions=CONTROLLER:65535,NORMAL
+ *** s2 ------------------------------------------------------------------------
+ NXST_FLOW reply (xid=0x4):
+ cookie=0x0, duration=9.503s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=3,dl_src=c2:80:1f:77:41:ed, dl_dst=32:bc:ec:65:a7:d1 actions=output:4
+ cookie=0x0, duration=9.437s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=5,dl_src=32:bc:ec:65:a7:d1, dl_dst=c2:80:1f:77:41:ed actions=output:3
+ cookie=0x3, duration=362.317s, table=0, n_packets=144, n_bytes=12240, idle_age=4, priority=9500,dl_type=0x88cc actions=CONTROLLER:65535
+ cookie=0x3, duration=362.32s, table=0, n_packets=4, n_bytes=168, idle_age=3, priority=10000,arp actions=CONTROLLER:65535,NORMAL
+ *** s3 ------------------------------------------------------------------------
+ NXST_FLOW reply (xid=0x4):
+ cookie=0x0, duration=9.41s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=2,dl_src=32:bc:ec:65:a7:d1, dl_dst=c2:80:1f:77:41:ed actions=output:3
+ *** s4 ------------------------------------------------------------------------
+ NXST_FLOW reply (xid=0x4):
+ cookie=0x0, duration=9.486s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=3,dl_src=32:bc:ec:65:a7:d1, dl_dst=c2:80:1f:77:41:ed actions=output:1
+
+How to configure QoS Attribute Mapping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section explains how to provision QoS attribute mapping constraint
+using NIC OF-Renderer.
+
+The QoS attribute mapping currently supports DiffServ. It uses a 6-bit
+differentiated services code point (DSCP) in the 8-bit differentiated
+services field (DS field) in the IP header.
+
++----------------+-----------------------------------------------------------+
+| Action | Function |
++================+===========================================================+
+| Allow | Permits the packet to be forwarded normally, but allows |
+| | for packet header fields, e.g., DSCP, to be modified. |
++----------------+-----------------------------------------------------------+
+
+The following steps explain QoS Attribute Mapping function:
+
+- Initially configure the QoS profile which contains profile name and
+ DSCP value.
+
+- When a packet is transferred from a source to destination, the flow
+ builder evaluates whether the transferred packet matches the
+ condition such as action, endpoints in the flow.
+
+- If the packet matches the endpoints, the flow builder applies the
+ flow matching action and DSCP value.
+
+Requirement
+^^^^^^^^^^^
+
+- Before execute the following steps, please, use the default
+ requirements. See section `Default
+ Requirements <#_default_requirements>`__.
+
+Configuration
+^^^^^^^^^^^^^
+
+Please execute the following CLI commands to test network intent using
+mininet:
+
+- To apply the QoS constraint, configure the QoS profile.
+
+::
+
+ intent:qosConfig -p <qos_profile_name> -d <valid_dscp_value>
+
+Example:
+
+::
+
+ intent:qosConfig -p High_Quality -d 46
+
+.. note::
+
+ Valid DSCP value ranges from 0-63.
+
+- To provision the network for the two hosts (h1 and h3), add intents
+ that allows traffic in both directions by execute the following CLI
+ command.
+
+Demonstrates the ALLOW action with constraint QoS and QoS profile name.
+
+::
+
+ intent:add -a ALLOW -t <DESTINATION_MAC> -f <SOURCE_MAC> -q QOS -p <qos_profile_name>
+
+Example:
+
+::
+
+ intent:add -a ALLOW -t 00:00:00:00:00:03 -f 00:00:00:00:00:01 -q QOS -p High_Quality
+ intent:add -a ALLOW -t 00:00:00:00:00:01 -f 00:00:00:00:00:03 -q QOS -p High_Quality
+
+Verification
+''''''''''''
+
+- As we have applied action type ALLOW now ping should happen between
+ hosts h1 and h3.
+
+::
+
+ mininet> h1 ping h3
+ PING 10.0.0.3 (10.0.0.3) 56(84) bytes of data.
+ 64 bytes from 10.0.0.3: icmp_req=1 ttl=64 time=0.984 ms
+ 64 bytes from 10.0.0.3: icmp_req=2 ttl=64 time=0.110 ms
+ 64 bytes from 10.0.0.3: icmp_req=3 ttl=64 time=0.098 ms
+
+- Verification of the flow entry and ensuring the mod\_nw\_tos is part
+ of actions.
+
+::
+
+ mininet> dpctl dump-flows
+ *** s1 ------------------------------------------------------------------------
+ NXST_FLOW reply (xid=0x4):
+ cookie=0x0, duration=21.873s, table=0, n_packets=3, n_bytes=294, idle_age=21, priority=9000,dl_src=00:00:00:00:00:03,dl_dst=00:00:00:00:00:01 actions=NORMAL,mod_nw_tos:184
+ cookie=0x0, duration=41.252s, table=0, n_packets=3, n_bytes=294, idle_age=41, priority=9000,dl_src=00:00:00:00:00:01,dl_dst=00:00:00:00:00:03 actions=NORMAL,mod_nw_tos:184
+
+Requirement
+~~~~~~~~~~~
+
+- Before execute the follow steps, please, use default requirements.
+ See section `Default Requirements <#_default_requirements>`__.
+
+How to configure Log Action
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section demonstrates log action in OF Renderer. This demonstration
+aims at enabling communication between two hosts and logging the flow
+statistics details of the particular traffic.
+
+Configuration
+^^^^^^^^^^^^^
+
+Please execute the following CLI commands to test network intent using
+mininet:
+
+- To provision the network for the two hosts (h1 and h3), add intents
+ that allows traffic in both directions by execute the following CLI
+ command.
+
+::
+
+ intent:add –a ALLOW -t <DESTINATION_MAC> -f <SOURCE_MAC>
+
+Example:
+
+::
+
+ intent:add -a ALLOW -t 00:00:00:00:00:03 -f 00:00:00:00:00:01
+ intent:add -a ALLOW -t 00:00:00:00:00:01 -f 00:00:00:00:00:03
+
+- To log the flow statistics details of the particular traffic.
+
+::
+
+ intent:add –a LOG -t <DESTINATION_MAC> -f <SOURCE_MAC>
+
+Example:
+
+::
+
+ intent:add -a LOG -t 00:00:00:00:00:03 -f 00:00:00:00:00:01
+
+Verification
+''''''''''''
+
+- As we have applied action type ALLOW now ping should happen between
+ hosts h1 and h3.
+
+::
+
+ mininet> h1 ping h3
+ PING 10.0.0.3 (10.0.0.3) 56(84) bytes of data.
+ 64 bytes from 10.0.0.3: icmp_req=1 ttl=64 time=0.984 ms
+ 64 bytes from 10.0.0.3: icmp_req=2 ttl=64 time=0.110 ms
+ 64 bytes from 10.0.0.3: icmp_req=3 ttl=64 time=0.098 ms
+
+- To view the flow statistics log details such as, byte count, packet
+ count and duration, check the karaf.log.
+
+::
+
+ 2015-12-15 22:56:20,256 | INFO | lt-dispatcher-23 | IntentFlowManager | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Creating block intent for endpoints: source00:00:00:00:00:01 destination 00:00:00:00:00:03
+ 2015-12-15 22:56:20,252 | INFO | lt-dispatcher-29 | FlowStatisticsListener | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Flow Statistics gathering for Byte Count:Counter64 [_value=238]
+ 2015-12-15 22:56:20,252 | INFO | lt-dispatcher-29 | FlowStatisticsListener | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Flow Statistics gathering for Packet Count:Counter64 [_value=3]
+ 2015-12-15 22:56:20,252 | INFO | lt-dispatcher-29 | FlowStatisticsListener | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Flow Statistics gathering for Duration in Nano second:Counter32 [_value=678000000]
+ 2015-12-15 22:56:20,252 | INFO | lt-dispatcher-29 | FlowStatisticsListener | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Flow Statistics gathering for Duration in Second:Counter32 [_value=49]
+
--- /dev/null
+Neutron Service User Guide
+==========================
+
+Overview
+--------
+
+This Karaf feature (``odl-neutron-service``) provides integration
+support for OpenStack Neutron via the OpenDaylight ML2 mechanism driver.
+The Neutron Service is only one of the components necessary for
+OpenStack integration. For those related components please refer to
+documentations of each component:
+
+- https://wiki.openstack.org/wiki/Neutron
+
+- https://launchpad.net/networking-odl
+
+- http://git.openstack.org/cgit/openstack/networking-odl/
+
+- https://wiki.opendaylight.org/view/NeutronNorthbound:Main
+
+Use cases and who will use the feature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want OpenStack integration with OpenDaylight, you will need this
+feature with an OpenDaylight provider feature like ovsdb/netvirt, group
+based policy, VTN, and lisp mapper. For provider configuration, please
+refer to each individual provider’s documentation. Since the Neutron
+service only provides the northbound API for the OpenStack Neutron ML2
+mechanism driver. Without those provider features, the Neutron service
+itself isn’t useful.
+
+Neutron Service feature Architecture
+------------------------------------
+
+The Neutron service provides northbound API for OpenStack Neutron via
+RESTCONF and also its dedicated REST API. It communicates through its
+YANG model with providers.
+
+.. figure:: ./images/neutron/odl-neutron-service-architecture.png
+ :alt: Neutron Service Architecture
+
+ Neutron Service Architecture
+
+Configuring Neutron Service feature
+-----------------------------------
+
+As the Karaf feature includes everything necessary for communicating
+northbound, no special configuration is needed. Usually this feature is
+used with an OpenDaylight southbound plugin that implements actual
+network virtualization functionality and OpenStack Neutron. The user
+wants to setup those configurations. Refer to each related
+documentations for each configurations.
+
+Administering or Managing ``odl-neutron-service``
+-------------------------------------------------
+
+There is no specific configuration regarding to Neutron service itself.
+For related configuration, please refer to OpenStack Neutron
+configuration and OpenDaylight related services which are providers for
+OpenStack.
+
+installing ``odl-neutron-service`` while the controller running
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. While OpenDaylight is running, in Karaf prompt, type:
+ ``feature:install odl-neutron-service``.
+
+2. Wait a while until the initialization is done and the controller
+ stabilizes.
+
+``odl-neutron-service`` provides only a unified interface for OpenStack
+Neutron. It doesn’t provide actual functionality for network
+virtualization. Refer to each OpenDaylight project documentation for
+actual configuration with OpenStack Neutron.
+
+Neutron Logger
+--------------
+
+Another service, the Neutron Logger, is provided for debugging/logging
+purposes. It logs changes on Neutron YANG models.
+
+::
+
+ feature:install odl-neutron-logger
+
--- /dev/null
+OF-CONFIG User Guide
+====================
+
+Overview
+--------
+
+OF-CONFIG defines an OpenFlow switch as an abstraction called an
+OpenFlow Logical Switch. The OF-CONFIG protocol enables configuration of
+essential artifacts of an OpenFlow Logical Switch so that an OpenFlow
+controller can communicate and control the OpenFlow Logical switch via
+the OpenFlow protocol. OF-CONFIG introduces an operating context for one
+or more OpenFlow data paths called an OpenFlow Capable Switch for one or
+more switches. An OpenFlow Capable Switch is intended to be equivalent
+to an actual physical or virtual network element (e.g. an Ethernet
+switch) which is hosting one or more OpenFlow data paths by partitioning
+a set of OpenFlow related resources such as ports and queues among the
+hosted OpenFlow data paths. The OF-CONFIG protocol enables dynamic
+association of the OpenFlow related resources of an OpenFlow Capable
+Switch with specific OpenFlow Logical Switches which are being hosted on
+the OpenFlow Capable Switch. OF-CONFIG does not specify or report how
+the partitioning of resources on an OpenFlow Capable Switch is achieved.
+OF-CONFIG assumes that resources such as ports and queues are
+partitioned amongst multiple OpenFlow Logical Switches such that each
+OpenFlow Logical Switch can assume full control over the resources that
+is assigned to it.
+
+How to start
+------------
+
+- start OF-CONFIG feature as below:
+
+ ::
+
+ feature:install odl-of-config-all
+
+Configuration on the OVS supporting OF-CONFIG
+---------------------------------------------
+
+.. note::
+
+ OVS is not supported by OF-CONFIG temporarily because the
+ OpenDaylight version of OF-CONFIG is 1.2 while the OVS version of
+ OF-CONFIG is not standard.
+
+The introduction of configuring the OVS can be referred to:
+
+*https://github.com/openvswitch/of-config.*
+
+Connection Establishment between the Capable/Logical Switch and OF-CONFIG
+-------------------------------------------------------------------------
+
+The OF-CONFIG protocol is based on NETCONF. So the switches supporting
+OF-CONFIG can also access OpenDaylight using the functions provided by
+NETCONF. This is the preparation step before connecting to OF-CONFIG.
+How to access the switch to OpenDaylight using the NETCONF can be
+referred to the `NETCONF Southbound User
+Guide <#_southbound_netconf_connector>`__ or `NETCONF Southbound
+examples on the
+wiki <https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf>`__.
+
+Now the switches supporting OF-CONFIG and they have connected to the
+controller using NETCONF as described in preparation phase. OF-CONFIG
+can check whether the switch can support OF-CONFIG by reading the
+capability list in NETCONF.
+
+The OF-CONFIG will get the information of the capable switch and logical
+switch via the NETCONF connection, and creates separate topologies for
+the capable and logical switches in the OpenDaylight Topology module.
+
+The Connection between the capable/logical switches and OF-CONFIG is
+finished.
+
+Configuration On Capable Switch
+-------------------------------
+
+Here is an example showing how to make the configuration to
+modify-controller-connection on the capable switch using OF-CONFIG.
+Other configurations can follow the same way of the example.
+
+- Example: modify-controller-connection
+
+.. note::
+
+ this configuration can execute via the NETCONF, which can be
+ referred to the `NETCONF Southbound User
+ Guide <#_southbound_netconf_connector>`__ or `NETCONF Southbound
+ examples on the
+ wiki <https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf>`__.
+
--- /dev/null
+OpenDaylight Controller Overview
+================================
+
+The OpenDaylight controller is JVM software and can be run from any
+operating system and hardware as long as it supports Java. The
+controller is an implementation of the Software Defined Network (SDN)
+concept and makes use of the following tools:
+
+- **Maven**: OpenDaylight uses Maven for easier build automation. Maven
+ uses pom.xml (Project Object Model) to script the dependencies
+ between bundle and also to describe what bundles to load and start.
+
+- **OSGi**: This framework is the back-end of OpenDaylight as it allows
+ dynamically loading bundles and packages JAR files, and binding
+ bundles together for exchanging information.
+
+- **JAVA interfaces**: Java interfaces are used for event listening,
+ specifications, and forming patterns. This is the main way in which
+ specific bundles implement call-back functions for events and also to
+ indicate awareness of specific state.
+
+- **REST APIs**: These are northbound APIs such as topology manager,
+ host tracker, flow programmer, static routing, and so on.
+
+The controller exposes open northbound APIs which are used by
+applications. The OSGi framework and bidirectional REST are supported
+for the northbound APIs. The OSGi framework is used for applications
+that run in the same address space as the controller while the REST
+(web-based) API is used for applications that do not run in the same
+address space (or even the same system) as the controller. The business
+logic and algorithms reside in the applications. These applications use
+the controller to gather network intelligence, run its algorithm to do
+analytics, and then orchestrate the new rules throughout the network. On
+the southbound, multiple protocols are supported as plugins, e.g.
+OpenFlow 1.0, OpenFlow 1.3, BGP-LS, and so on. The OpenDaylight
+controller starts with an OpenFlow 1.0 southbound plugin. Other
+OpenDaylight contributors begin adding to the controller code. These
+modules are linked dynamically into a **Service Abstraction Layer**
+(SAL).
+
+The SAL exposes services to which the modules north of it are written.
+The SAL figures out how to fulfill the requested service irrespective of
+the underlying protocol used between the controller and the network
+devices. This provides investment protection to the applications as
+OpenFlow and other protocols evolve over time. For the controller to
+control devices in its domain, it needs to know about the devices, their
+capabilities, reachability, and so on. This information is stored and
+managed by the **Topology Manager**. The other components like ARP
+handler, Host Tracker, Device Manager, and Switch Manager help in
+generating the topology database for the Topology Manager.
+
+For a more detailed overview of the OpenDaylight controller, see the
+*OpenDaylight Developer Guide*.
+
--- /dev/null
+OpFlex agent-ovs User Guide
+===========================
+
+Introduction
+------------
+
+agent-ovs is a policy agent that works with OVS to enforce a group-based
+policy networking model with locally attached virtual machines or
+containers. The policy agent is designed to work well with orchestration
+tools like OpenStack.
+
+Agent Configuration
+-------------------
+
+The agent configuration is handled using its config file which is by
+default found at "/etc/opflex-agent-ovs/opflex-agent-ovs.conf"
+
+Here is an example configuration file that documents the available
+options:
+
+::
+
+ {
+ // Logging configuration
+ // "log": {
+ // "level": "info"
+ // },
+
+ // Configuration related to the OpFlex protocol
+ "opflex": {
+ // The policy domain for this agent.
+ "domain": "openstack",
+
+ // The unique name in the policy domain for this agent.
+ "name": "example-agent",
+
+ // a list of peers to connect to, by hostname and port. One
+ // peer, or an anycast pseudo-peer, is sufficient to bootstrap
+ // the connection without needing an exhaustive list of all
+ // peers.
+ "peers": [
+ // EXAMPLE:
+ {"hostname": "10.0.0.30", "port": 8009}
+ ],
+
+ "ssl": {
+ // SSL mode. Possible values:
+ // disabled: communicate without encryption
+ // encrypted: encrypt but do not verify peers
+ // secure: encrypt and verify peer certificates
+ "mode": "disabled",
+
+ // The path to a directory containing trusted certificate
+ // authority public certificates, or a file containing a
+ // specific CA certificate.
+ "ca-store": "/etc/ssl/certs/"
+ },
+
+ "inspector": {
+ // Enable the MODB inspector service, which allows
+ // inspecting the state of the managed object database.
+ // Default: enabled
+ "enabled": true,
+
+ // Listen on the specified socket for the inspector
+ // Default /var/run/opflex-agent-ovs-inspect.sock
+ "socket-name": "/var/run/opflex-agent-ovs-inspect.sock"
+ }
+ },
+
+ // Endpoint sources provide metadata about local endpoints
+ "endpoint-sources": {
+ // Filesystem path to monitor for endpoint information
+ "filesystem": ["/var/lib/opflex-agent-ovs/endpoints"]
+ },
+
+ // Renderers enforce policy obtained via OpFlex.
+ "renderers": {
+ // Stitched-mode renderer for interoperating with a
+ // hardware fabric such as ACI
+ // EXAMPLE:
+ "stitched-mode": {
+ "ovs-bridge-name": "br0",
+
+ // Set encapsulation type. Must set either vxlan or vlan.
+ "encap": {
+ // Encapsulate traffic with VXLAN.
+ "vxlan" : {
+ // The name of the tunnel interface in OVS
+ "encap-iface": "br0_vxlan0",
+
+ // The name of the interface whose IP should be used
+ // as the source IP in encapsulated traffic.
+ "uplink-iface": "eth0.4093",
+
+ // The vlan tag, if any, used on the uplink interface.
+ // Set to zero or omit if the uplink is untagged.
+ "uplink-vlan": 4093,
+
+ // The IP address used for the destination IP in
+ // the encapsulated traffic. This should be an
+ // anycast IP address understood by the upstream
+ // stiched-mode fabric.
+ "remote-ip": "10.0.0.32",
+
+ // UDP port number of the encapsulated traffic.
+ "remote-port": 8472
+ }
+
+ // Encapsulate traffic with a locally-significant VLAN
+ // tag
+ // EXAMPLE:
+ // "vlan" : {
+ // // The name of the uplink interface in OVS
+ // "encap-iface": "team0"
+ // }
+ },
+
+ // Configure forwarding policy
+ "forwarding": {
+ // Configure the virtual distributed router
+ "virtual-router": {
+ // Enable virtual distributed router. Set to true
+ // to enable or false to disable. Default true.
+ "enabled": true,
+
+ // Override MAC address for virtual router.
+ // Default is "00:22:bd:f8:19:ff"
+ "mac": "00:22:bd:f8:19:ff",
+
+ // Configure IPv6-related settings for the virtual
+ // router
+ "ipv6" : {
+ // Send router advertisement messages in
+ // response to router solicitation requests as
+ // well as unsolicited advertisements. This
+ // is not required in stitched mode since the
+ // hardware router will send them.
+ "router-advertisement": true
+ }
+ },
+
+ // Configure virtual distributed DHCP server
+ "virtual-dhcp": {
+ // Enable virtual distributed DHCP server. Set to
+ // true to enable or false to disable. Default
+ // true.
+ "enabled": true,
+
+ // Override MAC address for virtual dhcp server.
+ // Default is "00:22:bd:f8:19:ff"
+ "mac": "00:22:bd:f8:19:ff"
+ },
+
+ "endpoint-advertisements": {
+ // Enable generation of periodic ARP/NDP
+ // advertisements for endpoints. Default true.
+ "enabled": "true"
+ }
+ },
+
+ // Location to store cached IDs for managing flow state
+ "flowid-cache-dir": "/var/lib/opflex-agent-ovs/ids"
+ }
+ }
+ }
+
+Endpoint Registration
+---------------------
+
+The agent learns about endpoints using endpoint metadata files located
+by default in "/var/lib/opflex-agent-ovs/endpoints".
+
+These are JSON-format files such as the (unusually complex) example
+below:
+
+::
+
+ {
+ "uuid": "83f18f0b-80f7-46e2-b06c-4d9487b0c754",
+ "policy-space-name": "test",
+ "endpoint-group-name": "group1",
+ "interface-name": "veth0",
+ "ip": [
+ "10.0.0.1", "fd8f:69d8:c12c:ca62::1"
+ ],
+ "dhcp4": {
+ "ip": "10.200.44.2",
+ "prefix-len": 24,
+ "routers": ["10.200.44.1"],
+ "dns-servers": ["8.8.8.8", "8.8.4.4"],
+ "domain": "example.com",
+ "static-routes": [
+ {
+ "dest": "169.254.169.0",
+ "dest-prefix": 24,
+ "next-hop": "10.0.0.1"
+ }
+ ]
+ },
+ "dhcp6": {
+ "dns-servers": ["2001:4860:4860::8888", "2001:4860:4860::8844"],
+ "search-list": ["test1.example.com", "example.com"]
+ },
+ "ip-address-mapping": [
+ {
+ "uuid": "91c5b217-d244-432c-922d-533c6c036ab4",
+ "floating-ip": "5.5.5.1",
+ "mapped-ip": "10.0.0.1",
+ "policy-space-name": "common",
+ "endpoint-group-name": "nat-epg"
+ },
+ {
+ "uuid": "22bfdc01-a390-4b6f-9b10-624d4ccb957b",
+ "floating-ip": "fdf1:9f86:d1af:6cc9::1",
+ "mapped-ip": "fd8f:69d8:c12c:ca62::1",
+ "policy-space-name": "common",
+ "endpoint-group-name": "nat-epg"
+ }
+ ],
+ "mac": "00:00:00:00:00:01",
+ "promiscuous-mode": false
+ }
+
+The possible parameters for these files are:
+
+**uuid**
+ A globally unique ID for the endpoint
+
+**endpoint-group-name**
+ The name of the endpoint group for the endpoint
+
+**policy-space-name**
+ The name of the policy space for the endpoint group.
+
+**interface-name**
+ The name of the OVS interface to which the endpoint is attached
+
+**ip**
+ A list of strings contains either IPv4 or IPv6 addresses that the
+ endpoint is allowed to use
+
+**mac**
+ The MAC address for the endpoint’s interface.
+
+**promiscuous-mode**
+ Allow traffic from this VM to bypass default port security
+
+**dhcp4**
+ A distributed DHCPv4 configuration block (see below)
+
+**dhcp6**
+ A distributed DHCPv6 configuration block (see below)
+
+**ip-address-mapping**
+ A list of IP address mapping configuration blocks (see below)
+
+DHCPv4 configuration blocks can contain the following parameters:
+
+**ip**
+ the IP address to return with DHCP. Must be one of the configured
+ IPv4 addresses.
+
+**prefix**
+ the subnet prefix length
+
+**routers**
+ a list of default gateways for the endpoint
+
+**dns**
+ a list of DNS server addresses
+
+**domain**
+ The domain name parameter to send in the DHCP reply
+
+**static-routes**
+ A list of static route configuration blocks, which contains a
+ "dest", "dest-prefix", and "next-hop" parameters to send as static
+ routes to the end host
+
+DHCPv6 configuration blocks can contain the following parameters:
+
+**dns**
+ A list of DNS servers for the endpoint
+
+**search-patch**
+ The DNS search path for the endpoint
+
+IP address mapping configuration blocks can contain the following
+parameters:
+
+**uuid**
+ a globally unique ID for the virtual endpoint created by the
+ mapping.
+
+**floating-ip**
+ Map using DNAT to this floating IPv4 or IPv6 address
+
+**mapped-ip**
+ the source IPv4 or IPv6 address; must be one of the IPs assigned to
+ the endpoint.
+
+**endpoint-group-name**
+ The name of the endpoint group for the NATed IP
+
+**policy-space-name**
+ The name of the policy space for the NATed IP
+
+Inspector
+---------
+
+The Opflex inspector is a useful command-line tool that will allow you
+to inspect the state of the managed object database for the agent for
+debugging and diagnosis purposes.
+
+The command is called "gbp\_inspect" and takes the following arguments:
+
+::
+
+ # gbp_inspect -h
+ Usage: ./gbp_inspect [options]
+ Allowed options:
+ -h [ --help ] Print this help message
+ --log arg Log to the specified file (default
+ standard out)
+ --level arg (=warning) Use the specified log level (default
+ info)
+ --syslog Log to syslog instead of file or
+ standard out
+ --socket arg (=/usr/local/var/run/opflex-agent-ovs-inspect.sock)
+ Connect to the specified UNIX domain
+ socket (default /usr/local/var/run/opfl
+ ex-agent-ovs-inspect.sock)
+ -q [ --query ] arg Query for a specific object with
+ subjectname,uri or all objects of a
+ specific type with subjectname
+ -r [ --recursive ] Retrieve the whole subtree for each
+ returned object
+ -f [ --follow-refs ] Follow references in returned objects
+ --load arg Load managed objects from the specified
+ file into the MODB view
+ -o [ --output ] arg Output the results to the specified
+ file (default standard out)
+ -t [ --type ] arg (=tree) Specify the output format: tree, list,
+ or dump (default tree)
+ -p [ --props ] Include object properties in output
+
+Here are some examples of the ways to use this tool.
+
+You can get information about the running system using one or more
+queries, which consist of an object model class name and optionally the
+URI of a specific object. The simplest query is to get a single object,
+nonrecursively:
+
+::
+
+ # gbp_inspect -q DmtreeRoot
+ --* DmtreeRoot,/
+ # gbp_inspect -q GbpEpGroup
+ --* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
+ --* GbpEpGroup,/PolicyUniverse/PolicySpace/test/GbpEpGroup/group1/
+ # gbp_inspect -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
+ --* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
+
+You can also display all the properties for each object:
+
+::
+
+ # gbp_inspect -p -q GbpeL24Classifier
+ --* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier4/
+ {
+ connectionTracking : 1 (reflexive)
+ dFromPort : 80
+ dToPort : 80
+ etherT : 2048 (ipv4)
+ name : classifier4
+ prot : 6
+ }
+ --* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier3/
+ {
+ etherT : 34525 (ipv6)
+ name : classifier3
+ order : 100
+ prot : 58
+ }
+ --* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier2/
+ {
+ etherT : 2048 (ipv4)
+ name : classifier2
+ order : 101
+ prot : 1
+ }
+
+You can also request to get the all the children of an object you query
+for:
+
+::
+
+ # gbp_inspect -r -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
+ --* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
+ |-* GbpeInstContext,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpeInstContext/
+ `-* GbpEpGroupToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpEpGroupToNetworkRSrc/
+
+You can also follow references found in any object downloads:
+
+::
+
+ # gbp_inspect -fr -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
+ --* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
+ |-* GbpeInstContext,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpeInstContext/
+ `-* GbpEpGroupToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpEpGroupToNetworkRSrc/
+ --* GbpFloodDomain,/PolicyUniverse/PolicySpace/common/GbpFloodDomain/fd_ext/
+ `-* GbpFloodDomainToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpFloodDomain/fd_ext/GbpFloodDomainToNetworkRSrc/
+ --* GbpBridgeDomain,/PolicyUniverse/PolicySpace/common/GbpBridgeDomain/bd_ext/
+ `-* GbpBridgeDomainToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpBridgeDomain/bd_ext/GbpBridgeDomainToNetworkRSrc/
+ --* GbpRoutingDomain,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/
+ |-* GbpRoutingDomainToIntSubnetsRSrc,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/GbpRoutingDomainToIntSubnetsRSrc/122/%2fPolicyUniverse%2fPolicySpace%2fcommon%2fGbpSubnets%2fsubnets_ext%2f/
+ `-* GbpForwardingBehavioralGroupToSubnetsRSrc,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/GbpForwardingBehavioralGroupToSubnetsRSrc/
+ --* GbpSubnets,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/
+ |-* GbpSubnet,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/GbpSubnet/subnet_ext4/
+ `-* GbpSubnet,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/GbpSubnet/subnet_ext6/
+
--- /dev/null
+Running XSQL Console Commands and Queries
+=========================================
+
+XSQL Overview
+-------------
+
+XSQL is an XML-based query language that describes simple stored
+procedures which parse XML data, query or update database tables, and
+compose XML output. XSQL allows you to query tree models like a
+sequential database. For example, you could run a query that lists all
+of the ports configured on a particular module and their attributes.
+
+The following sections cover the XSQL installation process, supported
+XSQL commands, and the way to structure queries.
+
+Installing XSQL
+---------------
+
+To run commands from the XSQL console, you must first install XSQL on
+your system:
+
+1. Navigate to the directory in which you unzipped OpenDaylight
+
+2. Start Karaf:
+
+ ::
+
+ ./bin/karaf
+
+3. Install XSQL:
+
+ ::
+
+ feature:install odl-mdsal-xsql
+
+XSQL Console Commands
+---------------------
+
+To enter a command in the XSQL console, structure the command as
+follows: **odl:xsql** *<XSQL command>*
+
+The following table describes the commands supported in this
+OpenDaylight release.
+
++-----------------------+----------------------------------------------------+
+| **Command** | **Description** |
++-----------------------+----------------------------------------------------+
+| **r** | Repeats the last command you executed. |
++-----------------------+----------------------------------------------------+
+| **list vtables** | Lists the schema node containers that are |
+| | currently installed. Whenever an OpenDaylight |
+| | module is installed, its YANG model is placed in |
+| | the schema context. At that point, the XSQL |
+| | receives a notification, confirms that the |
+| | module’s YANG model resides in the schema context |
+| | and then maps the model to XSQL by setting up the |
+| | necessary vtables and vfields. This command is |
+| | useful when you need to determine vtable |
+| | information for a query. |
++-----------------------+----------------------------------------------------+
+| **list vfields** | Lists the vfields present in a specific vtable. |
+| *<vtable name>* | This command is useful when you need to determine |
+| | vfields information for a query. |
++-----------------------+----------------------------------------------------+
+| **jdbc** *<ip | When the ODL server is behind a firewall, and the |
+| address>* | JDBC client cannot connect to the JDBC server, run |
+| | this command to start the client as a server and |
+| | establish a connection. |
++-----------------------+----------------------------------------------------+
+| **exit** | Closes the console. |
++-----------------------+----------------------------------------------------+
+| **tocsv** | Enables or disables the forwarding of query output |
+| | as a .csv file. |
++-----------------------+----------------------------------------------------+
+| **filename** | Specifies the .tocsv file to which the query data |
+| *<filename>* | is exported. If you do not specify a value for |
+| | this option when the toccsv option is enabled, the |
+| | filename for the query data file is generated |
+| | automatically. |
++-----------------------+----------------------------------------------------+
+
+Table: Supported XSQL Console Commands
+
+XSQL Queries
+------------
+
+You can run a query to extract information that meets the criteria you
+specify using the information provided by the **list vtables** and
+**list vfields** *<vtable name>* commands. Any query you run should be
+structured as follows:
+
+**select** *<vfields you want to search for, separated by a comma and a
+space>* **from** *<vtables you want to search in, separated by a comma
+and a space>* **where** *<criteria>* ***\*\ *<criteria operator>****;\*
+
+For example, if you want to search the nodes/node ID field in the
+nodes/node-connector table and find every instance of the
+Hardware-Address object that contains *BA* in its text string, enter the
+following query:
+
+::
+
+ select nodes/node.ID from nodes/node-connector where Hardware-Address like '%BA%';
+
+The following criteria operators are supported:
+
++----------------+-----------------------------------------------------------+
+| **Criteria | **Description** |
+| Operators** | |
++----------------+-----------------------------------------------------------+
+| **=** | Lists results that equal the value you specify. |
++----------------+-----------------------------------------------------------+
+| **!=** | Lists results that do not equal the value you specify. |
++----------------+-----------------------------------------------------------+
+| **like** | Lists results that contain the substring you specify. For |
+| | example, if you specify **like %BC%**, every string that |
+| | contains that particular substring is displayed. |
++----------------+-----------------------------------------------------------+
+| **<** | Lists results that are less than the value you specify. |
++----------------+-----------------------------------------------------------+
+| **>** | Lists results that are more than the value you specify. |
++----------------+-----------------------------------------------------------+
+| **and** | Lists results that match both values you specify. |
++----------------+-----------------------------------------------------------+
+| **or** | Lists results that match either of the two values you |
+| | specify. |
++----------------+-----------------------------------------------------------+
+| **>=** | Lists results that are more than or equal to the value |
+| | you specify. |
++----------------+-----------------------------------------------------------+
+| **⇐** | Lists results that are less than or equal to the value |
+| | you specify. |
++----------------+-----------------------------------------------------------+
+| **is null** | Lists results for which no value is assigned. |
++----------------+-----------------------------------------------------------+
+| **not null** | Lists results for which any value is assigned. |
++----------------+-----------------------------------------------------------+
+| **skip** | Use this operator to list matching results from a child |
+| | node, even if its parent node does not meet the specified |
+| | criteria. See the following example for more information. |
++----------------+-----------------------------------------------------------+
+
+Table: Supported XSQL Query Criteria Operators
+
+Example: Skip Criteria Operator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are looking at the following structure and want to determine all
+of the ports that belong to a YY type module:
+
+- Network Element 1
+
+ - Module 1, Type XX
+
+ - Module 1.1, Type YY
+
+ - Port 1
+
+ - Port 2
+
+ - Module 2, Type YY
+
+ - Port 1
+
+ - Port 2
+
+If you specify **Module.Type=\ *YY*** in your query criteria, the ports
+associated with module 1.1 will not be returned since its parent module
+is type XX. Instead, enter **Module.Type=\ *YY* or skip
+Module!=\ *YY***. This tells XSQL to disregard any parent module data
+that does not meet the type YY criteria and collect results for any
+matching child modules. In this example, you are instructing the query
+to skip module 1 and collect the relevant data from module 1.1.
+
--- /dev/null
+Service Function Chaining
+=========================
+
+OpenDaylight Service Function Chaining (SFC) Overiew
+----------------------------------------------------
+
+OpenDaylight Service Function Chaining (SFC) provides the ability to
+define an ordered list of a network services (e.g. firewalls, load
+balancers). These service are then "stitched" together in the network to
+create a service chain. This project provides the infrastructure
+(chaining logic, APIs) needed for ODL to provision a service chain in
+the network and an end-user application for defining such chains.
+
+- ACE - Access Control Entry
+
+- ACL - Access Control List
+
+- SCF - Service Classifier Function
+
+- SF - Service Function
+
+- SFC - Service Function Chain
+
+- SFF - Service Function Forwarder
+
+- SFG - Service Function Group
+
+- SFP - Service Function Path
+
+- RSP - Rendered Service Path
+
+- NSH - Network Service Header
+
+SFC User Interface
+------------------
+
+Overview
+~~~~~~~~
+
+SFC User Interface (SFC-UI) is based on Dlux project. It provides an
+easy way to create, read, update and delete configuration stored in
+Datastore. Moreover, it shows the status of all SFC features (e.g
+installed, uninstalled) and Karaf log messages as well.
+
+SFC-UI Architecture
+~~~~~~~~~~~~~~~~~~~
+
+SFC-UI operates purely by using RESTCONF.
+
+.. figure:: ./images/sfc/sfc-ui-architecture.png
+ :alt: SFC-UI integration into ODL
+
+ SFC-UI integration into ODL
+
+Configuring SFC-UI
+~~~~~~~~~~~~~~~~~~
+
+1. Run ODL distribution (run karaf)
+
+2. In karaf console execute: ``feature:install odl-sfc-ui``
+
+3. Visit SFC-UI on: ``http://<odl_ip_address>:8181/sfc/index.html``
+
+SFC Southbound REST Plugin
+--------------------------
+
+Overview
+~~~~~~~~
+
+The Southbound REST Plugin is used to send configuration from DataStore
+down to network devices supporting a REST API (i.e. they have a
+configured REST URI). It supports POST/PUT/DELETE operations, which are
+triggered accordingly by changes in the SFC data stores.
+
+- Access Control List (ACL)
+
+- Service Classifier Function (SCF)
+
+- Service Function (SF)
+
+- Service Function Group (SFG)
+
+- Service Function Schedule Type (SFST)
+
+- Service Function Forwader (SFF)
+
+- Rendered Service Path (RSP)
+
+Southbound REST Plugin Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From the user perspective, the REST plugin is another SFC Southbound
+plugin used to communicate with network devices.
+
+.. figure:: ./images/sfc/sb-rest-architecture-user.png
+ :alt: Soutbound REST Plugin integration into ODL
+
+ Soutbound REST Plugin integration into ODL
+
+Configuring Southbound REST Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Run ODL distribution (run karaf)
+
+2. In karaf console execute: ``feature:install odl-sfc-sb-rest``
+
+3. Configure REST URIs for SF/SFF through SFC User Interface or RESTCONF
+ (required configuration steps can be found in the tutorial stated
+ bellow)
+
+Tutorial
+~~~~~~~~
+
+Comprehensive tutorial on how to use the Southbound REST Plugin and how
+to control network devices with it can be found on:
+https://wiki.opendaylight.org/view/Service_Function_Chaining:Main#SFC_101
+
+SFC-OVS integration
+-------------------
+
+Overview
+~~~~~~~~
+
+SFC-OVS provides integration of SFC with Open vSwitch (OVS) devices.
+Integration is realized through mapping of SFC objects (like SF, SFF,
+Classifier, etc.) to OVS objects (like Bridge,
+TerminationPoint=Port/Interface). The mapping takes care of automatic
+instantiation (setup) of corresponding object whenever its counterpart
+is created. For example, when a new SFF is created, the SFC-OVS plugin
+will create a new OVS bridge and when a new OVS Bridge is created, the
+SFC-OVS plugin will create a new SFF.
+
+The feature is intended for SFC users willing to use Open vSwitch as
+underlying network infrastructure for deploying RSPs (Rendered Service
+Paths).
+
+SFC-OVS Architecture
+~~~~~~~~~~~~~~~~~~~~
+
+SFC-OVS uses the OVSDB MD-SAL Southbound API for getting/writing
+information from/to OVS devices. From the user perspective SFC-OVS acts
+as a layer between SFC DataStore and OVSDB.
+
+.. figure:: ./images/sfc/sfc-ovs-architecture-user.png
+ :alt: SFC-OVS integration into ODL
+
+ SFC-OVS integration into ODL
+
+Configuring SFC-OVS
+~~~~~~~~~~~~~~~~~~~
+
+1. Run ODL distribution (run karaf)
+
+2. In karaf console execute: ``feature:install odl-sfc-ovs``
+
+3. Configure Open vSwitch to use ODL as a manager, using following
+ command: ``ovs-vsctl set-manager tcp:<odl_ip_address>:6640``
+
+Tutorials
+~~~~~~~~~
+
+Verifying mapping from OVS to SFF
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Overview
+''''''''
+
+This tutorial shows the usual workflow when OVS configuration is
+transformed to corresponding SFC objects (in this case SFF).
+
+Prerequisities
+''''''''''''''
+
+- Open vSwitch installed (ovs-vsctl command available in shell)
+
+- SFC-OVS feature configured as stated above
+
+Instructions
+''''''''''''
+
+1. ``ovs-vsctl set-manager tcp:<odl_ip_address>:6640``
+
+2. ``ovs-vsctl add-br br1``
+
+3. ``ovs-vsctl add-port br1 testPort``
+
+Verification
+''''''''''''
+
+a. visit SFC User Interface:
+ ``http://<odl_ip_address>:8181/sfc/index.html#/sfc/serviceforwarder``
+
+b. use pure RESTCONF and send GET request to URL:
+ ``http://<odl_ip_address>:8181/restconf/config/service-function-forwarder:service-function-forwarders``
+
+There should be SFF, which name will be ending with *br1* and the SFF
+should containt two DataPlane locators: *br1* and *testPort*.
+
+Verifying mapping from SFF to OVS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Overview
+''''''''
+
+This tutorial shows the usual workflow during creation of OVS Bridge
+with use of SFC APIs.
+
+Prerequisities
+''''''''''''''
+
+- Open vSwitch installed (ovs-vsctl command available in shell)
+
+- SFC-OVS feature configured as stated above
+
+Instructions
+''''''''''''
+
+1. In shell execute: ``ovs-vsctl set-manager tcp:<odl_ip_address>:6640``
+
+2. Send POST request to URL:
+ ``http://<odl_ip_address>:8181/restconf/operations/service-function-forwarder-ovs:create-ovs-bridge``
+ Use Basic auth with credentials: "admin", "admin" and set
+ ``Content-Type: application/json``. The content of POST request
+ should be following:
+
+::
+
+ {
+ "input":
+ {
+ "name": "br-test",
+ "ovs-node": {
+ "ip": "<Open_vSwitch_ip_address>"
+ }
+ }
+ }
+
+Open\_vSwitch\_ip\_address is IP address of machine, where Open vSwitch
+is installed.
+
+Verification
+''''''''''''
+
+In shell execute: ``ovs-vsctl show``. There should be Bridge with name
+*br-test* and one port/interface called *br-test*.
+
+Also, corresponding SFF for this OVS Bridge should be configured, which
+can be verified through SFC User Interface or RESTCONF as stated in
+previous tutorial.
+
+SFC Classifier User Guide
+-------------------------
+
+Overview
+~~~~~~~~
+
+Description of classifier can be found in:
+https://datatracker.ietf.org/doc/draft-ietf-sfc-architecture/
+
+There are two types of classifier:
+
+1. OpenFlow Classifier
+
+2. Iptables Classifier
+
+OpenFlow Classifier
+~~~~~~~~~~~~~~~~~~~
+
+OpenFlow Classifier implements the classification criteria based on
+OpenFlow rules deployed into an OpenFlow switch. An Open vSwitch will
+take the role of a classifier and performs various encapsulations such
+NSH, VLAN, MPLS, etc. In the existing implementation, classifier can
+support NSH encapsulation. Matching information is based on ACL for MAC
+addresses, ports, protocol, IPv4 and IPv6. Supported protocols are TCP,
+UDP and SCTP. Actions information in the OF rules, shall be forwarding
+of the encapsulated packets with specific information related to the
+RSP.
+
+Classifier Architecture
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The OVSDB Southbound interface is used to create an instance of a bridge
+in a specific location (via IP address). This bridge contains the
+OpenFlow rules that perform the classification of the packets and react
+accordingly. The OpenFlow Southbound interface is used to translate the
+ACL information into OF rules within the Open vSwitch.
+
+.. note::
+
+ in order to create the instance of the bridge that takes the role of
+ a classifier, an "empty" SFF must be created.
+
+Configuring Classifier
+^^^^^^^^^^^^^^^^^^^^^^
+
+1. An empty SFF must be created in order to host the ACL that contains
+ the classification information.
+
+2. SFF data plane locator must be configured
+
+3. Classifier interface must be mannually added to SFF bridge.
+
+Administering or Managing Classifier
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Classification information is based on MAC addresses, protocol, ports
+and IP. ACL gathers this information and is assigned to an RSP which
+turns to be a specific path for a Service Chain.
+
+Iptables Classifier
+~~~~~~~~~~~~~~~~~~~
+
+Classifier manages everything from starting the packet listener to
+creation (and removal) of appropriate ip(6)tables rules and marking
+received packets accordingly. Its functionality is **available only on
+Linux** as it leverdges **NetfilterQueue**, which provides access to
+packets matched by an **iptables** rule. Classifier requires **root
+privileges** to be able to operate.
+
+So far it is capable of processing ACL for MAC addresses, ports, IPv4
+and IPv6. Supported protocols are TCP and UDP.
+
+Classifier Architecture
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Python code located in the project repository
+sfc-py/common/classifier.py.
+
+.. note::
+
+ classifier assumes that Rendered Service Path (RSP) **already
+ exists** in ODL when an ACL referencing it is obtained
+
+1. sfc\_agent receives an ACL and passes it for processing to the
+ classifier
+
+2. the RSP (its SFF locator) referenced by ACL is requested from ODL
+
+3. if the RSP exists in the ODL then ACL based iptables rules for it are
+ applied
+
+After this process is over, every packet successfully matched to an
+iptables rule (i.e. successfully classified) will be NSH encapsulated
+and forwarded to a related SFF, which knows how to traverse the RSP.
+
+Rules are created using appropriate iptables command. If the Access
+Control Entry (ACE) rule is MAC address related both iptables and
+ip6tabeles rules re issued. If ACE rule is IPv4 address related, only
+iptables rules are issued, same for IPv6.
+
+.. note::
+
+ iptables **raw** table contains all created rules
+
+Configuring Classifier
+^^^^^^^^^^^^^^^^^^^^^^
+
+| Classfier does’t need any configuration.
+| Its only requirement is that the **second (2) Netfilter Queue** is not
+ used by any other process and is **avalilable for the classifier**.
+
+Administering or Managing Classifier
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Classfier runs alongside sfc\_agent, therefore the commad for starting
+it locally is:
+
+::
+
+ sudo python3.4 sfc-py/sfc_agent.py --rest --odl-ip-port localhost:8181 --auto-sff-name --nfq-class
+
+SFC OpenFlow Renderer User Guide
+--------------------------------
+
+Overview
+~~~~~~~~
+
+The Service Function Chaining (SFC) OpenFlow Renderer (SFC OF Renderer)
+implements Service Chaining on OpenFlow switches. It listens for the
+creation of a Rendered Service Path (RSP), and once received it programs
+Service Function Forwarders (SFF) that are hosted on OpenFlow capable
+switches to steer packets through the service chain.
+
+Common acronyms used in the following sections:
+
+- SF - Service Function
+
+- SFF - Service Function Forwarder
+
+- SFC - Service Function Chain
+
+- SFP - Service Function Path
+
+- RSP - Rendered Service Path
+
+SFC OpenFlow Renderer Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SFC OF Renderer is invoked after a RSP is created using an MD-SAL
+listener called ``SfcOfRspDataListener``. Upon SFC OF Renderer
+initialization, the ``SfcOfRspDataListener`` registers itself to listen
+for RSP changes. When invoked, the ``SfcOfRspDataListener`` processes
+the RSP and calls the ``SfcOfFlowProgrammerImpl`` to create the
+necessary flows in the Service Function Forwarders configured in the
+RSP. Refer to the following diagram for more details.
+
+.. figure:: ./images/sfc/sfcofrenderer_architecture.png
+ :alt: SFC OpenFlow Renderer High Level Architecture
+
+ SFC OpenFlow Renderer High Level Architecture
+
+SFC OpenFlow Switch Flow pipeline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SFC OpenFlow Renderer uses the following tables for its Flow
+pipeline:
+
+- Table 0, Classifier
+
+- Table 1, Transport Ingress
+
+- Table 2, Path Mapper
+
+- Table 3, Path Mapper ACL
+
+- Table 4, Next Hop
+
+- Table 10, Transport Egress
+
+The OpenFlow Table Pipeline is intended to be generic to work for all of
+the different encapsulations supported by SFC.
+
+All of the tables are explained in detail in the following section.
+
+The SFFs (SFF1 and SFF2), SFs (SF1), and topology used for the flow
+tables in the following sections are as described in the following
+diagram.
+
+.. figure:: ./images/sfc/sfcofrenderer_nwtopo.png
+ :alt: SFC OpenFlow Renderer Typical Network Topology
+
+ SFC OpenFlow Renderer Typical Network Topology
+
+Classifier Table detailed
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible for the SFF to also act as a classifier. This table maps
+subscriber traffic to RSPs, and is explained in detail in the classifier
+documentation.
+
+If the SFF is not a classifier, then this table will just have a simple
+Goto Table 1 flow.
+
+Transport Ingress Table detailed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Transport Ingress table has an entry per expected tunnel transport
+type to be received in a particular SFF, as established in the SFC
+configuration.
+
+Here are two example on SFF1: one where the RSP ingress tunnel is MPLS
+assuming VLAN is used for the SFF-SF, and the other where the RSP
+ingress tunnel is NSH GRE (UDP port 4789):
+
++-------------+--------------------------------------+--------------------------+
+| Priority | Match | Action |
++=============+======================================+==========================+
+| 256 | EtherType==0x8847 (MPLS unicast) | Goto Table 2 |
++-------------+--------------------------------------+--------------------------+
+| 256 | EtherType==0x8100 (VLAN) | Goto Table 2 |
++-------------+--------------------------------------+--------------------------+
+| 256 | EtherType==0x0800,udp,tp\_dst==4789 | Goto Table 2 |
+| | (IP v4) | |
++-------------+--------------------------------------+--------------------------+
+| 5 | Match Any | Drop |
++-------------+--------------------------------------+--------------------------+
+
+Table: Table Transport Ingress
+
+Path Mapper Table detailed
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Path Mapper table has an entry per expected tunnel transport info to
+be received in a particular SFF, as established in the SFC
+configuration. The tunnel transport info is used to determine the RSP
+Path ID, and is stored in the OpenFlow Metadata. This table is not used
+for NSH, since the RSP Path ID is stored in the NSH header.
+
+For SF nodes that do not support NSH tunneling, the IP header DSCP field
+is used to store the RSP Path Id. The RSP Path Id is written to the DSCP
+field in the Transport Egress table for those packets sent to an SF.
+
+Here is an example on SFF1, assuming the following details:
+
+- VLAN ID 1000 is used for the SFF-SF
+
+- The RSP Path 1 tunnel uses MPLS label 100 for ingress and 101 for
+ egress
+
+- The RSP Path 2 (symmetric downlink path) uses MPLS label 101 for
+ ingress and 100 for egress
+
++--------------------------+--------------------------+--------------------------+
+| Priority | Match | Action |
++==========================+==========================+==========================+
+| 256 | MPLS Label==100 | RSP Path=1, Pop MPLS, |
+| | | Goto Table 4 |
++--------------------------+--------------------------+--------------------------+
+| 256 | MPLS Label==101 | RSP Path=2, Pop MPLS, |
+| | | Goto Table 4 |
++--------------------------+--------------------------+--------------------------+
+| 256 | VLAN ID==1000, IP | RSP Path=1, Pop VLAN, |
+| | DSCP==1 | Goto Table 4 |
++--------------------------+--------------------------+--------------------------+
+| 256 | VLAN ID==1000, IP | RSP Path=2, Pop VLAN, |
+| | DSCP==2 | Goto Table 4 |
++--------------------------+--------------------------+--------------------------+
+| 5 | Match Any | Goto Table 3 |
++--------------------------+--------------------------+--------------------------+
+
+Table: Table Path Mapper
+
+Path Mapper ACL Table detailed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This table is only populated when PacketIn packets are received from the
+switch for TcpProxy type SFs. These flows are created with an inactivity
+timer of 60 seconds and will be automatically deleted upon expiration.
+
+Next Hop Table detailed
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The Next Hop table uses the RSP Path Id and appropriate packet fields to
+determine where to send the packet next. For NSH, only the NSP (Network
+Services Path, RSP ID) and NSI (Network Services Index, next hop) fields
+from the NSH header are needed to determine the VXLAN tunnel destination
+IP. For VLAN or MPLS, then the source MAC address is used to determine
+the destination MAC address.
+
+Here are two examples on SFF1, assuming SFF1 is connected to SFF2. RSP
+Paths 1 and 2 are symmetric VLAN paths. RSP Paths 3 and 4 are symmetric
+NSH paths. RSP Path 1 ingress packets come from external to SFC, for
+which we don’t have the source MAC address (MacSrc).
+
++------------+--------------------------------+--------------------------------+
+| Priority | Match | Action |
++============+================================+================================+
+| 256 | RSP Path==1, MacSrc==SF1 | MacDst=SFF2, Goto Table 10 |
++------------+--------------------------------+--------------------------------+
+| 256 | RSP Path==2, MacSrc==SF1 | Goto Table 10 |
++------------+--------------------------------+--------------------------------+
+| 256 | RSP Path==2, MacSrc==SFF2 | MacDst=SF1, Goto Table 10 |
++------------+--------------------------------+--------------------------------+
+| 246 | RSP Path==1 | MacDst=SF1, Goto Table 10 |
++------------+--------------------------------+--------------------------------+
+| 256 | nsp=3,nsi=255 (SFF Ingress RSP | load:0xa000002→NXM\_NX\_TUN\_I |
+| | 3) | PV4\_DST[], |
+| | | Goto Table 10 |
++------------+--------------------------------+--------------------------------+
+| 256 | nsp=3,nsi=254 (SFF Ingress | load:0xa00000a→NXM\_NX\_TUN\_I |
+| | from SF, RSP 3) | PV4\_DST[], |
+| | | Goto Table 10 |
++------------+--------------------------------+--------------------------------+
+| 256 | nsp=4,nsi=254 (SFF1 Ingress | load:0xa00000a→NXM\_NX\_TUN\_I |
+| | from SFF2) | PV4\_DST[], |
+| | | Goto Table 10 |
++------------+--------------------------------+--------------------------------+
+| 5 | Match Any | Drop |
++------------+--------------------------------+--------------------------------+
+
+Table: Table Next Hop
+
+Transport Egress Table detailed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Transport Egress table prepares egress tunnel information and sends
+the packets out.
+
+Here are two examples on SFF1. RSP Paths 1 and 2 are symmetric MPLS
+paths that use VLAN for the SFF-SF. RSP Paths 3 and 4 are symmetric NSH
+paths. Since it is assumed that switches used for NSH will only have one
+VXLANport, the NSH packets are just sent back where they came from.
+
++------------+--------------------------------+--------------------------------+
+| Priority | Match | Action |
++============+================================+================================+
+| 256 | RSP Path==1, MacDst==SF1 | Push VLAN ID 1000, Port=SF1 |
++------------+--------------------------------+--------------------------------+
+| 256 | RSP Path==1, MacDst==SFF2 | Push MPLS Label 101, Port=SFF2 |
++------------+--------------------------------+--------------------------------+
+| 256 | RSP Path==2, MacDst==SF1 | Push VLAN ID 1000, Port=SF1 |
++------------+--------------------------------+--------------------------------+
+| 246 | RSP Path==2 | Push MPLS Label 100, |
+| | | Port=Ingress |
++------------+--------------------------------+--------------------------------+
+| 256 | nsp=3,nsi=255 (SFF Ingress RSP | IN\_PORT |
+| | 3) | |
++------------+--------------------------------+--------------------------------+
+| 256 | nsp=3,nsi=254 (SFF Ingress | IN\_PORT |
+| | from SF, RSP 3) | |
++------------+--------------------------------+--------------------------------+
+| 256 | nsp=4,nsi=254 (SFF1 Ingress | IN\_PORT |
+| | from SFF2) | |
++------------+--------------------------------+--------------------------------+
+| 5 | Match Any | Drop |
++------------+--------------------------------+--------------------------------+
+
+Table: Table Transport Egress
+
+Administering SFC OF Renderer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the SFC OpenFlow Renderer Karaf, at least the following Karaf
+features must be installed.
+
+- odl-openflowplugin-nxm-extensions
+
+- odl-openflowplugin-flow-services
+
+- odl-sfc-provider
+
+- odl-sfc-model
+
+- odl-sfc-openflow-renderer
+
+- odl-sfc-ui (optional)
+
+The following command can be used to view all of the currently installed
+Karaf features:
+
+::
+
+ opendaylight-user@root>feature:list -i
+
+Or, pipe the command to a grep to see a subset of the currently
+installed Karaf features:
+
+::
+
+ opendaylight-user@root>feature:list -i | grep sfc
+
+To install a particular feature, use the Karaf ``feature:install``
+command.
+
+SFC OF Renderer Tutorial
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Overview
+^^^^^^^^
+
+In this tutorial, 2 different encapsulations will be shown: MPLS and
+NSH. The following Network Topology diagram is a logical view of the
+SFFs and SFs involved in creating the Service Chains.
+
+.. figure:: ./images/sfc/sfcofrenderer_nwtopo.png
+ :alt: SFC OpenFlow Renderer Typical Network Topology
+
+ SFC OpenFlow Renderer Typical Network Topology
+
+Prerequisites
+^^^^^^^^^^^^^
+
+To use this example, SFF OpenFlow switches must be created and connected
+as illustrated above. Additionally, the SFs must be created and
+connected.
+
+Target Environment
+^^^^^^^^^^^^^^^^^^
+
+The target environment is not important, but this use-case was created
+and tested on Linux.
+
+Instructions
+^^^^^^^^^^^^
+
+The steps to use this tutorial are as follows. The referenced
+configuration in the steps is listed in the following sections.
+
+There are numerous ways to send the configuration. In the following
+configuration chapters, the appropriate ``curl`` command is shown for
+each configuration to be sent, including the URL.
+
+Steps to configure the SFC OF Renderer tutorial:
+
+1. Send the ``SF`` RESTCONF configuration
+
+2. Send the ``SFF`` RESTCONF configuration
+
+3. Send the ``SFC`` RESTCONF configuration
+
+4. Send the ``SFP`` RESTCONF configuration
+
+5. Create the ``RSP`` with a RESTCONF RPC command
+
+Once the configuration has been successfully created, query the Rendered
+Service Paths with either the SFC UI or via RESTCONF. Notice that the
+RSP is symmetrical, so the following 2 RSPs will be created:
+
+- sfc-path1
+
+- sfc-path1-Reverse
+
+At this point the Service Chains have been created, and the OpenFlow
+Switches are programmed to steer traffic through the Service Chain.
+Traffic can now be injected from a client into the Service Chain. To
+debug problems, the OpenFlow tables can be dumped with the following
+commands, assuming SFF1 is called ``s1`` and SFF2 is called ``s2``.
+
+::
+
+ sudo ovs-ofctl -O OpenFlow13 dump-flows s1
+
+::
+
+ sudo ovs-ofctl -O OpenFlow13 dump-flows s2
+
+In all the following configuration sections, replace the ``${JSON}``
+string with the appropriate JSON configuration. Also, change the
+``localhost`` desintation in the URL accordingly.
+
+SFC OF Renderer NSH Tutorial
+''''''''''''''''''''''''''''
+
+The following configuration sections show how to create the different
+elements using NSH encapsulation.
+
+| **NSH Service Function configuration**
+
+The Service Function configuration can be sent with the following
+command:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function:service-functions/
+
+**SF configuration JSON.**
+
+::
+
+ {
+ "service-functions": {
+ "service-function": [
+ {
+ "name": "sf1",
+ "type": "http-header-enrichment",
+ "nsh-aware": true,
+ "ip-mgmt-address": "10.0.0.2",
+ "sf-data-plane-locator": [
+ {
+ "name": "sf1dpl",
+ "ip": "10.0.0.10",
+ "port": 4789,
+ "transport": "service-locator:vxlan-gpe",
+ "service-function-forwarder": "sff1"
+ }
+ ]
+ },
+ {
+ "name": "sf2",
+ "type": "firewall",
+ "nsh-aware": true,
+ "ip-mgmt-address": "10.0.0.3",
+ "sf-data-plane-locator": [
+ {
+ "name": "sf2dpl",
+ "ip": "10.0.0.20",
+ "port": 4789,
+ "transport": "service-locator:vxlan-gpe",
+ "service-function-forwarder": "sff2"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+| **NSH Service Function Forwarder configuration**
+
+The Service Function Forwarder configuration can be sent with the
+following command:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-forwarder:service-function-forwarders/
+
+**SFF configuration JSON.**
+
+::
+
+ {
+ "service-function-forwarders": {
+ "service-function-forwarder": [
+ {
+ "name": "sff1",
+ "service-node": "openflow:2",
+ "sff-data-plane-locator": [
+ {
+ "name": "sff1dpl",
+ "data-plane-locator":
+ {
+ "ip": "10.0.0.1",
+ "port": 4789,
+ "transport": "service-locator:vxlan-gpe"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "name": "sf1",
+ "sff-sf-data-plane-locator":
+ {
+ "sf-dpl-name": "sf1dpl",
+ "sff-dpl-name": "sff1dpl"
+ }
+ }
+ ]
+ },
+ {
+ "name": "sff2",
+ "service-node": "openflow:3",
+ "sff-data-plane-locator": [
+ {
+ "name": "sff2dpl",
+ "data-plane-locator":
+ {
+ "ip": "10.0.0.2",
+ "port": 4789,
+ "transport": "service-locator:vxlan-gpe"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "name": "sf2",
+ "sff-sf-data-plane-locator":
+ {
+ "sf-dpl-name": "sf2dpl",
+ "sff-dpl-name": "sff2dpl"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+| **NSH Service Function Chain configuration**
+
+The Service Function Chain configuration can be sent with the following
+command:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-chain:service-function-chains/
+
+**SFC configuration JSON.**
+
+::
+
+ {
+ "service-function-chains": {
+ "service-function-chain": [
+ {
+ "name": "sfc-chain1",
+ "symmetric": true,
+ "sfc-service-function": [
+ {
+ "name": "hdr-enrich-abstract1",
+ "type": "http-header-enrichment"
+ },
+ {
+ "name": "firewall-abstract1",
+ "type": "firewall"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+| **NSH Service Function Path configuration**
+
+The Service Function Path configuration can be sent with the following
+command:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-path:service-function-paths/
+
+**SFP configuration JSON.**
+
+::
+
+ {
+ "service-function-paths": {
+ "service-function-path": [
+ {
+ "name": "sfc-path1",
+ "service-chain-name": "sfc-chain1",
+ "transport-type": "service-locator:vxlan-gpe",
+ "symmetric": true
+ }
+ ]
+ }
+ }
+
+| **NSH Rendered Service Path creation**
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:create-rendered-path/
+
+**RSP creation JSON.**
+
+::
+
+ {
+ "input": {
+ "name": "sfc-path1",
+ "parent-service-function-path": "sfc-path1",
+ "symmetric": true
+ }
+ }
+
+| **NSH Rendered Service Path removal**
+
+The following command can be used to remove a Rendered Service Path
+called ``sfc-path1``:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{"input": {"name": "sfc-path1" } }' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:delete-rendered-path/
+
+| **NSH Rendered Service Path Query**
+
+The following command can be used to query all of the created Rendered
+Service Paths:
+
+::
+
+ curl -H "Content-Type: application/json" -H "Cache-Control: no-cache" -X GET --user admin:admin http://localhost:8181/restconf/operational/rendered-service-path:rendered-service-paths/
+
+SFC OF Renderer MPLS Tutorial
+'''''''''''''''''''''''''''''
+
+The following configuration sections show how to create the different
+elements using MPLS encapsulation.
+
+| **MPLS Service Function configuration**
+
+The Service Function configuration can be sent with the following
+command:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function:service-functions/
+
+**SF configuration JSON.**
+
+::
+
+ {
+ "service-functions": {
+ "service-function": [
+ {
+ "name": "sf1",
+ "type": "http-header-enrichment",
+ "nsh-aware": false,
+ "ip-mgmt-address": "10.0.0.2",
+ "sf-data-plane-locator": [
+ {
+ "name": "sf1-sff1",
+ "mac": "00:00:08:01:02:01",
+ "vlan-id": 1000,
+ "transport": "service-locator:mac",
+ "service-function-forwarder": "sff1"
+ }
+ ]
+ },
+ {
+ "name": "sf2",
+ "type": "firewall",
+ "nsh-aware": false,
+ "ip-mgmt-address": "10.0.0.3",
+ "sf-data-plane-locator": [
+ {
+ "name": "sf2-sff2",
+ "mac": "00:00:08:01:03:01",
+ "vlan-id": 2000,
+ "transport": "service-locator:mac",
+ "service-function-forwarder": "sff2"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+| **MPLS Service Function Forwarder configuration**
+
+The Service Function Forwarder configuration can be sent with the
+following command:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-forwarder:service-function-forwarders/
+
+**SFF configuration JSON.**
+
+::
+
+ {
+ "service-function-forwarders": {
+ "service-function-forwarder": [
+ {
+ "name": "sff1",
+ "service-node": "openflow:2",
+ "sff-data-plane-locator": [
+ {
+ "name": "ulSff1Ingress",
+ "data-plane-locator":
+ {
+ "mpls-label": 100,
+ "transport": "service-locator:mpls"
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "mac": "11:11:11:11:11:11",
+ "port-id" : "1"
+ }
+ },
+ {
+ "name": "ulSff1ToSff2",
+ "data-plane-locator":
+ {
+ "mpls-label": 101,
+ "transport": "service-locator:mpls"
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "mac": "33:33:33:33:33:33",
+ "port-id" : "2"
+ }
+ },
+ {
+ "name": "toSf1",
+ "data-plane-locator":
+ {
+ "mac": "22:22:22:22:22:22",
+ "vlan-id": 1000,
+ "transport": "service-locator:mac",
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "mac": "33:33:33:33:33:33",
+ "port-id" : "3"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "name": "sf1",
+ "sff-sf-data-plane-locator":
+ {
+ "sf-dpl-name": "sf1-sff1",
+ "sff-dpl-name": "toSf1"
+ }
+ }
+ ]
+ },
+ {
+ "name": "sff2",
+ "service-node": "openflow:3",
+ "sff-data-plane-locator": [
+ {
+ "name": "ulSff2Ingress",
+ "data-plane-locator":
+ {
+ "mpls-label": 101,
+ "transport": "service-locator:mpls"
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "mac": "44:44:44:44:44:44",
+ "port-id" : "1"
+ }
+ },
+ {
+ "name": "ulSff2Egress",
+ "data-plane-locator":
+ {
+ "mpls-label": 102,
+ "transport": "service-locator:mpls"
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "mac": "66:66:66:66:66:66",
+ "port-id" : "2"
+ }
+ },
+ {
+ "name": "toSf2",
+ "data-plane-locator":
+ {
+ "mac": "55:55:55:55:55:55",
+ "vlan-id": 2000,
+ "transport": "service-locator:mac"
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "port-id" : "3"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "name": "sf2",
+ "sff-sf-data-plane-locator":
+ {
+ "sf-dpl-name": "sf2-sff2",
+ "sff-dpl-name": "toSf2"
+
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "port-id" : "3"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+| **MPLS Service Function Chain configuration**
+
+The Service Function Chain configuration can be sent with the following
+command:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-chain:service-function-chains/
+
+**SFC configuration JSON.**
+
+::
+
+ {
+ "service-function-chains": {
+ "service-function-chain": [
+ {
+ "name": "sfc-chain1",
+ "symmetric": true,
+ "sfc-service-function": [
+ {
+ "name": "hdr-enrich-abstract1",
+ "type": "http-header-enrichment"
+ },
+ {
+ "name": "firewall-abstract1",
+ "type": "firewall"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+| **MPLS Service Function Path configuration**
+
+The Service Function Path configuration can be sent with the following
+command:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-path:service-function-paths/
+
+**SFP configuration JSON.**
+
+::
+
+ {
+ "service-function-paths": {
+ "service-function-path": [
+ {
+ "name": "sfc-path1",
+ "service-chain-name": "sfc-chain1",
+ "transport-type": "service-locator:mpls",
+ "symmetric": true
+ }
+ ]
+ }
+ }
+
+| **MPLS Rendered Service Path creation**
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:create-rendered-path/
+
+**RSP creation JSON.**
+
+::
+
+ {
+ "input": {
+ "name": "sfc-path1",
+ "parent-service-function-path": "sfc-path1",
+ "symmetric": true
+ }
+ }
+
+| **MPLS Rendered Service Path removal**
+
+The following command can be used to remove a Rendered Service Path
+called ``sfc-path1``:
+
+::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{"input": {"name": "sfc-path1" } }' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:delete-rendered-path/
+
+| **MPLS Rendered Service Path Query**
+
+The following command can be used to query all of the created Rendered
+Service Paths:
+
+::
+
+ curl -H "Content-Type: application/json" -H "Cache-Control: no-cache" -X GET --user admin:admin http://localhost:8181/restconf/operational/rendered-service-path:rendered-service-paths/
+
+SFC IOS XE Renderer User Guide
+------------------------------
+
+Overview
+~~~~~~~~
+
+The early Service Function Chaining (SFC) renderer for IOS-XE devices
+(SFC IOS-XE renderer) implements Service Chaining functionality on
+IOS-XE capable switches. It listens for the creation of a Rendered
+Service Path (RSP) and sets up Service Function Forwarders (SFF) that
+are hosted on IOS-XE switches to steer traffic through the service
+chain.
+
+Common acronyms used in the following sections:
+
+- SF - Service Function
+
+- SFF - Service Function Forwarder
+
+- SFC - Service Function Chain
+
+- SP - Service Path
+
+- SFP - Service Function Path
+
+- RSP - Rendered Service Path
+
+- LSF - Local Service Forwarder
+
+- RSF - Remote Service Forwarder
+
+SFC IOS-XE Renderer Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the SFC IOS-XE renderer is initialized, all required listeners are
+registered to handle incoming data. It involves CSR/IOS-XE
+``NodeListener`` which stores data about all configurable devices
+including their mountpoints (used here as databrokers),
+``ServiceFunctionListener``, ``ServiceForwarderListener`` (see mapping)
+and ``RenderedPathListener`` used to listen for RSP changes. When the
+SFC IOS-XE renderer is invoked, ``RenderedPathListener`` calls the
+``IosXeRspProcessor`` which processes the RSP change and creates all
+necessary Service Paths and Remote Service Forwarders (if necessary) on
+IOS-XE devices.
+
+Service Path details
+~~~~~~~~~~~~~~~~~~~~
+
+Each Service Path is defined by index (represented by NSP) and contains
+service path entries. Each entry has appropriate service index (NSI) and
+definition of next hop. Next hop can be Service Function, different
+Service Function Forwarder or definition of end of chain - terminate.
+After terminating, the packet is sent to destination. If a SFF is
+defined as a next hop, it has to be present on device in the form of
+Remote Service Forwarder. RSFs are also created during RSP processing.
+
+Example of Service Path:
+
+::
+
+ service-chain service-path 200
+ service-index 255 service-function firewall-1
+ service-index 254 service-function dpi-1
+ service-index 253 terminate
+
+Mapping to IOS-XE SFC entities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Renderer contains mappers for SFs and SFFs. IOS-XE capable device is
+using its own definition of Service Functions and Service Function
+Forwarders according to appropriate .yang file.
+``ServiceFunctionListener`` serves as a listener for SF changes. If SF
+appears in datastore, listener extracts its management ip address and
+looks into cached IOS-XE nodes. If some of available nodes match,
+Service function is mapped in ``IosXeServiceFunctionMapper`` to be
+understandable by IOS-XE device and it’s written into device’s config.
+``ServiceForwarderListener`` is used in a similar way. All SFFs with
+suitable management ip address it mapped in
+``IosXeServiceForwarderMapper``. Remapped SFFs are configured as a Local
+Service Forwarders. It is not possible to directly create Remote Service
+Forwarder using IOS-XE renderer. RSF is created only during RSP
+processing.
+
+Administering SFC IOS-XE renderer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the SFC IOS-XE Renderer Karaf, at least the following Karaf
+features must be installed:
+
+- odl-aaa-shiro
+
+- odl-sfc-model
+
+- odl-sfc-provider
+
+- odl-restconf
+
+- odl-netconf-topology
+
+- odl-sfc-ios-xe-renderer
+
+SFC IOS-XE renderer Tutorial
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Overview
+^^^^^^^^
+
+This tutorial is a simple example how to create Service Path on IOS-XE
+capable device using IOS-XE renderer
+
+Preconditions
+^^^^^^^^^^^^^
+
+To connect to IOS-XE device, it is necessary to use several modified
+yang models and override device’s ones. All .yang files are in the
+``Yang/netconf`` folder in the ``sfc-ios-xe-renderer module`` in the SFC
+project. These files have to be copied to the ``cache/schema``
+directory, before Karaf is started. After that, custom capabilities have
+to be sent to network-topology:
+
+::
+
+ PUT ./config/network-topology:network-topology/topology/topology-netconf/node/<device-name>
+
+ <node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
+ <node-id>device-name</node-id>
+ <host xmlns="urn:opendaylight:netconf-node-topology">device-ip</host>
+ <port xmlns="urn:opendaylight:netconf-node-topology">2022</port>
+ <username xmlns="urn:opendaylight:netconf-node-topology">login</username>
+ <password xmlns="urn:opendaylight:netconf-node-topology">password</password>
+ <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
+ <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">0</keepalive-delay>
+ <yang-module-capabilities xmlns="urn:opendaylight:netconf-node-topology">
+ <override>true</override>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2013-07-15
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ urn:ietf:params:xml:ns:yang:ietf-yang-types?module=ietf-yang-types&revision=2013-07-15
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ urn:ios?module=ned&revision=2016-03-08
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ http://tail-f.com/yang/common?module=tailf-common&revision=2015-05-22
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ http://tail-f.com/yang/common?module=tailf-meta-extensions&revision=2013-11-07
+ </capability>
+ <capability xmlns="urn:opendaylight:netconf-node-topology">
+ http://tail-f.com/yang/common?module=tailf-cli-extensions&revision=2015-03-19
+ </capability>
+ </yang-module-capabilities>
+ </node>
+
+.. note::
+
+ The device name in the URL and in the XML must match.
+
+Instructions
+^^^^^^^^^^^^
+
+When the IOS-XE renderer is installed, all NETCONF nodes in
+topology-netconf are processed and all capable nodes with accessible
+mountpoints are cached. The first step is to create LSF on node.
+
+``Service Function Forwarder configuration``
+
+::
+
+ PUT ./config/service-function-forwarder:service-function-forwarders
+
+ {
+ "service-function-forwarders": {
+ "service-function-forwarder": [
+ {
+ "name": "CSR1Kv-2",
+ "ip-mgmt-address": "172.25.73.23",
+ "sff-data-plane-locator": [
+ {
+ "name": "CSR1Kv-2-dpl",
+ "data-plane-locator": {
+ "transport": "service-locator:vxlan-gpe",
+ "port": 6633,
+ "ip": "10.99.150.10"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+If the IOS-XE node with appropriate management IP exists, this
+configuration is mapped and LSF is created on the device. The same
+approach is used for Service Functions.
+
+::
+
+ PUT ./config/service-function:service-functions
+
+ {
+ "service-functions": {
+ "service-function": [
+ {
+ "name": "Firewall",
+ "ip-mgmt-address": "172.25.73.23",
+ "type": "service-function-type: firewall",
+ "nsh-aware": true,
+ "sf-data-plane-locator": [
+ {
+ "name": "firewall-dpl",
+ "port": 6633,
+ "ip": "12.1.1.2",
+ "transport": "service-locator:gre",
+ "service-function-forwarder": "CSR1Kv-2"
+ }
+ ]
+ },
+ {
+ "name": "Dpi",
+ "ip-mgmt-address": "172.25.73.23",
+ "type":"service-function-type: dpi",
+ "nsh-aware": true,
+ "sf-data-plane-locator": [
+ {
+ "name": "dpi-dpl",
+ "port": 6633,
+ "ip": "12.1.1.1",
+ "transport": "service-locator:gre",
+ "service-function-forwarder": "CSR1Kv-2"
+ }
+ ]
+ },
+ {
+ "name": "Qos",
+ "ip-mgmt-address": "172.25.73.23",
+ "type":"service-function-type: qos",
+ "nsh-aware": true,
+ "sf-data-plane-locator": [
+ {
+ "name": "qos-dpl",
+ "port": 6633,
+ "ip": "12.1.1.4",
+ "transport": "service-locator:gre",
+ "service-function-forwarder": "CSR1Kv-2"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+All these SFs are configured on the same device as the LSF. The next
+step is to prepare Service Function Chain. SFC is symmetric.
+
+::
+
+ PUT ./config/service-function-chain:service-function-chains/
+
+ {
+ "service-function-chains": {
+ "service-function-chain": [
+ {
+ "name": "CSR3XSF",
+ "symmetric": "true",
+ "sfc-service-function": [
+ {
+ "name": "Firewall",
+ "type": "service-function-type: firewall"
+ },
+ {
+ "name": "Dpi",
+ "type": "service-function-type: dpi"
+ },
+ {
+ "name": "Qos",
+ "type": "service-function-type: qos"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+Service Function Path:
+
+::
+
+ PUT ./config/service-function-path:service-function-paths/
+
+ {
+ "service-function-paths": {
+ "service-function-path": [
+ {
+ "name": "CSR3XSF-Path",
+ "service-chain-name": "CSR3XSF",
+ "starting-index": 255,
+ "symmetric": "true"
+ }
+ ]
+ }
+ }
+
+Without a classifier, there is possibility to POST RSP directly.
+
+::
+
+ POST ./operations/rendered-service-path:create-rendered-path
+
+ {
+ "input": {
+ "name": "CSR3XSF-Path-RSP",
+ "parent-service-function-path": "CSR3XSF-Path",
+ "symmetric": true
+ }
+ }
+
+The resulting configuration:
+
+::
+
+ !
+ service-chain service-function-forwarder local
+ ip address 10.99.150.10
+ !
+ service-chain service-function firewall
+ ip address 12.1.1.2
+ encapsulation gre enhanced divert
+ !
+ service-chain service-function dpi
+ ip address 12.1.1.1
+ encapsulation gre enhanced divert
+ !
+ service-chain service-function qos
+ ip address 12.1.1.4
+ encapsulation gre enhanced divert
+ !
+ service-chain service-path 1
+ service-index 255 service-function firewall
+ service-index 254 service-function dpi
+ service-index 253 service-function qos
+ service-index 252 terminate
+ !
+ service-chain service-path 2
+ service-index 255 service-function qos
+ service-index 254 service-function dpi
+ service-index 253 service-function firewall
+ service-index 252 terminate
+ !
+
+Service Path 1 is direct, Service Path 2 is reversed. Path numbers may
+vary.
+
+Service Function Scheduling Algorithms
+--------------------------------------
+
+Overview
+~~~~~~~~
+
+When creating the Rendered Service Path, the origin SFC controller chose
+the first available service function from a list of service function
+names. This may result in many issues such as overloaded service
+functions and a longer service path as SFC has no means to understand
+the status of service functions and network topology. The service
+function selection framework supports at least four algorithms (Random,
+Round Robin, Load Balancing and Shortest Path) to select the most
+appropriate service function when instantiating the Rendered Service
+Path. In addition, it is an extensible framework that allows 3rd party
+selection algorithm to be plugged in.
+
+Architecture
+~~~~~~~~~~~~
+
+The following figure illustrates the service function selection
+framework and algorithms.
+
+.. figure:: ./images/sfc/sf-selection-arch.png
+ :alt: SF Selection Architecture
+
+ SF Selection Architecture
+
+A user has three different ways to select one service function selection
+algorithm:
+
+1. Integrated RESTCONF Calls. OpenStack and/or other administration
+ system could provide plugins to call the APIs to select one
+ scheduling algorithm.
+
+2. Command line tools. Command line tools such as curl or browser
+ plugins such as POSTMAN (for Google Chrome) and RESTClient (for
+ Mozilla Firefox) could select schedule algorithm by making RESTCONF
+ calls.
+
+3. SFC-UI. Now the SFC-UI provides an option for choosing a selection
+ algorithm when creating a Rendered Service Path.
+
+The RESTCONF northbound SFC API provides GUI/RESTCONF interactions for
+choosing the service function selection algorithm. MD-SAL data store
+provides all supported service function selection algorithms, and
+provides APIs to enable one of the provided service function selection
+algorithms. Once a service function selection algorithm is enabled, the
+service function selection algorithm will work when creating a Rendered
+Service Path.
+
+Select SFs with Scheduler
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Administrator could use both the following ways to select one of the
+selection algorithm when creating a Rendered Service Path.
+
+- Command line tools. Command line tools includes Linux commands curl
+ or even browser plugins such as POSTMAN(for Google Chrome) or
+ RESTClient(for Mozilla Firefox). In this case, the following JSON
+ content is needed at the moment:
+ Service\_function\_schudule\_type.json
+
+ ::
+
+ {
+ "service-function-scheduler-types": {
+ "service-function-scheduler-type": [
+ {
+ "name": "random",
+ "type": "service-function-scheduler-type:random",
+ "enabled": false
+ },
+ {
+ "name": "roundrobin",
+ "type": "service-function-scheduler-type:round-robin",
+ "enabled": true
+ },
+ {
+ "name": "loadbalance",
+ "type": "service-function-scheduler-type:load-balance",
+ "enabled": false
+ },
+ {
+ "name": "shortestpath",
+ "type": "service-function-scheduler-type:shortest-path",
+ "enabled": false
+ }
+ ]
+ }
+ }
+
+ If using the Linux curl command, it could be:
+
+ ::
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '$${Service_function_schudule_type.json}'
+ -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-scheduler-type:service-function-scheduler-types/
+
+ Here is also a snapshot for using the RESTClient plugin:
+
+.. figure:: ./images/sfc/RESTClient-snapshot.png
+ :alt: Mozilla Firefox RESTClient
+
+ Mozilla Firefox RESTClient
+
+- SFC-UI.SFC-UI provides a drop down menu for service function
+ selection algorithm. Here is a snapshot for the user interaction from
+ SFC-UI when creating a Rendered Service Path.
+
+.. figure:: ./images/sfc/karaf-webui-select-a-type.png
+ :alt: Karaf Web UI
+
+ Karaf Web UI
+
+.. note::
+
+ Some service function selection algorithms in the drop list are not
+ implemented yet. Only the first three algorithms are committed at
+ the moment.
+
+Random
+^^^^^^
+
+Select Service Function from the name list randomly.
+
+Overview
+''''''''
+
+The Random algorithm is used to select one Service Function from the
+name list which it gets from the Service Function Type randomly.
+
+Prerequisites
+'''''''''''''
+
+- Service Function information are stored in datastore.
+
+- Either no algorithm or the Random algorithm is selected.
+
+Target Environment
+''''''''''''''''''
+
+The Random algorithm will work either no algorithm type is selected or
+the Random algorithm is selected.
+
+Instructions
+''''''''''''
+
+Once the plugins are installed into Karaf successfully, a user can use
+his favorite method to select the Random scheduling algorithm type.
+There are no special instructions for using the Random algorithm.
+
+Round Robin
+^^^^^^^^^^^
+
+Select Service Function from the name list in Round Robin manner.
+
+Overview
+''''''''
+
+The Round Robin algorithm is used to select one Service Function from
+the name list which it gets from the Service Function Type in a Round
+Robin manner, this will balance workloads to all Service Functions.
+However, this method cannot help all Service Functions load the same
+workload because it’s flow-based Round Robin.
+
+Prerequisites
+'''''''''''''
+
+- Service Function information are stored in datastore.
+
+- Round Robin algorithm is selected
+
+Target Environment
+''''''''''''''''''
+
+The Round Robin algorithm will work one the Round Robin algorithm is
+selected.
+
+Instructions
+''''''''''''
+
+Once the plugins are installed into Karaf successfully, a user can use
+his favorite method to select the Round Robin scheduling algorithm type.
+There are no special instructions for using the Round Robin algorithm.
+
+Load Balance Algorithm
+^^^^^^^^^^^^^^^^^^^^^^
+
+Select appropriate Service Function by actual CPU utilization.
+
+Overview
+''''''''
+
+The Load Balance Algorithm is used to select appropriate Service
+Function by actual CPU utilization of service functions. The CPU
+utilization of service function obtained from monitoring information
+reported via NETCONF.
+
+Prerequisites
+'''''''''''''
+
+- CPU-utilization for Service Function.
+
+- NETCONF server.
+
+- NETCONF client.
+
+- Each VM has a NETCONF server and it could work with NETCONF client
+ well.
+
+Instructions
+''''''''''''
+
+Set up VMs as Service Functions. enable NETCONF server in VMs. Ensure
+that you specify them separately. For example:
+
+a. Set up 4 VMs include 2 SFs' type are Firewall, Others are Napt44.
+ Name them as firewall-1, firewall-2, napt44-1, napt44-2 as Service
+ Function. The four VMs can run either the same server or different
+ servers.
+
+b. Install NETCONF server on every VM and enable it. More information on
+ NETCONF can be found on the OpenDaylight wiki here:
+ https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf:Manual_netopeer_installation
+
+c. Get Monitoring data from NETCONF server. These monitoring data should
+ be get from the NETCONF server which is running in VMs. The following
+ static XML data is an example:
+
+static XML data like this:
+
+::
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <service-function-description-monitor-report>
+ <SF-description>
+ <number-of-dataports>2</number-of-dataports>
+ <capabilities>
+ <supported-packet-rate>5</supported-packet-rate>
+ <supported-bandwidth>10</supported-bandwidth>
+ <supported-ACL-number>2000</supported-ACL-number>
+ <RIB-size>200</RIB-size>
+ <FIB-size>100</FIB-size>
+ <ports-bandwidth>
+ <port-bandwidth>
+ <port-id>1</port-id>
+ <ipaddress>10.0.0.1</ipaddress>
+ <macaddress>00:1e:67:a2:5f:f4</macaddress>
+ <supported-bandwidth>20</supported-bandwidth>
+ </port-bandwidth>
+ <port-bandwidth>
+ <port-id>2</port-id>
+ <ipaddress>10.0.0.2</ipaddress>
+ <macaddress>01:1e:67:a2:5f:f6</macaddress>
+ <supported-bandwidth>10</supported-bandwidth>
+ </port-bandwidth>
+ </ports-bandwidth>
+ </capabilities>
+ </SF-description>
+ <SF-monitoring-info>
+ <liveness>true</liveness>
+ <resource-utilization>
+ <packet-rate-utilization>10</packet-rate-utilization>
+ <bandwidth-utilization>15</bandwidth-utilization>
+ <CPU-utilization>12</CPU-utilization>
+ <memory-utilization>17</memory-utilization>
+ <available-memory>8</available-memory>
+ <RIB-utilization>20</RIB-utilization>
+ <FIB-utilization>25</FIB-utilization>
+ <power-utilization>30</power-utilization>
+ <SF-ports-bandwidth-utilization>
+ <port-bandwidth-utilization>
+ <port-id>1</port-id>
+ <bandwidth-utilization>20</bandwidth-utilization>
+ </port-bandwidth-utilization>
+ <port-bandwidth-utilization>
+ <port-id>2</port-id>
+ <bandwidth-utilization>30</bandwidth-utilization>
+ </port-bandwidth-utilization>
+ </SF-ports-bandwidth-utilization>
+ </resource-utilization>
+ </SF-monitoring-info>
+ </service-function-description-monitor-report>
+
+a. Unzip SFC release tarball.
+
+b. Run SFC: ${sfc}/bin/karaf. More information on Service Function
+ Chaining can be found on the OpenDaylight SFC’s wiki page:
+ https://wiki.opendaylight.org/view/Service_Function_Chaining:Main
+
+a. Deploy the SFC2 (firewall-abstract2⇒napt44-abstract2) and click
+ button to Create Rendered Service Path in SFC UI
+ (http://localhost:8181/sfc/index.html).
+
+b. Verify the Rendered Service Path to ensure the CPU utilization of the
+ selected hop is the minimum one among all the service functions with
+ same type. The correct RSP is firewall-1⇒napt44-2
+
+Shortest Path Algorithm
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Select appropriate Service Function by Dijkstra’s algorithm. Dijkstra’s
+algorithm is an algorithm for finding the shortest paths between nodes
+in a graph.
+
+Overview
+''''''''
+
+The Shortest Path Algorithm is used to select appropriate Service
+Function by actual topology.
+
+Prerequisites
+'''''''''''''
+
+- Depolyed topology (include SFFs, SFs and their links).
+
+- Dijkstra’s algorithm. More information on Dijkstra’s algorithm can be
+ found on the wiki here:
+ http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
+
+Instructions
+''''''''''''
+
+a. Unzip SFC release tarball.
+
+b. Run SFC: ${sfc}/bin/karaf.
+
+c. Depoly SFFs and SFs. import the service-function-forwarders.json and
+ service-functions.json in UI
+ (http://localhost:8181/sfc/index.html#/sfc/config)
+
+service-function-forwarders.json:
+
+::
+
+ {
+ "service-function-forwarders": {
+ "service-function-forwarder": [
+ {
+ "name": "SFF-br1",
+ "service-node": "OVSDB-test01",
+ "rest-uri": "http://localhost:5001",
+ "sff-data-plane-locator": [
+ {
+ "name": "eth0",
+ "service-function-forwarder-ovs:ovs-bridge": {
+ "uuid": "4c3778e4-840d-47f4-b45e-0988e514d26c",
+ "bridge-name": "br-tun"
+ },
+ "data-plane-locator": {
+ "port": 5000,
+ "ip": "192.168.1.1",
+ "transport": "service-locator:vxlan-gpe"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "sff-sf-data-plane-locator": {
+ "port": 10001,
+ "ip": "10.3.1.103"
+ },
+ "name": "napt44-1",
+ "type": "service-function-type:napt44"
+ },
+ {
+ "sff-sf-data-plane-locator": {
+ "port": 10003,
+ "ip": "10.3.1.102"
+ },
+ "name": "firewall-1",
+ "type": "service-function-type:firewall"
+ }
+ ],
+ "connected-sff-dictionary": [
+ {
+ "name": "SFF-br3"
+ }
+ ]
+ },
+ {
+ "name": "SFF-br2",
+ "service-node": "OVSDB-test01",
+ "rest-uri": "http://localhost:5002",
+ "sff-data-plane-locator": [
+ {
+ "name": "eth0",
+ "service-function-forwarder-ovs:ovs-bridge": {
+ "uuid": "fd4d849f-5140-48cd-bc60-6ad1f5fc0a1",
+ "bridge-name": "br-tun"
+ },
+ "data-plane-locator": {
+ "port": 5000,
+ "ip": "192.168.1.2",
+ "transport": "service-locator:vxlan-gpe"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "sff-sf-data-plane-locator": {
+ "port": 10002,
+ "ip": "10.3.1.103"
+ },
+ "name": "napt44-2",
+ "type": "service-function-type:napt44"
+ },
+ {
+ "sff-sf-data-plane-locator": {
+ "port": 10004,
+ "ip": "10.3.1.101"
+ },
+ "name": "firewall-2",
+ "type": "service-function-type:firewall"
+ }
+ ],
+ "connected-sff-dictionary": [
+ {
+ "name": "SFF-br3"
+ }
+ ]
+ },
+ {
+ "name": "SFF-br3",
+ "service-node": "OVSDB-test01",
+ "rest-uri": "http://localhost:5005",
+ "sff-data-plane-locator": [
+ {
+ "name": "eth0",
+ "service-function-forwarder-ovs:ovs-bridge": {
+ "uuid": "fd4d849f-5140-48cd-bc60-6ad1f5fc0a4",
+ "bridge-name": "br-tun"
+ },
+ "data-plane-locator": {
+ "port": 5000,
+ "ip": "192.168.1.2",
+ "transport": "service-locator:vxlan-gpe"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "sff-sf-data-plane-locator": {
+ "port": 10005,
+ "ip": "10.3.1.104"
+ },
+ "name": "test-server",
+ "type": "service-function-type:dpi"
+ },
+ {
+ "sff-sf-data-plane-locator": {
+ "port": 10006,
+ "ip": "10.3.1.102"
+ },
+ "name": "test-client",
+ "type": "service-function-type:dpi"
+ }
+ ],
+ "connected-sff-dictionary": [
+ {
+ "name": "SFF-br1"
+ },
+ {
+ "name": "SFF-br2"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+service-functions.json:
+
+::
+
+ {
+ "service-functions": {
+ "service-function": [
+ {
+ "rest-uri": "http://localhost:10001",
+ "ip-mgmt-address": "10.3.1.103",
+ "sf-data-plane-locator": [
+ {
+ "name": "preferred",
+ "port": 10001,
+ "ip": "10.3.1.103",
+ "service-function-forwarder": "SFF-br1"
+ }
+ ],
+ "name": "napt44-1",
+ "type": "service-function-type:napt44",
+ "nsh-aware": true
+ },
+ {
+ "rest-uri": "http://localhost:10002",
+ "ip-mgmt-address": "10.3.1.103",
+ "sf-data-plane-locator": [
+ {
+ "name": "master",
+ "port": 10002,
+ "ip": "10.3.1.103",
+ "service-function-forwarder": "SFF-br2"
+ }
+ ],
+ "name": "napt44-2",
+ "type": "service-function-type:napt44",
+ "nsh-aware": true
+ },
+ {
+ "rest-uri": "http://localhost:10003",
+ "ip-mgmt-address": "10.3.1.103",
+ "sf-data-plane-locator": [
+ {
+ "name": "1",
+ "port": 10003,
+ "ip": "10.3.1.102",
+ "service-function-forwarder": "SFF-br1"
+ }
+ ],
+ "name": "firewall-1",
+ "type": "service-function-type:firewall",
+ "nsh-aware": true
+ },
+ {
+ "rest-uri": "http://localhost:10004",
+ "ip-mgmt-address": "10.3.1.103",
+ "sf-data-plane-locator": [
+ {
+ "name": "2",
+ "port": 10004,
+ "ip": "10.3.1.101",
+ "service-function-forwarder": "SFF-br2"
+ }
+ ],
+ "name": "firewall-2",
+ "type": "service-function-type:firewall",
+ "nsh-aware": true
+ },
+ {
+ "rest-uri": "http://localhost:10005",
+ "ip-mgmt-address": "10.3.1.103",
+ "sf-data-plane-locator": [
+ {
+ "name": "3",
+ "port": 10005,
+ "ip": "10.3.1.104",
+ "service-function-forwarder": "SFF-br3"
+ }
+ ],
+ "name": "test-server",
+ "type": "service-function-type:dpi",
+ "nsh-aware": true
+ },
+ {
+ "rest-uri": "http://localhost:10006",
+ "ip-mgmt-address": "10.3.1.103",
+ "sf-data-plane-locator": [
+ {
+ "name": "4",
+ "port": 10006,
+ "ip": "10.3.1.102",
+ "service-function-forwarder": "SFF-br3"
+ }
+ ],
+ "name": "test-client",
+ "type": "service-function-type:dpi",
+ "nsh-aware": true
+ }
+ ]
+ }
+ }
+
+The depolyed topology like this:
+
+::
+
+ +----+ +----+ +----+
+ |sff1|+----------|sff3|---------+|sff2|
+ +----+ +----+ +----+
+ | |
+ +--------------+ +--------------+
+ | | | |
+ +----------+ +--------+ +----------+ +--------+
+ |firewall-1| |napt44-1| |firewall-2| |napt44-2|
+ +----------+ +--------+ +----------+ +--------+
+
+- Deploy the SFC2(firewall-abstract2⇒napt44-abstract2), select
+ "Shortest Path" as schedule type and click button to Create Rendered
+ Service Path in SFC UI (http://localhost:8181/sfc/index.html).
+
+.. figure:: ./images/sfc/sf-schedule-type.png
+ :alt: select schedule type
+
+ select schedule type
+
+- Verify the Rendered Service Path to ensure the selected hops are
+ linked in one SFF. The correct RSP is firewall-1⇒napt44-1 or
+ firewall-2⇒napt44-2. The first SF type is Firewall in Service
+ Function Chain. So the algorithm will select first Hop randomly among
+ all the SFs type is Firewall. Assume the first selected SF is
+ firewall-2. All the path from firewall-1 to SF which type is Napt44
+ are list:
+
+ - Path1: firewall-2 → sff2 → napt44-2
+
+ - Path2: firewall-2 → sff2 → sff3 → sff1 → napt44-1 The shortest
+ path is Path1, so the selected next hop is napt44-2.
+
+.. figure:: ./images/sfc/sf-rendered-service-path.png
+ :alt: rendered service path
+
+ rendered service path
+
+Service Function Load Balancing User Guide
+------------------------------------------
+
+Overview
+~~~~~~~~
+
+SFC Load-Balancing feature implements load balancing of Service
+Functions, rather than a one-to-one mapping between
+Service-Function-Forwarder and Service-Function.
+
+Load Balancing Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Service Function Groups (SFG) can replace Service Functions (SF) in the
+Rendered Path model. A Service Path can only be defined using SFGs or
+SFs, but not a combination of both.
+
+Relevant objects in the YANG model are as follows:
+
+1. Service-Function-Group-Algorithm:
+
+ ::
+
+ Service-Function-Group-Algorithms {
+ Service-Function-Group-Algorithm {
+ String name
+ String type
+ }
+ }
+
+ ::
+
+ Available types: ALL, SELECT, INDIRECT, FAST_FAILURE
+
+2. Service-Function-Group:
+
+ ::
+
+ Service-Function-Groups {
+ Service-Function-Group {
+ String name
+ String serviceFunctionGroupAlgorithmName
+ String type
+ String groupId
+ Service-Function-Group-Element {
+ String service-function-name
+ int index
+ }
+ }
+ }
+
+3. ServiceFunctionHop: holds a reference to a name of SFG (or SF)
+
+Tutorials
+~~~~~~~~~
+
+This tutorial will explain how to create a simple SFC configuration,
+with SFG instead of SF. In this example, the SFG will include two
+existing SF.
+
+Setup SFC
+^^^^^^^^^
+
+For general SFC setup and scenarios, please see the SFC wiki page:
+https://wiki.opendaylight.org/view/Service_Function_Chaining:Main#SFC_101
+
+Create an algorithm
+^^^^^^^^^^^^^^^^^^^
+
+POST -
+http://127.0.0.1:8181/restconf/config/service-function-group-algorithm:service-function-group-algorithms
+
+::
+
+ {
+ "service-function-group-algorithm": [
+ {
+ "name": "alg1"
+ "type": "ALL"
+ }
+ ]
+ }
+
+(Header "content-type": application/json)
+
+Verify: get all algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GET -
+http://127.0.0.1:8181/restconf/config/service-function-group-algorithm:service-function-group-algorithms
+
+In order to delete all algorithms: DELETE -
+http://127.0.0.1:8181/restconf/config/service-function-group-algorithm:service-function-group-algorithms
+
+Create a group
+^^^^^^^^^^^^^^
+
+POST -
+http://127.0.0.1:8181/restconf/config/service-function-group:service-function-groups
+
+::
+
+ {
+ "service-function-group": [
+ {
+ "rest-uri": "http://localhost:10002",
+ "ip-mgmt-address": "10.3.1.103",
+ "algorithm": "alg1",
+ "name": "SFG1",
+ "type": "service-function-type:napt44",
+ "sfc-service-function": [
+ {
+ "name":"napt44-104"
+ },
+ {
+ "name":"napt44-103-1"
+ }
+ ]
+ }
+ ]
+ }
+
+Verify: get all SFG’s
+^^^^^^^^^^^^^^^^^^^^^
+
+GET -
+http://127.0.0.1:8181/restconf/config/service-function-group:service-function-groups
+
+SFC Proof of Transit User Guide
+-------------------------------
+
+Overview
+~~~~~~~~
+
+Early Service Function Chaining (SFC) Proof of Transit (SFC Proof of
+Transit) implements Service Chaining Proof of Transit functionality on
+capable switches. After the creation of an Rendered Service Path (RSP),
+a user can configure to enable SFC proof of transit on the selected RSP
+to effect the proof of transit.
+
+Common acronyms used in the following sections:
+
+- SF - Service Function
+
+- SFF - Service Function Forwarder
+
+- SFC - Service Function Chain
+
+- SFP - Service Function Path
+
+- RSP - Rendered Service Path
+
+- SFCPOT - Service Function Chain Proof of Transit
+
+SFC Proof of Transit Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When SFC Proof of Transit is initialized, all required listeners are
+registered to handle incoming data. It involves ``SfcPotNodeListener``
+which stores data about all node devices including their mountpoints
+(used here as databrokers), ``SfcPotRSPDataListener``,
+``RenderedPathListener``. ``RenderedPathListener`` is used to listen for
+RSP changes. ``SfcPotRSPDataListener`` implements RPC services to enable
+or disable SFC Proof of Transit on a particular RSP. When the SFC Proof
+of Transit is invoked, RSP listeners and service implementations are
+setup to receive SFCPOT configurations. When a user configures via a
+POST RPC call to enable SFCPOT on a particular RSP, the configuration
+drives the creation of necessary augmentations to the RSP to effect the
+SFCPOT configurations.
+
+SFC Proof of Transit details
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Several deployments use traffic engineering, policy routing, segment
+routing or service function chaining (SFC) to steer packets through a
+specific set of nodes. In certain cases regulatory obligations or a
+compliance policy require to prove that all packets that are supposed to
+follow a specific path are indeed being forwarded across the exact set
+of nodes specified. I.e. if a packet flow is supposed to go through a
+series of service functions or network nodes, it has to be proven that
+all packets of the flow actually went through the service chain or
+collection of nodes specified by the policy. In case the packets of a
+flow weren’t appropriately processed, a proof of transit egress device
+would be required to identify the policy violation and take
+corresponding actions (e.g. drop or redirect the packet, send an alert
+etc.) corresponding to the policy.
+
+The SFCPOT approach is based on meta-data which is added to every
+packet. The meta data is updated at every hop and is used to verify
+whether a packet traversed all required nodes. A particular path is
+either described by a set of secret keys, or a set of shares of a single
+secret. Nodes on the path retrieve their individual keys or shares of a
+key (using for e.g. Shamir’s Shared Sharing Secret scheme) from a
+central controller. The complete key set is only known to the verifier-
+which is typically the ultimate node on a path that requires proof of
+transit. Each node in the path uses its secret or share of the secret to
+update the meta-data of the packets as the packets pass through the
+node. When the verifier receives a packet, it can use its key(s) along
+with the meta-data to validate whether the packet traversed the service
+chain correctly.
+
+SFC Proof of Transit entities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to implement SFC Proof of Transit for a service function chain,
+an RSP is a pre-requisite to identify the SFC to enable SFC PoT on. SFC
+Proof of Transit for a particular RSP is enabled by an RPC request to
+the controller along with necessary parameters to control some of the
+aspects of the SFC Proof of Transit process.
+
+The RPC handler identifies the RSP and generates SFC Proof of Transit
+parameters like secret share, secret etc., and adds the generated SFCPOT
+configuration parameters to SFC main as well as the various SFC hops.
+The last node in the SFC is configured as a verifier node to allow
+SFCPOT Proof of Transit process to be completed.
+
+The SFCPOT configuration generators and related handling are done by
+``SfcPotAPI``, ``SfcPotConfigGenerator``, ``SfcPotListener``,
+``SfcPotPolyAPI``, ``SfcPotPolyClassAPI`` and ``SfcPotPolyClass``.
+
+Administering SFC Proof of Transit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the SFC Proof of Transit Karaf, at least the following Karaf
+features must be installed:
+
+- odl-sfc-model
+
+- odl-sfc-provider
+
+- odl-sfc-netconf
+
+- odl-restconf
+
+- odl-netconf-topology
+
+- odl-netconf-connector-all
+
+- odl-sfc-pot
+
+SFC Proof of Transit Tutorial
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Overview
+^^^^^^^^
+
+This tutorial is a simple example how to configure Service Function
+Chain Proof of Transit using SFC POT feature.
+
+Preconditions
+^^^^^^^^^^^^^
+
+To enable a device to handle SFC Proof of Transit, it is expected that
+the netconf server device advertise capability as under ioam-scv.yang
+present under src/main/yang folder of sfc-pot feature. It is also
+expected that netconf notifications be enabled and its support
+capability advertised as capabilities.
+
+It is also expected that the devices are netconf mounted and available
+in the topology-netconf store.
+
+Instructions
+^^^^^^^^^^^^
+
+When SFC Proof of Transit is installed, all netconf nodes in
+topology-netconf are processed and all capable nodes with accessible
+mountpoints are cached.
+
+First step is to create the required RSP as usually done.
+
+Once RSP name is avaiable it is used to send a POST RPC to the
+controller similar to below:
+
+::
+
+ POST ./restconf/operations/sfc-ioam-nb-pot:enable-sfc-ioam-pot-rendered-path
+
+ {
+ "input": {
+ "sfc-ioam-pot-rsp-name": "rsp1"
+ }
+ }
+
+The following can be used to disable the SFC Proof of Transit on an RSP
+which removes the augmentations and stores back the RSP without the
+SFCPOT enabled features and also sending down a delete configuration to
+the SFCPOT configuration sub-tree in the nodes.
+
+::
+
+ POST ./restconf/operations/sfc-ioam-nb-pot:disable-sfc-ioam-pot-rendered-path
+
+ {
+ "input": {
+ "sfc-ioam-pot-rsp-name": "rsp1"
+ }
+ }
+
--- /dev/null
+SNMP4SDN User Guide
+===================
+
+Overview
+--------
+
+We propose a southbound plugin that can control the off-the-shelf
+commodity Ethernet switches for the purpose of building SDN using
+Ethernet switches. For Ethernet switches, forwarding table, VLAN table,
+and ACL are where one can install flow configuration on, and this is
+done via SNMP and CLI in the proposed plugin. In addition, some settings
+required for Ethernet switches in SDN, e.g., disabling STP and flooding,
+are proposed.
+
+.. figure:: ./images/snmp4sdn_in_odl_architecture.jpg
+ :alt: SNMP4SDN as an OpenDaylight southbound plugin
+
+ SNMP4SDN as an OpenDaylight southbound plugin
+
+Configuration
+-------------
+
+Just follow the steps:
+
+Prepare the switch list database file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A sample is
+`here <https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file>`__,
+and we suggest to save it as */etc/snmp4sdn\_swdb.csv* so that SNMP4SDN
+Plugin can automatically load this file. Note that the first line is
+title and should not be removed.
+
+Prepare the vendor-specific configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A sample is
+`here <https://wiki.opendaylight.org/view/SNMP4SDN:snmp4sdn_VendorSpecificSwitchConfig_file>`__,
+and we suggest to save it as
+*/etc/snmp4sdn\_VendorSpecificSwitchConfig.xml* so that SNMP4SDN Plugin
+can automatically load this file.
+
+Install SNMP4SDN Plugin
+-----------------------
+
+If using SNMP4SDN Plugin provided in OpenDaylight release, just do the
+following from the Karaf CLI:
+
+::
+
+ feature:install odl-snmp4sdn-all
+
+Troubleshooting
+---------------
+
+Installation Troubleshooting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Feature installation failure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When trying to install a feature, if the following failure occurs:
+
+::
+
+ Error executing command: Could not start bundle ...
+ Reason: Missing Constraint: Require-Capability: osgi.ee; filter="(&(osgi.ee=JavaSE)(version=1.7))"
+
+A workaround: exit Karaf, and edit the file
+<karaf\_directory>/etc/config.properties, remove the line
+*${services-${karaf.framework}}* and the ", \\" in the line above.
+
+Runtime Troubleshooting
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Problem starting SNMP Trap Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to get the following exception during controller startup.
+(The error would not be printed in Karaf console, one may see it in
+<karaf\_directory>/data/log/karaf.log)
+
+::
+
+ 2014-01-31 15:00:44.688 CET [fileinstall-./plugins] WARN o.o.snmp4sdn.internal.SNMPListener - Problem starting SNMP Trap Interface: {}
+ java.net.BindException: Permission denied
+ at java.net.PlainDatagramSocketImpl.bind0(Native Method) ~[na:1.7.0_51]
+ at java.net.AbstractPlainDatagramSocketImpl.bind(AbstractPlainDatagramSocketImpl.java:95) ~[na:1.7.0_51]
+ at java.net.DatagramSocket.bind(DatagramSocket.java:376) ~[na:1.7.0_51]
+ at java.net.DatagramSocket.<init>(DatagramSocket.java:231) ~[na:1.7.0_51]
+ at java.net.DatagramSocket.<init>(DatagramSocket.java:284) ~[na:1.7.0_51]
+ at java.net.DatagramSocket.<init>(DatagramSocket.java:256) ~[na:1.7.0_51]
+ at org.snmpj.SNMPTrapReceiverInterface.<init>(SNMPTrapReceiverInterface.java:126) ~[org.snmpj-1.4.3.jar:na]
+ at org.snmpj.SNMPTrapReceiverInterface.<init>(SNMPTrapReceiverInterface.java:99) ~[org.snmpj-1.4.3.jar:na]
+ at org.opendaylight.snmp4sdn.internal.SNMPListener.<init>(SNMPListener.java:75) ~[bundlefile:na]
+ at org.opendaylight.snmp4sdn.core.internal.Controller.start(Controller.java:174) [bundlefile:na]
+ ...
+
+This indicates that the controller is being run as a user which does not
+have sufficient OS privileges to bind the SNMPTRAP port (162/UDP)
+
+Switch list file missing
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SNMP4SDN Plugin needs a switch list file, which is necessary for
+topology discovery and should be provided by the administrator (so
+please prepare one for the first time using SNMP4SDN Plugin, here is the
+`sample <https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file>`__).
+The default file path is /etc/snmp4sdn\_swdb.csv. SNMP4SDN Plugin would
+automatically load this file and start topology discovery. If this file
+is not ready there, the following message like this will pop up:
+
+::
+
+ 2016-02-02 04:21:52,476 | INFO| Event Dispatcher | CmethUtil | 466 - org.opendaylight.snmp4sdn - 0.3.0.SNAPSHOT | CmethUtil.readDB() err: {}
+ java.io.FileNotFoundException: /etc/snmp4sdn_swdb.csv (No such file or directory)
+ at java.io.FileInputStream.open0(Native Method)[:1.8.0_65]
+ at java.io.FileInputStream.open(FileInputStream.java:195)[:1.8.0_65]
+ at java.io.FileInputStream.<init>(FileInputStream.java:138)[:1.8.0_65]
+ at java.io.FileInputStream.<init>(FileInputStream.java:93)[:1.8.0_65]
+ at java.io.FileReader.<init>(FileReader.java:58)[:1.8.0_65]
+ at org.opendaylight.snmp4sdn.internal.util.CmethUtil.readDB(CmethUtil.java:66)
+ at org.opendaylight.snmp4sdn.internal.util.CmethUtil.<init>(CmethUtil.java:43)
+ ...
+
+Configuration
+-------------
+
+Just follow the steps:
+
+1. Prepare the switch list database file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A sample is
+`here <https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file>`__,
+and we suggest to save it as */etc/snmp4sdn\_swdb.csv* so that SNMP4SDN
+Plugin can automatically load this file.
+
+.. note::
+
+ The first line is title and should not be removed.
+
+2. Prepare the vendor-specific configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A sample is
+`here <https://wiki.opendaylight.org/view/SNMP4SDN:snmp4sdn_VendorSpecificSwitchConfig_file>`__,
+and we suggest to save it as
+*/etc/snmp4sdn\_VendorSpecificSwitchConfig.xml* so that SNMP4SDN Plugin
+can automatically load this file.
+
+3. Install SNMP4SDN Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If using SNMP4SDN Plugin provided in OpenDaylight release, just do the
+following:
+
+Launch Karaf in Linux console:
+
+::
+
+ cd <Beryllium_controller_directory>/bin
+ (for example, cd distribution-karaf-x.x.x-Beryllium/bin)
+
+::
+
+ ./karaf
+
+Then in Karaf console, execute:
+
+::
+
+ feature:install odl-snmp4sdn-all
+
+4. Load switch list
+~~~~~~~~~~~~~~~~~~~
+
+For initialization, we need to feed SNMP4SDN Plugin the switch list.
+Actually SNMP4SDN Plugin automatically try to load the switch list at
+/etc/snmp4sdn\_swdb.csv if there is. If so, this step could be skipped.
+In Karaf console, execute:
+
+::
+
+ snmp4sdn:ReadDB <switch_list_path>
+ (For example, snmp4sdn:ReadDB /etc/snmp4sdn_swdb.csv)
+ (in Windows OS, For example, snmp4sdn:ReadDB D://snmp4sdn_swdb.csv)
+
+A sample is
+`here <https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file>`__,
+and we suggest to save it as */etc/snmp4sdn\_swdb.csv* so that SNMP4SDN
+Plugin can automatically load this file.
+
+.. note::
+
+ The first line is title and should not be removed.
+
+5. Show switch list
+~~~~~~~~~~~~~~~~~~~
+
+::
+
+ snmp4sdn:PrintDB
+
+Tutorial
+--------
+
+Topology Service
+~~~~~~~~~~~~~~~~
+
+Execute topology discovery
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The SNMP4SDN Plugin automatically executes topology discovery on
+startup. One may use the following commands to invoke topology discovery
+manually. Note that you may need to wait for seconds for itto complete.
+
+.. note::
+
+ Currently, one needs to manually execute *snmp4sdn:TopoDiscover*
+ first (just once), then later the automatic topology discovery can
+ be successful. If switches change (switch added or removed),
+ *snmp4sdn:TopoDiscover* is also required. A future version will fix
+ it to eliminate these requirements.
+
+::
+
+ snmp4sdn:TopoDiscover
+
+If one like to discover all inventory (i.e. switches and their ports)
+but not edges, just execute "TopoDiscoverSwitches":
+
+::
+
+ snmp4sdn:TopoDiscoverSwitches
+
+If one like to only discover all edges but not inventory, just execute
+"TopoDiscoverEdges":
+
+::
+
+ snmp4sdn:TopoDiscoverEdges
+
+You can also trigger topology discovery via the REST API by using
+``curl`` from the Linux console (or any other REST client):
+
+::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:rediscover
+
+You can change the periodic topology discovery interval via a REST API:
+
+::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:set-discovery-interval -d "{"input":{"interval-second":'<interval_time>'}}"
+ For example, set the interval as 15 seconds:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:set-discovery-interval -d "{"input":{"interval-second":'15'}}"
+
+Show the topology
+^^^^^^^^^^^^^^^^^
+
+SNMP4SDN Plugin supports to show topology via REST API:
+
+- Get topology
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:get-edge-list
+
+- Get switch list
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:get-node-list
+
+- Get switches' ports list
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:get-node-connector-list
+
+- The three commands above are just for user to get the latest topology
+ discovery result, it does not trigger SNMP4SDN Plugin to do topology
+ discovery.
+
+- To trigger SNMP4SDN Plugin to do topology discover, as described in
+ aforementioned *Execute topology discovery*.
+
+Flow configuration
+~~~~~~~~~~~~~~~~~~
+
+FDB configuration
+^^^^^^^^^^^^^^^^^
+
+SNMP4SDN supports to add entry on FDB table via REST API:
+
+- Get FDB table
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:get-fdb-table -d "{input:{"node-id":<switch-mac-address-in-number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:get-fdb-table -d "{input:{"node-id":158969157063648}}"
+
+- Get FDB table entry
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:get-fdb-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "dest-mac-addr":<destination-mac-address-in-number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:get-fdb-entry -d "{input:{"node-id":158969157063648, "vlan-id":1, "dest-mac-addr":158969157063648}}"
+
+- Set FDB table entry
+
+ (Notice invalid value: (1) non unicast mac (2) port not in the VLAN)
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:set-fdb-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "dest-mac-addr":<destination-mac-address-in-number>, "port":<port-in-number>, "type":'<type>'}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:set-fdb-entry -d "{input:{"node-id":158969157063648, "vlan-id":1, "dest-mac-addr":187649984473770, "port":23, "type":'MGMT'}}"
+
+- Delete FDB table entry
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:del-fdb-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "dest-mac-addr":<destination-mac-address-in-number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:del-fdb-entry -d "{input:{"node-id":158969157063648, "vlan-id":1, "dest-mac-addr":187649984473770}}"
+
+VLAN configuration
+^^^^^^^^^^^^^^^^^^
+
+SNMP4SDN supports to add entry on VLAN table via REST API:
+
+- Get VLAN table
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:get-vlan-table -d "{input:{node-id:<switch-mac-address-in-number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:get-vlan-table -d "{input:{node-id:158969157063648}}"
+
+- Add VLAN
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:add-vlan -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "vlan-name":'<vlan-name>'}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:add-vlan -d "{"input":{"node-id":158969157063648, "vlan-id":123, "vlan-name":'v123'}}"
+
+- Delete VLAN
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:delete-vlan -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:delete-vlan -d "{"input":{"node-id":158969157063648, "vlan-id":123}}"
+
+- Add VLAN and set ports
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:add-vlan-and-set-ports -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "vlan-name":'<vlan-name>', "tagged-port-list":'<tagged-ports-separated-by-comma>', "untagged-port-list":'<untagged-ports-separated-by-comma>'}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:add-vlan-and-set-ports -d "{"input":{"node-id":158969157063648, "vlan-id":123, "vlan-name":'v123', "tagged-port-list":'1,2,3', "untagged-port-list":'4,5,6'}}"
+
+- Set VLAN ports
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:set-vlan-ports -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "tagged-port-list":'<tagged-ports-separated-by-comma>', "untagged-port-list":'<untagged-ports-separated-by-comma>'}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:set-vlan-ports -d "{"input":{"node-id":"158969157063648", "vlan-id":"123", "tagged-port-list":'4,5', "untagged-port-list":'2,3'}}"
+
+ACL configuration
+^^^^^^^^^^^^^^^^^
+
+SNMP4SDN supports to add flow on ACL table via REST API. However, it is
+so far only implemented for the D-Link DGS-3120 switch.
+
+ACL configuration via CLI is vendor-specific, and SNMP4SDN will support
+configuration with vendor-specific CLI in future release.
+
+To do ACL configuration using the REST APIs, use commands like the
+following:
+
+- Clear ACL table
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:clear-acl-table -d "{"input":{"nodeId":<switch-mac-address-in-number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:clear-acl-table -d "{"input":{"nodeId":158969157063648}}"
+
+- Create ACL profile (IP layer)
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"acl-layer":'IP',"vlan-mask":<vlan_mask_in_number>,"src-ip-mask":'<src_ip_mask>',"dst-ip-mask":"<destination_ip_mask>"}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":158969157063648,"profile-id":1,"profile-name":'profile_1',"acl-layer":'IP',"vlan-mask":1,"src-ip-mask":'255.255.0.0',"dst-ip-mask":'255.255.255.255'}}"
+
+- Create ACL profile (MAC layer)
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"acl-layer":'ETHERNET',"vlan-mask":<vlan_mask_in_number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":158969157063648,"profile-id":2,"profile-name":'profile_2',"acl-layer":'ETHERNET',"vlan-mask":4095}}"
+
+- Delete ACL profile
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":158969157063648,"profile-id":1}}"
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-name":"<profile_name>"}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":158969157063648,"profile-name":'profile_2'}}"
+
+- Set ACL rule
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:set-acl-rule -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"rule-id":<rule_id_in_number>,"port-list":[<port_number>,<port_number>,...],"acl-layer":'<acl_layer>',"vlan-id":<vlan_id_in_number>,"src-ip":"<src_ip_address>","dst-ip":'<dst_ip_address>',"acl-action":'<acl_action>'}}"
+ (<acl_layer>: IP or ETHERNET)
+ (<acl_action>: PERMIT as permit, DENY as deny)
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:set-acl-rule -d "{input:{"nodeId":158969157063648,"profile-id":1,"profile-name":'profile_1',"rule-id":1,"port-list":[1,2,3],"acl-layer":'IP',"vlan-id":2,"src-ip":'1.1.1.1',"dst-ip":'2.2.2.2',"acl-action":'PERMIT'}}"
+
+- Delete ACL rule
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:del-acl-rule -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"rule-id":<rule_id_in_number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-rule -d "{input:{"nodeId":158969157063648,"profile-id":1,"profile-name":'profile_1',"rule-id":1}}"
+
+Special configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+SNMP4SDN supports setting the following special configurations via REST
+API:
+
+- Set STP port state
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:set-stp-port-state -d "{input:{"node-id":<switch-mac-address-in-number>, "port":<port_number>, enable:<true_or_false>}}"
+ (true: enable, false: disable)
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:set-stp-port-state -d "{input:{"node-id":158969157063648, "port":2, enable:false}}"
+
+- Get STP port state
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-stp-port-state -d "{input:{"node-id":<switch-mac-address-in-number>, "port":<port_number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-stp-port-state -d "{input:{"node-id":158969157063648, "port":2}}"
+
+- Get STP port root
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-stp-port-root -d "{input:{"node-id":<switch-mac-address-in-number>, "port":<port_number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-stp-port-root -d "{input:{"node-id":158969157063648, "port":2}}"
+
+- Enable STP
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:enable-stp -d "{input:{"node-id":<switch-mac-address-in-number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:enable-stp -d "{input:{"node-id":158969157063648}}"
+
+- Disable STP
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:disable-stp -d "{input:{"node-id":<switch-mac-address-in-number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:disable-stp -d "{input:{"node-id":158969157063648}}"
+
+- Get ARP table
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-arp-table -d "{input:{"node-id":<switch-mac-address-in-number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-arp-table -d "{input:{"node-id":158969157063648}}"
+
+- Set ARP entry
+
+ (Notice to give IP address with subnet prefix)
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:set-arp-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "ip-address":'<ip_address>', "mac-address":<mac_address_in_number>}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:set-arp-entry -d "{input:{"node-id":158969157063648, "ip-address":'10.217.9.9', "mac-address":1}}"
+
+- Get ARP entry
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-arp-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "ip-address":'<ip_address>'}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-arp-entry -d "{input:{"node-id":158969157063648, "ip-address":'10.217.9.9'}}"
+
+- Delete ARP entry
+
+ ::
+
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:delete-arp-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "ip-address":'<ip_address>'}}"
+
+ For example:
+ curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:delete-arp-entry -d "{input:{"node-id":158969157063648, "ip-address":'10.217.9.9'}}"
+
+Using Postman to invoke REST API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Besides using the curl tool to invoke REST API, like the examples
+aforementioned, one can also use GUI tool like Postman for better data
+display.
+
+- Install Postman: `Install Postman in the Chrome
+ browser <https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en>`__
+
+- In the chrome browser bar enter
+
+ ::
+
+ chrome://apps/
+
+- Click on Postman.
+
+Example: Get VLAN table using Postman
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As the screenshot shown below, one needs to fill in required fields.
+
+::
+
+ URL:
+ http://<controller_ip_address>:8181/restconf/operations/vlan:get-vlan-table
+
+ Accept header:
+ application/json
+
+ Content-type:
+ application/json
+
+ Body:
+ {input:{"node-id":<node_id>}}
+ for example:
+ {input:{"node-id":158969157063648}}
+
+.. figure:: ./images/snmp4sdn_getvlantable_postman.jpg
+ :alt: Example: Get VLAN table using Postman
+
+ Example: Get VLAN table using Postman
+
+Multi-vendor support
+--------------------
+
+So far the supported vendor-specific configurations:
+
+- Add VLAN and set ports
+
+- (More functions are TBD)
+
+The SNMP4SDN Plugin would examine whether the configuration is described
+in the vendor-specific configuration file. If yes, the configuration
+description would be adopted, otherwise just use the default
+configuration. For example, adding VLAN and setting the ports is
+supported via SNMP standard MIB. However we found some special cases,
+for example, certain Accton switch requires to add VLAN first and then
+allows to set the ports. So one may describe this in the vendor-specific
+configuration file.
+
+A vendor-specific configuration file sample is
+`here <https://wiki.opendaylight.org/view/SNMP4SDN:snmp4sdn_VendorSpecificSwitchConfig_file>`__,
+and we suggest to save it as
+*/etc/snmp4sdn\_VendorSpecificSwitchConfig.xml* so that SNMP4SDN Plugin
+can automatically load it.
+
+Help
+----
+
+- `SNMP4SDN Wiki <https://wiki.opendaylight.org/view/SNMP4SDN:Main>`__
+
+- SNMP4SDN Mailing Lists:
+ (`user <https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-users>`__,
+ `developer <https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-dev>`__)
+
+- Latest
+ `troubleshooting <https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Troubleshooting>`__
+ in Wiki
+
--- /dev/null
+SXP User Guide
+==============
+
+Overview
+--------
+
+SXP (Source-Group Tag eXchange Protocol) project is an effort to enhance
+OpenDaylight platform with IP-SGT (IP Address to Source Group Tag)
+bindings that can be learned from connected SXP-aware network nodes. The
+current implementation supports SXP protocol version 4 according to the
+Smith, Kandula - SXP `IETF
+draft <https://tools.ietf.org/html/draft-smith-kandula-sxp-04>`__ and
+grouping of peers and creating filters based on ACL/Prefix-list syntax
+for filtering outbound and inbound IP-SGT bindings. All protocol legacy
+versions 1-3 are supported as well. Additionally, version 4 adds
+bidirectional connection type as an extension of a unidirectional one.
+
+SXP Architecture
+----------------
+
+The SXP Server manages all connected clients in separate threads and a
+common SXP protocol agreement is used between connected peers. Each SXP
+network peer is modelled with its pertaining class, e.g., SXP Server
+represents the SXP Speaker, SXP Listener the Client. The server program
+creates the ServerSocket object on a specified port and waits until a
+client starts up and requests connect on the IP address and port of the
+server. The client program opens a Socket that is connected to the
+server running on the specified host IP address and port.
+
+The SXP Listener maintains connection with its speaker peer. From an
+opened channel pipeline, all incoming SXP messages are processed by
+various handlers. Message must be decoded, parsed and validated.
+
+The SXP Speaker is a counterpart to the SXP Listener. It maintains a
+connection with its listener peer and sends composed messages.
+
+The SXP Binding Handler extracts the IP-SGT binding from a message and
+pulls it into the SXP-Database. If an error is detected during the
+IP-SGT extraction, an appropriate error code and sub-code is selected
+and an error message is sent back to the connected peer. All transitive
+messages are routed directly to the output queue of SXP Binding
+Dispatcher.
+
+The SXP Binding Dispatcher represents a selector that will decides how
+many data from the SXP-database will be sent and when. It is responsible
+for message content composition based on maximum message length.
+
+The SXP Binding Filters handles filtering of outgoing and incoming
+IP-SGT bindings according to BGP filtering using ACL and Prefix List
+syntax for specifying filter or based on Peer-sequence length.
+
+The SXP Domains feature provides isolation of SXP peers and bindings
+learned between them, also exchange of Bindings is possible across
+SXP-Domains by ACL, Prefix List or Peer-Sequence filters
+
+Configuring SXP
+---------------
+
+The OpenDaylight Karaf distribution comes pre-configured with baseline
+SXP configuration. Configuration of SXP Nodes is also possible via
+NETCONF.
+
+- **22-sxp-controller-one-node.xml** (defines the basic parameters)
+
+Administering or Managing SXP
+-----------------------------
+
+By RPC (response is XML document containing requested data or operation
+status):
+
+- Get Connections POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:get-connections
+
+::
+
+ <input xmlns:xsi="urn:opendaylight:sxp:controller">
+ <domain-name>global</domain-name>
+ <requested-node>0.0.0.100</requested-node>
+ </input>
+
+- Add Connection POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:add-connection
+
+::
+
+ <input xmlns:xsi="urn:opendaylight:sxp:controller">
+ <requested-node>0.0.0.100</requested-node>
+ <domain-name>global</domain-name>
+ <connections>
+ <connection>
+ <peer-address>172.20.161.50</peer-address>
+ <tcp-port>64999</tcp-port>
+ <!-- Password setup: default | none leave empty -->
+ <password>default</password>
+ <!-- Mode: speaker/listener/both -->
+ <mode>speaker</mode>
+ <version>version4</version>
+ <description>Connection to ASR1K</description>
+ <!-- Timers setup: 0 to disable specific timer usability, the default value will be used -->
+ <connection-timers>
+ <!-- Speaker -->
+ <hold-time-min-acceptable>45</hold-time-min-acceptable>
+ <keep-alive-time>30</keep-alive-time>
+ </connection-timers>
+ </connection>
+ <connection>
+ <peer-address>172.20.161.178</peer-address>
+ <tcp-port>64999</tcp-port>
+ <!-- Password setup: default | none leave empty-->
+ <password>default</password>
+ <!-- Mode: speaker/listener/both -->
+ <mode>listener</mode>
+ <version>version4</version>
+ <description>Connection to ISR</description>
+ <!-- Timers setup: 0 to disable specific timer usability, the default value will be used -->
+ <connection-timers>
+ <!-- Listener -->
+ <reconciliation-time>120</reconciliation-time>
+ <hold-time>90</hold-time>
+ <hold-time-min>90</hold-time-min>
+ <hold-time-max>180</hold-time-max>
+ </connection-timers>
+ </connection>
+ </connections>
+ </input>
+
+- Delete Connection POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-connection
+
+::
+
+ <input xmlns:xsi="urn:opendaylight:sxp:controller">
+ <requested-node>0.0.0.100</requested-node>
+ <domain-name>global</domain-name>
+ <peer-address>172.20.161.50</peer-address>
+ </input>
+
+- Add Binding Entry POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:add-entry
+
+::
+
+ <input xmlns:xsi="urn:opendaylight:sxp:controller">
+ <requested-node>0.0.0.100</requested-node>
+ <domain-name>global</domain-name>
+ <ip-prefix>192.168.2.1/32</ip-prefix>
+ <sgt>20</sgt >
+ </input>
+
+- Update Binding Entry POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:update-entry
+
+::
+
+ <input xmlns:xsi="urn:opendaylight:sxp:controller">
+ <requested-node>0.0.0.100</requested-node>
+ <domain-name>global</domain-name>
+ <original-binding>
+ <ip-prefix>192.168.2.1/32</ip-prefix>
+ <sgt>20</sgt>
+ </original-binding>
+ <new-binding>
+ <ip-prefix>192.168.3.1/32</ip-prefix>
+ <sgt>30</sgt>
+ </new-binding>
+ </input>
+
+- Delete Binding Entry POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-entry
+
+::
+
+ <input xmlns:xsi="urn:opendaylight:sxp:controller">
+ <requested-node>0.0.0.100</requested-node>
+ <domain-name>global</domain-name>
+ <ip-prefix>192.168.3.1/32</ip-prefix>
+ <sgt>30</sgt >
+ </input>
+
+- Get Node Bindings
+
+ This RPC gets particular device bindings. An SXP-aware node is
+ identified with a unique Node-ID. If a user requests bindings for a
+ Speaker 20.0.0.2, the RPC will search for an appropriate path, which
+ contains 20.0.0.2 Node-ID, within locally learnt SXP data in the SXP
+ database and replies with associated bindings. POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:get-node-bindings
+
+::
+
+ <input xmlns:xsi="urn:opendaylight:sxp:controller">
+ <requested-node>20.0.0.2</requested-node>
+ <bindings-range>all</bindings-range>
+ <domain-name>global</domain-name>
+ </input>
+
+- Get Binding SGTs POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:get-binding-sgts
+
+::
+
+ <input xmlns:xsi="urn:opendaylight:sxp:controller">
+ <requested-node>0.0.0.100</requested-node>
+ <domain-name>global</domain-name>
+ <ip-prefix>192.168.12.2/32</ip-prefix>
+ </input>
+
+- Add PeerGroup with or without filters to node. POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:add-peer-group
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <requested-node>127.0.0.1</requested-node>
+ <sxp-peer-group>
+ <name>TEST</name>
+ <sxp-peers>
+ </sxp-peers>
+ <sxp-filter>
+ <filter-type>outbound</filter-type>
+ <acl-entry>
+ <entry-type>deny</entry-type>
+ <entry-seq>1</entry-seq>
+ <sgt-start>1</sgt-start>
+ <sgt-end>100</sgt-end>
+ </acl-entry>
+ <acl-entry>
+ <entry-type>permit</entry-type>
+ <entry-seq>45</entry-seq>
+ <matches>1</matches>
+ <matches>3</matches>
+ <matches>5</matches>
+ </acl-entry>
+ </sxp-filter>
+ </sxp-peer-group>
+ </input>
+
+- Delete PeerGroup with peer-group-name from node request-node. POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-peer-group
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <requested-node>127.0.0.1</requested-node>
+ <peer-group-name>TEST</peer-group-name>
+ </input>
+
+- Get PeerGroup with peer-group-name from node request-node. POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:get-peer-group
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <requested-node>127.0.0.1</requested-node>
+ <peer-group-name>TEST</peer-group-name>
+ </input>
+
+- Add Filter to peer group on node request-node. POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:add-filter
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <requested-node>127.0.0.1</requested-node>
+ <peer-group-name>TEST</peer-group-name>
+ <sxp-filter>
+ <filter-type>outbound</filter-type>
+ <acl-entry>
+ <entry-type>deny</entry-type>
+ <entry-seq>1</entry-seq>
+ <sgt-start>1</sgt-start>
+ <sgt-end>100</sgt-end>
+ </acl-entry>
+ <acl-entry>
+ <entry-type>permit</entry-type>
+ <entry-seq>45</entry-seq>
+ <matches>1</matches>
+ <matches>3</matches>
+ <matches>5</matches>
+ </acl-entry>
+ </sxp-filter>
+ </input>
+
+- Delete Filter from peer group on node request-node. POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-filter
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <requested-node>127.0.0.1</requested-node>
+ <peer-group-name>TEST</peer-group-name>
+ <filter-type>outbound</filter-type>
+ </input>
+
+- Update Filter of the same type in peer group on node request-node.
+ POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:update-filter
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <requested-node>127.0.0.1</requested-node>
+ <peer-group-name>TEST</peer-group-name>
+ <sxp-filter>
+ <filter-type>outbound</filter-type>
+ <acl-entry>
+ <entry-type>deny</entry-type>
+ <entry-seq>1</entry-seq>
+ <sgt-start>1</sgt-start>
+ <sgt-end>100</sgt-end>
+ </acl-entry>
+ <acl-entry>
+ <entry-type>permit</entry-type>
+ <entry-seq>45</entry-seq>
+ <matches>1</matches>
+ <matches>3</matches>
+ <matches>5</matches>
+ </acl-entry>
+ </sxp-filter>
+ </input>
+
+- Add new SXP aware Node POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:add-node
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <node-id>1.1.1.1</node-id>
+ <source-ip>0.0.0.0</source-ip>
+ <timers>
+ <retry-open-time>5</retry-open-time>
+ <hold-time-min-acceptable>120</hold-time-min-acceptable>
+ <delete-hold-down-time>120</delete-hold-down-time>
+ <hold-time-min>90</hold-time-min>
+ <reconciliation-time>120</reconciliation-time>
+ <hold-time>90</hold-time>
+ <hold-time-max>180</hold-time-max>
+ <keep-alive-time>30</keep-alive-time>
+ </timers>
+ <mapping-expanded>150</mapping-expanded>
+ <security>
+ <password>password</password>
+ </security>
+ <tcp-port>64999</tcp-port>
+ <version>version4</version>
+ <description>ODL SXP Controller</description>
+ <master-database></master-database>
+ </input>
+
+- Delete SXP aware node POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-node
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <node-id>1.1.1.1</node-id>
+ </input>
+
+- Add SXP Domain on node request-node. POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:add-domain
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <node-id>1.1.1.1</node-id>
+ <domain-name>global</domain-name>
+ </input>
+
+- Delete SXP Domain on node request-node. POST
+ http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-domain
+
+::
+
+ <input xmlns="urn:opendaylight:sxp:controller">
+ <node-id>1.1.1.1</node-id>
+ <domain-name>global</domain-name>
+ </input>
+
+Use cases for SXP
+~~~~~~~~~~~~~~~~~
+
+Cisco has a wide installed base of network devices supporting SXP. By
+including SXP in OpenDaylight, the binding of policy groups to IP
+addresses can be made available for possible further processing to a
+wide range of devices, and applications running on OpenDaylight. The
+range of applications that would be enabled is extensive. Here are just
+a few of them:
+
+OpenDaylight based applications can take advantage of the IP-SGT binding
+information. For example, access control can be defined by an operator
+in terms of policy groups, while OpenDaylight can configure access
+control lists on network elements using IP addresses, e.g., existing
+technology.
+
+Interoperability between different vendors. Vendors have different
+policy systems. Knowing the IP-SGT binding for Cisco makes it possible
+to maintain policy groups between Cisco and other vendors.
+
+OpenDaylight can aggregate the binding information from many devices and
+communicate it to a network element. For example, a firewall can use the
+IP-SGT binding information to know how to handle IPs based on the
+group-based ACLs it has set. But to do this with SXP alone, the firewall
+has to maintain a large number of network connections to get the binding
+information. This incurs heavy overhead costs to maintain all of the SXP
+peering and protocol information. OpenDaylight can aggregate the
+IP-group information so that the firewall need only connect to
+OpenDaylight. By moving the information flow outside of the network
+elements to a centralized position, we reduce the overhead of the CPU
+consumption on the enforcement element. This is a huge savings - it
+allows the enforcement point to only have to make one connection rather
+than thousands, so it can concentrate on its primary job of forwarding
+and enforcing.
+
+OpenDaylight can relay the binding information from one network element
+to others. Changes in group membership can be propagated more readily
+through a centralized model. For example, in a security application a
+particular host (e.g., user or IP Address) may be found to be acting
+suspiciously or violating established security policies. The defined
+response is to put the host into a different source group for
+remediation actions such as a lower quality of service, restricted
+access to critical servers, or special routing conditions to ensure
+deeper security enforcement (e.g., redirecting the host’s traffic
+through an IPS with very restrictive policies). Updated group membership
+for this host needs to be communicated to multiple network elements as
+soon as possible; a very efficient and effective method of propagation
+can be performed using OpenDaylight as a centralized point for relaying
+the information.
+
+OpenDayLight can create filters for exporting and receiving IP-SGT
+bindings used on specific peer groups, thus can provide more complex
+maintaining of policy groups.
+
+Although the IP-SGT binding is only one specific piece of information,
+and although SXP is implemented widely in a single vendor’s equipment,
+bringing the ability of OpenDaylight to process and distribute the
+bindings, is a very specific immediate useful implementation of policy
+groups. It would go a long way to develop both the usefulness of
+OpenDaylight and of policy groups.
+
--- /dev/null
+TSDR User Guide
+===============
+
+This document describes how to use HSQLDB, HBase, and Cassandra data
+stores to capture time series data using Time Series Data Repository
+(TSDR) features in OpenDaylight. This document contains configuration,
+administration, management, usage, and troubleshooting sections for the
+features.
+
+Overview
+--------
+
+The Time Series Data Repository (TSDR) project in OpenDaylight (ODL)
+creates a framework for collecting, storing, querying, and maintaining
+time series data. TSDR provides the framework for plugging in proper
+data collectors to collect various time series data and store the data
+into TSDR Data Stores. With a common data model and generic TSDR data
+persistence APIs, the user can choose various data stores to be plugged
+into the TSDR persistence framework. Currently, three types of data
+stores are supported: HSQLDB relational database, HBase NoSQL database,
+and Cassandra NoSQL database.
+
+With the capabilities of data collection, storage, query, aggregation,
+and purging provided by TSDR, network administrators can leverage
+various data driven appliations built on top of TSDR for security risk
+detection, performance analysis, operational configuration optimization,
+traffic engineering, and network analytics with automated intelligence.
+
+TSDR Architecture
+-----------------
+
+TSDR has the following major components:
+
+- Data Collection Service
+
+- Data Storage Service
+
+- TSDR Persistence Layer with data stores as plugins
+
+- TSDR Data Stores
+
+- Data Query Service
+
+- Grafana integration for time series data visualization
+
+- Data Aggregation Service
+
+- Data Purging Service
+
+The Data Collection Service handles the collection of time series data
+into TSDR and hands it over to the Data Storage Service. The Data
+Storage Service stores the data into TSDR through the TSDR Persistence
+Layer. The TSDR Persistence Layer provides generic Service APIs allowing
+various data stores to be plugged in. The Data Aggregation Service
+aggregates time series fine-grained raw data into course-grained roll-up
+data to control the size of the data. The Data Purging Service
+periodically purges both fine-grained raw data and course-granined
+aggregated data according to user-defined schedules.
+
+We have implemented The Data Collection Service, Data Storage Service,
+TSDR Persistence Layer, TSDR HSQLDB Data Store, TSDR HBase Data Store,
+and TSDR Cassandra Datastore. Among these services and components, time
+series data is communicated using a common TSDR data model, which is
+designed and implemented for the abstraction of time series data
+commonalities. With these functions, TSDR is able to collect the data
+from the data sources and store them into one of the TSDR data stores:
+HSQLDB Data Store, HBase Data Store or Cassandra Data Store. Besides a
+simple query command from Karaf console to retrieve data from the TSDR
+data stores, we also provided a Data Query Service for the user to use
+REST API to query the data from the data stores. Moreover, the user can
+use Grafana, which is a time series visualization tool to view the data
+stored in TSDR in various charting formats.
+
+Configuring TSDR Data Stores
+----------------------------
+
+To Configure HSQLDB Data Store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The HSQLDB based storage files get stored automatically in <karaf
+install folder>/tsdr/ directory. If you want to change the default
+storage location, the configuration file to change can be found in
+<karaf install folder>/etc directory. The filename is
+org.ops4j.datasource-metric.cfg. Change the last portion of the
+url=jdbc:hsqldb:./tsdr/metric to point to different directory.
+
+To Configure HBase Data Store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After installing HBase Server on the same machine as OpenDaylight, if
+the user accepts the default configuration of the HBase Data Store, the
+user can directly proceed with the installation of HBase Data Store from
+Karaf console.
+
+Optionally, the user can configure TSDR HBase Data Store following HBase
+Data Store Configuration Procedure.
+
+- HBase Data Store Configuration Steps
+
+ - Open the file etc/tsdr-persistence-hbase.peroperties under karaf
+ distribution directory.
+
+ - Edit the following parameters:
+
+ - HBase server name
+
+ - HBase server port
+
+ - HBase client connection pool size
+
+ - HBase client write buffer size
+
+After the configuration of HBase Data Store is complete, proceed with
+the installation of HBase Data Store from Karaf console.
+
+- HBase Data Store Installation Steps
+
+ - Start Karaf Console
+
+ - Run the following commands from Karaf Console: feature:install
+ odl-tsdr-hbase
+
+To Configure Cassandra Data Store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Currently, there’s no configuration needed for Cassandra Data Store. The
+user can use Cassandra data store directly after installing the feature
+from Karaf console.
+
+Additionally separate commands have been implemented to install various
+data collectors.
+
+Administering or Managing TSDR Data Stores
+------------------------------------------
+
+To Administer HSQLDB Data Store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the TSDR default datastore feature (odl-tsdr-hsqldb-all) is
+enabled, the TSDR captured OpenFlow statistics metrics can be accessed
+from Karaf Console by executing the command
+
+::
+
+ tsdr:list <metric-category> <starttimestamp> <endtimestamp>
+
+wherein
+
+- <metric-category> = any one of the following categories
+ FlowGroupStats, FlowMeterStats, FlowStats, FlowTableStats, PortStats,
+ QueueStats
+
+- <starttimestamp> = to filter the list of metrics starting this
+ timestamp
+
+- <endtimestamp> = to filter the list of metrics ending this timestamp
+
+- <starttimestamp> and <endtimestamp> are optional.
+
+- Maximum 1000 records will be displayed.
+
+To Administer HBase Data Store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Using Karaf Command to retrieve data from HBase Data Store
+
+The user first need to install hbase data store from karaf console:
+
+feature:install odl-tsdr-hbase
+
+The user can retrieve the data from HBase data store using the following
+commands from Karaf console:
+
+::
+
+ tsdr:list
+ tsdr:list <CategoryName> <StartTime> <EndTime>
+
+Typing tab will get the context prompt of the arguments when typeing the
+command in Karaf console.
+
+To Administer Cassandra Data Store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The user first needs to install Cassandra data store from Karaf console:
+
+::
+
+ feature:install odl-tsdr-cassandra
+
+Then the user can retrieve the data from Cassandra data store using the
+following commands from Karaf console:
+
+::
+
+ tsdr:list
+ tsdr:list <CategoryName> <StartTime> <EndTime>
+
+Typing tab will get the context prompt of the arguments when typeing the
+command in Karaf console.
+
+Installing TSDR Data Collectors
+-------------------------------
+
+When the user uses HSQLDB data store and installed "odl-tsdr-hsqldb-all"
+feature from Karaf console, besides the HSQLDB data store, OpenFlow data
+collector is also installed with this command. However, if the user
+needs to use other collectors, such as NetFlow Collector, Syslog
+Collector, SNMP Collector, and Controller Metrics Collector, the user
+needs to install them with separate commands. If the user uses HBase or
+Cassandra data store, no collectors will be installed when the data
+store is installed. Instead, the user needs to install each collector
+separately using feature install command from Karaf console.
+
+The following is the list of supported TSDR data collectors with the
+associated feature install commands:
+
+- OpenFlow Data Collector
+
+ ::
+
+ feature:install odl-tsdr-openflow-statistics-collector
+
+- SNMP Data Collector
+
+ ::
+
+ feature:install odl-tsdr-snmp-data-collector
+
+- NetFlow Data Collector
+
+ ::
+
+ feature:install odl-tsdr-netflow-statistics-collector
+
+- sFlow Data Collector feature:install
+ odl-tsdr-sflow-statistics-colletor
+
+- Syslog Data Collector
+
+ ::
+
+ feature:install odl-tsdr-syslog-collector
+
+- Controller Metrics Collector
+
+ ::
+
+ feature:install odl-tsdr-controller-metrics-collector
+
+In order to use controller metrics collector, the user needs to install
+Sigar library.
+
+The following is the instructions for installing Sigar library on
+Ubuntu:
+
+- Install back end library by "sudo apt-get install
+ libhyperic-sigar-java"
+
+- Execute "export
+ LD\_LIBRARY\_PATH=/usr/lib/jni/:/usr/lib:/usr/local/lib" to set the
+ path of the JNI (you can add this to the ".bashrc" in your home
+ directory)
+
+- Download the file "sigar-1.6.4.jar". It might be also in your ".m2"
+ directory under "~/.m2/resources/org/fusesource/sigar/1.6.4"
+
+- Create the directory "org/fusesource/sigar/1.6.4" under the "system"
+ directory in your controller home directory and place the
+ "sigar-1.6.4.jar" there
+
+Configuring TSDR Data Collectors
+--------------------------------
+
+- SNMP Data Collector Device Credential Configuration
+
+After installing SNMP Data Collector, a configuration file under etc/
+directory of ODL distribution is generated: etc/tsdr.snmp.cfg is
+created.
+
+The following is a sample tsdr.snmp.cfg file:
+
+credentials=[192.168.0.2,public],[192.168.0.3,public]
+
+The above credentials indicate that TSDR SNMP Collector is going to
+connect to two devices. The IPAddress and Read community string of these
+two devices are (192.168.0.2, public), and (192.168.0.3) respectively.
+
+The user can make changes to this configuration file any time during
+runtime. The configuration will be picked up by TSDR in the next cycle
+of data collection.
+
+Polling interval configuration for SNMP Collector and OpenFlow Stats Collector
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The default polling interval of SNMP Collector and OpenFlow Stats
+Collector is 30 seconds and 15 seconds respectively. The user can change
+the polling interval through restconf APIs at any time. The new polling
+interval will be picked up by TSDR in the next collection cycle.
+
+- Retrieve Polling Interval API for SNMP Collector
+
+ - URL:
+ http://localhost:8181/restconf/config/tsdr-snmp-data-collector:TSDRSnmpDataCollectorConfig
+
+ - Verb: GET
+
+- Update Polling Interval API for SNMP Collector
+
+ - URL:
+ http://localhost:8181/restconf/operations/tsdr-snmp-data-collector:setPollingInterval
+
+ - Verb: POST
+
+ - Content Type: application/json
+
+ - Input Payload:
+
+ ::
+
+ {
+ "input": {
+ "interval": "15000"
+ }
+ }
+
+- Retrieve Polling Interval API for OpenFlowStats Collector
+
+ - URL:
+ http://localhost:8181/restconf/config/tsdr-openflow-statistics-collector:TSDROSCConfig
+
+ - Verb: GET
+
+- Update Polling Interval API for OpenFlowStats Collector
+
+ - URL:
+ http://localhost:8181/restconf/operations/tsdr-openflow-statistics-collector:setPollingInterval
+
+ - Verb: POST
+
+ - Content Type: application/json
+
+ - Input Payload:
+
+ ::
+
+ {
+ "input": {
+ "interval": "15000"
+ }
+ }
+
+Querying TSDR from REST APIs
+----------------------------
+
+TSDR provides two REST APIs for querying data stored in TSDR data
+stores.
+
+- Query of TSDR Metrics
+
+ - URL: http://localhost:8181/tsdr/metrics/query
+
+ - Verb: GET
+
+ - Parameters:
+
+ - tsdrkey=[NID=][DC=][MN=][RK=]
+
+ ::
+
+ The TSDRKey format indicates the NodeID(NID), DataCategory(DC), MetricName(MN), and RecordKey(RK) of the monitored objects.
+ For example, the following is a valid tsdrkey:
+ [NID=openflow:1][DC=FLOWSTATS][MN=PacketCount][RK=Node:openflow:1,Table:0,Flow:3]
+ The following is also a valid tsdrkey:
+ tsdrkey=[NID=][DC=FLOWSTATS][MN=][RK=]
+ In the case when the sections in the tsdrkey is empty, the query will return all the records in the TSDR data store that matches the filled tsdrkey. In the above example, the query will return all the data in FLOWSTATS data category.
+ The query will return only the first 1000 records that match the query criteria.
+
+ - from=<time\_in\_seconds>
+
+ - until=<time\_in\_seconds>
+
+The following is an example curl command for querying metric data from
+TSDR data store:
+
+curl -G -v -H "Accept: application/json" -H "Content-Type:
+application/json" "http://localhost:8181/tsdr/metrics/query"
+--data-urlencode "tsdrkey=[NID=][DC=FLOWSTATS][MN=][RK=]"
+--data-urlencode "from=0" --data-urlencode "until=240000000000"\|more
+
+- Query of TSDR Log type of data
+
+ - URL:http://localhost:8181/tsdr/logs/query
+
+ - Verb: GET
+
+ - Parameters:
+
+ - tsdrkey=tsdrkey=[NID=][DC=][RK=]
+
+ ::
+
+ The TSDRKey format indicates the NodeID(NID), DataCategory(DC), and RecordKey(RK) of the monitored objects.
+ For example, the following is a valid tsdrkey:
+ [NID=openflow:1][DC=NETFLOW][RK]
+ The query will return only the first 1000 records that match the query criteria.
+
+ - from=<time\_in\_seconds>
+
+ - until=<time\_in\_seconds>
+
+The following is an example curl command for querying log type of data
+from TSDR data store:
+
+curl -G -v -H "Accept: application/json" -H "Content-Type:
+application/json" "http://localhost:8181/tsdr/logs/query"
+--data-urlencode "tsdrkey=[NID=][DC=NETFLOW][RK=]" --data-urlencode
+"from=0" --data-urlencode "until=240000000000"\|more
+
+Grafana integration with TSDR
+-----------------------------
+
+TSDR provides northbound integration with Grafana time series data
+visualization tool. All the metric type of data stored in TSDR data
+store can be visualized using Grafana.
+
+For the detailed instruction about how to install and configure Grafana
+to work with TSDR, please refer to the following link:
+
+https://wiki.opendaylight.org/view/Grafana_Integration_with_TSDR_Step-by-Step
+
+Purging Service configuration
+-----------------------------
+
+After the data stores are installed from Karaf console, the purging
+service will be installed as well. A configuration file called
+tsdr.data.purge.cfg will be generated under etc/ directory of ODL
+distribution.
+
+The following is the sample default content of the tsdr.data.purge.cfg
+file:
+
+host=127.0.0.1 data\_purge\_enabled=true data\_purge\_time=23:59:59
+data\_purge\_interval\_in\_minutes=1440 retention\_time\_in\_hours=168
+
+The host indicates the IPAddress of the data store. In the case when the
+data store is together with ODL controller, 127.0.0.1 should be the
+right value for the host IP. The other attributes are self-explained.
+The user can change those attributes at any time. The configuration
+change will be picked up right away by TSDR Purging service at runtime.
+
+How to use TSDR to collect, store, and view OpenFlow Interface Statistics
+-------------------------------------------------------------------------
+
+Overview
+~~~~~~~~
+
+This tutorial describes an example of using TSDR to collect, store, and
+view one type of time series data in OpenDaylight environment.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+You would need to have the following as prerequisits:
+
+- One or multiple OpenFlow enabled switches. Alternatively, you can use
+ mininet to simulate such a switch.
+
+- Successfully installed OpenDaylight Controller.
+
+- Successfully installed HBase Data Store following TSDR HBase Data
+ Store Installation Guide.
+
+- Connect the OpenFlow enabled switch(es) to OpenDaylight Controller.
+
+Target Environment
+~~~~~~~~~~~~~~~~~~
+
+HBase data store is only supported in Linux operation system.
+
+Instructions
+~~~~~~~~~~~~
+
+- Start OpenDaylight.
+
+- Connect OpenFlow enabled switch(es) to the controller.
+
+ - If using mininet, run the following commands from mininet command
+ line:
+
+ - mn --topo single,3 --controller
+ *remote,ip=172.17.252.210,port=6653* --switch
+ ovsk,protocols=OpenFlow13
+
+- Install tsdr hbase feature from Karaf:
+
+ - feature:install odl-tsdr-hbase
+
+- Install OpenFlow Statistics Collector from Karaf:
+
+ - feature:install odl-tsdr-openflow-statistics-collector
+
+- run the following command from Karaf console:
+
+ - tsdr:list PORTSTATS
+
+You should be able to see the interface statistics of the switch(es)
+from the HBase Data Store. If there are too many rows, you can use
+"tsdr:list InterfaceStats\|more" to view it page by page.
+
+By tabbing after "tsdr:list", you will see all the supported data
+categories. For example, "tsdr:list FlowStats" will output the Flow
+statistics data collected from the switch(es).
+
+Troubleshooting
+---------------
+
+Karaf logs
+~~~~~~~~~~
+
+All TSDR features and components write logging information including
+information messages, warnings, errors and debug messages into
+karaf.log.
+
+HBase and Cassandra logs
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+For HBase and Cassandra data stores, the database level logs are written
+into HBase log and Cassandra logs.
+
+- HBase log
+
+ - HBase log is under <HBase-installation-directory>/logs/.
+
+- Cassandra log
+
+ - Cassandra log is under {cassandra.logdir}/system.log. The default
+ {cassandra.logdir} is /var/log/cassandra/.
+
+Security
+--------
+
+TSDR gets the data from a variety of sources, which can be secured in
+different ways.
+
+- OpenFlow Security
+
+ - The OpenFlow data can be configured with Transport Layer Security
+ (TLS) since the OpenFlow Plugin that TSDR depends on provides this
+ security support.
+
+- SNMP Security
+
+ - The SNMP version3 has security support. However, since ODL SNMP
+ Plugin that TSDR depends on does not support version 3, we (TSDR)
+ will not have security support at this moment.
+
+- NetFlow Security
+
+ - NetFlow, which cannot be configured with security so we recommend
+ making sure it flows only over a secured management network.
+
+- Syslog Security
+
+ - Syslog, which cannot be configured with security so we recommend
+ making sure it flows only over a secured management network.
+
+Support multiple data stores simultaneously at runtime
+------------------------------------------------------
+
+TSDR supports running multiple data stores simultaneously at runtim. For
+example, it is possible to configure TSDR to push log type of data into
+Cassandra data store, while pushing metrics type of data into HBase.
+
+When you install one TSDR data store from karaf console, such as using
+feature:install odl-tsdr-hsqldb, a properties file will be generated
+under <Karaf-distribution-directory>/etc/. For example, when you install
+hsqldb, a file called tsdr-persistence-hsqldb.properties is generated
+under that directory.
+
+By default, all the types of data are supported in the data store. For
+example, the default content of tsdr-persistence-hsqldb.properties is as
+follows:
+
+::
+
+ metric-persistency=true
+ log-persistency=true
+ binary-persistency=true
+
+When the user would like to use different data stores to support
+different types of data, he/she could enable or disable a particular
+type of data persistence in the data stores by configuring the
+properties file accordingly.
+
+For example, if the user would like to store the log type of data in
+HBase, and store the metric and binary type of data in Cassandra, he/she
+needs to install both hbase and cassandra data stores from Karaf
+console. Then the user needs to modify the properties file under
+<Karaf-distribution-directory>/etc as follows:
+
+- tsdr-persistence-hbase.properties
+
+ ::
+
+ metric-persistency=false
+ log-persistency=true
+ binary-persistency=true
+
+- tsdr-persistence-cassandra.properties
+
+ ::
+
+ metric-psersistency=true
+ log-persistency=false
+ binary-persistency=false
+
--- /dev/null
+TTP CLI Tools User Guide
+========================
+
+Overview
+--------
+
+Table Type Patterns are a specification developed by the `Open
+Networking Foundation <https://www.opennetworking.org/>`__ to enable the
+description and negotiation of subsets of the OpenFlow protocol. This is
+particularly useful for hardware switches that support OpenFlow as it
+enables the to describe what features they do (and thus also what
+features they do not) support. More details can be found in the full
+specification listed on the `OpenFlow specifications
+page <https://www.opennetworking.org/sdn-resources/onf-specifications/openflow>`__.
+
+TTP CLI Tools Architecture
+--------------------------
+
+The TTP CLI Tools use the TTP Model and the YANG Tools/RESTCONF codecs
+to translate between the Data Transfer Objects (DTOs) and JSON/XML.
+
--- /dev/null
+UNI Manager Plug In Project
+===========================
+
+Overview
+--------
+
+The version of the UNI Manager (UNIMgr) plug-in included in OpenDaylight
+Beryllium release is experimental, serving as a proof-of-concept (PoC)
+for using features of OpenDaylight to provision networked elements with
+attributes satisfying Metro Ethernet Forum (MEF) requirements for
+delivery of Carrier Ethernet service. This initial version of UNIMgr
+does not enable the full set of MEF-defined functionality for Carrier
+Ethernet service. UNI Manager adheres to a minimum set of functionality
+defined by MEF 7.2 and 10.2 specifications.
+
+UNIMgr receives a request from applications to create an Ethernet
+Private Line (EPL) private Ethernet connection between two endpoints on
+the network. The request must include the IP addresses of the endpoints
+and a class of service identifier.
+
+UNI Manager plug-in translates the request for EPL service into (a)
+configuring two instances of Open vSwitch (OVS), each instance running
+in one of the UNI endpoints, with two ports and a bridge between the
+ports, and (b) creating a GRE tunnel to provide a private connection
+between the endpoints. This initial version of UNIMgr uses only OVSDB on
+its southbound interface to send configuration commands.
+
+UNIMgr also accepts a bits per second datarate parameter, which is
+translated to an OVSDB command to limit the rate at which the OVS
+instances will forward data traffic.
+
+The YANG module used to create the UNIMgr plug-in models MEF-defined UNI
+and Ethernet Virtual Connection (EVC) attributes but does not include
+the full set of UNI and EVC attributes. And of the attributes modeled in
+the YANG module only a subset of them are implemented in the UNIMgr
+listener code translating the Operational data tree to OVSDB commands.
+The YANG module used to develop the PoC UNIMgr plug-in is
+cl-unimgr-mef.yang. A copy of this module is available in the
+odl-unimgr-api bundle of the UNIMgr project.
+
+Limitations of the PoC version of UNI Manager in OpenDaylight Beryllium
+include those listed below: \* Uses only OVSDB southbound interface of
+OpenDaylight \* Only uses UNI ID, IP Address, and speed UNI attributes
+\* Only uses a subset of EVC per UNI attributes \* Does not use MEF
+Class of Service or Bandwidth Profile attributes \* Configures only Open
+vSwitch network elements
+
+Opportunities for evolution of the UNI Manager plug in include using
+complete MEF Service Layer and MEF Resource Layer YANG models and
+supporting other OpenDaylight southbound protocols like NetConf and
+OpenFlow.
+
+UNI Manager Components
+----------------------
+
+UNI Manager is comprised of the following OpenDaylight Karaf features:
+
++--------------------------------------+--------------------------------------+
+| odl-unimgr-api | OpenDaylight :: UniMgr :: api |
++--------------------------------------+--------------------------------------+
+| odl-unimgr | OpenDaylight :: UniMgr |
++--------------------------------------+--------------------------------------+
+| odl-unimgr-console | OpenDaylight :: UniMgr :: CLI |
++--------------------------------------+--------------------------------------+
+| odl-unimgr-rest | OpenDaylight :: UniMgr :: REST |
++--------------------------------------+--------------------------------------+
+| odl-unimgr-ui | OpenDaylight :: UniMgr :: UI |
++--------------------------------------+--------------------------------------+
+
+Installing UNI Manager Plug-in
+------------------------------
+
+After launching OpenDaylight install the feature for the UNI Manager
+plug-in. From the karaf command prompt execute the following command to
+install the UNI Manager plug-in:
+
+::
+
+ $ feature:install odl-manager-ui
+
+Explore and exercise the UNI Manager REST API
+---------------------------------------------
+
+To see the UNI Manager APIs, browse to this URL:
+http://localhost:8181/apidoc/explorer/index.html
+
+Replace localhost with the IP address or hostname where OpenDaylight is
+running if you are not running OpenDaylight locally on your machine.
+
+See also the UNI Manager Developer’s Guide for a full list and
+description of UNI Manager POSTMAN calls.
+
--- /dev/null
+Using the OpenDaylight User Interface (DLUX)
+============================================
+
+This section introduces you to the OpenDaylight User Experience (DLUX)
+application.
+
+Getting Started with DLUX
+-------------------------
+
+DLUX provides a number of different Karaf features, which you can enable
+and disable separately. In Beryllum they are: . odl-dlux-core .
+odl-dlux-node . odl-dlux-yangui . odl-dlux-yangvisualizer
+
+Logging In
+----------
+
+To log in to DLUX, after installing the application:
+
+1. Open a browser and enter the login URL
+ `http://<your-karaf-ip>:8181/index.html <http://<your-karaf-ip>:8181/index.html>`__
+ in your browser (Chrome is recommended).
+
+2. Login to the application with your username and password credentials.
+
+.. note::
+
+ OpenDaylight’s default credentials are *admin* for both the username
+ and password.
+
+Working with DLUX
+-----------------
+
+After you login to DLUX, if you enable only odl-dlux-core feature, you
+will see only topology application available in the left pane.
+
+.. note::
+
+ To make sure topology displays all the details, enable the
+ odl-l2switch-switch feature in Karaf.
+
+DLUX has other applications such as node, yang UI and those apps won’t
+show up, until you enable their features odl-dlux-node and
+odl-dlux-yangui respectively in the Karaf distribution.
+
+.. figure:: ./images/dlux-login.png
+ :alt: DLUX Modules
+
+ DLUX Modules
+
+.. note::
+
+ If you install your application in dlux, they will also show up on
+ the left hand navigation after browser page refresh.
+
+Viewing Network Statistics
+--------------------------
+
+The **Nodes** module on the left pane enables you to view the network
+statistics and port information for the switches in the network.
+
+To use the **Nodes** module:
+
+1. Select **Nodes** on the left pane. The right pane displays atable
+ that lists all the nodes, node connectors and the statistics.
+
+2. Enter a node ID in the **Search Nodes** tab to search by node
+ connectors.
+
+3. Click on the **Node Connector** number to view details such as port
+ ID, port name, number of ports per switch, MAC Address, and so on.
+
+4. Click **Flows** in the Statistics column to view Flow Table
+ Statistics for the particular node like table ID, packet match,
+ active flows and so on.
+
+5. Click **Node Connectors** to view Node Connector Statistics for the
+ particular node ID.
+
+Viewing Network Topology
+------------------------
+
+The Topology tab displays a graphical representation of network topology
+created.
+
+.. note::
+
+ DLUX does not allow for editing or adding topology information. The
+ topology is generated and edited in other modules, e.g., the
+ OpenFlow plugin. OpenDaylight stores this information in the MD-SAL
+ datastore where DLUX can read and display it.
+
+To view network topology:
+
+1. Select **Topology** on the left pane. You will view the graphical
+ representation on the right pane. In the diagram blue boxes represent
+ the switches, the black represents the hosts available, and lines
+ represents how the switches and hosts are connected.
+
+2. Hover your mouse on hosts, links, or switches to view source and
+ destination ports.
+
+3. Zoom in and zoom out using mouse scroll to verify topology for larger
+ topologies.
+
+.. figure:: ./images/dlux-topology.png
+ :alt: Topology Module
+
+ Topology Module
+
+Interacting with the YANG-based MD-SAL datastore
+------------------------------------------------
+
+The **Yang UI** module enables you to interact with the YANG-based
+MD-SAL datastore. For more information about YANG and how it interacts
+with the MD-SAL datastore, see the *Controller* and *YANG Tools* section
+of the *OpenDaylight Developer Guide*.
+
+.. figure:: ./images/dlux-yang-ui-screen.png
+ :alt: Yang UI
+
+ Yang UI
+
+To use Yang UI:
+
+1. Select **Yang UI** on the left pane. The right pane is divided in two
+ parts.
+
+2. The top part displays a tree of APIs, subAPIs, and buttons to call
+ possible functions (GET, POST, PUT, and DELETE).
+
+ .. note::
+
+ every subAPI can call every function. For example, subAPIs in
+ the *operational* store have GET functionality only.
+
+ Inputs can be filled from OpenDaylight when existing data from
+ OpenDaylight is displayed or can be filled by user on the page and
+ sent to OpenDaylight.
+
+ Buttons under the API tree are variable. It depends on subAPI
+ specifications. Common buttons are:
+
+ - GET to get data from OpenDaylight,
+
+ - PUT and POST for sending data to OpenDaylight for saving
+
+ - DELETE for sending data to OpenDaylight for deleting.
+
+ You must specify the xpath for all these operations. This path is
+ displayed in the same row before buttons and it may include text
+ inputs for specific path element identifiers.
+
+ .. figure:: ./images/dlux-yang-api-specification.png
+ :alt: Yang API Specification
+
+ Yang API Specification
+
+3. The bottom part of the right pane displays inputs according to the
+ chosen subAPI.
+
+ - Lists are handled as a special case. For example, a device can
+ store multiple flows. In this case "flow" is name of the list and
+ every list element is identified by a unique key value. Elements
+ of a list can, in turn, contain other lists.
+
+ - In Yang UI, each list element is rendered with the name of the
+ list it belongs to, its key, its value, and a button for removing
+ it from the list.
+
+ .. figure:: ./images/dlux-yang-sub-api-screen.png
+ :alt: Yang UI API Specification
+
+ Yang UI API Specification
+
+4. After filling in the relevant inputs, click the **Show Preview**
+ button under the API tree to display request that will be sent to
+ OpenDaylight. A pane is displayed on the right side with text of
+ request when some input is filled.
+
+Displaying Topology on the **Yang UI**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To display topology:
+
+1. Select subAPI network-topology <topology revision number> == >
+ operational == > network-topology.
+
+2. Get data from OpenDaylight by clicking on the "GET" button.
+
+3. Click **Display Topology**.
+
+.. figure:: ./images/dlux-yang-topology.png
+ :alt: DLUX Yang Topology
+
+ DLUX Yang Topology
+
+Configuring List Elements on the **Yang UI**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Lists in Yang UI are displayed as trees. To expand or collapse a list,
+click the arrow before name of the list. To configure list elements in
+Yang UI:
+
+1. To add a new list element with empty inputs use the plus icon-button
+ **+** that is provided after list name.
+
+2. To remove several list elements, use the **X** button that is
+ provided after every list element.
+
+ .. figure:: ./images/dlux-yang-list-elements.png
+ :alt: DLUX List Elements
+
+ DLUX List Elements
+
+3. In the YANG-based data store all elements of a list must have a
+ unique key. If you try to assign two or more elements the same key, a
+ warning icon **!** is displayed near their name buttons.
+
+ .. figure:: ./images/dlux-yang-list-warning.png
+ :alt: DLUX List Warnings
+
+ DLUX List Warnings
+
+4. When the list contains at least one list element, after the **+**
+ icon, there are buttons to select each individual list element. You
+ can choose one of them by clicking on it. In addition, to the right
+ of the list name, there is a button which will display a vertically
+ scrollable pane with all the list elements.
+
+ .. figure:: ./images/dlux-yang-list-button1.png
+ :alt: DLUX List Button1
+
+ DLUX List Button1
+
--- /dev/null
+YANG IDE User Guide
+===================
+
+Overview
+--------
+
+The YANG IDE project provides an Eclipse plugin that is used to create,
+view, and edit Yang model files. It currently supports version 1.0 of
+the Yang specification.
+
+The YANG IDE project uses components from the OpenDaylight project for
+parsing and verifying Yang model files. The "yangtools" parser in
+OpenDaylight is generally used for generating Java code associated with
+Yang models. If you are just using the YANG IDE to view and edit Yang
+models, you do not need to know any more about this.
+
+Although the YANG IDE plugin is used in Eclipse, it is not necessary to
+be familiar with the Java programming language to use it effectively.
+
+The YANG IDE also uses the Maven build tool, but you do not have to be a
+Maven expert to use it, or even know that much about it. Very little
+configuration of Maven files will have to be done by you. In fact, about
+the only thing you will likely ever need to change can be done entirely
+in the Eclipse GUI forms, without even seeing the internal structure of
+the Maven POM file (Project Object Model).
+
+The YANG IDE plugin provides features that are similar to other
+programming language plugins in the Eclipse ecosystem.
+
+For instance, you will find support for the following:
+
+- Immediate "as-you-type" display of syntactic and semantic errors
+
+- Intelligent completion of language tokens, limited to only choices
+ valid in the current scope and namespace
+
+- Consistent (and customizable) color-coding of syntactic and semantic
+ symbols
+
+- Provides access to remote Yang models by specifying dependency on
+ Maven artifact containing models (or by manual inclusion in project)
+
+- One-click navigation to referenced symbols in external files
+
+- Mouse hovers display descriptions of referenced components
+
+- Tools for refactoring or renaming components respect namespaces
+
+- Code templates can be entered for common conventions
+
+Forthcoming sections of this manual will step through how to utilize
+these features.
+
+Creating a Yang Project
+-----------------------
+
+After the plugin is installed, the next thing you have to do is create a
+Yang Project. This is done from the "File" menu, selecting "New", and
+navigating to the "Yang" section and selecting "YANG Project", and then
+clicking "Next" for more items to configure.
+
+Some shortcuts for these steps are the following:
+
+- Typically, the key sequence "Ctrl+n" (press "n" while holding down
+ one of the "ctrl" keys) is bound to the "new" function
+
+- In the "New" wizard dialog, the initial focus is in the filter field,
+ where you can enter "yang" to limit the choices to only the functions
+ provided by the YANG IDE plugin
+
+- On the "New" wizard dialog, instead of clicking the "Next" button
+ with your mouse, you can press "Alt+n" (you will see a hint for this
+ with the "N" being underlined)
+
+First Yang Project Wizard Page
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After the "Next" button is pressed, it goes to the first wizard page
+that is specific to creating Yang projects. you will see a subtitle on
+this page of "YANG Tools Configuration". In almost all cases, you should
+be able to click "Next" again on this page to go to the next wizard
+page.
+
+However, some information about the fields on this page would be
+helpful.
+
+You will see the following labeled fields and sections:
+
+Yang Files Root Directory
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This defaults to "src/main/yang". Except when creating your first Yang
+file, you, you do not even have to know this, as Eclipse presents the
+same interface to view your Yang files no matter what you set this to.
+
+Source Code Generators
+^^^^^^^^^^^^^^^^^^^^^^
+
+If you do not know what this is, you do not need to know about it. The
+"yangtools" Yang parser from OpenDaylight uses a "code generator"
+component to generate specific kinds of Java classes from the Yang
+models. Again, if you do not need to work with the generated Java code,
+you do not need to change this.
+
+Create Example YANG File
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is likely the only field you will ever have any reason to change.
+If this checkbox is set, when the YANG IDE creates the Yang project, it
+will create a sample "acme-system.yang" file which you can view and edit
+to demonstrate the features of the tool to yourself. If you do not need
+this file, then either delete it from the project or uncheck the
+checkbox to prevent its creation.
+
+When done with the fields on this page, click the "Next" button to go to
+the next wizard page.
+
+Second Yang Project Wizard Page
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This page has a subtitle of "New Maven project". There are several
+fields on this page, but you will only ever have to see and change the
+setting of the first field, the "Create a simple project" checkbox. You
+should always set this ON to avoid the selection of a Maven archetype,
+which is something you do not need to do for creating a Yang project.
+
+Click "Next" at the bottom of the page to move to the next wizard page.
+
+Third Yang Project Wizard Page
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This also has a subtitle of "New Maven project", but with different
+fields to set. You will likely only ever set the first two fields, and
+completely ignore everything else.
+
+The first field is labeled "Group id" in the "Artifact" section. It
+really does not matter what you set this to, but it does have to be set
+to something. For consistency, you might set this to the name or
+nickname of your organization. Otherwise, there are no constraints on
+the value of this field.
+
+The second field is labeled "Artifact id". The value of this field will
+be used as the name of the project you create, so you will have to think
+about what you want the project to be called. Also note that this name
+has to be unique in the Eclipse workspace. You cannot have two projects
+with the same name.
+
+After you have set this field, you will notice that the "Next" button is
+insensitive, but now the "Finish" button is sensitive. You can click
+"Finish" now (or use the keyboard shortcut of "Alt+f"), and the Yang IDE
+will finally create your project.
+
+Creating a Yang File
+--------------------
+
+Now that you have created your project, it is time to create your first
+Yang file.
+
+When you created the Yang project, you might have noticed the other
+option next to "YANG Project", which was "YANG File". That is what you
+will select now. Click "Next" to go to the first wizard page.
+
+First Yang File Wizard Page
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This wizard page lets you specify where the new file will be located,
+and its name.
+
+You have to select the particular project you want the file to go into,
+and it needs to go into the "src/main/yang" folder (or a different
+location if you changed that field when creating the project).
+
+You then enter the desired name of the file in the "File name". The file
+name should have no spaces or "special characters" in it. You can
+specify a ".yang" extent if you want. If you do not specify an extent,
+the YANG IDE will create it with the ".yang" extent.
+
+Click "Next" to go to the next wizard page.
+
+Second Yang File Wizard Page
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On this wizard page, you set some metadata about the module that is used
+to initialize the contents of the Yang file.
+
+It has the following fields:
+
+Module Name
+^^^^^^^^^^^
+
+This will default to the "base name" of the file name you created. For
+instance, if the file name you created was "network-setup.yang", this
+field will default to "network-setup". You should leave this value as
+is. There is no good reason to define a model with a name different from
+the file name.
+
+Namespace
+^^^^^^^^^
+
+This defaults to "urn:opendaylight:xxx", where "xxx" is the "base name"
+of the file name you created. You should put a lot of thought into
+designing a namespace naming scheme that is used throughout your
+organization. It is quite common for this namespace value to look like a
+"http" URL, but note that that is just a convention, and will not
+necessarily imply that there is a web page residing at that HTTP
+address.
+
+Prefix
+^^^^^^
+
+This defaults to the "base name" of the file name you created. It mostly
+does not technically matter what you set this to, as long as it is not
+empty. Conventionally, it should be a "nickname" that is used to refer
+to the given namespace in an abbreviated form, when referenced in an
+"import" statement in another Yang model file.
+
+Revision
+^^^^^^^^
+
+This has to be a date value in the form of "yyyy-mm-dd", representing
+the last modified date of this Yang model. The value will default to the
+current date.
+
+Revision Description
+^^^^^^^^^^^^^^^^^^^^
+
+This is just human-readable text, which will go into the "description"
+field underneath the Yang "revision" field, which will describe what
+went into this revision.
+
+When all the fields have the content you want, click the "Finish" button
+to set the YANG IDE create the file in the specified location. It will
+then present the new file in the editor view for additional
+modifications.
+
+Accessing Artifacts for Yang Model Imports
+------------------------------------------
+
+You might be working on Yang models that are "abstract" or are intended
+to be imported by other Yang models. You might also, and more likely, be
+working on Yang models that import other "abstract" Yang models.
+
+Assuming you are in that latter more common group, you need to consider
+for yourself, and for your organization, how you are going to get access
+to those models that you import.
+
+You could use a very simple and primitive approach of somehow obtaining
+those models from some source as plain files and just copying them into
+the "src/main/yang" folder of your project. For a simple demo or a
+"one-off" very short project, that might be sufficient.
+
+A more robust and maintainable approach would be to reference
+"coordinates" of the artifacts containing Yang models to import. When
+you specify unique coordinates associated with that artifact, the Yang
+IDE can retrieve the artifact in the background and make it available
+for your "import" statements.
+
+Those "coordinates" that I speak of refer to the Maven concepts of
+"group id", "artifact id", and "version". you may remember "group id"
+and "artifact id" from the wizard page for creating a Yang project. It
+is the same idea. If you ever produce Yang model artifacts that other
+people are going to import, you will want to think more about what you
+set those values to when you created the project.
+
+For example, the OpenDaylight project produces several importable
+artifacts that you can specify to get access to common Yang models.
+
+Turning on Indexing for Maven Repositories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before we talk about how to add dependencies to Maven artifacts with
+Yang models for import, I need to explain how to make it easier to find
+those artifacts.
+
+In the Yang project that you have created, the "pom.xml" file (also
+called a "POM file") is the file that Maven uses to specify
+dependencies. We will talk about that in a minute, but first we need to
+talk about "repositories". These are where artifacts are stored.
+
+We are going to have Eclipse show us the "Maven Repositories" view. In
+the main menu, select "Window" and then "Show View", and then "Other".
+Like in the "New" dialog, you can enter "maven" in the filter field to
+limit the list to views with "maven" in the name. Click on the "Maven
+Repositories" entry and click OK.
+
+This will usually create the view in the bottom panel of the window.
+
+The view presents an outline view of four principal elements:
+
+- Local Repositories
+
+- Global Repositories
+
+- Project Repositories
+
+- Custom Repositories
+
+For this purpose, the only section you care about is "Project
+Repositories", being the repositories that are only specified in the POM
+for the project. There should be a "right-pointing arrow" icon on the
+line. Click that to expand the entry.
+
+You should see two entries there:
+
+- opendaylight-release
+
+- opendaylight-snapshot
+
+You will also see internet URLs associated with each of those
+repositories.
+
+For this purpose, you only care about the first one. Right-click on that
+entry and select "Full Index Enabled". The first time you do this on the
+first project you create, it will spend several minutes walking the
+entire tree of artifacts available at that repository and "indexing" all
+of those components. When this is done, searching for available
+artifacts in that repository will go very quickly.
+
+Adding Dependencies Containing Yang Models
+------------------------------------------
+
+Double-click the "pom.xml" file in your project. Instead of just
+bringing up the view of an XML file (although you can see that if you
+like), it presents a GUI form editor with a handful of tabs.
+
+The first tab, "Overview", shows things like the "Group Id", "Artifact
+Id", and "Version", which represents the "Maven coordinate" of your
+project, which I have mentioned before.
+
+Now click on the "Dependencies" tab. You will now see two list
+components, labeled "Dependencies" and "Dependency Management". You only
+care about the "Dependencies" section.
+
+In the "Dependencies" section, you should see one dependency for an
+artifact called "yang-binding". This artifact is part of OpenDaylight,
+but you do not need to know anything about it.
+
+Now click the "Add" button.
+
+This brings up a dialog titled "Select Dependency". It has three fields
+at the top labeled "Group Id", "Artifact Id", and "Version", with a
+"Scope" dropdown. You will never have a need to change the "Scope"
+dropdown, so ignore it. Despite the fact that you will need to get
+values into these fields, in general usage, you will never have to
+manually enter values into them, but you will see values being inserted
+into these fields by the next steps I describe.
+
+Below those fields is a field labeled "Enter groupId, artifactId …".
+This is effectively a "filter field", like on the "New" dialog, but
+instead of limiting the list from a short list of choices, the value you
+enter there will be matched against all of the artifacts that were
+indexed in the "opendaylight-release" repository (and others). It will
+match the string you enter as a substring of any groupId or artifactId.
+
+For all of the entries that match that substring, it will list an entry
+showing the groupId and artifactId, with an expansion arrow. If you open
+it by clicking on the arrow, you will see individual entries
+corresponding to each available version of that artifact, along with
+some metadata about the artifacts between square brackets, mostly
+indicating what "type" of artifact is.
+
+For your purposes, you only ever want to use "bundle" or "jar"
+artifacts.
+
+Let us consider an example that many people will probably be using.
+
+In the filter field, enter "ietf-yang-types". Depending on what versions
+are available, you should see a small handful of "groupId, artifactId"
+entries there. One of them should be groupId
+"org.opendaylight.mdsal.model" and artifactId "ietf-yang-types". Click
+on the expansion arrow to open that.
+
+What you will see at this point depends on what versions are available.
+You will likely want to select the newest one (most likely top of the
+list) that is also either a "bundle" or "jar" type artifact.
+
+If you click on that resulting version entry, you should notice at this
+point that the "Group Id", "Artifact Id", and "Version" fields at the
+top of the dialog are now filled in with the values corresponding to
+this artifact and version.
+
+If this is the version that you want, click OK and this artifact will be
+added to the dependencies in the POM.
+
+This will now make the Yang models found in that artifact available in
+"import" statements in Yang models, not to mention the completion
+choices for that "import" statement.
+
== CAPWAP Developer Guide
-=== Overview
-The Control And Provisioning of Wireless Access Points (CAPWAP) plugin project aims to
-provide new southbound interface for controller to be able to monitor and manage
-CAPWAP compliant wireless termination point (WTP) network devices. The CAPWAP
-feature will provide REST based northbound APIs.
-
-=== CAPWAP Architecture
-The CAPWAP feature is implemented as an MD-SAL based provider module, which
-helps discover WTP devices and update their states in the MD-SAL operational datastore.
-
-=== CAPWAP APIs and Interfaces
-This section describes the APIs for interacting with the CAPWAP plugin.
-
-==== Discovered WTPs
-The CAPWAP project maintains list of discovered CAPWAP WTPs that is YANG-based in MD-SAL.
-These models are available via RESTCONF.
-
-* Name: Discovered-WTPs
-* URL: http://${IPADDRESS}:8181/restconf/operational/capwap-impl:capwap-ac-root/
-* Description: Displays list of discovered WTPs and their basic attributes
-
-=== API Reference Documentation
-Go to http://${IPADDRESS}:8181/apidoc/explorer/index.html, sign in, and expand the
-capwap-impl panel. From there, users can execute various API calls to test their
-CAPWAP deployment.
-
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/capwap-developer-guide.html
== Cardinal: OpenDaylight Monitoring as a Service
-=== Overview
-Cardinal (OpenDaylight Monitoring as a Service) enables OpenDaylight and the underlying software defined network to be remotely monitored by deployed Network Management Systems (NMS) or Analytics suite. In the Boron release, Cardinal adds:
-
-. OpenDaylight MIB.
-. Enable ODL diagnostics/monitoring to be exposed across SNMP (v2c, v3) and REST north-bound.
-. Extend ODL System health, Karaf parameter and feature info, ODL plugin scalability and network parameters.
-. Support autonomous notifications (SNMP Traps).
-
-=== Cardinal Architecture
-The Cardinal architecture can be found at the below link:
-
-https://wiki.opendaylight.org/images/8/89/Cardinal-ODL_Monitoring_as_a_Service_V2.pdf
-
-=== Key APIs and Interfaces
-There are 2 main APIs for requesting snmpget request of the Karaf info and System info.
-To expose these APIs, it assumes that you already have the `odl-cardinal` and `odl-restconf` features installed. You can do that by entering the following at the Karaf console:
-
- feature:install odl-cardinal
- feature:install odl-restconf-all
-
-==== System Info APIs
-
-Open the REST interface and using the basic authentication, execute REST APIs for system info as:
-
- http://localhost:8181/restconf/operational/cardinal:CardinalSystemInfo/
-
-You should get the response code of the same as 200 OK with the following output as:
-
- {
- "CardinalSystemInfo": {
- "odlSystemMemUsage": " 9",
- "odlSystemSysInfo": " OpenDaylight Node Information",
- "odlSystemOdlUptime": " 00:29",
- "odlSystemCpuUsage": " 271",
- "odlSystemHostAddress": " Address of the Host should come up"
- }
- }
-
-==== Karaf Info APIs
-
-Open the REST interface and using the basic authentication, execute REST APIs for system info as:
-
- http://localhost:8181/restconf/operational/cardinal-karaf:CardinalKarafInfo/
-
-You should get the response code of the same as 200 OK with the following output as:
-
- {
- "CardinalKarafInfo": {
- "odlKarafBundleListActive1": " org.ops4j.pax.url.mvn_2.4.5 [1]",
- "odlKarafBundleListActive2": " org.ops4j.pax.url.wrap_2.4.5 [2]",
- "odlKarafBundleListActive3": " org.ops4j.pax.logging.pax-logging-api_1.8.4 [3]",
- "odlKarafBundleListActive4": " org.ops4j.pax.logging.pax-logging-service_1.8.4 [4]",
- "odlKarafBundleListActive5": " org.apache.karaf.service.guard_3.0.6 [5]",
- "odlKarafBundleListActive6": " org.apache.felix.configadmin_1.8.4 [6]",
- "odlKarafBundleListActive7": " org.apache.felix.fileinstall_3.5.2 [7]",
- "odlKarafBundleListActive8": " org.objectweb.asm.all_5.0.3 [8]",
- "odlKarafBundleListActive9": " org.apache.aries.util_1.1.1 [9]",
- "odlKarafBundleListActive10": " org.apache.aries.proxy.api_1.0.1 [10]",
- "odlKarafBundleListInstalled1": " org.ops4j.pax.url.mvn_2.4.5 [1]",
- "odlKarafBundleListInstalled2": " org.ops4j.pax.url.wrap_2.4.5 [2]",
- "odlKarafBundleListInstalled3": " org.ops4j.pax.logging.pax-logging-api_1.8.4 [3]",
- "odlKarafBundleListInstalled4": " org.ops4j.pax.logging.pax-logging-service_1.8.4 [4]",
- "odlKarafBundleListInstalled5": " org.apache.karaf.service.guard_3.0.6 [5]",
- "odlKarafFeatureListInstalled1": " config",
- "odlKarafFeatureListInstalled2": " region",
- "odlKarafFeatureListInstalled3": " package",
- "odlKarafFeatureListInstalled4": " http",
- "odlKarafFeatureListInstalled5": " war",
- "odlKarafFeatureListInstalled6": " kar",
- "odlKarafFeatureListInstalled7": " ssh",
- "odlKarafFeatureListInstalled8": " management",
- "odlKarafFeatureListInstalled9": " odl-netty",
- "odlKarafFeatureListInstalled10": " odl-lmax",
- "odlKarafBundleListResolved1": " org.ops4j.pax.url.mvn_2.4.5 [1]",
- "odlKarafBundleListResolved2": " org.ops4j.pax.url.wrap_2.4.5 [2]",
- "odlKarafBundleListResolved3": " org.ops4j.pax.logging.pax-logging-api_1.8.4 [3]",
- "odlKarafBundleListResolved4": " org.ops4j.pax.logging.pax-logging-service_1.8.4 [4]",
- "odlKarafBundleListResolved5": " org.apache.karaf.service.guard_3.0.6 [5]",
- "odlKarafFeatureListUnInstalled1": " aries-annotation",
- "odlKarafFeatureListUnInstalled2": " wrapper",
- "odlKarafFeatureListUnInstalled3": " service-wrapper",
- "odlKarafFeatureListUnInstalled4": " obr",
- "odlKarafFeatureListUnInstalled5": " http-whiteboard",
- "odlKarafFeatureListUnInstalled6": " jetty",
- "odlKarafFeatureListUnInstalled7": " webconsole",
- "odlKarafFeatureListUnInstalled8": " scheduler",
- "odlKarafFeatureListUnInstalled9": " eventadmin",
- "odlKarafFeatureListUnInstalled10": " jasypt-encryption"
- }
- }
-
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/cardinal_-opendaylight-monitoring-as-a-service.rst
== DIDM Developer Guide
-=== Overview
-
-The Device Identification and Driver Management (DIDM) project addresses the
-need to provide device-specific functionality. Device-specific functionality is
-code that performs a feature, and the code is knowledgeable of the capability
-and limitations of the device. For example, configuring VLANs and adjusting
-FlowMods are features, and there may be different implementations for different
-device types. Device-specific functionality is implemented as Device Drivers.
-Device Drivers need to be associated with the devices they can be used with. To
-determine this association requires the ability to identify the device type.
-
-=== DIDM Architecture
-
-The DIDM project creates the infrastructure to support the following functions:
-
- * *Discovery* - Determination that a device exists in the controller
- management domain and connectivity to the device can be established. For
- devices that support the OpenFlow protocol, the existing discovery
- mechanism in OpenDaylight suffices. Devices that do not support OpenFlow
- will be discovered through manual means such as the operator entering
- device information via GUI or REST API.
- * *Identification* – Determination of the device type.
- * *Driver Registration* – Registration of Device Drivers as routed RPCs.
- * *Synchronization* – Collection of device information, device configuration,
- and link (connection) information.
- * *Data Models for Common Features* – Data models will be defined to
- perform common features such as VLAN configuration. For example,
- applications can configure a VLAN by writing the VLAN data to the data store
- as specified by the common data model.
- * *RPCs for Common Features* – Configuring VLANs and adjusting
- FlowMods are example of features. RPCs will be defined that specify the
- APIs for these features. Drivers implement features for specific devices and
- support the APIs defined by the RPCs. There may be different Driver
- implementations for different device types.
-
-
-=== Key APIs and Interfaces
-
-==== FlowObjective API
-
-Following are the list of the APIs to create the flow objectives to install the
-flow rule in OpenFlow switch in pipeline agnostic way. Currently these APIs are
-getting consumed by Atrium project.
-
-Install the Forwarding Objective:
-
----
-http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:forward
----
-
-Install the Filter Objective
-
----
-http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:filter
----
-
-
-Install the Next Objective:
-
----
-http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:next
----
-
-==== Flow mod driver API
-
-The Beryllium release includes a flow mod driver for the HP 3800.
-This driver adjusts the flows and push the same to the device.
-This API takes the flow to be adjusted as input and displays the adjusted flow as output in the REST output container.
-Here is the REST API to adjust and push flows to HP 3800 device:
-
-----
-http://<CONTROLLER-IP:8181>/restconf/operations/openflow-feature:adjust-flow
-----
-
-Here is an example of an ARP flow and how it gets adjusted and pushed to device HP3800:
-
-.adjust-flow input
-----
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<input xmlns="urn:opendaylight:params:xml:ns:yang:didm:drivers:openflow" xmlns:opendaylight-inventory="urn:opendaylight:inventory">
- <node>/opendaylight-inventory:nodes/opendaylight-inventory:node[opendaylight-inventory:id='openflow:673249119553088']</node>
- <flow>
- <match>
- <ethernet-match>
- <ethernet-type>
- <type>2054</type>
- </ethernet-type>
- </ethernet-match>
- </match>
- <flags>SEND_FLOW_REM</flags>
- <priority>0</priority>
- <flow-name>ARP_FLOW</flow-name>
- <instructions>
- <instruction>
- <order>0</order>
- <apply-actions>
- <action>
- <order>0</order>
- <output-action>
- <output-node-connector>CONTROLLER</output-node-connector>
- <max-length>65535</max-length>
- </output-action>
- </action>
- <action>
- <order>1</order>
- <output-action>
- <output-node-connector>NORMAL</output-node-connector>
- <max-length>65535</max-length>
- </output-action>
- </action>
- </apply-actions>
- </instruction>
- </instructions>
- <idle-timeout>180</idle-timeout>
- <hard-timeout>1800</hard-timeout>
- <cookie>10</cookie>
- </flow>
-</input>
-----
-
-In the output, you can see that the table ID has been identified for the given
-flow and two flow mods are created as a result of adjustment. The first one is
-to catch ARP packets in Hardware table 100 with an action to goto table 200.
-The second flow mod is in table 200 with actions: output normal and output
-controller.
-
-.adjust-flow output
-----
-{
- "output": {
- "flow": [
- {
- "idle-timeout": 180,
- "instructions": {
- "instruction": [
- {
- "order": 0,
- "apply-actions": {
- "action": [
- {
- "order": 1,
- "output-action": {
- "output-node-connector": "NORMAL",
- "max-length": 65535
- }
- },
- {
- "order": 0,
- "output-action": {
- "output-node-connector": "CONTROLLER",
- "max-length": 65535
- }
- }
- ]
- }
- }
- ]
- },
- "strict": false,
- "table_id": 200,
- "flags": "SEND_FLOW_REM",
- "cookie": 10,
- "hard-timeout": 1800,
- "match": {
- "ethernet-match": {
- "ethernet-type": {
- "type": 2054
- }
- }
- },
- "flow-name": "ARP_FLOW",
- "priority": 0
- },
- {
- "idle-timeout": 180,
- "instructions": {
- "instruction": [
- {
- "order": 0,
- "go-to-table": {
- "table_id": 200
- }
- }
- ]
- },
- "strict": false,
- "table_id": 100,
- "flags": "SEND_FLOW_REM",
- "cookie": 10,
- "hard-timeout": 1800,
- "match": {},
- "flow-name": "ARP_FLOW",
- "priority": 0
- }
- ]
- }
-}
-----
-
-=== API Reference Documentation
-Go to http://${CONTROLLER-IP}:8181/apidoc/explorer/index.html, and look under DIDM section
-to see all the available REST calls and tables
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/didm-developer-guide.html
== DLUX
-=== Setup and Run
-==== Required Technology Stack
-* AngularJS (JavaScript client-side framework, http://www.angularjs.org )
-
-
-==== Run DLUX
-
-To turn on the DLUX UI, install DLUX core feature via running following command on the Karaf console -
-
- feature:install odl-dlux-core
-
-The above command will install odl-restconf and DLUX topology application internally, along with core DLUX components.
-Once this feature is successfully installed, access the UI at http://localhost:8181/index.html.
-The default credentials for login are admin/admin.
-
-All the applications in DLUX are Karaf features. A user can install other dlux applications such as node and yang-ui from Karaf
-console using commands such as -
-
-----
-$ feature:install odl-dlux-node
-
-$ feature:install odl-dlux-yangui
-----
-
-=== DLUX Modules
-
-DLUX modules are the individual features such as nodes and topology. Each module has a defined structure and you can find
-all existing modules at https://github.com/opendaylight/dlux/tree/stable/lithium/modules.
-
-==== Module Structure
-
- * module_folder
- ** <module_name>.module.js
- ** <module_name>.controller.js
- ** <module_name>.services.js
- ** <module_name>.directives.js
- ** <module_name>.filter.js
- ** index.tpl.html
- ** <a_stylesheet>.css
-
-==== Create New Module
-===== Define the module
-
-. Create an empty maven project and create your module folder under src/main/resources.
-. Create an empty file with pattern <module_name>.module.js.
-. Next, you need to surround the angular module with a define function. This allows RequireJs to see our module.js files.
- The first argument is an array which contains all the module's dependencies. The second argument is a callback function,
- whose body contain the AngularJS code base. The function parameters correspond with the order of dependencies. Each dependency is injected into a parameter, if it is provided.
-. Finally, you will return the angular module to be able to inject it as a parameter in others modules.
-
-For each new module, you must have at least these two dependencies :
-
-* angularAMD : It's a wrapper around AngularJS to provide an AMD (Asynchronous Module Definition) support, which is used by RequireJs. For more information see the https://github.com/amdjs/amdjs-api/blob/master/AMD.md[AMD documentation].
-* app/core/core.services : This one is mandatory, if you want to add content in the navigation menu, the left bar or the top bar.
-
-The following are not mandatory, but very often used.
-
-* angular-ui-router : A library to provide URL routing.
-* routingConfig : To set the level access to a page.
-
-Your module.js file might look like this:
-
- define(['angularAMD','app/routingConfig', 'angular-ui-router','app/core/core.services'], function(ng) {
- var module = angular.module('app.a_module', ['ui.router.state', 'app.core']);
- // module configuration
- module.config(function() {
- [...]
- });
- return module;
- });
-
-===== Set the register function
-AngularJS allows lazy registration of a module's components such as controller, factory etc. Once you will install your application,
-DLUX will load your module javascript, but not your angular component during bootstrap phase. You have to register your angular components
-to make sure they are available at the runtime.
-
-Here is how to register your module's component for lazy initialization -
-
- module.config(function($compileProvider, $controllerProvider, $provide) {
- module.register = {
- controller : $controllerProvider.register,
- directive : $compileProvider.directive,
- factory : $provide.factory,
- service : $provide.service
- };
- });
-
-===== Set the route
-The next step is to set up the route for your module. This part is also done in the configuration method of the module. We have to add *$stateProvider* as a parameter.
-
- module.config(function($stateProvider) {
- var access = routingConfig.accessLevels;
- $stateProvider.state('main.module', {
- url: 'module',
- views : {
- 'content' : {
- templateUrl: 'src/app/module/module.tpl.html',
- controller: 'ModuleCtrl'
- }
- }
- });
- });
-
-===== Adding element to the navigation menu
-To be able to add item to the navigation menu, the module requires the *NavHelperProvider* parameter in the configuration method.
-*addToMenu* method in *NavMenuHelper* helper allows an item addition to the menu.
-
- var module = angular.module('app.a_module', ['app.core']);
- module.config(function(NavMenuHelper) {
- NavMenuHelper.addToMenu('myFirstModule', {
- "link" : "#/module/index",
- "active" : "module",
- "title" : "My First Module",
- "icon" : "icon-sitemap",
- "page" : {
- "title" : "My First Module",
- "description" : "My first module"
- }
- });
- });
-
-The first parameter is an ID that refers to the level of your menu and the second is a object. For now, The ID parameter supports two levels of depth.
-If your ID looks like 'rootNode.childNode', the helper will look for a node named 'rootNode' and it will append the 'childNode' to it. If the root node doesn't exist, it will create it.
-
-
-===== Link the AngularJS module's controller file
-
-To include the module's controller file, you can use the NavHelperProvider. It contains a method that will load the given file.
-
- [...]
- NavHelperProvider.addControllerUrl('<path_to_module_folder>/<module_name>.controller');
-
-This completes your module.js file.
-
-
-==== Create the controller, factory, directive, etc
-
-Creating the controller and other components is similar to the module.
-
-* First, add the define method.
-* Second, add the relative path to the module definition.
-* Last, create your methods as you usually do it with AngularJS.
-
-For example -
-
- define(['<relative_path_to_module>/<module_name>.module'], function(module) {
- module.register.controller('ModuleCtrl', function($rootScope, $scope) {
- });
- });
-
-=== Add new application using DLUX modularity
-DLUX works as a Karaf based UI platform, where you can create a new Karaf feature of your UI component and install that UI applications in DLUX using blueprint.
-This page will help you to create and load a new application for DLUX. You don't have to add new module in DLUX repository.
-
-==== Add a new OSGi blueprint bundle
-The OSGi Blueprint Container specification allows us to use dependency injection in our OSGi environment. Each DLUX application module registers itself via blueprint configuration. Each application will have its own blueprint.xml to place its configuration.
-
-1. Create a maven project to place blueprint configuration. For reference, take a look at topology bundle, present at https://github.com/opendaylight/dlux/tree/stable/lithium/bundles/topology. All the existing DLUX modules' configurations are available under bundles directory of DLUX code.
-
-2. In pom.xml, you have to add a maven plugin to unpack your module code under generated-resources of this project. For reference, you can check pom.xml of dlux/bundles/topology at https://github.com/opendaylight/dlux/tree/stable/lithium/bundles/topology. Your bundle will eventually get deployed in Karaf as feature, so your bundle should contain all your module code. If you want to combine module and bundle project, that should not be an issue either.
-
-3. Create a blueprint.xml configuration file under src/main/resources/OSGI-INF/blueprint. Below is the content of the blueprint.xml taken from topology bundles's blueprint.xml. Any new application should create a blueprint.xml in following format -
-
-----
-<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
- <reference id="httpService" availability="mandatory" activation="eager" interface="org.osgi.service.http.HttpService"/>
- <reference id="loader" availability="mandatory" activation="eager" interface="org.opendaylight.dlux.loader.DluxModuleLoader"/>
-
- <bean id="bundle" init-method="initialize" destroy-method="clean" class="org.opendaylight.dlux.loader.DluxModule">
- <property name="httpService" ref="httpService"/>
- <property name="loader" ref="loader"/>
- <property name="moduleName" value="topology "/>
- <property name="url" value="/src/app/topology"/>
- <property name="directory" value="/topology"/>
- <property name="requireJs" value="app/topology/topology.module"/>
- <property name="angularJs" value="app.topology"/>
- <property name="cssDependencies">
- <list>
- <value>http://yui.yahooapis.com/3.18.1/build/cssreset/cssreset-min.css</value>
- <value>src/app/topology/topology-custom.css</value>
- </list>
- </property>
- </bean>
-</blueprint>
-----
-
-In above configuration, there are two references with id httpService and loader. These two beans will already be initialized by dlux-core, so any new application can use them. Without these two bean references, a new application will not be able to register.
-
-Next is the initialization of your application bean, which will be an instance of class org.opendaylight.dlux.loader.DluxModule. There are 5 properties that you should provide in this bean besides the references of httpService and loader. Lets talk about those bean properties in little more detail.
-
-*moduleName* : Name of your module. This name should be unique in DLUX.
-
-*url*: This is the url via which RequireJS in DLUX will try to load your module JS/HTML files. Also, this is the url that browser will use to load the static HTML, JS or CSS files. RequireJS in DLUX has a base path of *src*, so all the url should start with /src so RequireJS and the browser can correctly find the files.
-
-*directory*: In your bundle's pom.xml, you unpack your module code. This is the directory where your actual static files will reside. The above mentioned url is registered with httpService, so when browser makes a call to that url, it will be redirected to the directory mentioned here. In the above example, all the topology files are present under /topology directory and the browser/RequireJS can access those files with uri /src/app/topology.
-
-*requireJS*: This is the path to your RequireJS module. If you notice closely, you will see the initial path of RequireJS app/topology in the above example matches with the last part of url. This path will be be used by RequireJS. As mentioned above, we have kept *src* as base path in RequireJS, that is the exact reason that url start with /src.
-
-*angularJS*: name of your AngularJS module.
-
-*cssDependencies*: If the application has any external/internal css dependencies, then those can be added here. If you create your own css files, just point to those css files here. Use the url path that you mentioned above, so the browser can find your css file.
-
-OSGi understands blueprint.xml, once you will deploy your bundle in karaf (or you can create a new feature for your application), karaf will read your blueprint.xml and it will try to register your application with dlux. Once successful, if you refresh your dlux UI, you will see your application in left hand navigation bar of dlux.
-
-
-=== Yang Utils
-Yang Utils are used by UI to perform all CRUD operations. All of these utilities are present in yangutils.services.js file. It has following AngularJS factories -
-
-.Factories
-* *arrayUtils* – defines functions for working with arrays.
-* *pathUtils* – defines functions for working with xpath (paths to APIs and subAPIs). It divides xpath string to array of elements, so this array can be later used for search functions.
-* *syncFact* – provides synchronization between requests to and from OpenDaylight when it’s needed.
-* *custFunct* – it is linked with apiConnector.createCustomFunctionalityApis in yangui controller in yangui.controller.js. That function makes it possible to create some custom function called by the click on button in index.tpl.html. All custom functions are stored in array and linked to specific subAPI. When particular subAPI is expanded and clicked, its inputs (linked root node with its child nodes) are displayed in the bottom part of the page and its buttons with custom functionality are displayed also.
-* *reqBuilder* – Builds object in JSON format from input fields of the UI page. *Show Preview* button on Yang UI use this builder. This request is sent to OpenDaylight when button PUT or POST is clicked.
-* *yinParser* – factory for reading .xml files of yang models and creating object hierarchy. Every statement from yang is represented by a node.
-* *nodeWrapper* – adds functions to objects in tree hierarchy created with yinParser. These functions provide functionality for every type of node.
-* *apiConnector* – the main functionality is filling the main structures and linking them. Structure of APIs and subAPIs which is two level array - first level is filled by main APIs, second level is filled by others sub APIs. Second main structure is array of root nodes, which are objects including root node and its children nodes. Linking these two structures is creating links between every subAPI (second level of APIs array) and its root node, which must be displayed like inputs when subAPI is expanded.
-* *yangUtils* – some top level functions which are used by yangui controller for creating the main structures.
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/dlux.html
== L2Switch Developer Guide
-=== Overview
-The L2Switch project provides Layer2 switch functionality.
-
-=== L2Switch Architecture
-* Packet Handler
- ** Decodes the packets coming to the controller and dispatches them appropriately
-* Loop Remover
- ** Removes loops in the network
-* Arp Handler
- ** Handles the decoded ARP packets
-* Address Tracker
- ** Learns the Addresses (MAC and IP) of entities in the network
-* Host Tracker
- ** Tracks the locations of hosts in the network
-* L2Switch Main
- ** Installs flows on each switch based on network traffic
-
-=== Key APIs and Interfaces
-* Packet Handler
-* Loop Remover
-* Arp Handler
-* Address Tracker
-* Host Tracker
-* L2Switch Main
-
-==== Packet Dispatcher
-===== Classes
-* AbstractPacketDecoder
- ** Defines the methods that all decoders must implement
-* EthernetDecoder
- ** The base decoder which decodes the packet into an Ethernet packet
-* ArpDecoder, Ipv4Decoder, Ipv6Decoder
- ** Decodes Ethernet packets into the either an ARP or IPv4 or IPv6 packet
-
-===== Further development
-There is a need for more decoders. A developer can write
-
-* A decoder for another EtherType, i.e. LLDP.
-* A higher layer decoder for the body of the IPv4 packet or IPv6 packet, i.e. TCP and UDP.
-
-How to write a new decoder
-
-* extends AbstractDecoder<A, B>
- ** A refers to the notification that the new decoder consumes
- ** B refers to the notification that the new decoder produces
-* implements xPacketListener
- ** The new decoder must specify which notification it is listening to
-* canDecode method
- ** This method should examine the consumed notification to see whether the new decoder can decode the contents of the packet
-* decode method
- ** This method does the actual decoding of the packet
-
-==== Loop Remover
-===== Classes
-* *LoopRemoverModule*
- ** Reads config subsystem value for _is-install-lldp-flow_
- *** If _is-install-lldp-flow_ is true, then an *InitialFlowWriter* is created
- ** Creates and initializes the other LoopRemover classes
-* *InitialFlowWriter*
- ** Only created when _is-install-lldp-flow_ is true
- ** Installs a flow, which forwards all LLDP packets to the controller, on each switch
-* *TopologyLinkDataChangeHandler*
- ** Listens to data change events on the Topology tree
- ** When these changes occur, it waits _graph-refresh-delay_ seconds and then tells *NetworkGraphImpl* to update
- ** Writes an STP (Spanning Tree Protocol) status of "forwarding" or "discarding" to each link in the Topology data tree
- *** Forwarding links can forward packets.
- *** Discarding links cannot forward packets.
-* *NetworkGraphImpl*
- ** Creates a loop-free graph of the network
-
-===== Configuration
-* graph-refresh-delay
- ** Used in TopologyLinkDataChangeHandler
- ** A higher value has the advantage of doing less graph updates, at the potential cost of losing some packets because the graph didn't update immediately.
- ** A lower value has the advantage of handling network topology changes quicker, at the cost of doing more computation.
-* is-install-lldp-flow
- ** Used in LoopRemoverModule
- ** "true" means a flow that sends all LLDP packets to the controller will be installed on each switch
- ** "false" means this flow will not be installed
-* lldp-flow-table-id
- ** The LLDP flow will be installed on the specified flow table of each switch
-* lldp-flow-priority
- ** The LLDP flow will be installed with the specified priority
-* lldp-flow-idle-timeout
- ** The LLDP flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
-* lldp-flow-hard-timeout
- ** The LLDP flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
-
-===== Further development
-No suggestions at the moment.
-
-===== Validating changes to Loop Remover
-STP Status information is added to the Inventory data tree.
-
-* A status of "forwarding" means the link is active and packets are flowing on it.
-* A status of "discarding" means the link is inactive and packets are not sent over it.
-
-The STP status of a link can be checked through a browser or a REST Client.
-
- http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:2
-
-
-The STP status should still be there after changes are made.
-
-==== Arp Handler
-===== Classes
-* *ArpHandlerModule*
- ** Reads config subsystem value for _is-proactive-flood-mode_
- *** If _is-proactive-flood-mode_ is true, then a ProactiveFloodFlowWriter is created
- *** If _is-proactive-flood-mode_ is false, then an InitialFlowWriter is created
-* *ProactiveFloodFlowWriter*
- ** Only created when _is-proactive-flood-mode_ is true
- ** Installs a flood flow on each switch. With this flood flow, a packet that doesn't match any other flows will be flooded/broadcast from that switch.
-* *InitialFlowWriter*
- ** Only created when _is-proactive-flood-mode_ is false
- ** Installs a flow, which sends all ARP packets to the controller, on each switch
-* *ArpPacketHandler*
- ** Only created when _is-proactive-flood-mode_ is false
- ** Handles and processes the controller's incoming ARP packets
- ** Uses *PacketDispatcher* to send the ARP packet back into the network
-* *PacketDispatcher*
- ** Only created when _is-proactive-flood-mode_ is false
- ** Sends packets out to the network
- ** Uses *InventoryReader* to determine which node-connector to a send a packet on
-* *InventoryReader*
- ** Only created when _is-proactive-flood-mode_ is false
- ** Maintains a list of each switch's node-connectors
-
-===== Configuration
-* is-proactive-flood-mode
- ** "true" means that flood flows will be installed on each switch. With this flood flow, each switch will flood a packet that doesn't match any other flows.
- *** Advantage: Fewer packets are sent to the controller because those packets are flooded to the network.
- *** Disadvantage: A lot of network traffic is generated.
- ** "false" means the previously mentioned flood flows will not be installed. Instead an ARP flow will be installed on each switch that sends all ARP packets to the controller.
- *** Advantage: Less network traffic is generated.
- *** Disadvantage: The controller handles more packets (ARP requests & replies) and the ARP process takes longer than if there were flood flows.
-* flood-flow-table-id
- ** The flood flow will be installed on the specified flow table of each switch
-* flood-flow-priority
- ** The flood flow will be installed with the specified priority
-* flood-flow-idle-timeout
- ** The flood flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
-* flood-flow-hard-timeout
- ** The flood flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
-* arp-flow-table-id
- ** The ARP flow will be installed on the specified flow table of each switch
-* arp-flow-priority
- ** The ARP flow will be installed with the specified priority
-* arp-flow-idle-timeout
- ** The ARP flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
-* arp-flow-hard-timeout
- ** The ARP flow will timeout (removed from the switch) after _arp-flow-hard-timeout_ seconds, regardless of how many packets it is forwarding
-
-===== Further development
-The *ProactiveFloodFlowWriter* needs to be improved. It does have the advantage of having less traffic come to the controller; however, it generates too much network traffic.
-
-==== Address Tracker
-===== Classes
-* AddressTrackerModule
- ** Reads config subsystem value for _observe-addresses-from_
- ** If _observe-addresses-from_ contains "arp", then an AddressObserverUsingArp is created
- ** If _observe-addresses-from_ contains "ipv4", then an AddressObserverUsingIpv4 is created
- ** If _observe-addresses-from_ contains "ipv6", then an AddressObserverUsingIpv6 is created
-* AddressObserverUsingArp
- ** Registers for ARP packet notifications
- ** Uses *AddressObservationWriter* to write address observations from ARP packets
-* AddressObserverUsingIpv4
- ** Registers for IPv4 packet notifications
- ** Uses *AddressObservationWriter* to write address observations from IPv4 packets
-* AddressObserverUsingIpv6
- ** Registers for IPv6 packet notifications
- ** Uses *AddressObservationWriter* to write address observations from IPv6 packets
-* AddressObservationWriter
- ** Writes new Address Observations to the Inventory data tree
- ** Updates existing Address Observations with updated "last seen" timestamps
- *** Uses the _timestamp-update-intervval_ configuration variable to determine whether or not to update
-
-===== Configuration
-* timestamp-update-interval
- ** A last-seen timestamp is associated with each address. This last-seen timestamp will only be updated after _timestamp-update-interval_ milliseconds.
- ** A higher value has the advantage of performing less writes to the database.
- ** A lower value has the advantage of knowing how fresh an address is.
-* observe-addresses-from
- ** IP and MAC addresses can be observed/learned from ARP, IPv4, and IPv6 packets. Set which packets to make these observations from.
-
-===== Further development
-Further improvements can be made to the *AddressObservationWriter* so that it (1) doesn't make any unnecessary writes to the DB and
-(2) is optimized for multi-threaded environments.
-
-===== Validating changes to Address Tracker
-Address Observations are added to the Inventory data tree.
-
-The Address Observations on a Node Connector can be checked through a browser or a REST Client.
-
- http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
-
-
-The Address Observations should still be there after changes.
-
-==== Developer's Guide for Host Tracker
-
-===== Validationg changes to Host Tracker
-Host information is added to the Topology data tree.
-
-* Host address
-* Attachment point (link) to a node/switch
-
-This host information and attachment point information can be checked through a browser or a REST Client.
-
- http://10.194.126.91:8080/restconf/operational/network-topology:network-topology/topology/flow:1/
-
-Host information should still be there after changes.
-
-==== L2Switch Main
-===== Classes
-* L2SwitchMainModule
- ** Reads config subsystem value for _is-install-dropall-flow_
- *** If _is-install-dropall-flow_ is true, then an *InitialFlowWriter* is created
- ** Reads config subsystem value for _is-learning-only-mode_
- *** If _is-learning-only-mode_ is false, then a *ReactiveFlowWriter* is created
-* InitialFlowWriter
- ** Only created when _is-install-dropall-flow_ is true
- ** Installs a flow, which drops all packets, on each switch. This flow has low priority and means that packets that don't match any higher-priority flows will simply be dropped.
-* ReactiveFlowWriter
- ** Reacts to network traffic and installs MAC-to-MAC flows on switches. These flows have matches based on MAC source and MAC destination.
- ** Uses *FlowWriterServiceImpl* to write these flows to the switches
-* FlowWriterService / FlowWriterServiceImpl
- ** Writes flows to switches
-
-===== Configuration
-* is-install-dropall-flow
- ** "true" means a drop-all flow will be installed on each switch, so the default action will be to drop a packet instead of sending it to the controller
- ** "false" means this flow will not be installed
-* dropall-flow-table-id
- ** The dropall flow will be installed on the specified flow table of each switch
- ** This field is only relevant when "is-install-dropall-flow" is set to "true"
-* dropall-flow-priority
- ** The dropall flow will be installed with the specified priority
- ** This field is only relevant when "is-install-dropall-flow" is set to "true"
-* dropall-flow-idle-timeout
- ** The dropall flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
- ** This field is only relevant when "is-install-dropall-flow" is set to "true"
-* dropall-flow-hard-timeout
- ** The dropall flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
- ** This field is only relevant when "is-install-dropall-flow" is set to "true"
-* is-learning-only-mode
- ** "true" means that the L2Switch will only be learning addresses. No additional flows to optimize network traffic will be installed.
- ** "false" means that the L2Switch will react to network traffic and install flows on the switches to optimize traffic. Currently, MAC-to-MAC flows are installed.
-* reactive-flow-table-id
- ** The reactive flow will be installed on the specified flow table of each switch
- ** This field is only relevant when "is-learning-only-mode" is set to "false"
-* reactive-flow-priority
- ** The reactive flow will be installed with the specified priority
- ** This field is only relevant when "is-learning-only-mode" is set to "false"
-* reactive-flow-idle-timeout
- ** The reactive flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
- ** This field is only relevant when "is-learning-only-mode" is set to "false"
-* reactive-flow-hard-timeout
- ** The reactive flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
- ** This field is only relevant when "is-learning-only-mode" is set to "false"
-
-===== Further development
-The *ReactiveFlowWriter* needs to be improved to install the MAC-to-MAC flows faster. For the first ping, the ARP request and reply are successful.
-However, then the ping packets are sent out. The first ping packet is dropped sometimes because the MAC-to-MAC flow isn't installed quickly enough.
-The second, third, and following ping packets are successful though.
-
-=== API Reference Documentation
-Further documentation can be found by checking out the L2Switch project.
-
-=== Checking out the L2Switch project
- git clone https://git.opendaylight.org/gerrit/p/l2switch.git
-
-The above command will create a directory called "l2switch" with the project.
-
-=== Testing your changes to the L2Switch project
-==== Running the L2Switch project
-To run the base distribution, you can use the following command
-
- ./distribution/base/target/distributions-l2switch-base-0.1.0-SNAPSHOT-osgipackage/opendaylight/run.sh
-
-If you need additional resources, you can use these command line arguments:
-
- -Xms1024m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=1024m'
-
-To run the karaf distribution, you can use the following command:
-
- ./distribution/karaf/target/assembly/bin/karaf
-
-==== Create a network using mininet
- sudo mn --controller=remote,ip=<Controller IP> --topo=linear,3 --switch ovsk,protocols=OpenFlow13
- sudo mn --controller=remote,ip=127.0.0.1 --topo=linear,3 --switch ovsk,protocols=OpenFlow13
-
-The above command will create a virtual network consisting of 3 switches.
-Each switch will connect to the controller located at the specified IP, i.e. 127.0.0.1
-
- sudo mn --controller=remote,ip=127.0.0.1 --mac --topo=linear,3 --switch ovsk,protocols=OpenFlow13
-
-The above command has the "mac" option, which makes it easier to distinguish between Host MAC addresses and Switch MAC addresses.
-
-==== Generating network traffic using mininet
- h1 ping h2
-
-The above command will cause host1 (h1) to ping host2 (h2)
-
- pingall
-
-'pingall' will cause each host to ping every other host.
-
-==== Miscellaneous mininet commands
- link s1 s2 down
-
-This will bring the link between switch1 (s1) and switch2 (s2) down
-
- link s1 s2 up
-
-This will bring the link between switch1 (s1) and switch2 (s2) up
-
- link s1 h1 down
-
-This will bring the link between switch1 (s1) and host1 (h1) down
-
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/l2switch-developer-guide.html
== LACP Developer Guide
-=== LACP Overview
-The OpenDaylight LACP (Link Aggregation Control Protocol) project can be used to
-aggregate multiple links between OpenDaylight controlled network switches and
-LACP enabled legacy switches or hosts operating in active LACP mode.
-OpenDaylight LACP passively negotiates automatic bundling of multiple links to form
-a single LAG (Link Aggregation Group). LAGs are realised in the OpenDaylight controlled
-switches using OpenFlow 1.3+ group table functionality.
-
-
-=== LACP Architecture
-
-* *inventory*
- ** Maintains list of OpenDaylight controlled switches and port information
- ** List of LAGs created and physical ports that are part
- of the LAG
- ** Interacts with MD-SAL to update LACP related information
-
-* *inventorylistener*
- ** This module interacts with MD-SAL for receiving node/node-connector notifications
-
-* *flow*
- ** Programs the switch to punt LACP PDU (Protocol Data Unit) to controller
-
-* *packethandler*
- ** Receives and transmits LACP PDUs to the LACP enabled endpoint
- ** Provides infrastructure services for group table programming
-
-* *core*
- ** Performs LACP state machine processing
-
-
-==== How LAG programming is implemented
-
-The LAG representing the aggregated multiple physical ports
-are realized in the OpenDaylight controlled switches by creating a
-group table entry (Group table supported from OpenFlow 1.3 onwards).
-The group table entry has a group type *Select* and action referring to
-the aggregated physical ports.
-Any data traffic to be sent out through the LAG can be sent
-through the *group entry* available for the LAG.
-
-Suppose there are ports P1-P8 in a node.
-When LACP project is installed, a group table entry for handling broadcast traffic is automatically
-created on all the switches that have registered to the controller.
-
-[options="header"]
-|=================================
-|GroupID |GroupType|EgressPorts
-|<B'castgID>|ALL |P1,P2,...P8
-|=================================
-
-Now, assume P1 & P2 are now part of LAG1. The group table would be programmed as follows:
-
-[options="header"]
-|========================================
-|GroupID |GroupType|EgressPorts
-|<B'castgID>|ALL |P3,P4,...P8
-|<LAG1> |SELECT |P1,P2
-|========================================
-
-When a second LAG, LAG2, is formed with ports P3 and P4,
-
-[options="header"]
-|===============================================
-|GroupID |GroupType|EgressPorts
-|<B'castgID>|ALL |P5,P6,...P8
-|<LAG1> |SELECT |P1,P2
-|<LAG2> |SELECT |P3,P4
-|===============================================
-
-==== How applications can program OpenFlow flows using LACP-created LAG groups
-
-OpenDaylight controller modules can get the information of LAG by listening/querying the LACP Aggregator datastore.
-
-When any application receives packets, it can check, if the ingress port is part of a LAG by verifying the
-LAG Aggregator reference (lacp-agg-ref) for the source nodeConnector that OpenFlow plugin provides.
-
-When applications want to add flows to egress out of the LAG, they must use the group entry corresponding to the LAG.
-
-From the above example, for a flow to egress out of LAG1,
-
-*add-flow eth_type=<xxxx>,ip_dst=<x.x.x.x>,actions=output:<LAG1>*
-
-Similarly, when applications want traffic to be broadcasted, they should use the group table entries *<B'castgID>,<LAG1>,<LAG2>* in output action.
-
-For all applications, the group table information is accessible from LACP Aggregator datastore.
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/lacp-developer-guide.html
== NetIDE Developer Guide ==
-=== Overview ===
-The NetIDE Network Engine enables portability and cooperation inside a single
-network by using a client/server multi-controller SDN architecture. Separate
-"Client SDN Controllers" host the various SDN Applications with their access
-to the actual physical network abstracted and coordinated through a single
-"Server SDN Controller", in this instance OpenDaylight. This allows
-applications written for Ryu/Floodlight/Pyretic to execute on OpenDaylight
-managed infrastructure.
-
-The "Network Engine" is modular by design:
-
-* An OpenDaylight plugin, "shim", sends/receives messages to/from subscribed SDN
-Client Controllers. This consumes the ODL OpenFlow Plugin
-* An initial suite of SDN Client Controller "Backends": Floodlight, Ryu, Pyretic.
-Further controllers may be added over time as the engine is extensible.
-
-The Network Engine provides a compatibility layer capable of translating calls of
-the network applications running on top of the client controllers, into calls for
-the server controller framework. The communication between the client and the
-server layers is achieved through the NetIDE intermediate protocol,
-which is an application-layer protocol on top of TCP that transmits the network
-control/management messages from the client to the server controller and vice-versa.
-Between client and server controller sits the Core Layer which also "speaks" the
-intermediate protocol. The core layer implements three main functions:
-
-... interfacing with the client backends and server shim, controlling the lifecycle
-of controllers as well as modules in them,
-... orchestrating the execution of individual modules (in one client controller)
-or complete applications (possibly spread across multiple client controllers),
-... interfacing with the tools.
-
-.NetIDE Network Engine Architecture
-image::netide/arch-engine.jpg[width=500]
-
-=== NetIDE Intermediate Protocol ===
-
-The Intermediate Protocol serves several needs, it has to:
-
-... carry control messages between core and shim/backend, e.g., to start up/take
-down a particular module, providing unique identifiers for modules,
-... carry event and action messages between shim, core, and backend, properly
-demultiplexing such messages to the right module based on identifiers,
-... encapsulate messages specific to a particular SBI protocol version (e.g.,
-OpenFlow 1.X, NETCONF, etc.) towards the client controllers with proper information
-to recognize these messages as such.
-
-The NetIDE packages can be added as dependencies in Maven projects by putting the
-following code in the _pom.xml_ file.
-
- <dependency>
- <groupId>org.opendaylight.netide</groupId>
- <artifactId>api</artifactId>
- <version>${NETIDE_VERSION}</version>
- </dependency>
-
-The current stable version for NetIDE is `0.1.0-Beryllium`.
-
-
-
-==== Protocol specification
-
-Messages of the NetIDE protocol contain two basic elements: the NetIDE header and
-the data (or payload). The NetIDE header, described below, is placed
-before the payload and serves as the communication and control link between the
-different components of the Network Engine. The payload can contain management
-messages, used by the components of the Network Engine to exchange relevant
-information, or control/configuration messages (such as OpenFlow, NETCONF, etc.)
-crossing the Network Engine generated by either network application modules or by
-the network elements.
-
-The NetIDE header is defined as follows:
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | netide_ver | type | length |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | xid |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | module_id |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | |
- + datapath_id +
- | |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
-where each tick mark represents one bit position. Alternatively, in a C-style coding
-format, the NetIDE header can be represented with the following structure:
-
- struct netide_header {
- uint8_t netide_ver ;
- uint8_t type ;
- uint16_t length ;
- uint32_t xid
- uint32_t module_id
- uint64_t datapath_id
- };
-
-* +netide_ver+ is the version of the NetIDE protocol (the current version is v1.2, which
-is identified with value 0x03).
-* +length+ is the total length of the payload in bytes.
-* +type+ contains a code that indicates the type of the message according with the
-following values:
-+
- enum type {
- NETIDE_HELLO = 0x01 ,
- NETIDE_ERROR = 0x02 ,
- NETIDE_MGMT = 0x03 ,
- MODULE_ANNOUNCEMENT = 0x04 ,
- MODULE_ACKNOWLEDGE = 0x05 ,
- NETIDE_HEARTBEAT = 0x06 ,
- NETIDE_OPENFLOW = 0x11 ,
- NETIDE_NETCONF = 0x12 ,
- NETIDE_OPFLEX = 0x13
- };
-+
-* +datapath_id+ is a 64-bit field that uniquely identifies the network elements.
-* +module_id+ is a 32-bits field that uniquely identifies Backends and application modules running
-on top of each client controller. The composition mechanism in the core layer leverages
-on this field to implement the correct execution flow of these modules.
-* +xid+ is the transaction identifier associated to the each message. Replies must use the same
-value to facilitate the pairing.
-
-
-==== Module announcement
-
-The first operation performed by a Backend is registering itself and the modules that
-it is running to the Core. This is done by using the +MODULE_ANNOUNCEMENT+ and
-+MODULE_ACKNOWLEDGE+ message types. As a result of this process, each Backend and
-application module can be recognized by the Core through an identifier (the +module_id+)
-placed in the NetIDE header. First, a Backend registers itself by using the following
-schema: backend-<platform name>-<pid>.
-
-For example,odule a Ryu Backend will register by using the following name in the message
-backend-ryu-12345 where 12345 is the process ID of the registering instance of the
-Ryu platform. The format of the message is the following:
-
- struct NetIDE_message {
- netide_ver = 0x03
- type = MODULE_ANNOUNCEMENT
- length = len(" backend -< platform_name >-<pid >")
- xid = 0
- module_id = 0
- datapath_id = 0
- data = " backend -< platform_name >-<pid >"
- }
-
-The answer generated by the Core will include a +module_id+ number and the Backend name in
-the payload (the same indicated in the +MODULE_ANNOUNCEMENT+ message):
-
- struct NetIDE_message {
- netide_ver = 0x03
- type = MODULE_ACKNOWLEDGE
- length = len(" backend -< platform_name >-<pid >")
- xid = 0
- module_id = MODULE_ID
- datapath_id = 0
- data = " backend -< platform_name >-<pid >"
- }
-
-Once a Backend has successfully registered itself, it can start registering its modules with the same
-procedure described above by indicating the name of the module in the data (e.g. data="Firewall").
-From this point on, the Backend will insert its own +module_id+ in the header of the messages it generates
- (e.g. heartbeat, hello messages, OpenFlow echo messages from the client controllers, etc.).
-Otherwise, it will encapsulate the control/configuration messages (e.g. FlowMod, PacketOut,
-FeatureRequest, NETCONF request, etc.) generated by network application modules with the specific
-+module_id+s.
-
-
-==== Heartbeat
-
-The heartbeat mechanism has been introduced after the adoption of the ZeroMQ messaging queuing
-library to transmit the NetIDE messages. Unfortunately, the ZeroMQ library does not offer any
-mechanism to find out about disrupted connections (and also completely unresponsive peers).
-This limitation of the ZeroMQ library can be an issue for the Core's composition mechanism and for
-the tools connected to the Network Engine, as they cannot understand when an client controller
-disconnects or crashes. As a consequence, Backends must periodically send (let's say every 5
-seconds) a "heartbeat" message to the Core. If the Core does not receive at least one "heartbeat"
-message from the Backend within a certain timeframe, the Core considers it disconnected, removes
-all the related data from its memory structures and informs the relevant tools. The format of the
-message is the following:
-
- struct NetIDE_message {
- netide_ver = 0x03
- type = NETIDE_HEARTBEAT
- length = 0
- xid = 0
- module_id = backend -id
- datapath_id = 0
- data = 0
- }
-
-==== Handshake
-
-Upon a successful connection with the Core, the client controller must immediately send a hello
-message with the list of the control and/or management protocols needed by the applications
-deployed on top of it.
-
- struct NetIDE_message {
- struct netide_header header ;
- uint8 data [0]
- };
-
-The header contains the following values:
-
-* +netide ver=0x03+
-* +type=NETIDE_HELLO+
-* +length=2*NR_PROTOCOLS+
-* +data+ contains one 2-byte word (in big endian order) for each protocol, with the first
-byte containing the code of the protocol according to the above enum, while the second byte in-
-dictates the version of the protocol (e.g. according to the ONF specification, 0x01 for OpenFlow
-v1.0, 0x02 for OpenFlow v1.1, etc.). NETCONF version is marked with 0x01 that refers to the
-specification in the RFC6241, while OpFlex version is marked with 0x00 since this protocol is
-still in work-in-progress stage.
-
-The Core relays hello messages to the server controller which responds with another hello message
-containing the following:
-
-* +netide ver=0x03+
-* +type=NETIDE_HELLO+
-* +length=2*NR_PROTOCOLS+
-
-If at least one of the protocols requested by the client is supported. In particular, +data+ contains the
-codes of the protocols that match the client's request (2-bytes words, big endian order). If the hand-
-shake fails because none of the requested protocols is supported by the server controller, the header
-of the answer is as follows:
-
-* +netide ver=0x03+
-* +type=NETIDE_ERROR+
-* +length=2*NR_PROTOCOLS+
-* +data+ contains the codes of all the protocols supported by the server
-controller (2-bytes words, big endian order). In this case, the TCP session is terminated by the
-server controller just after the answer is received by the client.
-`
\ No newline at end of file
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/netide-developer-guide.html
== Neutron Northbound
-=== How to add new API support
-OpenStack Neutron is a moving target. It is continuously adding new features
-as new rest APIs. Here is a basic step to add new API support:
-
-In the Neutron Northbound project:
-
-* Add new YANG model for it under `neutron/model/src/main/yang` and
- `update neutron.yang`
-* Add northbound API for it, and neutron-spi
-** Implement `Neutron<New API>Request.java` and `Neutron<New API>Norhtbound.java`
- under
- `neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/`
-** Implement `INeutron<New API>CRUD.java` and new data structure if any under
- `neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/`
-** update
- `neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/NeutronCRUDInterfaces.java`
- to wire new CRUD interface
-** Add unit tests, `Neutron<New structure>JAXBTest.java` under
- `neutron/neutron-spi/src/test/java/org/opendaylight/neutron/spi/`
-* update
- `neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/NeutronNorthboundRSApplication.java`
- to wire new northbound api to `RSApplication`
-* Add transcriber, `Neutron<New API>Interface.java` under
- `transcriber/src/main/java/org/opendaylight/neutron/transcriber/`
-* update
- `transcriber/src/main/java/org/opendaylight/neutron/transcriber/NeutronTranscriberProvider.java`
- to wire a new transcriber
-** Add integration tests `Neutron<New API>Tests.java`
- under `integration/test/src/test/java/org/opendaylight/neutron/e2etest/`
-** update `integration/test/src/test/java/org/opendaylight/neutron/e2etest/ITNeutronE2E.java`
- to run a newly added tests.
-
-In OpenStack networking-odl
-
-* Add new driver (or plugin) for new API with tests.
-
-In a southbound Neutron Provider
-
-* implement actual backend to realize those new API by listening related YANG
- models.
-
-
-=== How to write transcriber
-
-For each Neutron data object, there is an `Neutron*Interface` defined within
-the transcriber artifact that will write that object to the MD-SAL
-configuration datastore.
-
-All `Neutron*Interface` extend `AbstractNeutronInterface`, in which two methods
-are defined:
-
-* one takes the Neutron object as input, and will create a data object from it.
-* one takes an uuid as input, and will create a data object containing the uuid.
-
-----
-protected abstract T toMd(S neutronObject);
-protected abstract T toMd(String uuid);
-----
-
-In addition the `AbstractNeutronInterface` class provides several other
-helper methods (`addMd`, `updateMd`, `removeMd`), which handle the actual
-writing to the configuration datastore.
-
-==== The semantics of the `toMD()` methods
-Each of the Neutron YANG models defines structures containing data.
-Further each YANG-modeled structure has it own builder.
-A particular `toMD()` method instantiates an instance of the correct
-builder, fills in the properties of the builder from the corresponding
-values of the Neutron object and then creates the YANG-modeled structures
-via the `build()` method.
-
-As an example, one of the `toMD` code for Neutron Networks is
-presented below:
-
-----
-protected Network toMd(NeutronNetwork network) {
- NetworkBuilder networkBuilder = new NetworkBuilder();
- networkBuilder.setAdminStateUp(network.getAdminStateUp());
- if (network.getNetworkName() != null) {
- networkBuilder.setName(network.getNetworkName());
- }
- if (network.getShared() != null) {
- networkBuilder.setShared(network.getShared());
- }
- if (network.getStatus() != null) {
- networkBuilder.setStatus(network.getStatus());
- }
- if (network.getSubnets() != null) {
- List<Uuid> subnets = new ArrayList<Uuid>();
- for( String subnet : network.getSubnets()) {
- subnets.add(toUuid(subnet));
- }
- networkBuilder.setSubnets(subnets);
- }
- if (network.getTenantID() != null) {
- networkBuilder.setTenantId(toUuid(network.getTenantID()));
- }
- if (network.getNetworkUUID() != null) {
- networkBuilder.setUuid(toUuid(network.getNetworkUUID()));
- } else {
- logger.warn("Attempting to write neutron network without UUID");
- }
- return networkBuilder.build();
-}
-----
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/neutron-northbound.html
== Neutron Service Developer Guide
-=== Overview
-This Karaf feature (`odl-neutron-service`) provides integration support for OpenStack Neutron
-via the OpenDaylight ML2 mechanism driver. The Neutron Service is only one of the
-components necessary for OpenStack integration.
-It defines YANG models for OpenStack Neutron data models and northbound
-API via REST API and YANG model RESTCONF.
-
-Those developers who want to add new provider for new OpenStack Neutron
-extensions/services (Neutron constantly adds new extensions/services and OpenDaylight
-will keep up with those new things) need to communicate with this Neutron
-Service or add models to Neutron Service.
-If you want to add new extensions/services themselves to the Neutron Service,
-new YANG data models need to be added, but that is out of scope of this document
-because this guide is for a developer who will be _using_ the feature
-to build something separate, but _not_ somebody who will be developing
-code for this feature itself.
-
-=== Neutron Service Architecture
-image::neutron/odl-neutron-service-developer-architecture.png[height="450px", width="550px", title="Neutron Service Architecture"]
-// image original: https://docs.google.com/drawings/d/15xtroJahSFt93K10Zp8AVln_WZgowmhv7MC_2VdZQzg/edit?usp=sharing
-
-The Neutron Service defines YANG models for OpenStack Neutron integration.
-When OpenStack admins/users request changes (creation/update/deletion)
-of Neutron resources, e.g., Neutron network, Neutron subnet, Neutron port, the corresponding YANG model within OpenDaylight will be modified.
-The OpenDaylight OpenStack will subscribe the changes on those models and
-will be notified those modification through MD-SAL when changes are made.
-Then the provider will do the necessary tasks to realize OpenStack integration.
-How to realize it (or even not realize it) is up to each provider.
-The Neutron Service itself does not take care of it.
-
-=== How to Write a SB Neutron Consumer
-In Boron, there is only one options for SB Neutron Consumers:
-
-* Listening for changes via the Neutron YANG model
-
-Until Beryllium there was another way with the legacy I*Aware interface.
-From Boron, the interface was eliminated. So all the SB Neutron Consumers
-have to use Neutron YANG model.
-
-
-=== Neutron YANG models
-Neutron service defines YANG models for Neutron. The details can be found
-at
-
-* https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=tree;f=model/src/main/yang;hb=refs/heads/stable/boron
-
-Basically those models are based on OpenStack Neutron API definitions.
-For exact definitions, OpenStack Neutron source code needs to be referred
-as the above documentation doesn't always cover the necessary details.
-There is nothing special to utilize those Neutron YANG models.
-The basic procedure will be:
-
-. subscribe for changes made to the the model
-. respond on the data change notification for each models
-
-[NOTE]
-Currently there is no way to refuse the request configuration at this
-point. That is left to future work.
-
-[source,java]
-----
-public class NeutronNetworkChangeListener implements DataChangeListener, AutoCloseable {
- private ListenerRegistration<DataChangeListener> registration;
- private DataBroker db;
-
- public NeutronNetworkChangeListener(DataBroker db){
- this.db = db;
- // create identity path to register on service startup
- InstanceIdentifier<Network> path = InstanceIdentifier
- .create(Neutron.class)
- .child(Networks.class)
- .child(Network.class);
- LOG.debug("Register listener for Neutron Network model data changes");
- // register for Data Change Notification
- registration =
- this.db.registerDataChangeListener(LogicalDatastoreType.CONFIGURATION, path, this, DataChangeScope.ONE);
-
- }
-
- @Override
- public void onDataChanged(
- AsyncDataChangeEvent<InstanceIdentifier<?>, DataObject> changes) {
- LOG.trace("Data changes : {}",changes);
-
- // handle data change notification
- Object[] subscribers = NeutronIAwareUtil.getInstances(INeutronNetworkAware.class, this);
- createNetwork(changes, subscribers);
- updateNetwork(changes, subscribers);
- deleteNetwork(changes, subscribers);
- }
-}
-----
-
-=== Neutron configuration
-From Boron, new models of configuration for OpenDaylight to tell
-OpenStack neutron/networking-odl its configuration/capability.
-
-==== hostconfig
-This is for OpenDaylight to tell per-node configuration to Neutron.
-Especially this is used by pseudo agent port binding heavily.
-
-The model definition can be found at
-
-* https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-hostconfig.yang;hb=refs/heads/stable/boron
-
-How to populate this for pseudo agent port binding is documented at
-
-* http://git.openstack.org/cgit/openstack/networking-odl/tree/doc/source/devref/hostconfig.rst
-
-==== Neutron extension config
-In Boron this is experimental.
-The model definition can be found at
-
-* https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=model/src/main/yang/neutron-extensions.yang;hb=refs/heads/stable/boron
-
-Each Neutron Service provider has its own feature set. Some support
-the full features of OpenStack, but others support only a subset.
-With same supported Neutron API, some functionality may or may not be
-supported. So there is a need for a way that OpenDaylight can tell networking-odl its
-capability. Thus networking-odl can initialize Neutron properly based
-on reported capability.
-
-
-=== Neutorn Logger
-There is another small Karaf feature, `odl-neutron-logger`, which logs changes of Neutron
-YANG models. which can be used for debug/audit.
-
-It would also help to understand how to listen the change.
-
-* https://git.opendaylight.org/gerrit/gitweb?p=neutron.git;a=blob;f=neutron-logger/src/main/java/org/opendaylight/neutron/logger/NeutronLogger.java;hb=refs/heads/stable/boron
-
-
-=== API Reference Documentation
-The OpenStack Neutron API references
-
-* http://developer.openstack.org/api-ref-networking-v2.html
-* http://developer.openstack.org/api-ref-networking-v2-ext.html
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/neutron-service-developer-guide.html
== Network Intent Composition (NIC) Developer Guide
-=== Overview
-The Network Intent Composition (NIC) provides four features:
-
-* odl-nic-core-hazelcast: Provides a distributed intent mapping service, implemented
- using hazelcast, that stores metadata needed by odl-nic-core feature.
-
-* odl-nic-core-mdsal: Provides an intent rest API to external applications for CRUD operations on intents, conflict resolution and event handling. Uses MD-SAL as backend.
-
-* odl-nic-console: Provides a karaf CLI extension for intent CRUD operations and mapping service operations.
-
-* odl-nic-renderer-of - Generic Openflow Renderer.
-
-* odl-nic-renderer-vtn - a feature that transforms an intent to a network
-modification using the VTN project
-
-* odl-nic-renderer-gbp - a feature that transforms an intent to a network
-modification using the Group Policy project
-
-* odl-nic-renderer-nemo - a feature that transforms an intent to a network
-modification using the NEMO project
-
-* odl-nic-listeners - adds support for event listening. (depends on: odl-nic-renderer-of)
-
-* odl-nic-neutron-integration - allow integration with openstack neutron to allow coexistence between existing neutron security rules and intents pushed by ODL applications.
-
-_Only a single renderer feature should be installed at a time for the Boron
-release._
-
-=== odl-nic-core-mdsal XOR odl-nic-core-hazelcast
-This feature supplies the base models for the Network Intent Composition (NIC)
-capability. This includes the definition of intent as well as the configuration
-and operational data trees.
-
-This feature only provides an information model. The interface for NIC is to
-modify the information model via the configuraiton data tree, which will
-trigger the renderer to make the appropriate changes in the controlled
-network.
-
-=== Installation
-
-==== First you need to install one of the core installations:
-
- feature:install odl-nic-core-service-mdsal odl-nic-console
-
-_OR_
-
- feature:install odl-nic-core-service-hazelcast odl-nic-console
-
-==== Then pick a renderer:
-
- feature:install odl-nic-listeners (will install odl-nic-renderer-of)
-
-_OR_
-
- feature:install odl-nic-renderer-vtn
-
-_OR_
-
- feature:install odl-nic-renderer-gbp
-
-_OR_
-
- feature:install odl-nic-renderer-nemo
-
-=== REST Supported operations
-
-==== POST / PUT (configuration)
-This operations create instances of an intent in the configuration data tree
-and trigger the creation or modification of an intent.
-
-==== GET (configuration / operational)
-This operation lists all or fetches a single intent from the data tree.
-
-==== DELETE (configuration)
-This operation will cause an intent to be removed from the system and trigger
-any configuration changes on the network rendered from this intent to be
-removed.
-
-=== odl-nic-cli user guide
-
-This feature provides karaf console CLI command to manipulate the intent
-data model. The CLI essentailly invokes the equivalent data operations.
-
-==== intent:add
-
-Creates a new intent in the configuration data tree
-
-----
-DESCRIPTION
- intent:add
-
- Adds an intent to the controller.
-
-Examples: --actions [ALLOW] --from <subject> --to <subject>
- --actions [BLOCK] --from <subject>
-
-SYNTAX
- intent:add [options]
-
-OPTIONS
- -a, --actions
- Action to be performed.
- -a / --actions BLOCK/ALLOW
- (defaults to [BLOCK])
- --help
- Display this help message
- -t, --to
- Second Subject.
- -t / --to <subject>
- (defaults to any)
- -f, --from
- First subject.
- -f / --from <subject>
- (defaults to any)
-----
-
-==== intent:delete
-Removes an existing intent from the system
-
-----
-DESCRIPTION
- intent:remove
-
- Removes an intent from the controller.
-
-SYNTAX
- intent:remove id
-
-ARGUMENTS
- id Intent Id
-----
-
-==== intent:list
-Lists all the intents in the system
-
-----
-DESCRIPTION
- intent:list
-
- Lists all intents in the controller.
-
-SYNTAX
- intent:list [options]
-
-OPTIONS
- -c, --config
- List Configuration Data (optional).
- -c / --config <ENTER>
- --help
- Display this help message
-----
-
-==== intent:show
-Displays the details of a single intent
-
-----
-DESCRIPTION
- intent:show
-
- Shows detailed information about an intent.
-
-SYNTAX
- intent:show id
-
-ARGUMENTS
- id Intent Id
-----
-
-==== intent:map
-
-List/Add/Delete current state from/to the mapping service.
-
-----
-DESCRIPTION
- intent:map
-
- List/Add/Delete current state from/to the mapping service.
-
-SYNTAX
- intent:map [options]
-
- Examples: --list, -l [ENTER], to retrieve all keys.
- --add-key <key> [ENTER], to add a new key with empty contents.
- --del-key <key> [ENTER], to remove a key with it's values."
- --add-key <key> --value [<value 1>, <value 2>, ...] [ENTER],
- to add a new key with some values (json format).
-OPTIONS
- --help
- Display this help message
- -l, --list
- List values associated with a particular key.
- -l / --filter <regular expression> [ENTER]
- --add-key
- Adds a new key to the mapping service.
- --add-key <key name> [ENTER]
- --value
- Specifies which value should be added/delete from the mapping service.
- --value "key=>value"... --value "key=>value" [ENTER]
- (defaults to [])
- --del-key
- Deletes a key from the mapping service.
- --del-key <key name> [ENTER]
-----
-
-=== Sample Use case: MPLS
-
-==== Description
-
-The scope of this use-case is to add MPLS intents between two MPLS endpoints. The use-case tries to address the real-world scenario illustrated in the diagram below:
-
-.MPLS VPN Service Diagram
-image::nic/MPLS_VPN_Service_Diagram.png[MPLS VPN Service Diagram,width=500]
-
-where PE (Provider Edge) and P (Provider) switches are managed by Opendaylight. In NIC's terminology the endpoints are the PE switches. There could be many P switches between the PEs.
-
-In order for NIC to recognize endpoints as MPLS endpoints, the user is expected to add mapping information about the PE switches to NIC's mapping service to include the below properties:
-
- 1. MPLS Label to identify a PE
- 2. IPv4 Prefix for the customer site that are connected to a PE
- 3. Switch-Port: Ingress (or Egress) for source (or Destination) endpoint of the source (or Destination) PE
-
-An intent:add between two MPLS endpoints renders Openflow rules for:
- 1. push/pop labels to the MPLS endpoint nodes after an IPv4 Prefix match.
- 2. forward to port rule after MPLS label match to all the switches that form the shortest path between the endpoints (calculated using Dijkstra algorithm).
-
-Additionally, we have also added constraints to Intent model for protection and failover mechanism to ensure end-to-end connectivity between endpoints.
-By specifying these constraints to intent:add the use-case aims to reduces the risk of connectivity failure due to a single link or port down event on a forwarding device.
-
- - Protection constraint: Constraint that requires an end-to-end connectivity to be protected by providing redundant paths.
- - Failover constraint: Constraint that specifies the type of failover implementation.
- slow-reroute: Uses disjoint path calculation algorithms like Suurballe to provide alternate end-to-end routes.
- fast-reroute: Uses failure detection feature in hardware forwarding device through OF group table features (Future plans)
-When no constraint is requested by the user we default to offering a since end-to-end route using Dijkstra shortest path.
-
-==== How to use it?
-
-1. Start Karaf and install related features:
-+
- feature:install odl-nic-core-service-mdsal odl-nic-core odl-nic-console odl-nic-listeners
- feature:install odl-dlux-all odl-dlux-core odl-dlux-yangui odl-dlux-yangvisualizer
-+
-2. Start mininet topology and verify in DLUX Topology page for the nodes and link.
-+
- mn --controller=remote,ip=$CONTROLLER_IP --custom ~/shortest_path.py --topo shortest_path --switch ovsk,protocols=OpenFlow13
-
- cat shortest.py -->
- from mininet.topo import Topo
- from mininet.cli import CLI
- from mininet.net import Mininet
- from mininet.link import TCLink
- from mininet.util import irange,dumpNodeConnections
- from mininet.log import setLogLevel
-
- class Fast_Failover_Demo_Topo(Topo):
-
- def __init__(self):
- # Initialize topology and default options
- Topo.__init__(self)
-
- s1 = self.addSwitch('s1',dpid='0000000000000001')
- s2a = self.addSwitch('s2a',dpid='000000000000002a')
- s2b = self.addSwitch('s2b',dpid='000000000000002b')
- s2c = self.addSwitch('s2c',dpid='000000000000002c')
- s3 = self.addSwitch('s3',dpid='0000000000000003')
- self.addLink(s1, s2a)
- self.addLink(s1, s2b)
- self.addLink(s2b, s2c)
- self.addLink(s3, s2a)
- self.addLink(s3, s2c)
- host_1 = self.addHost('h1',ip='10.0.0.1',mac='10:00:00:00:00:01')
- host_2 = self.addHost('h2',ip='10.0.0.2',mac='10:00:00:00:00:02')
- self.addLink(host_1, s1)
- self.addLink(host_2, s3)
-
- topos = { 'shortest_path': ( lambda: Demo_Topo() ) }
-+
-3. Update the mapping service with required information
-+
-Sample payload:
-+
- {
- "mappings": {
- "outer-map": [
- {
- "id": "uva",
- "inner-map": [
- {
- "inner-key": "ip_prefix",
- "value": "10.0.0.1/32"
- },
- {
- "inner-key": "mpls_label",
- "value": "15"
- },
- {
- "inner-key": "switch_port",
- "value": "openflow:1:1"
- }
- ]
- },
- {
- "id": "eur",
- "inner-map": [
- {
- "inner-key": "ip_prefix",
- "value": "10.0.0.2/32"
- },
- {
- "inner-key": "mpls_label",
- "value": "16"
- },
- {
- "inner-key": "switch_port",
- "value": "openflow:3:1"
- }
- ]
- }
- ]
- }
- }
-+
-4. Create bidirectional Intents using Karaf command line or RestCONF:
-+
-Example:
-+
- intent:add -f uva -t eur -a ALLOW
- intent:add -f eur -t uva -a ALLOW
-+
-5. Verify by running ovs command on mininet if the flows were pushed correctly to the nodes that form the shortest path.
-+
-Example:
-+
- ovs-ofctl -O OpenFlow13 dump-flows s1
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/network-intent-composition-(nic)-developer-guide.html
+++ /dev/null
-==== bundle-parent
-This inherits from +odlparent+ and enables functionality useful for OSGi bundles: +
-
-* +maven-javadoc-plugin+ is activated, to build the Javadoc JAR;
-* +maven-source-plugin+ is activated, to build the source JAR;
-* +maven-bundle-plugin+ is activated (including extensions), to build OSGi bundles (using the “bundle” packaging).
-
-In addition to this, JUnit is included as a default dependency in “test” scope.
== ODL Parent Developer Guide
-include::odlparent-parents-developer.adoc[]
-
-include::odlparent-features-developer.adoc[]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/odl-parent-developer-guide.html
+++ /dev/null
-=== Features
-
-The ODL Parent component for OpenDaylight provides a number of Karaf features which can be used by other Karaf features
-to use certain third-party upstream dependencies.
-
-These features are: +
-
-* Akka features (in the +features-akka+ repository): +
-** +odl-akka-all+ — all Akka bundles;
-** +odl-akka-scala+ — Scala runtime for OpenDaylight;
-** +odl-akka-system+ — Akka actor framework bundles;
-** +odl-akka-clustering+ — Akka clustering bundles and dependencies;
-** +odl-akka-leveldb+ — LevelDB;
-** +odl-akka-persistence+ — Akka persistence;
-* general third-party features (in the +features-odlparent+ repository):
-** +odl-netty+ — all Netty bundles;
-** +odl-guava+ — Guava;
-** +odl-lmax+ — LMAX Disruptor.
-
-To use these, you need to declare a dependency on the appropriate repository in your +features.xml+ file:
-
---------------------------------------
-<repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
---------------------------------------
-
-and then include the feature, _e.g._:
-
---------------------------------------
-<feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
- [...]
- <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
- [...]
-</feature>
---------------------------------------
-
-You also need to depend on the features repository in your POM:
-
---------------------------------------
-<dependency>
- <groupId>org.opendaylight.odlparent</groupId>
- <artifactId>features-odlparent</artifactId>
- <classifier>features</classifier>
- <type>xml</type>
-</dependency>
---------------------------------------
-
-assuming the appropriate dependency management:
-
---------------------------------------
-<dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>org.opendaylight.odlparent</groupId>
- <artifactId>odlparent-artifacts</artifactId>
- <version>1.7.0-SNAPSHOT</version>
- <scope>import</scope>
- <type>pom</type>
- </dependency>
- </dependencies>
-</dependencyManagement>
---------------------------------------
-
-(the version number there is appropriate for Boron). For the time being you also need to depend separately on the
-individual JARs as compile-time dependencies to build your dependent code; the relevant dependencies are managed in
-+odlparent+'s dependency management.
-
-The suggested version ranges are as follows: +
-
-* +odl-netty+: +[4.0.37,4.1.0)+ or +[4.0.37,5.0.0)+;
-* +odl-guava+: +[18,19)+ (if your code is ready for it, +[19,20)+ is also available, but the current default version of
- Guava in OpenDaylight is 18);
-* +odl-lmax+: +[3.3.4,4.0.0)+
+++ /dev/null
-==== features-parent
-This inherits from +odlparent+ and enables functionality useful for Karaf features: +
-
-* +karaf-maven-plugin+ is activated, to build Karaf features — but for OpenDaylight, projects need to use “jar”
- packaging (**not** “kar”);
-* +features.xml+ files are processed from templates stored in +src/main/features/features.xml+;
-* Karaf features are tested after build to ensure they can be activated in a Karaf container.
-
-The +features.xml+ processing allows versions to be ommitted from certain feature dependencies, and replaced with
-“+{{VERSION}}+”. For example:
-
---------------------------------------
-<features name="odl-mdsal-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.2.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.2.0 http://karaf.apache.org/xmlns/features/v1.2.0">
-
- <repository>mvn:org.opendaylight.odlparent/features-odlparent/{{VERSION}}/xml/features</repository>
-
- [...]
- <feature name='odl-mdsal-broker-local' version='${project.version}' description="OpenDaylight :: MDSAL :: Broker">
- <feature version='${yangtools.version}'>odl-yangtools-common</feature>
- <feature version='${mdsal.version}'>odl-mdsal-binding-dom-adapter</feature>
- <feature version='${mdsal.model.version}'>odl-mdsal-models</feature>
- <feature version='${project.version}'>odl-mdsal-common</feature>
- <feature version='${config.version}'>odl-config-startup</feature>
- <feature version='${config.version}'>odl-config-netty</feature>
- <feature version='[3.3.0,4.0.0)'>odl-lmax</feature>
- [...]
- <bundle>mvn:org.opendaylight.controller/sal-dom-broker-config/{{VERSION}}</bundle>
- <bundle start-level="40">mvn:org.opendaylight.controller/blueprint/{{VERSION}}</bundle>
- <configfile finalname="${config.configfile.directory}/${config.mdsal.configfile}">mvn:org.opendaylight.controller/md-sal-config/{{VERSION}}/xml/config</configfile>
- </feature>
---------------------------------------
-
-As illustrated, versions can be ommitted in this way for repository dependencies, bundle dependencies and configuration
-files. They must be specified traditionally (either hard-coded, or using Maven properties) for feature dependencies.
+++ /dev/null
-==== odlparent
-This inherits from +odlparent-lite+ and mainly provides dependency and plugin management for OpenDaylight projects.
-
-If you use any of the following libraries, you should rely on +odlparent+ to provide the appropriate versions: +
-
-* Akka (and Scala)
-* Apache Commons: +
-** +commons-codec+
-** +commons-fileupload+
-** +commons-io+
-** +commons-lang+
-** +commons-lang3+
-** +commons-net+
-* Apache Shiro
-* Guava
-* JAX-RS with Jersey
-* JSON processing: +
-** GSON
-** Jackson
-* Logging: +
-** Logback
-** SLF4J
-* Netty
-* OSGi: +
-** Apache Felix
-** core OSGi dependencies (+core+, +compendium+...)
-* Testing: +
-** Hamcrest
-** JSON assert
-** JUnit
-** Mockito
-** Pax Exam
-** PowerMock
-* XML/XSL: +
-** Xerces
-** XML APIs
-
-[NOTE]
-This list isn't exhaustive.
-It's also not cast in stone; if you'd like to add a new dependency (or migrate a dependency), please contact
-https://lists.opendaylight.org/mailman/listinfo/odlparent-dev[the mailing list].
-
-+odlparent+ also enforces some Checkstyle verification rules. In particular, it enforces the common license header
-used in all OpenDaylight code:
-
---------------------------------------
-/*
- * Copyright © ${year} ${holder} and others. All rights reserved.
- *
- * This program and the accompanying materials are made available under the
- * terms of the Eclipse Public License v1.0 which accompanies this distribution,
- * and is available at http://www.eclipse.org/legal/epl-v10.html
- */
---------------------------------------
-
-where “+${year}+” is initially the first year of publication, then (after a year has passed) the first and latest years
-of publication, separated by commas (_e.g._ “2014, 2016”), and “+${holder}+” is the initial copyright holder (typically,
-the first author's employer).
-“All rights reserved” is optional.
-
-If you need to disable this license check, _e.g._ for files imported under another license (EPL-compatible of course),
-you can override the +maven-checkstyle-plugin+ configuration. +features-test+ does this for its
-+CustomBundleUrlStreamHandlerFactory+ class, which is ASL-licensed:
-
---------------------------------------
-<plugin>
- <artifactId>maven-checkstyle-plugin</artifactId>
- <executions>
- <execution>
- <id>check-license</id>
- <goals>
- <goal>check</goal>
- </goals>
- <phase>process-sources</phase>
- <configuration>
- <configLocation>check-license.xml</configLocation>
- <headerLocation>EPL-LICENSE.regexp.txt</headerLocation>
- <includeResources>false</includeResources>
- <includeTestResources>false</includeTestResources>
- <sourceDirectory>${project.build.sourceDirectory}</sourceDirectory>
- <excludes>
- <!-- Skip Apache Licensed files -->
- org/opendaylight/odlparent/featuretest/CustomBundleUrlStreamHandlerFactory.java
- </excludes>
- <failsOnError>false</failsOnError>
- <consoleOutput>true</consoleOutput>
- </configuration>
- </execution>
- </executions>
-</plugin>
---------------------------------------
+++ /dev/null
-==== odlparent-lite
-This is the base parent for all OpenDaylight Maven projects and modules. It provides the following, notably to allow
-publishing artifacts to Maven Central: +
-
-* license information;
-* organization information;
-* issue management information (a link to our Bugzilla);
-* continuous integration information (a link to our Jenkins setup);
-* default Maven plugins (+maven-clean-plugin+, +maven-deploy-plugin+, +maven-install-plugin+,
- +maven-javadoc-plugin+ with HelpMojo support, +maven-project-info-reports-plugin+, +maven-site-plugin+ with
- Asciidoc support, +jdepend-maven-plugin+);
-* distribution management information.
-
-It also defines two profiles which help during development:
-
-* +q+ (+-Pq+), the quick profile, which disables tests, code coverage, Javadoc generation, code analysis, etc. —
- anything which isn't necessary to build the bundles and features (see
- http://blog2.vorburger.ch/2016/06/improve-maven-build-speed-with-q.html[this blog post] for details);
-* +addInstallRepositoryPath+ (+-DaddInstallRepositoryPath=.../karaf/system+) which can be used to drop a bundle
- in the appropriate Karaf location, to enable hot-reloading of bundles during development (see
- http://blog2.vorburger.ch/2016/06/maven-install-into-additional.html[this blog post] for details).
-
-For modules which don't produce any useful artifacts (_e.g._ aggregator POMs), you should add the following to avoid
-processing artifacts:
-
---------------------------------------
-<build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-deploy-plugin</artifactId>
- <configuration>
- <skip>true</skip>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-install-plugin</artifactId>
- <configuration>
- <skip>true</skip>
- </configuration>
- </plugin>
- </plugins>
-</build>
---------------------------------------
+++ /dev/null
-=== Parent POMs
-
-==== Overview
-The ODL Parent component for OpenDaylight provides a number of Maven parent POMs which allow Maven projects to be
-easily integrated in the OpenDaylight ecosystem.
-Technically, the aim of projects in OpenDaylight is to produce Karaf features, and these parent projects provide common
-support for the different types of projects involved.
-
-These parent projects are: +
-
-* +odlparent-lite+ — the basic parent POM for Maven modules which don't produce artifacts (_e.g._ aggregator POMs)
-* +odlparent+ — the common parent POM for Maven modules containing Java code
-* +bundle-parent+ — the parent POM for Maven modules producing OSGi bundles
-* +features-parent+ — the parent POM for Maven modules producing Karaf features
-
-include::odlparent-odlparent-lite-developer.adoc[]
-
-include::odlparent-odlparent-developer.adoc[]
-
-include::odlparent-bundle-parent-developer.adoc[]
-
-include::odlparent-features-parent-developer.adoc[]
== OF-CONFIG Developer Guide ==
-=== Overview ===
-OF-CONFIG defines an OpenFlow switch as an abstraction called an
-OpenFlow Logical Switch. The OF-CONFIG protocol enables configuration of
-essential artifacts of an OpenFlow Logical Switch so that an OpenFlow
-controller can communicate and control the OpenFlow Logical switch via
-the OpenFlow protocol. OF-CONFIG introduces an operating context for one
-or more OpenFlow data paths called an OpenFlow Capable Switch for one or
-more switches. An OpenFlow Capable Switch is intended to be equivalent
-to an actual physical or virtual network element (e.g. an Ethernet
-switch) which is hosting one or more OpenFlow data paths by partitioning
-a set of OpenFlow related resources such as ports and queues among the
-hosted OpenFlow data paths. The OF-CONFIG protocol enables dynamic
-association of the OpenFlow related resources of an OpenFlow Capable
-Switch with specific OpenFlow Logical Switches which are being hosted on
-the OpenFlow Capable Switch. OF-CONFIG does not specify or report how
-the partitioning of resources on an OpenFlow Capable Switch is achieved.
-OF-CONFIG assumes that resources such as ports and queues are
-partitioned amongst multiple OpenFlow Logical Switches such that each
-OpenFlow Logical Switch can assume full control over the resources that
-is assigned to it.
-
-=== How to start ===
-
-- start OF-CONFIG feature as below:
-+
- feature:install odl-of-config-all
-
-=== Compatible with NETCONF ===
-
-- Config OpenFlow Capable Switch via OpenFlow Configuration Points
-+
-Method: POST
-+
-URI: http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules
-+
-Headers: Content-Type" and "Accept" header attributes set to application/xml
-+
-Payload:
-+
-[source, xml]
-----
-<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">prefix:sal-netconf-connector</type>
- <name>testtool</name>
- <address xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">10.74.151.67</address>
- <port xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">830</port>
- <username xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">mininet</username>
- <password xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">mininet</password>
- <tcp-only xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">false</tcp-only>
- <event-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:netty">prefix:netty-event-executor</type>
- <name>global-event-executor</name>
- </event-executor>
- <binding-registry xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">prefix:binding-broker-osgi-registry</type>
- <name>binding-osgi-broker</name>
- </binding-registry>
- <dom-registry xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">prefix:dom-broker-osgi-registry</type>
- <name>dom-broker</name>
- </dom-registry>
- <client-dispatcher xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:config:netconf">prefix:netconf-client-dispatcher</type>
- <name>global-netconf-dispatcher</name>
- </client-dispatcher>
- <processing-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:threadpool">prefix:threadpool</type>
- <name>global-netconf-processing-executor</name>
- </processing-executor>
-</module>
-----
-
-- NETCONF establishes the connections with OpenFlow Capable Switches using
-the parameters in the previous step. NETCONF also gets the
-information of whether the OpenFlow Switch supports NETCONF during the signal handshaking.
-The information will be stored in the NETCONF topology as prosperity of a node.
-
-- OF-CONFIG can be aware of the switches accessing and leaving
-by monitoring the data changes in the NETCONF topology. For the detailed
-information it can be refered to the link:https://git.opendaylight.org/gerrit/gitweb?p=of-config.git;a=blob_plain;f=southbound/southbound-impl/src/main/java/org/opendaylight/ofconfig/southbound/impl/OdlOfconfigApiServiceImpl.java;hb=refs/heads/stable/boron[implementation].
-
-=== The establishment of OF-CONFIG topology ===
-
-Firstly, OF-CONFIG will check whether the newly accessed switch supports
-OF-CONFIG by querying the NETCONF interface.
-
-. During the NETCONF connection's establishment, the NETCONF and the
-switches will exchange the their capabilities via the "hello" message.
-
-. OF-CONFIG gets the connection information between the NETCONF and
-switches by monitoring the data changes via the interface of
-DataChangeListener.
-
-. After the NETCONF connection established, the OF-CONFIG module will
-check whether OF-CONFIG capability is in the switch's capabilities list
-which is got in step 1.
-
-. If the result of step 3 is yes, the OF-CONFIG will call the
-following processing steps to create the topology database.
-
-
-For the detailed information it can be referred to the link:https://git.opendaylight.org/gerrit/gitweb?p=of-config.git;a=blob_plain;f=southbound/southbound-impl/src/main/java/org/opendaylight/ofconfig/southbound/impl/listener/OfconfigListenerHelper.java;hb=refs/heads/stable/boron[implementation].
-
-Secondly, the capable switch node and logical switch node are added in
-the OF-CONFIG topology if the switch supports OF-CONFIG.
-
-OF-CONFIG's topology compromise: Capable Switch topology (underlay) and
-logical Switch topology (overlay). Both of them are enhanced (augment) on
-
-/topo:network-topology/topo:topology/topo:node
-
-The NETCONF will add the nodes in the Topology via the path
-of "/topo:network-topology/topo:topology/topo:node" if it gets the
-configuration information of the switches.
-
-For the detailed information it can be referred to the link:https://git.opendaylight.org/gerrit/gitweb?p=of-config.git;a=blob;f=southbound/southbound-api/src/main/yang/odl-ofconfig-topology.yang;h=dbdaec46ee59da3791386011f571d7434dd1e416;hb=refs/heads/stable/boron[implementation].
-
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/of-config-developer-guide.html
== OpenFlow Protocol Library Developer Guide
-=== Introduction
-OpenFlow Protocol Library is component in OpenDaylight, that mediates communication
-between OpenDaylight controller and hardware devices supporting OpenFlow protocol.
-Primary goal is to provide user (or upper layers of OpenDaylight) communication
-channel, that can be used for managing network hardware devices.
-
-=== Features Overview
-There are three features inside openflowjava:
-
-* *odl-openflowjava-protocol* provides all openflowjava bundles, that are needed
-for communication with openflow devices. It ensures message translation and
-handles network connections. It also provides openflow protocol specific
-model.
-* *odl-openflowjava-all* currently contains only odl-openflowjava-protocol feature.
-* *odl-openflowjava-stats* provides mechanism for message counting and reporting.
-Can be used for performance analysis.
-
-=== odl-openflowjava-protocol Architecture
-Basic bundles contained in this feature are openflow-protocol-api,
-openflow-protocol-impl, openflow-protocol-spi and util.
-
-* *openflow-protocol-api* - contains openflow model, constants and keys used for
-(de)serializer registration.
-* *openflow-protocol-impl* - contains message factories, that translate binary
-messages into DataObjects and vice versa. Bundle also contains network connection
-handlers - servers, netty pipeline handlers, ...
-* *openflow-protocol-spi* - entry point for openflowjava configuration,
-startup and close. Basically starts implementation.
-* *util* - utility classes for binary-Java conversions and to ease experimenter
-key creation
-
-=== odl-openflowjava-stats Feature
-Runs over odl-openflowjava-protocol. It counts various message types / events
-and reports counts in specified time periods. Statistics collection can be
-configured in openflowjava-config/src/main/resources/45-openflowjava-stats.xml
-
-=== Key APIs and Interfaces
-Basic API / SPI classes are ConnectionAdapter (Rpc/notifications) and
-SwitchConnectionProcider (configure, start, shutdown)
-
-//=== API Reference Documentation
-//Provide links to JavaDoc, REST API documentation, etc. [TBD]
-
-=== Installation ===
-Pull the code and import project into your IDE.
-----
-git clone ssh://<username>@git.opendaylight.org:29418/openflowjava.git
-----
-=== Configuration ===
-Current implementation allows to configure:
-
-* listening port (mandatory)
-* transfer protocol (mandatory)
-* switch idle timeout (mandatory)
-* TLS configuration (optional)
-* thread count (optional)
-
-You can find exemplary Openflow Protocol Library instance configuration below:
-----
-<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <!-- default OF-switch-connection-provider (port 6633) -->
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider:impl">prefix:openflow-switch-connection-provider-impl</type>
- <name>openflow-switch-connection-provider-default-impl</name>
- <port>6633</port>
-<!-- Possible transport-protocol options: TCP, TLS, UDP -->
- <transport-protocol>TCP</transport-protocol>
- <switch-idle-timeout>15000</switch-idle-timeout>
-<!-- Exemplary TLS configuration:
- - uncomment the <tls> tag
- - copy exemplary-switch-privkey.pem, exemplary-switch-cert.pem and exemplary-cacert.pem
- files into your virtual machine
- - set VM encryption options to use copied keys
- - start communication
- Please visit OpenflowPlugin or Openflow Protocol Library#Documentation wiki pages
- for detailed information regarding TLS -->
-<!-- <tls>
- <keystore>/exemplary-ctlKeystore</keystore>
- <keystore-type>JKS</keystore-type>
- <keystore-path-type>CLASSPATH</keystore-path-type>
- <keystore-password>opendaylight</keystore-password>
- <truststore>/exemplary-ctlTrustStore</truststore>
- <truststore-type>JKS</truststore-type>
- <truststore-path-type>CLASSPATH</truststore-path-type>
- <truststore-password>opendaylight</truststore-password>
- <certificate-password>opendaylight</certificate-password>
- </tls> -->
-<!-- Exemplary thread model configuration. Uncomment <threads> tag below to adjust default thread model -->
-<!-- <threads>
- <boss-threads>2</boss-threads>
- <worker-threads>8</worker-threads>
- </threads> -->
- </module>
-----
-----
- <!-- default OF-switch-connection-provider (port 6653) -->
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider:impl">prefix:openflow-switch-connection-provider-impl</type>
- <name>openflow-switch-connection-provider-legacy-impl</name>
- <port>6653</port>
-<!-- Possible transport-protocol options: TCP, TLS, UDP -->
- <transport-protocol>TCP</transport-protocol>
- <switch-idle-timeout>15000</switch-idle-timeout>
-<!-- Exemplary TLS configuration:
- - uncomment the <tls> tag
- - copy exemplary-switch-privkey.pem, exemplary-switch-cert.pem and exemplary-cacert.pem
- files into your virtual machine
- - set VM encryption options to use copied keys
- - start communication
- Please visit OpenflowPlugin or Openflow Protocol Library#Documentation wiki pages
- for detailed information regarding TLS -->
-<!-- <tls>
- <keystore>/exemplary-ctlKeystore</keystore>
- <keystore-type>JKS</keystore-type>
- <keystore-path-type>CLASSPATH</keystore-path-type>
- <keystore-password>opendaylight</keystore-password>
- <truststore>/exemplary-ctlTrustStore</truststore>
- <truststore-type>JKS</truststore-type>
- <truststore-path-type>CLASSPATH</truststore-path-type>
- <truststore-password>opendaylight</truststore-password>
- <certificate-password>opendaylight</certificate-password>
- </tls> -->
-<!-- Exemplary thread model configuration. Uncomment <threads> tag below to adjust default thread model -->
-<!-- <threads>
- <boss-threads>2</boss-threads>
- <worker-threads>8</worker-threads>
- </threads> -->
- </module>
-----
-----
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:common:config:impl">prefix:openflow-provider-impl</type>
- <name>openflow-provider-impl</name>
- <openflow-switch-connection-provider>
- <type xmlns:ofSwitch="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider">ofSwitch:openflow-switch-connection-provider</type>
- <name>openflow-switch-connection-provider-default</name>
- </openflow-switch-connection-provider>
- <openflow-switch-connection-provider>
- <type xmlns:ofSwitch="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider">ofSwitch:openflow-switch-connection-provider</type>
- <name>openflow-switch-connection-provider-legacy</name>
- </openflow-switch-connection-provider>
- <binding-aware-broker>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-broker-osgi-registry</type>
- <name>binding-osgi-broker</name>
- </binding-aware-broker>
- </module>
- </modules>
-----
-Possible transport-protocol options:
-
-* TCP
-* TLS
-* UDP
-
-Switch-idle timeout specifies time needed to detect idle state of switch. When
-no message is received from switch within this time, upper layers are notified
-on switch idleness.
-To be able to use this exemplary TLS configuration:
-
-* uncomment the +<tls>+ tag
-* copy _exemplary-switch-privkey.pem_, _exemplary-switch-cert.pem_ and
-_exemplary-cacert.pem_ files into your virtual machine
-* set VM encryption options to use copied keys (please visit TLS support wiki page
-for detailed information regarding TLS)
-* start communication
-
-Thread model configuration specifies how many threads are desired to perform
-Netty's I/O operations.
-
-* boss-threads specifies the number of threads that register incoming connections
-* worker-threads specifies the number of threads performing read / write
-(+ serialization / deserialization) operations.
-
-
-=== Architecture
-
-==== Public API +(openflow-protocol-api)+
-Set of interfaces and builders for immutable data transfer objects representing
-Openflow Protocol structures.
-
-Transfer objects and service APIs are infered from several YANG models
-using code generator to reduce verbosity of definition and repeatibility of code.
-
-The following YANG modules are defined:
-
-* openflow-types - defines common Openflow specific types
-* openflow-instruction - defines base Openflow instructions
-* openflow-action - defines base Openflow actions
-* openflow-augments - defines object augmentations
-* openflow-extensible-match - defines Openflow OXM match
-* openflow-protocol - defines Openflow Protocol messages
-* system-notifications - defines system notification objects
-* openflow-configuration - defines structures used in ConfigSubsystem
-
-This modules also reuse types from following YANG modules:
-
-* ietf-inet-types - IP adresses, IP prefixes, IP-protocol related types
-* ietf-yang-types - Mac Address, etc.
-
-The use of predefined types is to make APIs contracts more safe, better readable
-and documented (e.g using MacAddress instead of byte array...)
-
-==== TCP Channel pipeline +(openflow-protocol-impl)+
-
-Creates channel processing pipeline based on configuration and support.
-
-.TCP Channel pipeline
-imageopenflowjava/500px-TCPChannelPipeline.png[width=500]
-
-.Switch Connection Provider
-Implementation of connection point for other projects. Library exposes its
-functionality through this class.
-Library can be configured, started and shutdowned here. There are also methods
-for custom (de)serializer registration.
-
-.Tcp Connection Initializer
-In order to initialize TCP connection to a device (switch), OF Plugin calls method
-+initiateConnection()+ in +SwitchConnectionProvider+. This method in turn initializes
-(Bootstrap) server side channel towards the device.
-
-.TCP Handler
-Represents single server that is handling incoming connections over TCP / TLS protocol.
-TCP Handler creates a single instance of TCP Channel Initializer that will initialize
-channels. After that it binds to configured InetAddress and port. When a new
-device connects, TCP Handler registers its channel and passes control to
-TCP Channel Initializer.
-
-.TCP Channel Initializer
-This class is used for channel initialization / rejection and passing arguments.
-After a new channel has been registered it calls Switch Connection Handler's
-(OF Plugin) accept method to decide if the library should keep the newly registered
-channel or if the channel should be closed. If the channel has been accepted,
-TCP Channel Initializer creates the whole pipeline with needed handlers and also
-with ConnectionAdapter instance. After the channel pipeline is ready, Switch
-Connection Handler is notified with +onConnectionReady+ notification.
-OpenFlow Plugin can now start sending messages downstream.
-
-.Idle Handler
-If there are no messages received for more than time specified, this handler
-triggers idle state notification.
-The switch idle timeout is received as a parameter from ConnectionConfiguration
-settings. Idle State Handler is inactive while there are messages received within
-the switch idle timeout. If there are no messages received for more than timeout
-specified, handler creates SwitchIdleEvent message and sends it upstream.
-
-.TLS Handler
-It encrypts and decrypts messages over TLS protocol.
-Engaging TLS Handler into pipeline is matter of configuration (+<tls>+ tag).
-TLS communication is either unsupported or required. TLS Handler is represented
-as a Netty's SslHandler.
-
-.OF Frame Decoder
-Parses input stream into correct length message frames for further processing.
-Framing is based on Openflow header length. If received message is shorter than
-minimal length of OpenFlow message (8 bytes), OF Frame Decoder waits for more data.
-After receiving at least 8 bytes the decoder checks length in OpenFlow header.
-If there are still some bytes missing, the decoder waits for them. Else the OF
-Frame Decoder sends correct length message to next handler in the channel pipeline.
-
-.OF Version Detector
-Detects version of used OpenFlow Protocol and discards unsupported version messages.
-If the detected version is supported, OF Version Detector creates
-+VersionMessageWrapper+ object containing the detected version and byte message
-and sends this object upstream.
-
-.OF Decoder
-Chooses correct deserilization factory (based on message type) and deserializes
-messages into generated DTOs (Data Transfer Object).
-OF Decoder receives +VersionMessageWrapper+ object and passes it to
-+DeserializationFactory+ which will return translated DTO. +DeserializationFactory+
-creates +MessageCodeKey+ object with version and type of received message and
-Class of object that will be the received message deserialized into. This object
-is used as key when searching for appropriate decoder in +DecoderTable+.
-+DecoderTable+ is basically a map storing decoders. Found decoder translates
-received message into DTO. If there was no decoder found, null is returned. After
-returning translated DTO back to OF Decoder, the decoder checks if it is null or not.
-When the DTO is null, the decoder logs this state and throws an Exception. Else it
-passes the DTO further upstream. Finally, the OF Decoder releases ByteBuf containing
-received and decoded byte message.
-
-.OF Encoder
-Chooses correct serialization factory (based on type of DTO) and serializes DTOs
-into byte messages.
-OF Encoder does the opposite than the OF Decoder using the same principle.
-OF Encoder receives DTO, passes it for translation and if the result is not null,
-it sends translated DTO downstream as a ByteBuf. Searching for appropriate encoder
-is done via MessageTypeKey, based on version and class of received DTO.
-
-.Delegating Inbound Handler
-Delegates received DTOs to Connection Adapter.
-It also reacts on channelInactive and channelUnregistered events. Upon one of
-these events is triggered, DelegatingInboundHandler creates DisconnectEvent message
-and sends it upstream, notifying upper layers about switch disconnection.
-
-.Channel Outbound Queue
-Message flushing handler.
-Stores outgoing messages (DTOs) and flushes them. Flush is performed based on time
-expired and on the number of messages enqueued.
-
-.Connection Adapter
-Provides a facade on top of pipeline, which hides netty.io specifics. Provides a
-set of methods to register for incoming messages and to send messages to particular
-channel / session.
-ConnectionAdapterImpl basically implements three interfaces (unified in one
-superinterface ConnectionFacade):
-
-* ConnectionAdapter
-* MessageConsumer
-* OpenflowProtocolService
-
-
-*ConnectionAdapter* interface has methods for setting up listeners (message,
-system and connection ready listener), method to check if all listeners are set,
-checking if the channel is alive and disconnect method. Disconnect method clears
-responseCache and disables consuming of new messages.
-
-*MessageConsumer* interface holds only one method: +consume()+. +Consume()+ method
-is called from DelegatingInboundHandler. This method processes received DTO's based
-on their type. There are three types of received objects:
-
-* System notifications - invoke system notifications in OpenFlow Plugin
-(systemListener set). In case of +DisconnectEvent+ message, the Connection Adapter
-clears response cache and disables consume() method processing,
-* OpenFlow asynchronous messages (from switch) - invoke corresponding notifications
-in OpenFlow Plugin,
-* OpenFlow symmetric messages (replies to requests) - create +RpcResponseKey+
-with XID and DTO's class set. This +RpcResponseKey+ is then used to find
-corresponding future object in responseCache. Future object is set with success
-flag, received message and errors (if any occurred). In case no corresponding
-future was found in responseCache, Connection Adapter logs warning and discards
-the message. Connection Adapter also logs warning when an unknown DTO is received.
-
-*OpenflowProtocolService* interface contains all rpc-methods for sending messages
-from upper layers (OpenFlow Plugin) downstream and responding. Request messages
-return Future filled with expected reply message, otherwise the expected Future
-is of type Void.
-
-*NOTE:*
-MultipartRequest message is the only exception. Basically it is request - reply
-Message type, but it wouldn't be able to process more following MultipartReply
-messages if this was implemented as rpc (only one Future). This is why MultipartReply
-is implemented as notification. OpenFlow Plugin takes care of correct message
-processing.
-
-
-==== UDP Channel pipeline (openflow-protocol-impl)
-Creates UDP channel processing pipeline based on configuration and support.
-*Switch Connection Provider*, *Channel Outbound Queue* and *Connection Adapter*
-fulfill the same role as in case of TCP connection / channel pipeline (please
-see above).
-
-.UDP Channel pipeline
-image::openflowjava/500px-UdpChannelPipeline.png[width=500]
-
-.UDP Handler
-
-Represents single server that is handling incoming connections over UDP (DTLS)
-protocol.
-UDP Handler creates a single instance of UDP Channel Initializer that will
-initialize channels. After that it binds to configured InetAddress and port.
-When a new device connects, UDP Handler registers its channel and passes control
-to UDP Channel Initializer.
-
-.UDP Channel Initializer
-This class is used for channel initialization and passing arguments.
-After a new channel has been registered (for UDP there is always only one channel)
-UDP Channel Initializer creates whole pipeline with needed handlers.
-
-.DTLS Handler
-Haven't been implemented yet. Will take care of secure DTLS connections.
-
-.OF Datagram Packet Handler
-Combines functionality of OF Frame Decoder and OF Version Detector. Extracts
-messages from received datagram packets and checks if message version is supported.
-If there is a message received from yet unknown sender, OF Datagram Packet Handler
-creates Connection Adapter for this sender and stores it under sender's address in
-+UdpConnectionMap+. This map is also used for sending the messages and for correct
-Connection Adapter lookup - to delegate messages from one channel to multiple sessions.
-
-.OF Datagram Packet Decoder
-Chooses correct deserilization factory (based on message type) and deserializes
-messages into generated DTOs.
-OF Decoder receives +VersionMessageUdpWrapper+ object and passes it to
-+DeserializationFactory+ which will return translated DTO. +DeserializationFactory+
-creates +MessageCodeKey+ object with version and type of received message and
-Class of object that will be the received message deserialized into. This object
-is used as key when searching for appropriate decoder in +DecoderTable+.
-+DecoderTable+ is basically a map storing decoders. Found decoder translates
-received message into DTO (DataTransferObject). If there was no decoder found,
-null is returned. After returning translated DTO back to OF Datagram Packet Decoder,
-the decoder checks if it is null or not. When the DTO is null, the decoder logs
-this state. Else it looks up appropriate Connection Adapter in +UdpConnectionMap+
-and passes the DTO to found Connection Adapter. Finally, the OF Decoder releases
-+ByteBuf+ containing received and decoded byte message.
-
-.OF Datagram Packet Encoder
-Chooses correct serialization factory (based on type of DTO) and serializes DTOs
-into byte messages.
-OF Datagram Packet Encoder does the opposite than the OF Datagram Packet Decoder
-using the same principle. OF Encoder receives DTO, passes it for translation and
-if the result is not null, it sends translated DTO downstream as a datagram packet.
-Searching for appropriate encoder is done via MessageTypeKey, based on version
-and class of received DTO.
-
-==== SPI (openflow-protocol-spi)
-Defines interface for library's connection point for other projects. Library
-exposes its functionality through this interface.
-
-==== Integration test (openflow-protocol-it)
-Testing communication with simple client.
-
-==== Simple client(simple-client)
-Lightweight switch simulator - programmable with desired scenarios.
-
-==== Utility (util)
-Contains utility classes, mainly for work with ByteBuf.
-
-
-=== Library's lifecycle
-
-Steps (after the library's bundle is started):
-
-* [1] Library is configured by ConfigSubsystem (adress, ports, encryption, ...)
-* [2] Plugin injects its SwitchConnectionHandler into the Library
-* [3] Plugin starts the Library
-* [4] Library creates configured protocol handler (e.g. TCP Handler)
-* [5] Protocol Handler creates Channel Initializer
-* [6] Channel Initializer asks plugin whether to accept incoming connection on
-each new switch connection
-* [7] Plugin responds:
- - true - continue building pipeline
- - false - reject connection / disconnect channel
-* [8] Library notifies Plugin with onSwitchConnected(ConnectionAdapter)
-notification, passing reference to ConnectionAdapter, that will handle the connection
-* [9] Plugin registers its system and message listeners
-* [10] FireConnectionReadyNotification() is triggered, announcing that pipeline
-handlers needed for communication have been created and Plugin can start
-communication
-* [11] Plugin shutdowns the Library when desired
-
-.Library lifecycle
-image::openflowjava/Library_lifecycle.png[width=500]
-
-
-=== Statistics collection
-
-==== Introduction
-Statistics collection collects message statistics.
-Current collected statistics (+DS+ - downstream, +US+ - upstream):
-
-* +DS_ENTERED_OFJAVA+ - all messages that entered openflowjava (picked up from
-openflowplugin)
-* +DS_ENCODE_SUCCESS+ - successfully encoded messages
-* +DS_ENCODE_FAIL+ - messages that failed during encoding (serialization) process
-* +DS_FLOW_MODS_ENTERED+ - all flow-mod messages that entered openflowjava
-* +DS_FLOW_MODS_SENT+ - all flow-mod messages that were successfully sent
-* +US_RECEIVED_IN_OFJAVA+ - messages received from switch
-* +US_DECODE_SUCCESS+ - successfully decoded messages
-* +US_DECODE_FAIL+ - messages that failed during decoding (deserialization) process
-* +US_MESSAGE_PASS+ - messages handed over to openflowplugin
-
-==== Karaf
-In orded to start statistics, it is needed to feature:install odl-openflowjava-stats.
-To see the logs one should use log:set DEBUG org.opendaylight.openflowjava.statistics
-and than probably log:display (you can log:list to see if the logging has been set).
-To adjust collection settings it is enough to modify 45-openflowjava-stats.xml.
-
-==== JConsole
-JConsole provides two commands for the statistics collection:
-
-* printing current statistics
-* resetting statistic counters
-
-After attaching JConsole to correct process, one only needs to go into MBeans
-+tab -> org.opendaylight.controller -> RuntimeBean -> statistics-collection-service-impl
--> statistics-collection-service-impl -> Operations+ to be able to use this commands.
-
-=== TLS Support
-NOTE: see OpenFlow Plugin Developper Guide
-
-=== Extensibility
-
-==== Introduction
-
-Entry point for the extensibility is +SwitchConnectionProvider+.
-+SwitchConnectionProvider+ contains methods for (de)serializer registration.
-To register deserializer it is needed to use .register*Deserializer(key, impl).
-To register serializer one must use .register*Serializer(key, impl). Registration
-can occur either during configuration or at runtime.
-
-*NOTE*: In case when experimenter message is received and no (de)serializer was
-registered, the library will throw +IllegalArgumentException+.
-
-==== Basic Principle
-In order to use extensions it is needed to augment existing model and register new (de)serializers.
-
-Augmenting the model:
-1. Create new augmentation
-
-Register (de)serializers:
-1. Create your (de)serializer
-2. Let it implement +OFDeserializer<>+ / +OFSerializer<>+
-- in case the structure you are (de)serializing needs to be used in Multipart
-TableFeatures messages, let it implement +HeaderDeserializer<>+ / +HeaderSerializer+
-3. Implement prescribed methods
-4. Register your deserializer under appropriate key (in our case
-+ExperimenterActionDeserializerKey+)
-5. Register your serializer under appropriate key (in our case
-+ExperimenterActionSerializerKey+)
-6. Done, test your implementation
-
-*NOTE*: If you don't know what key should be used with your (de)serializer
-implementation, please visit <<registration_keys, Registration keys>> page.
-
-==== Example
-Let's say we have vendor / experimenter action represented by this structure:
-----
-struct foo_action {
- uint16_t type;
- uint16_t length;
- uint32_t experimenter;
- uint16_t first;
- uint16_t second;
- uint8_t pad[4];
-}
-----
-First, we have to augment existing model. We create new module, which imports
-"+openflow-types.yang+" (don't forget to update your +pom.xml+ with api dependency).
-Now we create foo action identity:
-----
-import openflow-types {prefix oft;}
-identity foo {
- description "Foo action description";
- base oft:action-base;
-}
-----
-
-This will be used as type in our structure. Now we must augment existing action
-structure, so that we will have the desired fields first and second. In order to
-create new augmentation, our module has to import "+openflow-action.yang+". The
-augment should look like this:
-----
-import openflow-action {prefix ofaction;}
-augment "/ofaction:actions-container/ofaction:action" {
- ext:augment-identifier "foo-action";
- leaf first {
- type uint16;
- }
- leaf second {
- type uint16;
- }
- }
-----
-We are finished with model changes. Run mvn clean compile to generate sources.
-After generation is done, we need to implement our (de)serializer.
-
-Deserializer:
-----
-public class FooActionDeserializer extends OFDeserializer<Action> {
- @Override
- public Action deserialize(ByteBuf input) {
- ActionBuilder builder = new ActionBuilder();
- input.skipBytes(SIZE_OF_SHORT_IN_BYTES); *// we know the type of action*
- builder.setType(Foo.class);
- input.skipBytes(SIZE_OF_SHORT_IN_BYTES); *// we don't need length*
- *// now create experimenterIdAugmentation - so that openflowplugin can
- differentiate correct vendor codec*
- ExperimenterIdActionBuilder expIdBuilder = new ExperimenterIdActionBuilder();
- expIdBuilder.setExperimenter(new ExperimenterId(input.readUnsignedInt()));
- builder.addAugmentation(ExperimenterIdAction.class, expIdBuilder.build());
- FooActionBuilder fooBuilder = new FooActionBuilder();
- fooBuilder.setFirst(input.readUnsignedShort());
- fooBuilder.setSecond(input.readUnsignedShort());
- builder.addAugmentation(FooAction.class, fooBuilder.build());
- input.skipBytes(4); *// padding*
- return builder.build();
- }
-}
-----
-Serializer:
-----
-public class FooActionSerializer extends OFSerializer<Action> {
- @Override
- public void serialize(Action action, ByteBuf outBuffer) {
- outBuffer.writeShort(FOO_CODE);
- outBuffer.writeShort(16);
- *// we don't have to check for ExperimenterIdAction augmentation - our
- serializer*
- *// was called based on the vendor / experimenter ID, so we simply write
- it to buffer*
- outBuffer.writeInt(VENDOR / EXPERIMENTER ID);
- FooAction foo = action.getAugmentation(FooAction.class);
- outBuffer.writeShort(foo.getFirst());
- outBuffer.writeShort(foo.getSecond());
- outBuffer.writeZero(4); //write padding
- }
-}
-----
-Register both deserializer and serializer:
-+SwitchConnectionProvider.registerDeserializer(new
-ExperimenterActionDeserializerKey(0x04, VENDOR / EXPERIMENTER ID),
-new FooActionDeserializer());+
-+SwitchConnectionProvider.registerSerializer(new
-ExperimenterActionSerializerKey(0x04, VENDOR / EXPERIMENTER ID),
-new FooActionSerializer());+
-
-We are ready to test our implementation.
-
-*NOTE:* Vendor / Experimenter structures define only vendor / experimenter ID as
-common distinguisher (besides action type). Vendor / Experimenter ID is unique
-for all vendor messages - that's why vendor is able to register only one class
-under ExperimenterAction(De)SerializerKey. And that's why vendor has to switch
-/ choose between his subclasses / subtypes on his own.
-
-==== Detailed walkthrough: Deserialization extensibility
-
-.External interface & class description
-*OFGeneralDeserializer:*
-
-* +OFDeserializer<E extends DataObject>+
-** _deserialize(ByteBuf)_ - deserializes given ByteBuf
-* +HeaderDeserializer<E extends DataObject>+
-** _deserializeHeaders(ByteBuf)_ - deserializes only E headers (used in Multipart
-TableFeatures messages)
-
-*DeserializerRegistryInjector*
-
-* +injectDeserializerRegistry(DeserializerRegistry)+ - injects deserializer
-registry into deserializer. Useful when custom deserializer needs access to
-other deserializers.
-
-*NOTE:* DeserializerRegistryInjector is not OFGeneralDeserializer descendand.
-It is a standalone interface.
-
-*MessageCodeKey and its descendants*
-These keys are used as for deserializer lookup in DeserializerRegistry.
-MessageCodeKey should is used in general, while its descendants are used in more
-special cases. For Example ActionDeserializerKey is used for Action deserializer
-lookup and (de)registration. Vendor is provided with special keys, which contain
-only the most necessary fields. These keys usually start with "Experimenter"
-prefix (MatchEntryDeserializerKey is an exception).
-
-MessageCodeKey has these fields:
-
-* short version - Openflow wire version number
-* int value - value read from byte message
-* Class<?> clazz - class of object being creating
-
-.Scenario walkthrough
-* [1] The scenario starts in a custom bundle which wants to extend library's
-functionality. The custom bundle creates deserializers which implement exposed
-+OFDeserializer+ / +HeaderDeserializer+ interfaces (wrapped under
-+OFGeneralDeserializer+ unifying super interface).
-* [2] Created deserializers are paired with corresponding ExperimenterKeys,
-which are used for deserializer lookup.
-If you don't know what key should be used with your (de)serializer implementation,
-please visit <<registration_keys, Registration keys>> page.
-* [3] Paired deserializers are passed to the OF Library
-via *SwitchConnectionProvider*._registerCustomDeserializer(key, impl)_.
-Library registers the deserializer.
-** While registering, Library checks if the deserializer is an instance of
-*DeserializerRegistryInjector* interface. If yes, the DeserializerRegistry
-(which stores all deserializer references) is injected into the deserializer.
-
-This is particularly useful when the deserializer needs access to other
-deserializers. For example +IntructionsDeserializer+ needs access to
-+ActionsDeserializer+ in order to be able to process
-OFPIT_WRITE_ACTIONS/OFPIT_APPLY_ACTIONS instructions.
-
-.Deserialization scenario walkthrough
-image::openflowjava/800px-Extensibility.png[width=500]
-
-==== Detailed walkthrough: Serialization extensibility
-.External interface & class description
-
-*OFGeneralSerializer:*
-
-* OFSerializer<E extends DataObject>
-** _serialize(E,ByteBuf)_ - serializes E into given ByteBuf
-* +HeaderSerializer<E extends DataObject>+
-** _serializeHeaders(E,ByteBuf)_ - serializes E headers (used in Multipart
-TableFeatures messages)
-
-*SerializerRegistryInjector*
-* +injectSerializerRegistry(SerializerRegistry)+ - injects serializer registry
-into serializer. Useful when custom serializer needs access to other serializers.
-
-*NOTE:* SerializerRegistryInjector is not OFGeneralSerializer descendand.
-
-*MessageTypeKey and its descendants*
-These keys are used as for serializer lookup in SerializerRegistry.
-MessageTypeKey should is used in general, while its descendants are used in more
-special cases. For Example ActionSerializerKey is used for Action serializer
-lookup and (de)registration. Vendor is provided with special keys, which contain
-only the most necessary fields. These keys usually start with "Experimenter"
-prefix (MatchEntrySerializerKey is an exception).
-
-MessageTypeKey has these fields:
-
-* _short version_ - Openflow wire version number
-* _Class<E> msgType_ - DTO class
-
-Scenario walkthrough
-
-* [1] Serialization extensbility principles are similar to the deserialization
-principles. The scenario starts in a custom bundle. The custom bundle creates
-serializers which implement exposed OFSerializer / HeaderSerializer interfaces
-(wrapped under OFGeneralSerializer unifying super interface).
-* [2] Created serializers are paired with their ExperimenterKeys, which are used
-for serializer lookup.
-If you don't know what key should be used with your serializer implementation,
-please visit <<registration_keys, Registration keys>> page.
-* [3] Paired serializers are passed to the OF Library via
-*SwitchConnectionProvider*._registerCustomSerializer(key, impl)_. Library
-registers the serializer.
-* While registering, Library checks if the serializer is an instance of
-*SerializerRegistryInjector* interface. If yes, the SerializerRegistry (which
-stores all serializer references) is injected into the serializer.
-
-This is particularly useful when the serializer needs access to other deserializers.
-For example IntructionsSerializer needs access to ActionsSerializer in order to
-be able to process OFPIT_WRITE_ACTIONS/OFPIT_APPLY_ACTIONS instructions.
-
-.Serialization scenario walkthrough
-image::openflowjava/800px-Extensibility2.png[width=500]
-
-==== Internal description
-
-*SwitchConnectionProvider*
-+SwitchConnectionProvider+ constructs and initializes both deserializer and
-serializer registries with default (de)serializers. It also injects the
-+DeserializerRegistry+ into the +DeserializationFactory+, the +SerializerRegistry+
-into the +SerializationFactory+.
-When call to register custom (de)serializer is made, +SwitchConnectionProvider+
-calls register method on appropriate registry.
-
-*DeserializerRegistry / SerializerRegistry*
-Both registries contain init() method to initialize default (de)serializers.
-Registration checks if key or (de)serializer implementation are not +null+. If at
-least one of the is +null+, +NullPointerException+ is thrown. Else the
-(de)serializer implementation is checked if it is +(De)SerializerRegistryInjector+
-instance. If it is an instance of this interface, the registry is injected into
-this (de)serializer implementation.
-
-+GetSerializer(key)+ or +GetDeserializer(key)+ performs registry lookup. Because
-there are two separate interfaces that might be put into the registry, the
-registry uses their unifying super interface. Get(De)Serializer(key) method casts
-the super interface to desired type. There is also a null check for the
-(de)serializer received from the registry. If the deserializer wasn't found,
-+NullPointerException+ with key description is thrown.
-
-
-[[registration_keys]]
-==== Registration keys
-
-.Deserialization
-
-*Possible openflow extensions and their keys*
-
-There are three vendor specific extensions in Openflow v1.0 and eight in
-Openflow v1.3. These extensions are registered under registration keys,
-that are shown in table below:
-
-.*Deserialization*
-[options="header",cols="20%,10%,40%,30%"]
-|========================================================================================================================================================
-|Extension type |OpenFlow|Registration key |Utility class
-|Vendor message |1.0 |ExperimenterIdDeserializerKey(1, experimenterId, ExperimenterMessage.class) |ExperimenterDeserializerKeyFactory
-|Action |1.0 |ExperimenterActionDeserializerKey(1, experimenter ID) |.
-|Stats message |1.0 |ExperimenterMultipartReplyMessageDeserializerKey(1, experimenter ID) |ExperimenterDeserializerKeyFactory
-|Experimenter message |1.3 |ExperimenterIdDeserializerKey(4, experimenterId, ExperimenterMessage.class) |ExperimenterDeserializerKeyFactory
-|Match entry |1.3 |MatchEntryDeserializerKey(4, (number) ${oxm_Class}, (number) ${oxm_Field}); |.
-| | |key.setExperimenterId(experimenter ID); |.
-|Action |1.3 |ExperimenterActionDeserializerKey(4, experimenter ID) |.
-|Instruction |1.3 |ExperimenterInstructionDeserializerKey(4, experimenter ID) |.
-|Multipart |1.3 |ExperimenterIdDeserializerKey(4, experimenterId, MultipartReplyMessage.class) |ExperimenterDeserializerKeyFactory
-|Multipart - Table features|1.3 |ExperimenterIdDeserializerKey(4, experimenterId, TableFeatureProperties.class) |ExperimenterDeserializerKeyFactory
-|Error |1.3 |ExperimenterIdDeserializerKey(4, experimenterId, ErrorMessage.class) |ExperimenterDeserializerKeyFactory
-|Queue property |1.3 |ExperimenterIdDeserializerKey(4, experimenterId, QueueProperty.class) |ExperimenterDeserializerKeyFactory
-|Meter band type |1.3 |ExperimenterIdDeserializerKey(4, experimenterId, MeterBandExperimenterCase.class)|ExperimenterDeserializerKeyFactory
-|========================================================================================================================================================
-
-.Serialization
-
-*Possible openflow extensions and their keys*
-
-There are three vendor specific extensions in Openflow v1.0 and seven Openflow
-v1.3. These extensions are registered under registration keys, that are shown in
-table below:
-
-
-.*Serialization*
-[options="header",cols="20%,10%,40%,30%"]
-|=============================================================================================================================================================
-|Extension type |OpenFlow|Registration key |Utility class
-|Vendor message |1.0 |ExperimenterIdSerializerKey<>(1, experimenterId, ExperimenterInput.class) |ExperimenterSerializerKeyFactory
-|Action |1.0 |ExperimenterActionSerializerKey(1, experimenterId, sub-type) |.
-|Stats message |1.0 |ExperimenterMultipartRequestSerializerKey(1, experimenter ID) |ExperimenterSerializerKeyFactory
-|Experimenter message |1.3 |ExperimenterIdSerializerKey<>(4, experimenterId, ExperimenterInput.class) |ExperimenterSerializerKeyFactory
-|Match entry |1.3 |MatchEntrySerializerKey<>(4, (class) ${oxm_Class}, (class) ${oxm_Field}); |.
-| | |key.setExperimenterId(experimenter ID) |.
-|Action |1.3 |ExperimenterActionSerializerKey(4, experimenterId, sub-type) |.
-|Instruction |1.3 |ExperimenterInstructionSerializerKey(4, experimenter ID) |.
-|Multipart |1.3 |ExperimenterIdSerializerKey<>(4, experimenterId, MultipartRequestExperimenterCase.class)|ExperimenterSerializerKeyFactory
-|Multipart - Table features|1.3 |ExperimenterIdSerializerKey<>(4, experimenterId, TableFeatureProperties.class) |ExperimenterSerializerKeyFactory
-|Meter band type |1.3 |ExperimenterIdSerializerKey<>(4, experimenterId, MeterBandExperimenterCase.class) |ExperimenterSerializerKeyFactory
-|=============================================================================================================================================================
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/openflow-protocol-library-developer-guide.html
== OpFlex agent-ovs Developer Guide
-=== Overview
-agent-ovs is a policy agent that works with OVS to enforce a
-group-based policy networking model with locally attached virtual
-machines or containers. The policy agent is designed to work well with
-orchestration tools like OpenStack.
-
-=== agent-ovs Architecture
-agent-ovs uses libopflex to communicate with an OpFlex-based policy
-repository to enforce policy on network endpoints attached to OVS by
-an orchestration system.
-
-The key components are:
-
-* Agent - coordinates startup and configuration
-* Renderers - Renderers are responsible for rendering policy. This is
- a very general mechanism but the currently-implemented renderer is
- the stitched-mode renderer that can work along with with hardware
- fabrics such as ACI that support policy enforcement.
-* EndpointManager - Keep track of network endpoints and declare them
- to the endpoint repository
-* PolicyManager - Keep track of and index policies
-* FlowManager - render policies to OVS
-
-=== API Reference Documentation
-Internal API documentation can be found here:
-https://jenkins.opendaylight.org/opflex/job/opflex-merge/ws/agent-ovs/doc/html/index.html
\ No newline at end of file
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/opflex-agent-ovs-developer-guide.html
== OpFlex genie Developer Guide
-=== Overview
-Genie is a tool for code generation from a model. It supports
-generating C\++ and Java code. C++ can be generated suitable for use
-with libopflex. C++ and Java can be generated as a plain set of
-objects.
-
-=== Group-based Policy Model
-The group-based policy model is included with the genie tool and can
-be found under the MODEL directory. By running mvn exec:java,
-libmodelgbp will be generated as a library project that, when built
-and installed, will work with libopflex. This model is used by the
-OVS agent.
-
-=== API Reference Documentation
-Complete API documentation for the generated libmodelgbp can be found here:
-https://jenkins.opendaylight.org/opflex/job/opflex-merge/ws/libopflex/doc/html/index.html
\ No newline at end of file
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/opflex-genie-developer-guide.html
== OpFlex libopflex Developer Guide
-=== Overview
-The OpFlex framework allows you to develop agents that can communicate
-using the OpFlex protocol and act as a policy element in an
-OpFlex-based distributed control system. The OpFlex architecture
-provides a distributed control system based on a declarative policy
-information model. The policies are defined at a logically centralized
-policy repository and enforced within a set of distributed policy
-elements. The policy repository communicates with the subordinate
-policy elements using the OpFlex control protocol. This protocol
-allows for bidirectional communication of policy, events, statistics,
-and faults.
-
-Rather than simply providing access to the OpFlex protocol, this
-framework allows you to directly manipulate a management information
-tree containing a hierarchy of managed objects. This tree is kept in
-sync as needed with other policy elements in the system, and you are
-automatically notified when important changes to the model
-occur. Additionally, we can ensure that only those managed objects
-that are important to the local policy element are synchronized
-locally.
-
-==== Object Model
-
-Interactions with the OpFlex framework happen through the management
-information tree. This is a tree of managed objects defined by an
-object model specific to your application. There are a few important
-major category of objects that can appear in the model.
-
-* First, there is the policy object. A policy object represents some
- data related to a policy that describes a user intent for how the
- system should behave. A policy object is stored in the policy
- repository which is the source of "truth" for this object.
-* Second, there is an endpoint object. A endpoint represents an entity
- in the system to which we want to apply policy, which could be a
- network interface, a storage array, or other relevent policy
- endpoint. Endpoints are discovered and reported by policy elements
- locally, and are synchronized into the endpoint repository. The
- originating policy element is the source of truth for the endpoints
- it discovers. Policy elements can retrieve information about
- endpoints discovered by other policy elements by resolving endpoints
- from the endpoint repository.
-* Third, there is the observable object. An observable object
- represents some state related to the operational status or health of
- the policy element. Observable objects will be reported to the
- observer.
-* Finally, there is the local-only object. This is the simplest object
- because it exists only local to a particular policy element. These
- objects can be used to store state specific to that policy element,
- or as helpers to resolve other objects. Read on to learn more.
-
-You can use the genie tool that is included with the framework to
-produce your application model along with a set of generated accessor
-classes that can work with this framework library. You should refer to
-the documentation that accompanies the genie tool for information on
-how to use to to generate your object model. Later in this guide,
-we'll go through examples of how to use the generated managed object
-accessor classes.
-
-==== Programming by Side Effect
-
-When developing software on the OpFlex framework, you'll need to think
-in a slightly different way. Rather than calling an API function that
-would perform some specific action, you'll need to write a managed
-object to the managed object database. Writing that object to the
-store will trigger the side effect of performing the action that you
-want.
-
-For example, a policy element will need to have a component
-responsible for discovering policy endpoints. When it discovers a
-policy endpoint, it would write an endpoint object into the managed
-object database. That endpoint object will contain a reference to
-policy that is relevant to the endpoint object. This will trigger a
-whole cascade of events. First, the framework will notice that an
-endpoint object has been created and it will write it to the endpoint
-repository. Second, the framework to will attempt to resolve the
-unresolved reference to the relevent policy object. There might be a
-whole chain of policy resolutions that will be automatically performed
-to download all the relevent policy until there are no longer any
-dangling references.
-
-As long as there is a locally-created object in the system with a
-reference to that policy, the framework will continually ensure that
-the policy and any transitive policies are kept up to date. The policy
-element can subscribe to updates to these policy classes that will be
-invoked either the first time the policy is resolved or any time the
-policy changes.
-
-A consequence of this design is that the managed object database can
-be temporarily in an inconsistent state with unresolved dangling
-references. Eventually, however, the inconsistency will be fully
-resolved. The policy element must be able to cleanly handle
-partially-resolved or inconsistent state and eventually reach the
-correct state as it receives these update notifications. Note that, in
-the OpFlex architecture, when there is no policy that specifically
-allows a particular action, that action must be prevented.
-
-Let's cover one slightly more complex example. If a policy element
-needs to discover information about an endpoint that is not local to
-that policy element, it will need to retrieve that information from
-the endpoint repository. However, just as there is no API call to
-retrieve a policy object from the policy repository, there is no API
-call to retrieve an endpoint from the endpoint repository.
-
-To get this information, the policy element needs to create a
-local-only object that references the endpoint. Once it creates this
-local-only object, if the endpoint is not already resolved, the
-framework will notice the dangling reference and automatically resolve
-the endpoint from the endpoint respository. When the endpoint
-resolution completes, the framework deliver an update notification to
-the policy element. The policy element will continue to receive any
-updates related to that endpoint until the policy element remove the
-local-only reference to the object. Once this occurs, the framework
-can garbage-collect any unreferenced objects.
-
-==== Threading and Ownership
-The OpFlex framework uses a somewhat unique threading model. Each
-managed object in the system belongs to a particular owner. An owner
-would typically be a single thread that is reponsible for all updates
-to objects with that owner. Though anything can read the state of a
-managed object, only the owner of a managed object is permitted to
-write to it. Though this is not strictly required for correctness, the
-performance of the system wil be best if you ensure that only one
-thread at a time is writing to objects with a particular owner.
-
-Change notifications are delivered in a serialized fashion by a single
-thread. Blocking this thread from a notification callback will stall
-delivery of all notifications. It is therefore best practice to ensure
-that you do not block or perform long-running operations from a
-notification callback.
-
-=== Key APIs and Interfaces
-==== Basic Usage and Initialization
-The primary interface point into the framework is
-opflex::ofcore::OFFramework. You can choose to instantiate your own
-copy of the framework, or you can use the static default instance.
-
-Before you can use the framework, you must initialize it by installing
-your model metadata. The model metadata is accessible through the
-generated model library. In this case, it assumes your model is called
-"mymodel":
-
-[source,cpp]
-----
-#include <opflex/ofcore/OFFramework.h>
-#include <mymodel/metadata/metadata.hpp>
-// ...
-using opflex::ofcore::OFFramework;
-OFFramework::defaultInstance().setModel(mymodel::getMetadata());
-----
-
-The other critical piece of information required for initialization is
-the OpFlex identity information. The identity information is required
-in order to successfully connect to OpFlex peers. In OpFlex, each
-component has a unique name within its policy domain, and each policy
-domain is identified by a globally unique domain name. You can set
-this identity information by calling:
-
-[source,cpp]
-----
-OFFramework::defaultInstance()
- .setOpflexIdentity("[component name]", "[unique domain]");
-----
-You can then start the framework simply by calling:
-
-[source,cpp]
-----
-OFFramework::defaultInstance().start();
-----
-
-Finally, you can add peers after the framework is started by calling
-the +opflex::ofcore::OFFramework::addPeer+ method:
-
-[source,cpp]
-----
-OFFramework::defaultInstance().addPeer("192.168.1.5", 1234);
-----
-
-When connecting to the peer, that peer may provide an additional list
-of peers to connect to, which will be automatically added as peers. If
-the peer does not include itself in the list, then the framework will
-disconnect from that peer and add the peers in the list. In this way,
-it is possible to automatically bootstrap the correct set of peers
-using a known hostname or IP address or a known, fixed anycast IP
-address.
-
-To cleanly shut down, you can call:
-
-[source,cpp]
-----
-OFFramework::defaultInstance().stop();
-----
-
-==== Working with Data in the Tree
-===== Reading from the Tree
-
-You can access data in the managed tree using the generated accessor
-classes. The details of exactly which classes you'll use will depend
-on the model you're using, but let's assume that we have a simple
-model called "simple" with the following classes:
-
-* root - The root node. The URI for the root node is "/"
-* foo - A policy object, and a child of root, with a scalar string
- property called "bar", and a unsigned 64-bit integer property called
- baz. The bar property is the naming property for foo. The URI for a
- foo object would be "/foo/[value of bar]/"
-* fooref - A local-only child of root, with a reference to a foo, and
- a scalar string property called "bar". The bar property is the
- naming property for foo. The URI for a fooref object would be
- "/fooref/[value of bar]/"
-
-In this example, we'll have a generated class for each of the
-objects. There are two main ways to get access to an object in the
-tree.
-
-First, we can get instantiate an accessor class to any node in the
-tree by calling one of its static resolve functions. The resolve
-functions can take either an already-built URI that represents the
-object, or you can call the version that will locate the object by its
-naming properties.
-
-Second, we can access the object also from its parent object using the
-appropriate child resolver member functions.
-
-However we read it, the object we get back is an immutable view into
-the object it references. The properties set locally on that object
-will not change even though the underlying object may have been
-updated in the store. Note, however, that its children can change
-between when you first retrieve the object and when you resolve any
-children.
-
-Another thing that is critical to note again is that when you attempt
-to resolve an object, you can get back nothing, even if the object
-actually does exist on another OpFlex node. You must ensure that some
-object in the managed object database references the remote managed
-object you want before it will be visible to you.
-
-To get access to the root node using the default framework instance,
-we can simply call:
-
-[source,cpp]
-----
-using boost::shared_ptr;
-using boost::optional;
-optional<shared_ptr<simple::root> > r(simple::root::resolve());
-----
-
-Note that whenever we can a resolve function, we get back our data in
-the form of an optional shared pointer to the object instance. If the
-node does not exist, then the optional will be set to
-boost::none. Note that if you dereference an optional that has not
-been set, you'll trigger an assert, so you must check the return as
-follows:
-
-[source,cpp]
-----
-if (!r) {
- // handle missing object
-}
-----
-Now let's get a child node of the root in three different ways:
-
-[source,cpp]
-----
-// Get foo1 by constructing its URI from the root
-optional<shared_ptr<simple::foo> > foo1(simple::foo::resolve("test"));
-// get foo1 by constructing its URI relative to its parent
-foo1 = r.get()->resolveFoo("test");
-// get foo1 by manually building its URI
-foo1 = simple::foo::resolve(opflex::modb::URIBuilder()
- .addElement("foo")
- .addElement("test")
- .build());
-----
-
-All three of these calls will give us the same object, which is the
-"foo" object located at "/foo/test/".
-
-The foo class has a single string property called "bar". We can easily
-access it as follows:
-
-[source,cpp]
-----
-const std::string& barv = foo1.getBar();
-----
-
-===== Writing to the Tree
-Writing to the tree is nearly as easy as reading from it. The key
-concept to understand is the mutator object. If you want to make
-changes to the tree, you must allocate a mutator object. The mutator
-will register itself in some thread-local storage in the framework
-instance you're using. The mutator is specific to a single "owner" for
-the data, so you can only make changes to data associated with that
-owner.
-
-Whenever you modify one of the accessor classes, the change is
-actually forwarded to the currently-active mutator. You won't see any
-of the changes you make until you call the commit member function on
-the mutator. When you do that, all the changes you made are written
-into the store.
-
-Once the changes are written into the store, you will need to call the
-appropriate resolve function again to see the changes.
-
-Allocating a mutator is simple. To create a mutator for the default
-framework instance associated with the owner "owner1", just allocate
-the mutator on the stack. Be sure to call commit() before it goes out
-of scope or you'll lose your changes.
-
-[source,cpp]
-----
-{
- opflex::modb::Mutator mutator("owner1");
- // make changes here
- mutator.commit();
-}
-----
-
-Note that if an exception is thrown while making changes but before
-committing, the mutator will go out of scope and the changes will be
-discarded.
-
-To create a new node, you must call the appropriate add[Child] member
-function on its parent. This function takes parameters for each of the
-naming properties for the object:
-
-[source,cpp]
-----
-shared_ptr<simple::foo> newfoo(root->addFoo("test"));
-----
-
-This will return a shared pointer to a new foo object that has been
-registered in the active mutator but not yet committed. The "bar"
-naming property will be set automatically, but if you want to set the
-"baz" property now, you can do so by calling:
-
-[source,cpp]
-----
-newfoo->setBaz(42);
-----
-
-Note that creating the root node requires a call to the special static
-class method createRootElement:
-
-[source,cpp]
-----
-shared_ptr<simple::root> newroot(simple::root::createRootElement());
-----
-
-Here's a complete example that ties this all together:
-
-[source,cpp]
-----
-{
- opflex::modb::Mutator mutator("owner1");
- shared_ptr<simple::root> newroot(simple::root::createRootElement());
- shared_ptr<simple::root> newfoo(newroot->addFoo("test"));
- newfoo->setBaz(42);
-
- mutator.commit();
-}
-----
-
-==== Update Notifications
-When using the OpFlex framework, you're likely to find that most of
-your time is spend responding to changes in the managed object
-database. To get these notifications, you're going to need to register
-some number of listeners.
-
-You can register an object listener to see all changes related to a
-particular class by calling a static function for that class. You'll
-then get notifications whenever any object in that class is added,
-updated, or deleted. The listener should queue a task to read the new
-state and perform appropriate processing. If this function blocks or
-peforms a long-running operation, then the dispatching of update
-notifications will be stalled, but there will not be any other
-deleterious effects.
-
-If multiple changes happen to the same URI, then at least one
-notification will be delivered but some events may be consolidated.
-
-The update you get will tell you the URI and the Class ID of the
-changed object. The class ID is a unique ID for each class. When you
-get the update, you'll need to call the appropriate resolve function
-to retrieve the new value.
-
-You'll need to create your own object listener derived from
-opflex::modb::ObjectListener:
-
-[source,cpp]
-----
-class MyListener : public ObjectListener {
-public:
- MyListener() { }
- virtual void objectUpdated(class_id_t class_id, const URI& uri) {
- // Your handler here
- }
-};
-----
-
-To register your listener with the default framework instance, just
-call the appropriate class static method:
-
-[source,cpp]
-----
-MyListener listener;
-simple::foo::registerListener(&listener);
-// main loop
-simple::foo::unregisterListener(&listener);
-----
-
-The listener will now recieve notifications whenever any foo or any
-children of any foo object changes.
-
-Note that you must ensure that you unregister your listeners before
-deallocating them.
-
-=== API Reference Documentation
-Complete API documentation can be found through doxygen here:
-https://jenkins.opendaylight.org/opflex/job/opflex-merge/ws/libopflex/doc/html/index.html
-
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/opflex-libopflex-developer-guide.html
* SDNi Aggregator: Northbound SDNi plugin acts as an aggregator for collecting network information such as topology, stats, host etc. This plugin can be evolving as per needs of network data requested to be shared across federated SDN controllers.
* SDNi REST API: REST API view autogenerated and accessible through RESTCONF to fetch the aggregated information from the northbound plugin – SDNi aggregator.The RESTCONF protocol operates on a conceptual datastore defined with the YANG data modeling language.
* SDNi Wrapper: SDNi BGP Wrapper will be responsible for the sharing and collecting information to/from federated controllers.
+* SDNi UI:This component displays the SDN controllers connected to each other.
=== SDNi Aggregator
*Topology Data:* Controller IP Address, Links, Nodes, Link Bandwidths, MAC Address of switches, Latency, Host IP address.
+http://${IPADDRESS}:8181/restconf/operations/opendaylight-sdni-topology-msg:getAllPeerTopology
+
+*Peer Topology Data:* Controller IP Address, Links, Nodes, Link Bandwidths, MAC Address of switches, Latency, Host IP address.
+
http://${IPADDRESS}:8181/restconf/operations/opendaylight-sdni-qos-msg:get-all-node-connectors-statistics
*QOS Data:* Node, Port, Transmit Packets, Receive Packets, Collision Count, Receive Frame Error, Receive Over Run Error, Receive Crc Error
+http://${IPADDRESS}:8181/restconf/operations/opendaylight-sdni-qos-msg:get-all-peer-node-connectors-statistics
+
+*Peer QOS Data:* Node, Port, Transmit Packets, Receive Packets, Collision Count, Receive Frame Error, Receive Over Run Error, Receive Crc Error
+
=== SDNi Wrapper
.SDNiWrapper
image::SDNiWrapper.png[]
* SDNiWrapper is an extension of ODL-BGPCEP where SDNi topology data is exchange along with the Update NLRI message. Refer http://tools.ietf.org/html/draft-ietf-idr-ls-distribution-04 for more information on NLRI.
* SDNiWrapper gets the controller’s network capabilities through SDNi REST API and serialize it in Update NLRI message. This NLRI message will get exchange between the clustered controllers through BGP-UPDATE message. Similarly peer controller’s UPDATE message is received and unpacked then format to SDNi Network capability data, which will be stored for further purpose.
+=== SDNi UI
+This component displays the SDN controllers connected to each other.
+
+http://localhost:8181/index.html#/sdniUI/sdnController
+
=== API Reference Documentation
Go to http://${IPADDRESS}:8181/apidoc/explorer/index.html, sign in, and expand the opendaylight-sdni panel. From there, users can execute various API calls to test their sdni deployment.
+++ /dev/null
-=== SFC Classifier Control and Date plane Developer guide
-
-==== Overview
-Description of classifier can be found in: https://datatracker.ietf.org/doc/draft-ietf-sfc-architecture/
-
-Classifier manages everything from starting the packet listener to creation (and removal) of appropriate ip(6)tables rules and marking received packets accordingly. Its functionality is *available only on Linux* as it leverdges *NetfilterQueue*, which provides access to packets matched by an *iptables* rule. Classifier requires *root privileges* to be able to operate.
-
-So far it is capable of processing ACL for MAC addresses, ports, IPv4 and IPv6. Supported protocols are TCP and UDP.
-
-==== Classifier Architecture
-Python code located in the project repository sfc-py/common/classifier.py.
-
-NOTE: classifier assumes that Rendered Service Path (RSP) *already exists* in ODL when an ACL referencing it is obtained
-
-.How it works:
-. sfc_agent receives an ACL and passes it for processing to the classifier
-. the RSP (its SFF locator) referenced by ACL is requested from ODL
-. if the RSP exists in the ODL then ACL based iptables rules for it are applied
-
-After this process is over, every packet successfully matched to an iptables rule (i.e. successfully classified) will be NSH encapsulated and forwarded to a related SFF, which knows how to traverse the RSP.
-
-Rules are created using appropriate iptables command. If the Access Control Entry (ACE) rule is MAC address related both iptables and ip6tabeles rules re issued. If ACE rule is IPv4 address related, only iptables rules are issued, same for IPv6.
-
-NOTE: iptables *raw* table contains all created rules
-
-Information regarding already registered RSP(s) are stored in an internal data-store, which is represented as a dictionary:
-
- {rsp_id: {'name': <rsp_name>,
- 'chains': {'chain_name': (<ipv>,),
- ...
- },
- 'sff': {'ip': <ip>,
- 'port': <port>,
- 'starting-index': <starting-index>,
- 'transport-type': <transport-type>
- },
- },
- ...
- }
-
-.Where
- * `name`: name of the RSP
- * `chains`: dictionary of iptables chains related to the RSP with information about IP version for which the chain exists
- * `SFF`: SFF forwarding parameters
- - `ip`: SFF IP address
- - `port`: SFF port
- - `starting-index`: index given to packet at first RSP hop
- - `transport-type`: encapsulation protocol
-
-==== Key APIs and Interfaces
-This features exposes API to configure classifier (corresponds to service-function-classifier.yang)
-
-==== API Reference Documentation
-See: sfc-model/src/main/yang/service-function-classifier.yang
+++ /dev/null
-=== Service Function Load Balancing Developer Guide
-
-==== Overview
-SFC Load-Balancing feature implements load balancing of Service Functions, rather than a one-to-one mapping between Service Function Forwarder and Service Function.
-
-==== Load Balancing Architecture
-Service Function Groups (SFG) can replace Service Functions (SF) in the Rendered Path model.
-A Service Path can only be defined using SFGs or SFs, but not a combination of both.
-
-Relevant objects in the YANG model are as follows:
-
-1. Service-Function-Group-Algorithm:
-
- Service-Function-Group-Algorithms {
- Service-Function-Group-Algorithm {
- String name
- String type
- }
- }
-
- Available types: ALL, SELECT, INDIRECT, FAST_FAILURE
-
-2. Service-Function-Group:
-
- Service-Function-Groups {
- Service-Function-Group {
- String name
- String serviceFunctionGroupAlgorithmName
- String type
- String groupId
- Service-Function-Group-Element {
- String service-function-name
- int index
- }
- }
- }
-
-3. ServiceFunctionHop: holds a reference to a name of SFG (or SF)
-
-==== Key APIs and Interfaces
-This feature enhances the existing SFC API.
-
-REST API commands include:
-* For Service Function Group (SFG): read existing SFG, write new SFG, delete existing SFG, add Service Function (SF) to SFG, and delete SF from SFG
-* For Service Function Group Algorithm (SFG-Alg): read, write, delete
-
-Bundle providing the REST API: sfc-sb-rest
-* Service Function Groups and Algorithms are defined in: sfc-sfg and sfc-sfg-alg
-* Relevant JAVA API: SfcProviderServiceFunctionGroupAPI, SfcProviderServiceFunctionGroupAlgAPI
\ No newline at end of file
+++ /dev/null
-=== SFC-OVS Plugin
-
-==== Overview
-SFC-OVS provides integration of SFC with Open vSwitch (OVS) devices.
-Integration is realized through mapping of SFC objects (like SF, SFF,
-Classifier, etc.) to OVS objects (like Bridge, TerminationPoint=Port/Interface).
-The mapping takes care of automatic instantiation (setup) of corresponding object
-whenever its counterpart is created. For example, when a new SFF is created,
-the SFC-OVS plugin will create a new OVS bridge and when a new OVS Bridge is
-created, the SFC-OVS plugin will create a new SFF.
-
-==== SFC-OVS Architecture
-SFC-OVS uses the OVSDB MD-SAL Southbound API for getting/writing information
-from/to OVS devices. The core functionality consists of two types of mapping:
-
-a. mapping from OVS to SFC
-** OVS Bridge is mapped to SFF
-** OVS TerminationPoints are mapped to SFF DataPlane locators
-
-b. mapping from SFC to OVS
-** SFF is mapped to OVS Bridge
-** SFF DataPlane locators are mapped to OVS TerminationPoints
-
-.SFC < -- > OVS mapping flow diagram
-image::sfc/sfc-ovs-architecture.png[width=500]
-
-==== Key APIs and Interfaces
-* SFF to OVS mapping API (methods to convert SFF object to OVS Bridge
-and OVS TerminationPoints)
-* OVS to SFF mapping API (methods to convert OVS Bridge and OVS TerminationPoints
-to SFF object)
+++ /dev/null
-=== SFC Southbound REST Plugin
-
-==== Overview
-The Southbound REST Plugin is used to send configuration from DataStore down to
-network devices supporting a REST API (i.e. they have a configured REST URI).
-It supports POST/PUT/DELETE operations, which are triggered accordingly by
-changes in the SFC data stores.
-
-.In its current state it listens to changes in these SFC data stores:
-* Access Control List (ACL)
-* Service Classifier Function (SCF)
-* Service Function (SF)
-* Service Function Group (SFG)
-* Service Function Schedule Type (SFST)
-* Service Function Forwader (SFF)
-* Rendered Service Path (RSP)
-
-==== Southbound REST Plugin Architecture
-.The Southbound REST Plugin is built from three main components:
-. *listeners* - used to listen on changes in the SFC data stores
-. *JSON exporters* - used to export JSON-encoded data from binding-aware data
-store objects
-. *tasks* - used to collect REST URIs of network devices and to send JSON-encoded
-data down to these devices
-
-.Southbound REST Plugin Architecture diagram
-image::sfc/sb-rest-architecture.png[width=500]
-
-==== Key APIs and Interfaces
-The plugin provides Southbound REST API designated to listening REST devices. It supports
-POST/PUT/DELETE operations. The operation (with corresponding JSON-encoded data) is sent
-to unique REST URL belonging to certain datatype.
-
-.The URLs are following:
-* Access Control List (ACL):
-+http://<host>:<port>/config/ietf-acl:access-lists/access-list/+
-* Service Function (SF):
-+http://<host>:<port>/config/service-function:service-functions/service-function/+
-* Service Function Group (SFG):
-+http://<host>:<port>/config/service-function:service-function-groups/service-function-group/+
-* Service Function Schedule Type (SFST):
-+http://<host>:<port>/config/service-function-scheduler-type:service-function-scheduler-types/service-function-scheduler-type/+
-* Service Function Forwarder (SFF):
-+http://<host>:<port>/config/service-function-forwarder:service-function-forwarders/service-function-forwarder/+
-* Rendered Service Path (RSP):
-+http://<host>:<port>/operational/rendered-service-path:rendered-service-paths/rendered-service-path/+
-
-Therefore, network devices willing to receive REST messages must listen on
-these REST URLs.
-
-[NOTE]
-Service Classifier Function (SCF) URL does not exist, because SCF is considered
-as one of the network devices willing to receive REST messages. However, there
-is a listener hooked on the SCF data store, which is triggering POST/PUT/DELETE
-operations of ACL object, because ACL is referenced in +service-function-classifier.yang+
+++ /dev/null
-=== Service Function Monitoring
-
-==== SF Monitoring Overview
-TBD
-
-==== SF Monitoring Architecture
-TBD
-
-==== SF Monitoring YANG model
-TBD
-
-==== Key APIs and Interfaces
-TBD
-
-===== API Group 1
-TBD
-
-==== API Reference Documentation
-TBD
+++ /dev/null
-=== Service Function Scheduling Algorithms
-
-==== Overview
-When creating the Rendered Service Path (RSP), the earlier release of SFC
-chose the first available service function from a list of service function
-names. Now a new API is introduced to allow developers to develop their own
-schedule algorithms when creating the RSP. There are four scheduling algorithms
-(Random, Round Robin, Load Balance and Shortest Path) are provided as examples
-for the API definition. This guide gives a simple introduction of how to develop
-service function scheduling algorithms based on the current extensible framework.
-
-==== Architecture
-The following figure illustrates the service function selection framework and
-algorithms.
-
-.SF Scheduling Algorithm framework Architecture
-image::sfc-sf-selection-arch.png["SF Selection Architecture",width=500]
-
-The YANG Model defines the Service Function Scheduling Algorithm type
-identities and how they are stored in the MD-SAL data store for the scheduling
-algorithms.
-
-The MD-SAL data store stores all informations for the scheduling algorithms,
-including their types, names, and status.
-
-The API provides some basic APIs to manage the informations stored in the
-MD-SAL data store, like putting new items into it, getting all scheduling
-algorithms, etc.
-
-The RESTCONF API provides APIs to manage the informations stored in the MD-SAL
-data store through RESTful calls.
-
-The Service Function Chain Renderer gets the enabled scheduling algorithm type,
-and schedules the service functions with scheduling algorithm implementation.
-
-==== Key APIs and Interfaces
-While developing a new Service Function Scheduling Algorithm, a new class
-should be added and it should extend the base schedule class
-SfcServiceFunctionSchedulerAPI. And the new class should implement the abstract
-function:
-
-+public List<String> scheduleServiceFuntions(ServiceFunctionChain chain, int serviceIndex)+.
-
-.input
-* *+ServiceFunctionChain chain+*: the chain which will be rendered
-* *+int serviceIndex+*: the initial service index for this rendered service path
-
-.output
-* *+List<String>+*: a list of service funtion names which scheduled by the
-Service Function Scheduling Algorithm.
-
-==== API Reference Documentation
-Please refer the API docs generated in the mdsal-apidocs.
== Service Function Chaining
-include::sfc_overview.adoc[SFC Overview]
-
-include::odl-sfc-classifier-dev.adoc[SFC Classifier]
-
-include::odl-sfc-ovs-dev.adoc[SFC OVS]
-
-include::odl-sfc-sb-rest-dev.adoc[SFC SouthBound REST plugin]
-
-include::odl-sfc-load-balance-dev.adoc[Service Function Grouping and Load Balancing developer guide]
-
-include::odl-sfc-sf-scheduler-dev.adoc[Service Function selection scheduler]
-
-// Commented out because it has no content
-//include::odl-sfc-sf-monitoring-dev.adoc[Service Function Monitoring]
-
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/alto-developer-guide.html
+++ /dev/null
-=== OpenDaylight Service Function Chaining (SFC) Overiew
-
-OpenDaylight Service Function Chaining (SFC) provides the ability to define an ordered list of a network services (e.g. firewalls, load balancers). These service are then "stitched" together in the network to create a service chain. This project provides the infrastructure (chaining logic, APIs) needed for ODL to provision a service chain in the network and an end-user application for defining such chains.
-
-.List of acronyms:
-* ACE - Access Control Entry
-* ACL - Access Control List
-* SCF - Service Classifier Function
-* SF - Service Function
-* SFC - Service Function Chain
-* SFF - Service Function Forwarder
-* SFG - Service Function Group
-* SFP - Service Function Path
-* RSP - Rendered Service Path
-* NSH - Network Service Header
== SNMP4SDN Developer Guide
-=== Overview
-We propose a southbound plugin that can control the off-the-shelf commodity Ethernet switches for the purpose of building SDN using Ethernet switches. For Ethernet switches, forwarding table, VLAN table, and ACL are where one can install flow configuration on, and this is done via SNMP and CLI in the proposed plugin. In addition, some settings required for Ethernet switches in SDN, e.g., disabling STP and flooding, are proposed.
-
-.SNMP4SDN as an OpenDaylight southbound plugin
-image::snmp4sdn_in_odl_architecture.jpg["SNMP4SDN as an OpenDaylight southbound plugin",width=400]
-
-=== Architecture
-The modules in the plugin are depicted as the following figure.
-
-.Modules in the SNMP4SDN Plugin
-image::snmp4sdn_modules.jpg["Modules in the SNMP4SDN Plugin",width=400]
-
-* AclService: add/remove ACL profile and rule on the switches.
-* FdbService: add/modify/remove FDB table entry on the switches.
-* VlanService: add/modify/remove VLAN table entry on the switches.
-* TopologyService: query and acquire the subnet topology.
-* InventoryService: acquire the switches and their ports.
-* DiscoveryService: probe and resolve the underlying switches as well as the port pairs connecting the switches. The probing is realized by SNMP queries. The updates from discovery will also be reflected to the TopologyService.
-* MiscConfigService: do kinds of settings on switches
-** Supported STP and ARP settings such as enable/disable STP, get port's STP state, get ARP table, set ARP entry, and others
-* VendorSpecificHandler: to assist the flow configuration services to call the switch-talking modules with correct parameters value and order.
-* Switch-talking modules
-** For the services above, when they need to read or configure the underlying switches via SNMP or CLI, these queries are dealt with the modules SNMPHandler and CLIHandler which directly talk with the switches. The SNMPListener is to listen to snmp trap such as link up/down event or switch on/off event.
-
-=== Design
-In terms of the architecture of the SNMP4SDN Plugin's features, the features include flow configuration, topology discovery, and multi-vendor support. Their architectures please refer to Wiki (https://wiki.opendaylight.org/view/SNMP4SDN:Developer_Guide#Design[Developer Guide - Design]).
-
-=== Installation and Configuration Guide
-* Please refer to the 'Getting Started Guide' in https://www.opendaylight.org/downloads, find the SNMP4SDN section.
-* For the latest full guide, please refer to Wiki (https://wiki.opendaylight.org/view/SNMP4SDN:Installation_Guide[Installation Guide], https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Configuration[User Guide - Configuration]).
-
-=== Tutorial
-* For the latest full guide, please refer to Wiki (https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Tutorial_.2F_How-To[User Guide - Tutorial]).
-
-// === Commit the code via Git CLI
-// The steps to commit code is the same with controller's project, please refer to Wiki (https://wiki.opendaylight.org/view/OpenDaylight_Controller:Pulling,_Hacking,_and_Pushing_the_Code_from_the_CLI#Commit_the_code_via_Git_CLI[here]). Just note to replace the Git location as
-// ----
-// ssh://username@git.opendaylight.org29418/snmp4sdn.git
-// ----
-
-=== Programmatic Interface(s)
-SNMP4SDN Plugin exposes APIs via MD-SAL with YANG model. The methods (RPC call) and data structures for them are listed below.
-
-==== TopologyService
-* RPC call
-** get-edge-list
-** get-node-list
-** get-node-connector-list
-** set-discovery-interval (given interval time in seconds)
-** rediscover
-
-* Data structure
-** node: composed of node-id, node-type
-** node-connector: composed of node-connector-id, node-connector-type, node
-** topo-edge: composed of head-node-connector-id, head-node-connector-type, head-node-id, head-node-type, tail-node-connector-id, tail-node-connector-type, tail-node-id, tail-node-type
-
-==== VlanService
-* RPC call
-** add-vlan (given node ID, VLAN ID, VLAN name)
-** add-vlan-and-set-ports (given node ID, VLAN ID, VLAN name, tagged ports, untagged ports)
-** set-vlan-ports (given node ID, VLAN ID, tagged ports, untagged ports)
-** delete-vlan (given node ID, VLAN ID)
-** get-vlan-table (given node ID)
-
-==== AclService
-* RPC call
-** create-acl-profile (given node ID, acl-profile-index, acl-profile)
-** del-acl-profile (given node ID, acl-profile-index)
-** set-acl-rule (given node ID, acl-index, acl-rule)
-** del-acl-rule (given node ID, acl-index)
-** clear-acl-table (given node ID)
-
-* Data structure
-** acl-profile-index: composed of profile-id, profile name
-** acl-profile: composed of acl-layer, vlan-mask, src-ip-mask, dst-ip-mask
-** acl-layer: IP or ETHERNET
-** acl-index: composed of acl-profile-index, acl-rule-index
-** acl-rule-index: composed of rule-id, rule-name
-** acl-rule: composed of port-list, acl-layer, acl-field, acl-action
-** acl-field: composed of vlan-id, src-ip, dst-ip
-** acl-action: PERMIT or DENY
-
-==== FdbService
-* RPC call
-** set-fdb-entry (given fdb-entry)
-** del-fdb-entry (given node-id, vlan-id, dest-mac-adddr)
-** get-fdb-entry (given node-id, vlan-id, dest-mac-adddr)
-** get-fdb-table (given node-id)
-
-* Data structure
-** fdb-entry: composed of node-id, vlan-id, dest-mac-addr, port, fdb-entry-type
-** fdb-entry-type: OTHER/INVALID/LEARNED/SELF/MGMT
-
-==== MiscConfigService
-* RPC call
-** set-stp-port-state (given node-id, port, is_nable)
-** get-stp-port-state (given node-id, port)
-** get-stp-port-root (given node-id, port)
-** enable-stp (given node-id)
-** disable-stp (given node-id)
-** delete-arp-entry (given node-id, ip-address)
-** set-arp-entry (given node-id, arp-entry)
-** get-arp-entry (given node-id, ip-address)
-** get-arp-table (given node-id)
-
-* Data structure
-** stp-port-state: DISABLE/BLOCKING/LISTENING/LEARNING/FORWARDING/BROKEN
-** arp-entry: composed of ip-address and mac-address
-
-==== SwitchDbService
-* RPC call
-** reload-db
-(The following 4 RPC implemention is TBD)
-** add-switch-entry
-** delete-switch-entry
-** clear-db
-** update-db
-
-* Data structure
-** switch-info: compose of node-ip, node-mac, community, cli-user-name, cli-password, model
-
-=== Help
-* https://wiki.opendaylight.org/view/SNMP4SDN:Main[SNMP4SDN Wiki]
-* SNMP4SDN Mailing List (https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-users[user], https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-dev[developer])
-* https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Troubleshooting[Latest troubleshooting in Wiki]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/alto-developer-guide.html
== SXP Developer Guide
-=== Overview
-SXP (Source-Group Tag eXchange Protocol) project is an effort to enhance OpenDaylight platform with IP-SGT (IP Address to Source Group Tag) bindings that can be learned from connected SXP-aware network nodes. The current implementation supports SXP protocol version 4 according to the Smith, Kandula - SXP https://tools.ietf.org/html/draft-smith-kandula-sxp-04[IETF draft] and grouping of peers and creating filters based on ACL/Prefix-list syntax for filtering outbound and inbound IP-SGT bindings. All protocol legacy versions 1-3 are supported as well. Additionally, version 4 adds bidirectional connection type as an extension of a unidirectional one.
-
-=== SXP Architecture
-The SXP Server manages all connected clients in separate threads and a common SXP protocol agreement is used between connected peers. Each SXP network peer is modelled with its pertaining class, e.g., SXP Server represents the SXP Speaker, SXP Listener the Client. The server program creates the ServerSocket object on a specified port and waits until a client starts up and requests connect on the IP address and port of the server. The client program opens a Socket that is connected to the server running on the specified host IP address and port.
-
-The SXP Listener maintains connection with its speaker peer. From an opened channel pipeline, all incoming SXP messages are processed by various handlers. Message must be decoded, parsed and validated.
-
-The SXP Speaker is a counterpart to the SXP Listener. It maintains a connection with its listener peer and sends composed messages.
-
-The SXP Binding Handler extracts the IP-SGT binding from a message and pulls it into the SXP-Database. If an error is detected during the IP-SGT extraction, an appropriate error code and sub-code is selected and an error message is sent back to the connected peer. All transitive messages are routed directly to the output queue of SXP Binding Dispatcher.
-
-The SXP Binding Dispatcher represents a selector that will decides how many data from the SXP-database will be sent and when. It is responsible for message content composition based on maximum message length.
-
-The SXP Binding Filters handles filtering of outgoing and incoming IP-SGT bindings according to BGP filtering using ACL and Prefix List syntax for specifying filter or based on Peer-sequence length.
-
-The SXP Domains feature provides isolation of SXP peers and bindings learned between them, also exchange of Bindings is possible across SXP-Domains by ACL, Prefix List or Peer-Sequence filters
-
-=== Key APIs and Interfaces
-As this project is fairly small, it provides only few features that install and
-provide all APIs and implementations for this project.
-
-* sxp-controller
-* sxp-api
-* spx-core
-
-==== sxp-controller
-RPC request handling
-
-==== sxp-api
-Contains data holders and entities
-
-==== spx-core
-Main logic and core features
-
-=== API Reference Documentation
-https://wiki.opendaylight.org/images/9/91/SXP_Restconf_Interface_and_Dynamic_Tree.pdf[RESTCONF Interface and Dynamic Tree]
-https://wiki.opendaylight.org/images/6/6e/SXP_Specification_and_Architecture_v03.pdf[Specification and Architecture]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/sxp-developer-guide.html
+++ /dev/null
-==== Chapter Overview
-The Topology Processing Framework allows the creation of aggregated topologies and filtered views over existing topologies. Currently, aggregation and filtration is supported for topologies that follow https://github.com/opendaylight/yangtools/blob/master/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang[network-topology], opendaylight-inventory or i2rs model. When a request to create an aggregated or filtered topology is received, the framework creates one listener per underlay topology. Whenever any specified underlay topology is changed, the appropriate listener is triggered with the change and the change is processed. Two types of correlations (functionalities) are currently supported:
-
-* Aggregation
-** Unification
-** Equality
-* Filtration
-
-==== Terminology
-We use the term underlay item (physical node) for items (nodes, links, termination-points) from underlay and overlay item (logical node) for items from overlay topologies regardless of whether those are actually physical network elements.
-
-==== Aggregation
-Aggregation is an operation which creates an aggregated item from two or more items in the underlay topology if the aggregation condition is fulfilled. Requests for aggregated topologies must specify a list of underlay topologies over which the overlay (aggregated) topology will be created and a target field in the underlay item that the framework will check for equality.
-
-===== Create Overlay Node
-First, each new underlay item is inserted into the proper topology store. Once the item is stored, the framework compares it (using the target field value) with all stored underlay items from underlay topologies. If there is a target-field match, a new overlay item is created containing pointers to all 'equal' underlay items. The newly created overlay item is also given new references to its supporting underlay items.
-
-.Equality case:
-If an item doesn't fulfill the equality condition with any other items, processing finishes after adding the item into topology store. It will stay there for future use, ready to create an aggregated item with a new underlay item, with which it would satisfy the equality condition.
-
-.Unification case:
-An overlay item is created for all underlay items, even those which don't fulfill the equality condition with any other items. This means that an overlay item is created for every underlay item, but for items which satisfy the equality condition, an aggregated item is created.
-
-===== Update Node
-Processing of updated underlay items depends on whether the target field has been modified. If yes, then:
-
-* if the underlay item belonged to some overlay item, it is removed from that item. Next, if the aggregation condition on the target field is satisfied, the item is inserted into another overlay item. If the condition isn't met then:
-** in equality case - the item will not be present in overlay topology.
-** in unification case - the item will create an overlay item with a single underlay item and this will be written into overlay topology.
-* if the item didn't belong to some overlay item, it is checked again for aggregation with other underlay items.
-
-===== Remove Node
-The underlay item is removed from the corresponding topology store, from it's overlay item (if it belongs to one) and this way it is also removed from overlay topology.
-
-.Equality case:
-If there is only one underlay item left in the overlay item, the overlay item is removed.
-
-.Unification case:
-The overlay item is removed once it refers to no underlay item.
-
-==== Filtration
-Filtration is an operation which results in creation of overlay topology containing only items fulfilling conditions set in the topoprocessing request.
-
-===== Create Underlay Item
-If a newly created underlay item passes all filtrators and their conditions, then it is stored in topology store and a creation notification is delivered into topology manager. No operation otherwise.
-
-===== Update Underlay Item
-First, the updated item is checked for presence in topology store:
-
-// TODO: what do processUpdatedData and processCreatedData notifications actually cause to happen?
-* if it is present in topology store:
-** if it meets the filtering conditions, then processUpdatedData notification is triggered
-** else processRemovedData notification is triggered
-* if item isn't present in topology store
-** if item meets filtering conditions, then processCreatedData notification is triggered
-** else it is ignored
-
-===== Remove Underlay Item
-If an underlay node is supporting some overlay node, the overlay node is simply removed.
-
-===== Default Filtrator Types
-There are seven types of default filtrators defined in the framework:
-
-* IPv4-address filtrator - checks if specified field meets IPv4 address + mask criteria
-* IPv6-address filtrator - checks if specified field meets IPv6 address + mask criteria
-* Specific number filtrator - checks for specific number
-* Specific string filtrator - checks for specific string
-* Range number filtrator - checks if specified field is higher than provided minimum (inclusive) and lower than provided maximum (inclusive)
-* Range string filtrator - checks if specified field is alphabetically greater than provided minimum (inclusive) and alphabetically lower than provided maximum (inclusive)
-* Script filtrator - allows a user or application to implement their own filtrator
-
-===== Register Custom Filtrator
-There might be some use case that cannot be achieved with the default filtrators. In these cases, the framework offers the possibility for a user or application to register a custom filtrator.
-
-==== Pre-Filtration / Filtration & Aggregation
-This feature was introduced in order to lower memory and performance demands. It is a combination of the filtration and aggregation operations. First, uninteresting items are filtered out and then aggregation is performed only on items that passed filtration. This way the framework saves on compute time. The PreAggregationFiltrator and TopologyAggregator share the same TopoStoreProvider (and thus topology store) which results in lower memory demands (as underlay items are stored only in one topology store - they aren't stored twice).
+++ /dev/null
-==== Chapter Overview
-In this chapter we describe the architecture of the Topology Processing Framework. In the first part, we provide information about available features and basic class relationships. In the second part, we describe our model specific approach, which is used to provide support for different models.
-
-==== Basic Architecture
-The Topology Processing Framework consists of several Karaf features:
-
-* odl-topoprocessing-framework
-* odl-topoprocessing-inventory
-* odl-topoprocessing-network-topology
-* odl-topoprocessing-i2rs
-* odl-topoprocessing-inventory-rendering
-
-The feature odl-topoprocessing-framework contains the topoprocessing-api, topoprocessing-spi and topoprocessing-impl
-bundles. This feature is the core of the Topology Processing Framework and is required by all others features.
-
-* topoprocessing-api - contains correlation definitions and definitions required for rendering
-* topoprocessing-spi - entry point for topoprocessing service (start and close)
-* topoprocessing-impl - contains base implementations of handlers, listeners, aggregators and filtrators
-
-TopoProcessingProvider is the entry point for Topology Processing Framework. It requires a DataBroker instance. The DataBroker is needed for listener registration. There is also the TopologyRequestListener which listens on aggregated topology requests (placed into the configuration datastore) and UnderlayTopologyListeners which listen on underlay topology data changes (made in operational datastore). The TopologyRequestHandler saves toporequest data and provides a method for translating a path to the specified leaf. When a change in the topology occurs, the registered UnderlayTopologyListener processes this information for further aggregation and/or filtration. Finally, after an overlay topology is created, it is passed to the TopologyWriter, which writes this topology into operational datastore.
-
-.Class relationship
-image::topoprocessing/TopologyRequestHandler_classesRelationship.png[width=500]
-
-[1] TopologyRequestHandler instantiates TopologyWriter and TopologyManager. Then, according to the request, initializes either TopologyAggregator, TopologyFiltrator or LinkCalculator.
-
-[2] It creates as many instances of UnderlayTopologyListener as there are underlay topologies.
-
-[3] PhysicalNodes are created for relevant incoming nodes (those having node ID).
-
-[4a] It performs aggregation and creates logical nodes.
-
-[4b] It performs filtration and creates logical nodes.
-
-[4c] It performs link computation and creates links between logical nodes.
-
-[5] Logical nodes are put into wrapper.
-
-[6] The wrapper is translated into the appropriate format and written into datastore.
-
-==== Model Specific Approach
-The Topology Processing Framework consists of several modules and Karaf features, which provide support for different input models. Currently we support the network-topology, opendaylight-inventory and i2rs models. For each of these input models, the Topology Processing Framework has one module and one Karaf feature.
-
-===== How it works
-.User point of view:
-When you start the odl-topoprocessing-framework feature, the Topology Processing Framework starts without knowledge how to work with any input models. In order to allow the Topology Processing Framework to process some kind of input model, you must install one (or more) model specific features. Installing these features will also start odl-topoprocessing-framework feature if it is not already running. These features inject appropriate logic into the odl-topoprocessing-framework feature. From that point, the Topology Processing Framework is able to process different kinds of input models, specifically those that you install features for.
-
-.Developer point of view:
-The topoprocessing-impl module contains (among other things) classes and interfaces, which are common for every model specific topoprocessing module. These classes and interfaces are implemented and extended by classes in particular model specific modules.
-Model specific modules also depend on the TopoProcessingProvider class in the topoprocessing-spi module. This dependency is injected during installation of model specific features in Karaf. When a model specific feature is started, it calls the registerAdapters(adapters) method of the injected TopoProcessingProvider object. After this step, the Topology Processing Framework is able to use registered model adapters to work with input models.
-
-To achieve the described functionality we created a ModelAdapter interface. It represents installed feature and provides methods for creating crucial structures specific to each model.
-
-.ModelAdapter interface
-image::topoprocessing/ModelAdapter.png[width=300]
-
-===== Model Specific Features
-
-* odl-topoprocessing-network-topology - this feature contains logic to work with network-topology model
-* odl-topoprocessing-inventory - this feature contains logic to work with opendaylight-inventory model
-* odl-topoprocessing-i2rs - this feature contains logic to work with i2rs model
-
-==== Inventory Model Support
-The opendaylight-inventory model contains only nodes, termination points, information regarding these structures. This model co-operates with network-topology model, where other topology related information is stored. This means that we have to handle two input models at once. To support the inventory model, InventoryListener and NotificationInterConnector classes were introduced. Please see the flow diagrams below.
-
-.Network topology model
-image::topoprocessing/Network_topology_model_flow_diagram.png[width=500]
-
-.Inventory model
-image::topoprocessing/Inventory_model_listener_diagram.png[width=500]
-
-Here we can see the InventoryListener and NotificationInterConnector classes. InventoryListener listens on data changes in the inventory model and passes these changes wrapped as an UnderlayItem for further processing to NotificationInterConnector. It doesn't contain node information - it contains a leafNode (node based on which aggregation occurs) instead.
-The node information is stored in the topology model, where UnderlayTopologyListener is registered as usual. This listener delivers the missing information.
-
-Then the NotificationInterConnector combines the two notifications into a complete UnderlayItem (no null values) and delivers this UnderlayItem for further processing (to next TopologyOperator).
== Topology Processing Framework Developer Guide
-=== Overview
-The Topology Processing Framework allows developers to aggregate and filter topologies according to defined correlations. It also provides functionality, which you can use to make your own topology model by automating the translation from one model to another. For example to translate from the opendaylight-inventory model to only using the network-topology model.
-
-=== Architecture
-include::odl-topoprocessing-architecture-dev.adoc[]
-
-=== Aggregation and Filtration
-include::odl-topoprocessing-aggregation-filtration-dev.adoc[]
-
-=== Link Computation
-include::odl-topoprocessing-link-computation-dev.adoc[]
-
-=== Wrapper, RPC Republishing, Writing Mechanism
-include::odl-topoprocessing-wrapper-rpc-writing-dev.adoc[]
-
-=== Topology Rendering Guide - Inventory Rendering
-include::odl-topoprocessing-inventory-rendering-dev.adoc[]
-
-=== Key APIs and Interfaces
-The basic provider class is TopoProcessingProvider which provides startup and shutdown
-methods. Otherwise, the framework communicates via requests and outputs stored
-in the MD-SAL datastores.
-
-=== API Reference Documentation
-You can find API examples on https://wiki.opendaylight.org/view/Topology_Processing_Framework:Developer_Guide:End_to_End_Example[this wiki page].
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/topology-processing-framework-developer-guide.html
+++ /dev/null
-==== Chapter Overview
-In the most recent OpenDaylight release, the opendaylight-inventory model is marked as deprecated. To facilitate migration from it to the network-topology model, there were requests to render (translate) data from inventory model (whether augmented or not) to another model for further processing. The Topology Processing Framework was extended to provide this functionality by implementing several rendering-specific classes. This chapter is a step-by-step guide on how to implement your own topology rendering using our inventory rendering as an example.
-
-==== Use case
-For the purpose of this guide we are going to render the following augmented fields from the OpenFlow model:
-
-* from inventory node:
-** manufacturer
-** hardware
-** software
-** serial-number
-** description
-** ip-address
-* from inventory node-connector:
-** name
-** hardware-address
-** current-speed
-** maximum-speed
-
-We also want to preserve the node ID and termination-point ID from opendaylight-topology-inventory model, which is network-topology part of the inventory model.
-
-==== Implementation
-There are two ways to implement support for your specific topology rendering:
-
-* add a module to your project that depends on the Topology Processing Framework
-* add a module to the Topology Processing Framework itself
-
-Regardless, a successful implementation must complete all of the following steps.
-
-===== Step1 - Target Model Creation
-Because the network-topology node does not have fields to store all desired data, it is necessary to create new model to render this extra data in to. For this guide we created the inventory-rendering model. The picture below shows how data will be rendered and stored.
-
-.Rendering to the inventory-rendering model
-image::topoprocessing/Inventory_Rendering_Use_case.png[width=500]
-
-IMPORTANT: When implementing your version of the topology-rendering model in the Topology Processing Framework, the source file of the model (.yang) must be saved in /topoprocessing-api/src/main/yang folder so corresponding structures can be generated during build and can be accessed from every module through dependencies.
-
-When the target model is created you have to add an identifier through which you can set your new model as output model. To do that you have to add another identity item to topology-correlation.yang file. For our inventory-rendering model identity looks like this:
-
-[source,yang]
-----
-identity inventory-rendering-model {
- description "inventory-rendering.yang";
- base model;
-}
-----
-
-After that you will be able to set inventory-rendering-model as output model in XML.
-
-===== Step2 - Module and Feature Creation
-IMPORTANT: This and following steps are based on the <<_model_specific_approach,model specific approach>> in the Topology Processing Framework. We highly recommend that you familiarize yourself with this approach in advance.
-
-To create a base module and add it as a feature to Karaf in the Topology Processing Framework we made the changes in following https://git.opendaylight.org/gerrit/#/c/26223/[commit]. Changes in other projects will likely be similar.
-
-[options="header"]
-|======
-|File |Changes
-|pom.xml |add new module to topoprocessing
-|features.xml |add feature to topoprocessing
-|features/pom.xml |add dependencies needed by features
-|topoprocessing-artifacts/pom.xml |add artifact
-|topoprocessing-config/pom.xml |add configuration file
-|81-topoprocessing-inventory-rendering-config.xml |configuration file for new module
-|topoprocessing-inventory-rendering/pom.xml |main pom for new module
-|TopoProcessingProviderIR.java |contains startup method which register new model adapter
-|TopoProcessingProviderIRModule.java |generated class which contains createInstance method. You should call your startup method from here.
-|TopoProcessingProviderIRModuleFactory.java |generated class. You will probably not need to edit this file
-|log4j.xml |configuration file for logger
-topoprocessing-inventory-rendering-provider-impl.yang|main yang module. Generated classes are generated according to this yang file
-|======
-
-===== Step3 - Module Adapters Creation
-There are seven mandatory interfaces or abstract classes that needs to be implemented in each module. They are:
-
-* TopoProcessingProvider - provides module registration
-* ModelAdapter - provides model specific instances
-* TopologyRequestListener - listens on changes in the configuration datastore
-* TopologyRequestHandler - processes configuration datastore changes
-* UnderlayTopologyListener - listens for changes in the specific model
-* LinkTransaltor and NodeTranslator - used by OverlayItemTranslator to create NormalizedNodes from OverlayItems
-
-The name convention we used was to add an abbreviation for the specific model to the beginning of implementing class name (e.g. the IRModelAdapter refers to class which implements ModelAdapter in module Inventory Rendering). In the case of the provider class, we put the abbreviation at the end.
-
-[IMPORTANT]
-======
-* In the next sections, we use the terms TopologyRequestListener, TopologyRequestHandler, etc. without a prepended or appended abbreviation because the steps apply regardless of which specific model you are targeting.
-* If you want to implement rendering from inventory to network-topology, you can just copy-paste our module and additional changes will be required only in the output part.
-======
-
-*Provider part*
-
-This part is the starting point of the whole module. It is responsible for creating and registering TopologyRequestListeners. It is necessary to create three classes which will import:
-
-* *TopoProcessingProviderModule* - is a generated class from topoprocessing-inventory-rendering-provider-impl.yang (created in previous step, file will appear after first build). Its method `createInstance()` is called at the feature start and must be modified to create an instance of TopoProcessingProvider and call its `startup(TopoProcessingProvider topoProvider)` function.
-* *TopoProcessingProvider* - in `startup(TopoProcessingProvider topoProvider)` function provides ModelAdapter registration to TopoProcessingProviderImpl.
-* *ModelAdapter* - provides creation of corresponding module specific classes.
-
-*Input part*
-
-This includes the creation of the classes responsible for input data processing. In this case, we had to create five classes implementing:
-
-* *TopologyRequestListener* and *TopologyRequestHandler* - when notified about a change in the configuration datastore, verify if the change contains a topology request (has correlations in it) and creates UnderlayTopologyListeners if needed. The implementation of these classes will differ according to the model in which are correlations saved (network-topology or i2rs). In the case of using network-topology, as the input model, you can use our classes IRTopologyRequestListener and IRTopologyRequestHandler.
-* *UnderlayTopologyListener* - registers underlay listeners according to input model. In our case (listening in the inventory model), we created listeners for the network-topology model and inventory model, and set the NotificationInterConnector as the first operator and set the IRRenderingOperator as the second operator (after NotificationInterConnector). Same as for TopologyRequestListener/Handler, if you are rendering from the inventory model, you can use our class IRUnderlayTopologyListener.
-* *InventoryListener* - a new implementation of this class is required only for inventory input model. This is because the InventoryListener from topoprocessing-impl requires pathIdentifier which is absent in the case of rendering.
-* *TopologyOperator* - replaces classic topoprocessing operator. While the classic operator provides specific operations on topology, the rendering operator just wraps each received UnderlayItem to OverlayItem and sends them to write.
-
-[IMPORTANT]
-======
-For purposes of topology rendering from inventory to network-topology, there are misused fields in UnderlayItem as follows:
-
-* item - contains node from network-topology part of inventory
-* leafItem - contains node from inventory
-
-In case of implementing UnderlayTopologyListener or InventoryListener you have to carefully adjust UnderlayItem creation to these terms.
-======
-
-*Output part*
-
-The output part of topology rendering is responsible for translating received overlay items to normalized nodes. In the case of inventory rendering, this is where node information from inventory are combined with node information from network-topology. This combined information is stored in our inventory-rendering model normalized node and passed to the writer.
-
-The output part consists of two translators implementing the NodeTranslator and LinkTranslator interfaces.
-
-*NodeTranslator implementation* - The NodeTranslator interface has one `translate(OverlayItemWrapper wrapper)` method. For our purposes, there is one important thing in wrapper - the list of OverlayItems which have one or more common UnderlayItems. Regardless of this list, in the case of rendering it will always contains only one OverlayItem. This item has list of UnderlayItems, but again in case of rendering there will be only one UnderlayItem item in this list. In NodeTranslator, the OverlayItem and corresponding UnderlayItem represent nodes from the translating model.
-
-The UnderlayItem has several attributes. How you will use these attributes in your rendering is up to you, as you create this item in your topology operator. For example, as mentioned above, in our inventory rendering example is an inventory node normalized node stored in the UnderlayItem leafNode attribute, and we also store node-id from network-topology model in UnderlayItem itemId attribute. You can now use these attributes to build a normalized node for your new model. How to read and create normalized nodes is out of scope of this document.
-
-*LinkTranslator implementation* - The LinkTranslator interface also has one `translate(OverlayItemWrapper wrapper)` method. In our inventory rendering this method returns `null`, because the inventory model doesn't have links. But if you also need links, this is the place where you should translate it into a normalized node for your model. In LinkTranslator, the OverlayItem and corresponding UnderlayItem represent links from the translating model. As in NodeTranslator, there will be only one OverlayItem and one UnderlayItem in the corresponding lists.
-
-==== Testing
-If you want to test our implementation you must apply https://git.opendaylight.org/gerrit/#/c/26612[this patch]. It adds an OpenFlow Plugin dependency so we can use it in the Karaf distribution as a feature. After adding patch and building the whole framework, you can start Karaf. Next, you have to install necessary features. In our case it is:
-
-`feature:install odl-restconf-noauth odl-topoprocessing-inventory-rendering odl-openflowplugin-southbound odl-openflowplugin-nsf-model`
-
-Now you can send messages to REST from any REST client (e.g. Postman in Chrome). Messages have to have following headers:
-
-[options="header"]
-|=====
-|Header |Value
-|Content-Type:|application/xml
-|Accept: |application/xml
-|username: |admin
-|password: |admin
-|=====
-
-Firstly send topology request to http://localhost:8181/restconf/config/network-topology:network-topology/topology/render:1 with method PUT. Example of simple rendering request:
-
-[source, xml]
-----
-<topology xmlns="urn:TBD:params:xml:ns:yang:network-topology">
- <topology-id>render:1</topology-id>
- <correlations xmlns="urn:opendaylight:topology:correlation" >
- <output-model>inventory-rendering-model</output-model>
- <correlation>
- <correlation-id>1</correlation-id>
- <type>rendering-only</type>
- <correlation-item>node</correlation-item>
- <rendering>
- <underlay-topology>und-topo:1</underlay-topology>
- </rendering>
- </correlation>
- </correlations>
-</topology>
-----
-This request says that we want create topology with name render:1 and this topology should be stored in the inventory-rendering-model and it should be created from topology flow:1 by node rendering.
-
-Next we send the network-topology part of topology flow:1. So to the URL http://localhost:8181/restconf/config/network-topology:network-topology/topology/und-topo:1 we PUT:
-[source,xml]
-----
-<topology xmlns="urn:TBD:params:xml:ns:yang:network-topology"
- xmlns:it="urn:opendaylight:model:topology:inventory"
- xmlns:i="urn:opendaylight:inventory">
- <topology-id>und-topo:1</topology-id>
- <node>
- <node-id>openflow:1</node-id>
- <it:inventory-node-ref>
- /i:nodes/i:node[i:id="openflow:1"]
- </it:inventory-node-ref>
- <termination-point>
- <tp-id>tp:1</tp-id>
- <it:inventory-node-connector-ref>
- /i:nodes/i:node[i:id="openflow:1"]/i:node-connector[i:id="openflow:1:1"]
- </it:inventory-node-connector-ref>
- </termination-point>
- </node>
-</topology>
-----
-And the last input will be inventory part of topology. To the URL http://localhost:8181/restconf/config/opendaylight-inventory:nodes we PUT:
-[source,xml]
-----
-<nodes
- xmlns="urn:opendaylight:inventory">
- <node>
- <id>openflow:1</id>
- <node-connector>
- <id>openflow:1:1</id>
- <port-number
- xmlns="urn:opendaylight:flow:inventory">1
- </port-number>
- <current-speed
- xmlns="urn:opendaylight:flow:inventory">10000000
- </current-speed>
- <name
- xmlns="urn:opendaylight:flow:inventory">s1-eth1
- </name>
- <supported
- xmlns="urn:opendaylight:flow:inventory">
- </supported>
- <current-feature
- xmlns="urn:opendaylight:flow:inventory">copper ten-gb-fd
- </current-feature>
- <configuration
- xmlns="urn:opendaylight:flow:inventory">
- </configuration>
- <peer-features
- xmlns="urn:opendaylight:flow:inventory">
- </peer-features>
- <maximum-speed
- xmlns="urn:opendaylight:flow:inventory">0
- </maximum-speed>
- <advertised-features
- xmlns="urn:opendaylight:flow:inventory">
- </advertised-features>
- <hardware-address
- xmlns="urn:opendaylight:flow:inventory">0E:DC:8C:63:EC:D1
- </hardware-address>
- <state
- xmlns="urn:opendaylight:flow:inventory">
- <link-down>false</link-down>
- <blocked>false</blocked>
- <live>false</live>
- </state>
- <flow-capable-node-connector-statistics
- xmlns="urn:opendaylight:port:statistics">
- <receive-errors>0</receive-errors>
- <receive-frame-error>0</receive-frame-error>
- <receive-over-run-error>0</receive-over-run-error>
- <receive-crc-error>0</receive-crc-error>
- <bytes>
- <transmitted>595</transmitted>
- <received>378</received>
- </bytes>
- <receive-drops>0</receive-drops>
- <duration>
- <second>28</second>
- <nanosecond>410000000</nanosecond>
- </duration>
- <transmit-errors>0</transmit-errors>
- <collision-count>0</collision-count>
- <packets>
- <transmitted>7</transmitted>
- <received>5</received>
- </packets>
- <transmit-drops>0</transmit-drops>
- </flow-capable-node-connector-statistics>
- </node-connector>
- <node-connector>
- <id>openflow:1:LOCAL</id>
- <port-number
- xmlns="urn:opendaylight:flow:inventory">4294967294
- </port-number>
- <current-speed
- xmlns="urn:opendaylight:flow:inventory">0
- </current-speed>
- <name
- xmlns="urn:opendaylight:flow:inventory">s1
- </name>
- <supported
- xmlns="urn:opendaylight:flow:inventory">
- </supported>
- <current-feature
- xmlns="urn:opendaylight:flow:inventory">
- </current-feature>
- <configuration
- xmlns="urn:opendaylight:flow:inventory">
- </configuration>
- <peer-features
- xmlns="urn:opendaylight:flow:inventory">
- </peer-features>
- <maximum-speed
- xmlns="urn:opendaylight:flow:inventory">0
- </maximum-speed>
- <advertised-features
- xmlns="urn:opendaylight:flow:inventory">
- </advertised-features>
- <hardware-address
- xmlns="urn:opendaylight:flow:inventory">BA:63:87:0C:76:41
- </hardware-address>
- <state
- xmlns="urn:opendaylight:flow:inventory">
- <link-down>false</link-down>
- <blocked>false</blocked>
- <live>false</live>
- </state>
- <flow-capable-node-connector-statistics
- xmlns="urn:opendaylight:port:statistics">
- <receive-errors>0</receive-errors>
- <receive-frame-error>0</receive-frame-error>
- <receive-over-run-error>0</receive-over-run-error>
- <receive-crc-error>0</receive-crc-error>
- <bytes>
- <transmitted>576</transmitted>
- <received>468</received>
- </bytes>
- <receive-drops>0</receive-drops>
- <duration>
- <second>28</second>
- <nanosecond>426000000</nanosecond>
- </duration>
- <transmit-errors>0</transmit-errors>
- <collision-count>0</collision-count>
- <packets>
- <transmitted>6</transmitted>
- <received>6</received>
- </packets>
- <transmit-drops>0</transmit-drops>
- </flow-capable-node-connector-statistics>
- </node-connector>
- <serial-number
- xmlns="urn:opendaylight:flow:inventory">None
- </serial-number>
- <manufacturer
- xmlns="urn:opendaylight:flow:inventory">Nicira, Inc.
- </manufacturer>
- <hardware
- xmlns="urn:opendaylight:flow:inventory">Open vSwitch
- </hardware>
- <software
- xmlns="urn:opendaylight:flow:inventory">2.1.3
- </software>
- <description
- xmlns="urn:opendaylight:flow:inventory">None
- </description>
- <ip-address
- xmlns="urn:opendaylight:flow:inventory">10.20.30.40
- </ip-address>
- <meter-features
- xmlns="urn:opendaylight:meter:statistics">
- <max_bands>0</max_bands>
- <max_color>0</max_color>
- <max_meter>0</max_meter>
- </meter-features>
- <group-features
- xmlns="urn:opendaylight:group:statistics">
- <group-capabilities-supported
- xmlns:x="urn:opendaylight:group:types">x:chaining
- </group-capabilities-supported>
- <group-capabilities-supported
- xmlns:x="urn:opendaylight:group:types">x:select-weight
- </group-capabilities-supported>
- <group-capabilities-supported
- xmlns:x="urn:opendaylight:group:types">x:select-liveness
- </group-capabilities-supported>
- <max-groups>4294967040</max-groups>
- <actions>67082241</actions>
- <actions>0</actions>
- </group-features>
- </node>
-</nodes>
-----
-After this, the expected result from a GET request to http://127.0.0.1:8181/restconf/operational/network-topology:network-topology is:
-[source,xml]
-----
-<network-topology
- xmlns="urn:TBD:params:xml:ns:yang:network-topology">
- <topology>
- <topology-id>render:1</topology-id>
- <node>
- <node-id>openflow:1</node-id>
- <node-augmentation
- xmlns="urn:opendaylight:topology:inventory:rendering">
- <ip-address>10.20.30.40</ip-address>
- <serial-number>None</serial-number>
- <manufacturer>Nicira, Inc.</manufacturer>
- <description>None</description>
- <hardware>Open vSwitch</hardware>
- <software>2.1.3</software>
- </node-augmentation>
- <termination-point>
- <tp-id>openflow:1:1</tp-id>
- <tp-augmentation
- xmlns="urn:opendaylight:topology:inventory:rendering">
- <hardware-address>0E:DC:8C:63:EC:D1</hardware-address>
- <current-speed>10000000</current-speed>
- <maximum-speed>0</maximum-speed>
- <name>s1-eth1</name>
- </tp-augmentation>
- </termination-point>
- <termination-point>
- <tp-id>openflow:1:LOCAL</tp-id>
- <tp-augmentation
- xmlns="urn:opendaylight:topology:inventory:rendering">
- <hardware-address>BA:63:87:0C:76:41</hardware-address>
- <current-speed>0</current-speed>
- <maximum-speed>0</maximum-speed>
- <name>s1</name>
- </tp-augmentation>
- </termination-point>
- </node>
- </topology>
-</network-topology>
-----
+++ /dev/null
-==== Chapter Overview
-While processing the topology request, we create overlay nodes with lists of supporting underlay nodes. Because these overlay nodes have completely new identifiers, we lose link information. To regain this link information, we provide Link Computation functionality. Its main purpose is to create new overlay links based on the links from the underlay topologies and underlay items from overlay items. The required information for Link Computation is provided via the Link Computation model in (https://git.opendaylight.org/gerrit/gitweb?p=topoprocessing.git;a=blob;f=topoprocessing-api/src/main/yang/topology-link-computation.yang;hb=refs/heads/stable/beryllium[topology-link-computation.yang]).
-
-==== Link Computation Functionality
-Let us consider two topologies with following components:
-
-Topology 1:
-
-* Node: `node:1:1`
-* Node: `node:1:2`
-* Node: `node:1:3`
-* Link: `link:1:1` (from `node:1:1` to `node:1:2`)
-* Link: `link:1:2` (from `node:1:3` to `node:1:2`)
-
-Topology 2:
-
-* Node: `node:2:1`
-* Node: `node:2:2`
-* Node: `node:2:3`
-* Link: `link:2:1` (from `node:2:1` to `node:2:3`)
-
-Now let's say that we applied some operations over these topologies that results into aggregating together
-
-* `node:1:1` and `node:2:3` (`node:1`)
-* `node:1:2` and `node:2:2` (`node:2`)
-* `node:1:3` and `node:2:1` (`node:3`)
-
-At this point we can no longer use available links in new topology because of the node ID change, so we must create new overlay links with source and destination node set to new nodes IDs. It means that `link:1:1` from topology 1 will create new link `link:1`. Since original source (`node:1:1`) is already aggregated under `node:1`, it will become source node for `link:1`. Using same method the destination will be `node:2`. And the final output will be three links:
-
-* `link:1`, from `node:1` to `node:2`
-* `link:2`, from `node:3` to `node:2`
-* `link:3`, from `node:3` to `node:1`
-
-.Overlay topology with computed links
-image::topoprocessing/LinkComputation.png[width=461]
-
-==== In-Depth Look
-The main logic behind Link Computation is executed in the LinkCalculator operator. The required information is passed to LinkCalculator through the LinkComputation section of the topology request. This section is defined in the topology-link-computation.yang file. The main logic also covers cases when some underlay nodes may not pass through other topology operators.
-
-===== Link Computation Model
-There are three essential pieces of information for link computations. All of them are provided within the LinkComputation section. These pieces are:
-
-* output model
-
-[source, yang]
-----
-leaf output-model {
- type identityref {
- base topo-corr:model;
- }
- description "Desired output model for computed links.";
-}
-----
-
-* overlay topology with new nodes
-
-[source, yang]
-----
-container node-info {
- leaf node-topology {
- type string;
- mandatory true;
- description "Topology that contains aggregated nodes.
- This topology will be used for storing computed links.";
- }
- uses topo-corr:input-model-grouping;
-}
-----
-
-* underlay topologies with original links
-
-[source, yang]
-----
-list link-info {
- key "link-topology input-model";
- leaf link-topology {
- type string;
- mandatory true;
- description "Topology that contains underlay (base) links.";
- }
- leaf aggregated-links {
- type boolean;
- description "Defines if link computation should be based on supporting-links.";
- }
- uses topo-corr:input-model-grouping;
-}
-----
-
-This whole section is augmented into `network-topology:topology`. By placing this section out of correlations section, it allows us to send link computation request separately from topology operations request.
-
-===== Main Logic
-Taking into consideration that some of the underlay nodes may not transform into overlay nodes (e.g. they are filtered out), we created two possible states for links:
-
-* matched - a link is considered as matched when both original source and destination node were transformed to overlay nodes
-* waiting - a link is considered as waiting if original source, destination or both nodes are missing from the overlay topology
-
-All links in waiting the state are stored in waitingLinks list, already matched links are stored in matchedLinks list and overlay nodes are stored in the storedOverlayNodes list. All processing is based only on information in these lists.
-Processing created, updated and removed underlay items is slightly different and described in next sections separately.
-
-*Processing Created Items*
-
-Created items can be either nodes or links, depending on the type of listener from which they came. In the case of a link, it is immediately added to waitingLinks and calculation for possible overlay link creations (calculatePossibleLink) is started. The flow diagram for this process is shown in the following picture:
-
-.Flow diagram of processing created items
-image::topoprocessing/LinkComputationFlowDiagram.png[width=500]
-
-Searching for the source and destination nodes in the calculatePossibleLink method runs over each node in storedOverlayNodes and the IDs of each supporting node is compared against IDs from the underlay link's source and destination nodes. If there are any nodes missing, the link remains in the waiting state. If both the source and destination nodes are found, the corresponding overlay nodes is recorded as the new source and destination. The link is then removed from waitingLinks and a new CalculatedLink is added to the matched links. At the end, the new link (if it exists) is written into the datastore.
-
-If the created item is an overlayNode, this is added to storedOverlayNodes and we call calculatePossibleLink for every link in waitingLinks.
-
-*Processing Updated Items*
-
-The difference from processing created items is that we have three possible types of updated items: overlay nodes, waiting underlay links, and matched underlay links.
-
-* In the case of a change in a matched link, this must be recalculated and based on the result it will either be matched with new source and destination or will be returned to waiting links. If the link is moved back to a waiting state, it must also be removed from the datastore.
-* In the case of change in a waiting link, it is passed to the calculation process and based on the result will either remain in waiting state or be promoted to the matched state.
-* In the case of a change in an overlay node, storedOverlayNodes must be updated properly and all links must be recalculated in case of changes.
-
-*Processing Removed items*
-
-Same as for processing updated item. There can be three types of removed items:
-
-* In case of waiting link removal, the link is just removed from waitingLinks
-* In case of matched link removal, the link is removed from matchingLinks and datastore
-* In case of overlay node removal, the node must be removed form storedOverlayNodes and all matching links must be recalculated
-
+++ /dev/null
-==== Chapter Overview
-During the process of aggregation and filtration, overlay items (so called logical nodes) were created from underlay items (physical nodes). In the topology manager, overlay items are put into a wrapper. A wrapper is identified with unique ID and contains list of logical nodes. Wrappers are used to deal with transitivity of underlay items - which permits grouping of overlay items (into wrappers).
-
-.Wrapper
-image::topoprocessing/wrapper.png[width=500]
-
-PN1, PN2, PN3 = physical nodes
-
-LN1, LN2 = logical nodes
-
-==== RPC Republishing
-All RPCs registered to handle underlay items are re-registered under their corresponding wrapper ID. RPCs of underlay items (belonging to an overlay item) are gathered, and registered under ID of their wrapper.
-
-===== RPC Call
-When RPC is called on overlay item, this call is delegated to it's underlay items, this means that the RPC is called on all underlay items of this overlay item.
-
-==== Writing Mechanism
-When a wrapper (containing overlay item(s) with it's underlay item(s)) is ready to be written into data store, it has to be converted into DOM format. After this translation is done, the result is written into datastore. Physical nodes are stored as supporting-nodes.
-In order to use resources responsibly, writing operation is divided into two steps. First, a set of threads registers prepared operations (deletes and puts) and one thread makes actual write operation in batch.
== TTP CLI Tools Developer Guide
-=== Overview
-Table Type Patterns are a specification developed by the
-https://www.opennetworking.org/[Open Networking Foundation] to enable
-the description and negotiation of subsets of the OpenFlow protocol.
-This is particularly useful for hardware switches that support OpenFlow
-as it enables the to describe what features they do (and thus also what
-features they do not) support. More details can be found in the full
-specification listed on the
-https://www.opennetworking.org/sdn-resources/onf-specifications/openflow[OpenFlow
-specifications page].
-
-The TTP CLI Tools provide a way for people interested in TTPs to read
-in, validate, output, and manipulate TTPs as a self-contained,
-executable jar file.
-
-=== TTP CLI Tools Architecture
-The TTP CLI Tools use the TTP Model and the YANG Tools/RESTCONF codecs
-to translate between the Data Transfer Objects (DTOs) and JSON/XML.
-
-=== Command Line Options
-This will cover the various options for the CLI Tools. For now, there
-are no options and it merely outputs fixed data using the codecs.
-
-// The CLI tools don't have an APIs in the common sense.
-//
-// === Key APIs and Interfaces
-// Document the key things a user would want to use. For some features,
-// there will only be one logical grouping of APIs. For others there may be
-// more than one grouping.
-//
-// Assuming the API is MD-SAL- and YANG-based, the APIs will be available
-// both via RESTCONF and via Java APIs. Giving a few examples using each is
-// likely a good idea.
-//
-// ==== API Group 1
-// Provide a description of what the API does and some examples of how to
-// use it.
-//
-// ==== API Group 2
-// Provide a description of what the API does and some examples of how to
-// use it.
-//
-// === API Reference Documentation
-// Provide links to JavaDoc, REST API documentation, etc.
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/ttp-cli-tools-developer-guide.html
== TTP Model Developer Guide
-=== Overview
-Table Type Patterns are a specification developed by the
-https://www.opennetworking.org/[Open Networking Foundation] to enable
-the description and negotiation of subsets of the OpenFlow protocol.
-This is particularly useful for hardware switches that support OpenFlow
-as it enables the to describe what features they do (and thus also what
-features they do not) support. More details can be found in the full
-specification listed on the
-https://www.opennetworking.org/sdn-resources/onf-specifications/openflow[OpenFlow
-specifications page].
-
-=== TTP Model Architecture
-The TTP Model provides a YANG-modeled type for a TTP and allows them
-to be associated with a master list of known TTPs, as well as active
-and supported TTPs with nodes in the MD-SAL inventory model.
-
-=== Key APIs and Interfaces
-The key API provided by the TTP Model feature is the ability to store
-a set of TTPs in the MD-SAL as well as associate zero or one active
-TTPs and zero or more supported TTPs along with a given node in the
-MD-SAL inventory model.
-
-=== API Reference Documentation
-
-==== RESTCONF
-See the generated RESTCONF API documentation at:
-http://localhost:8181/apidoc/explorer/index.html
-
-Look for the onf-ttp module to expand and see the various RESTCONF
-APIs.
-
-==== Java Bindings
-
-//TODO: Provide a link to JavaDoc.
-
-As stated above there are 3 locations where a Table Type Pattern can be
-placed into the MD-SAL Data Store. They correspond to 3 different REST
-API URIs:
-
-. +restconf/config/onf-ttp:opendaylight-ttps/onf-ttp:table-type-patterns/+
-. +restconf/config/opendaylight-inventory:nodes/node/{id}/ttp-inventory-node:active_ttp/+
-. +restconf/config/opendaylight-inventory:nodes/node/{id}/ttp-inventory-node:supported_ttps/+
-
-[NOTE]
-===============================
-Typically, these URIs are running on the machine the controller is on
-at port 8181. If you are on the same machine they can thus be accessed
-at +http://localhost:8181/<uri>+
-===============================
-
-=== Using the TTP Model RESTCONF APIs
-
-==== Setting REST HTTP Headers
-
-===== Authentication
-
-The REST API calls require authentication by default. The default
-method is to use basic auth with a user name and password of `admin'.
-
-===== Content-Type and Accept
-
-RESTCONF supports both xml and json. This example focuses on JSON, but
-xml can be used just as easily. When doing a PUT or POST be sure to
-specify the appropriate +Conetnt-Type+ header: either
-+application/json+ or +application/xml+.
-
-When doing a GET be sure to specify the appropriate +Accept+ header:
-again, either +application/json+ or +application/xml+.
-
-==== Content
-
-The contents of a PUT or POST should be a OpenDaylight Table Type
-Pattern. An example of one is provided below. The example can also be
-found at https://git.opendaylight.org/gerrit/gitweb?p=ttp.git;a=blob;f=parser/sample-TTP-from-tests.ttp;h=45130949b25c6f86b750959d27d04ec2208935fb;hb=HEAD[+parser/sample-TTP-from-tests.ttp+ in the TTP git repository].
-
-.Sample Table Type Pattern (json)
------------------------------------------------------
-{
- "table-type-patterns": {
- "table-type-pattern": [
- {
- "security": {
- "doc": [
- "This TTP is not published for use by ONF. It is an example and for",
- "illustrative purposes only.",
- "If this TTP were published for use it would include",
- "guidance as to any security considerations in this doc member."
- ]
- },
- "NDM_metadata": {
- "authority": "org.opennetworking.fawg",
- "OF_protocol_version": "1.3.3",
- "version": "1.0.0",
- "type": "TTPv1",
- "doc": [
- "Example of a TTP supporting L2 (unicast, multicast, flooding), L3 (unicast only),",
- "and an ACL table."
- ],
- "name": "L2-L3-ACLs"
- },
- "identifiers": [
- {
- "doc": [
- "The VLAN ID of a locally attached L2 subnet on a Router."
- ],
- "var": "<subnet_VID>"
- },
- {
- "doc": [
- "An OpenFlow group identifier (integer) identifying a group table entry",
- "of the type indicated by the variable name"
- ],
- "var": "<<group_entry_types/name>>"
- }
- ],
- "features": [
- {
- "doc": [
- "Flow entry notification Extension – notification of changes in flow entries"
- ],
- "feature": "ext187"
- },
- {
- "doc": [
- "Group notifications Extension – notification of changes in group or meter entries"
- ],
- "feature": "ext235"
- }
- ],
- "meter_table": {
- "meter_types": [
- {
- "name": "ControllerMeterType",
- "bands": [
- {
- "type": "DROP",
- "rate": "1000..10000",
- "burst": "50..200"
- }
- ]
- },
- {
- "name": "TrafficMeter",
- "bands": [
- {
- "type": "DSCP_REMARK",
- "rate": "10000..500000",
- "burst": "50..500"
- },
- {
- "type": "DROP",
- "rate": "10000..500000",
- "burst": "50..500"
- }
- ]
- }
- ],
- "built_in_meters": [
- {
- "name": "ControllerMeter",
- "meter_id": 1,
- "type": "ControllerMeterType",
- "bands": [
- {
- "rate": 2000,
- "burst": 75
- }
- ]
- },
- {
- "name": "AllArpMeter",
- "meter_id": 2,
- "type": "ControllerMeterType",
- "bands": [
- {
- "rate": 1000,
- "burst": 50
- }
- ]
- }
- ]
- },
- "table_map": [
- {
- "name": "ControlFrame",
- "number": 0
- },
- {
- "name": "IngressVLAN",
- "number": 10
- },
- {
- "name": "MacLearning",
- "number": 20
- },
- {
- "name": "ACL",
- "number": 30
- },
- {
- "name": "L2",
- "number": 40
- },
- {
- "name": "ProtoFilter",
- "number": 50
- },
- {
- "name": "IPv4",
- "number": 60
- },
- {
- "name": "IPv6",
- "number": 80
- }
- ],
- "parameters": [
- {
- "doc": [
- "documentation"
- ],
- "name": "Showing-curt-how-this-works",
- "type": "type1"
- }
- ],
- "flow_tables": [
- {
- "doc": [
- "Filters L2 control reserved destination addresses and",
- "may forward control packets to the controller.",
- "Directs all other packets to the Ingress VLAN table."
- ],
- "name": "ControlFrame",
- "flow_mod_types": [
- {
- "doc": [
- "This match/action pair allows for flow_mods that match on either",
- "ETH_TYPE or ETH_DST (or both) and send the packet to the",
- "controller, subject to metering."
- ],
- "name": "Frame-To-Controller",
- "match_set": [
- {
- "field": "ETH_TYPE",
- "match_type": "all_or_exact"
- },
- {
- "field": "ETH_DST",
- "match_type": "exact"
- }
- ],
- "instruction_set": [
- {
- "doc": [
- "This meter may be used to limit the rate of PACKET_IN frames",
- "sent to the controller"
- ],
- "instruction": "METER",
- "meter_name": "ControllerMeter"
- },
- {
- "instruction": "APPLY_ACTIONS",
- "actions": [
- {
- "action": "OUTPUT",
- "port": "CONTROLLER"
- }
- ]
- }
- ]
- }
- ],
- "built_in_flow_mods": [
- {
- "doc": [
- "Mandatory filtering of control frames with C-VLAN Bridge reserved DA."
- ],
- "name": "Control-Frame-Filter",
- "priority": "1",
- "match_set": [
- {
- "field": "ETH_DST",
- "mask": "0xfffffffffff0",
- "value": "0x0180C2000000"
- }
- ]
- },
- {
- "doc": [
- "Mandatory miss flow_mod, sends packets to IngressVLAN table."
- ],
- "name": "Non-Control-Frame",
- "priority": "0",
- "instruction_set": [
- {
- "instruction": "GOTO_TABLE",
- "table": "IngressVLAN"
- }
- ]
- }
- ]
- }
- ],
- "group_entry_types": [
- {
- "doc": [
- "Output to a port, removing VLAN tag if needed.",
- "Entry per port, plus entry per untagged VID per port."
- ],
- "name": "EgressPort",
- "group_type": "INDIRECT",
- "bucket_types": [
- {
- "name": "OutputTagged",
- "action_set": [
- {
- "action": "OUTPUT",
- "port": "<port_no>"
- }
- ]
- },
- {
- "name": "OutputUntagged",
- "action_set": [
- {
- "action": "POP_VLAN"
- },
- {
- "action": "OUTPUT",
- "port": "<port_no>"
- }
- ]
- },
- {
- "opt_tag": "VID-X",
- "name": "OutputVIDTranslate",
- "action_set": [
- {
- "action": "SET_FIELD",
- "field": "VLAN_VID",
- "value": "<local_vid>"
- },
- {
- "action": "OUTPUT",
- "port": "<port_no>"
- }
- ]
- }
- ]
- }
- ],
- "flow_paths": [
- {
- "doc": [
- "This object contains just a few examples of flow paths, it is not",
- "a comprehensive list of the flow paths required for this TTP. It is",
- "intended that the flow paths array could include either a list of",
- "required flow paths or a list of specific flow paths that are not",
- "required (whichever is more concise or more useful."
- ],
- "name": "L2-2",
- "path": [
- "Non-Control-Frame",
- "IV-pass",
- "Known-MAC",
- "ACLskip",
- "L2-Unicast",
- "EgressPort"
- ]
- },
- {
- "name": "L2-3",
- "path": [
- "Non-Control-Frame",
- "IV-pass",
- "Known-MAC",
- "ACLskip",
- "L2-Multicast",
- "L2Mcast",
- "[EgressPort]"
- ]
- },
- {
- "name": "L2-4",
- "path": [
- "Non-Control-Frame",
- "IV-pass",
- "Known-MAC",
- "ACL-skip",
- "VID-flood",
- "VIDflood",
- "[EgressPort]"
- ]
- },
- {
- "name": "L2-5",
- "path": [
- "Non-Control-Frame",
- "IV-pass",
- "Known-MAC",
- "ACLskip",
- "L2-Drop"
- ]
- },
- {
- "name": "v4-1",
- "path": [
- "Non-Control-Frame",
- "IV-pass",
- "Known-MAC",
- "ACLskip",
- "L2-Router-MAC",
- "IPv4",
- "v4-Unicast",
- "NextHop",
- "EgressPort"
- ]
- },
- {
- "name": "v4-2",
- "path": [
- "Non-Control-Frame",
- "IV-pass",
- "Known-MAC",
- "ACLskip",
- "L2-Router-MAC",
- "IPv4",
- "v4-Unicast-ECMP",
- "L3ECMP",
- "NextHop",
- "EgressPort"
- ]
- }
- ]
- }
- ]
- }
-}
------------------------------------------------------
-
-==== Making a REST Call
-
-In this example we'll do a PUT to install the sample TTP from above
-into OpenDaylight and then retrieve it both as json and as xml. We'll
-use the https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm[
-Postman - REST Client] for Chrome in the examples, but any method of
-accessing REST should work.
-
-First, we'll fill in the basic information:
-
-.Filling in URL, content, Content-Type and basic auth
-image::ttp-screen1-basic-auth.png[width=500]
-
-. Set the URL to +http://localhost:8181/restconf/config/onf-ttp:opendaylight-ttps/onf-ttp:table-type-patterns/+
-. Set the action to +PUT+
-. Click Headers and
-. Set a header for +Content-Type+ to +application/json+
-. Make sure the content is set to raw and
-. Copy the sample TTP from above into the content
-. Click the Basic Auth tab and
-. Set the username and password to admin
-. Click Refresh headers
-
-.Refreshing basic auth headers
-image::ttp-screen2-applied-basic-auth.png[width=500]
-
-After clicking Refresh headers, we can see that a new header
-(+Authorization+) has been created and this will allow us to
-authenticate to make the REST call.
-
-.PUTting a TTP
-image::ttp-screen3-sent-put.png[width=500]
-
-At this point, clicking send should result in a Status response of +200
-OK+ indicating we've successfully PUT the TTP into OpenDaylight.
-
-.Retrieving the TTP as json via a GET
-image::ttp-screen4-get-json.png[width=500]
-
-We can now retrieve the TTP by:
-
-. Changing the action to +GET+
-. Setting an +Accept+ header to +application/json+ and
-. Pressing send
-
-.Retrieving the TTP as xml via a GET
-image::ttp-screen5-get-xml.png[width=500]
-
-The same process can retrieve the content as xml by setting the
-+Accept+ header to +application/xml+.
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/ttp-model-developer-guide.html
== Virtual Tenant Network (VTN)
-include::vtn-overview.adoc[VTN Overview]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/virtual-tenant-network-(vtn)-developer-guide.html
+++ /dev/null
-=== OpenDaylight Virtual Tenant Network (VTN) Overview
-
-OpenDaylight Virtual Tenant Network (VTN) is an application that provides multi-tenant virtual network on an SDN controller.
-
-Conventionally, huge investment in the network systems and operating expenses are needed because the network is configured as a silo for each department and system. Therefore various network appliances must be installed for each tenant and those boxes cannot be shared with others. It is a heavy work to design, implement and operate the entire complex network.
-
-The uniqueness of VTN is a logical abstraction plane. This enables the complete separation of logical plane from physical plane. Users can design and deploy any desired network without knowing the physical network topology or bandwidth restrictions.
-
-VTN allows the users to define the network with a look and feel of conventional L2/L3 network. Once the network is designed on VTN, it will automatically be mapped into underlying physical network, and then configured on the individual switch leverage SDN control protocol. The definition of logical plane makes it possible not only to hide the complexity of the underlying network but also to better manage network resources. It achieves reducing reconfiguration time of network services and minimizing network configuration errors. OpenDaylight Virtual Tenant Network (VTN) is an application that provides multi-tenant virtual network on an SDN controller. It provides API for creating a common virtual network irrespective of the physical network.
-
-.VTN Architecture
-image::vtn/vtn-overview.png[width=500]
-
-It is implemented as two major components
-
-* <<_vtn_manager,VTN Manager>>
-* <<_vtn_coordinator,VTN Coordinator>>
-
-==== VTN Manager
-An OpenDaylight Plugin that interacts with other modules to implement the components of the VTN model. It also provides a REST interface to configure VTN components in OpenDaylight. VTN Manager is implemented as one plugin to the OpenDaylight. This provides a REST interface to create/update/delete VTN components. The user command in VTN Coordinator is translated as REST API to VTN Manager by the OpenDaylight Driver component. In addition to the above mentioned role, it also provides an implementation to the OpenStack L2 Network Functions API.
-
-===== Function Outline
-
-The table identifies the functions and the interface used by VTN Components:
-
-[options="header"]
-|===
-| Component | Interface | Purpose
-| VTN Manager |RESTful API | Configure VTN Virtualization model components in OpenDaylight
-| VTN Manager | Neutron API implementation | Handle Networks API from OpenStack (Neutron Interface)
-| VTN Coordinator | RESTful API |
-(1) Uses the RESTful interface of VTN Manager and configures VTN Virtualization model components in OpenDaylight. +
-(2) Handles multiple OpenDaylight orchestration. +
-(3) Provides API to read the physical network details. See https://wiki.OpenDaylight.org/view/OpenDaylight_Virtual_Tenant_Network_(VTN):VTN_Coordinator:RestApi:L2_Network_Example_Using_VTN_Virtualization[samples] for usage.
-
-|===
-
-===== Feature Overview
-
-There are three features
-
-* *odl-vtn-manager* provides VTN Manager's JAVA API.
-* *odl-vtn-manager-rest* provides VTN Manager's REST API.
-* *odl-vtn-manager-neutron* provides the integration with Neutron interface.
-
-REST API documentation for VTN Manager, please refer to:
-https://jenkins.opendaylight.org/releng/view/vtn/job/vtn-merge-beryllium/lastSuccessfulBuild/artifact/manager/model/target/site/models/
-
-For VTN Java API documentation, please refer to: https://jenkins.opendaylight.org/releng/view/vtn/job/vtn-merge-beryllium/lastSuccessfulBuild/artifact/target/apidocs/index.html
-
-Once the Karaf distribution is up, install dlux and apidocs.
-
-----
-feature:install odl-dlux-all odl-mdsal-apidocs
-----
-
-====== Logging In
-
-To Log in to DLUX, after installing the application:
-
-* Open a browser and enter the login URL as http://<OpenDaylight-IP>:8181/index.html.
-
-NOTE: Replace "<OpenDaylight-IP>" with the IP address of OpenDaylight based on your environment.
-
-* Login to the application with user ID and password credentials as admin.
-
-NOTE: admin is the only default user available for DLUX in this release.
-
-* In the right hand side frame, click "Yang UI".
-
-YANG documentation for VTN Manager, please refer to: https://jenkins.opendaylight.org/releng/view/vtn/job/vtn-merge-beryllium/lastSuccessfulBuild/artifact/manager/model/target/site/models/
-
-==== VTN Coordinator
-
-The VTN Coordinator is an external application that provides a REST interface for an user to use OpenDaylight VTN Virtualization. It interacts with the VTN Manager plugin to implement the user configuration. It is also capable of multiple OpenDaylight orchestration. It realizes VTN provisioning in OpenDaylight instances. In the OpenDaylight architecture VTN Coordinator is part of the network application, orchestration and services layer. VTN Coordinator will use the REST interface exposed by the VTN Manger to realize the virtual network using OpenDaylight. It uses OpenDaylight APIs (REST) to construct the virtual network in OpenDaylight instances. It provides REST APIs for northbound VTN applications and supports virtual networks spanning across multiple OpenDaylight by coordinating across OpenDaylight.
-
-VTN Coordinator Components:
-
-* Transaction Coordinator
-* Unified Provider Physical Layer (UPPL)
-* Unified Provider Logical LAyer (UPLL)
-* OpenDaylight Controller Diver (ODC Driver)
-
-===== OpenDaylight Virtual Tenant Network (VTN) API Overview
-
-The VTN API module is a sub component of the VTN Coordinator and provides the northbound REST API interface for VTN applications. It consists of two subcomponents:
-
-* Web Server
-* VTN service Java API Library
-
-.VTN-Coordinator_api-architechture
-image::vtn/vtn-coordinator-api-architecture.png[width=300]
-
-====== Web Server
-
-The Web Server module handles the REST APIs received from the VTN applications. It translates the REST APIs to the appropriate Java APIs.
-
-The main functions of this module are:
-
-* Starts via the startup script `catalina.sh`.
-* VTN Application sends HTTP request to Web server in XML or JSON format.
-* Creates a session and acquire a read/write lock.
-* Invokes the VTN Service Java API Library corresponding to the specified URI.
-* Returns the response to the VTN Application.
-
-====== WebServer Class Details
-The list below shows the classes available for Web Server module and their descriptions:
-
-Init Manager:: It is a singleton class for executing the acquisition of configuration information from properties file, log initialization, initialization of VTN Service Java API Library. Executed by init() of VtnServiceWebAPIServlet.
-Configuration Manager:: Maintains the configuration information acquired from properties file.
-VtnServiceCommonUtil:: Utility class
-VtnServiceWebUtil:: Utility class
-VtnServiceWebAPIServlet:: Receives HTTP request from VTN Application and calls the method of corresponding VtnServiceWebAPIHandler.
-herits class HttpServlet, and overrides doGet(), doPut(), doDelete(), doPost().
-VtnServiceWebAPIHandler:: Creates JsonObject(com.google.gson) from HTTP request, and calls method of corresponding VtnServiceWebAPIController.
-VtnServiceWebAPIController:: Creates RestResource() class and calls UPLL API/UPPL API through Java API.
- the time of calling UPLL API/UPPL API, performs the creation/deletion of session, acquisition/release of configuration mode, acquisition/release of read lock by TC API through Java API.
-Data Converter:: Converts HTTP request to JsonObject and JsonXML to JSON.
-
-
-====== VTN Service Java API Library
-It provides the Java API library to communicate with the lower layer modules in the VTN Coordinator.
-The main functions of this library are:
-
-* Creates an IPC client session to the lower layer.
-* Converts the request to IPC framework format.
-* Invokes the lower layer API (i.e. UPPL API, UPLL API, TC API).
-* Returns the response from the lower layer to the web server
-* VTN Service Java API Library Class Details
-
-===== Feature Overview
-
-VTN Coordinator doesn't have Karaf features.
-
-For VTN Coordinator REST API, please refer to: https://wiki.opendaylight.org/view/OpenDaylight_Virtual_Tenant_Network_%28VTN%29:VTN_Coordinator:RestApi
-
-==== Usage Examples
-* https://wiki.OpenDaylight.org/view/OpenDaylight_Virtual_Tenant_Network_(VTN):VTN_Coordinator:RestApi:How_to_configure_L2_Network_with_Single_Controller[L2 Network using Single Controller]
-
+++ /dev/null
-=== YANG Java Binding: Mapping rules\r
-This chapter covers the details of mapping YANG to Java.\r
-\r
-NOTE: The following source code examples does not show canonical generated\r
-code, but rather illustrative example. Generated classes and interfaces may\r
-differ from this examples, but APIs are preserved.\r
-\r
-==== General conversion rules\r
-\r
-===== Package names of YANG models\r
-\r
-The package name consists of the following parts: +\r
-\r
-* *Opendaylight prefix* - Specifies the opendaylight prefix. Every package name\r
-starts with the prefix `org.opendaylight.yang.gen.v`.\r
-* *Java Binding version* - Specifies the YANG Java Binding version.\r
- Curent Binding version is `1`.\r
-* *Namespace* - Specified by the value of `namespace` substatement.\r
- URI is converted to package name structure.\r
-* *Revision* - Specifies the concatenation of word `rev` and value of `module`\r
- substatements `revision` argument value without leading zeros before month and day.\r
- For example: `rev201379`\r
-\r
-After the package name is generated, we check if it contains any Java keywords\r
-or starts with a digit. If so, then we add an underscore before the offending\r
-token.\r
-\r
-The following is a list of keywords which are prefixed with underscore:\r
-\r
-abstract, assert, boolean, break, byte, case, catch, char, class, const,\r
-continue, default, double, do, else, enum, extends, false, final, finally,\r
-float, for, goto, if, implements, import, instanceof, int, interface, long,\r
-native, new, null, package, private, protected, public, return, short, static,\r
-strictfp, super, switch, synchronized, this, throw, throws, transient, true, try,\r
-void, volatile, while\r
-\r
-As an example suppose following yang model:\r
-\r
-[source, yang]\r
-----\r
-module module {\r
- namespace "urn:2:case#module";\r
- prefix "sbd";\r
- organization "OPEN DAYLIGHT";\r
- contact "http://www.example.com/";\r
- revision 2013-07-09 {\r
- }\r
-}\r
-----\r
-\r
-After applying rules (replacing digits and Java keywords) the resulting\r
-package name is `org.opendaylight.yang.gen.v1.urn._2._case.module.rev201379`\r
-\r
-===== Additional Packages\r
-\r
-In cases when YANG statement contain some of specific YANG\r
-statements additional packages are generated to designate this containment.\r
-Table below provides details of parent statement and nested statements, which\r
-yields additional package generation:\r
-\r
-[options="header"]\r
-|===\r
-|Parent statement | Substatement\r
-|`list` |list, container, choice\r
-|`container` | list, container, choice\r
-|`choice` | leaf, list, leaf-list, container, case\r
-|`case` | list, container, choice\r
-|rpc `input` or `output` | list, container, (choice isn't supported)\r
-|`notification` | list, container, (choice isn't supported)\r
-|`augment` | list, container, choice, case |\r
-|===\r
-\r
-Substatements are not only mapped to Java setter methods in the interface\r
-representing the parent statement, but they also generate packages with\r
-names consisting of the parent statement package name with the parent statement\r
-name appended.\r
-\r
-For example, this YANG model considers the container statement `cont` as the\r
-direct substatement of the module.\r
-\r
-[source, yang]\r
-----\r
-container cont {\r
- container cont-inner {\r
- }\r
- list outter-list {\r
- list list-in-list {\r
- }\r
- }\r
-}\r
-----\r
-\r
-Container `cont` is the parent statement for the substatements\r
-`cont-inner` and `outter-list`. `list outter-list` is the parent\r
-statement for substatement `list-in-list`.\r
-\r
-Java code is generated in the following structure: +\r
-\r
-* `org.opendaylight.yang.gen.v1.urn.module.rev201379` - package contains direct\r
- substatements of module statement\r
-** `Cont.java`\r
-* `org.opendaylight.yang.gen.v1.urn.module.rev201379.cont` - package contains\r
- substatements of `cont` container statement\r
-** `ContInner.java` - interface representing container `cont-inner`\r
-** `OutterList.java` - interface representing list `outer-list`\r
-* `org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.outter.list` - package\r
- contains substatements of outter-list list element\r
- ** `ListInList.java`\r
-\r
-===== Class and interface names\r
-Some YANG statements are mapped to Java classes and interfaces. The name of YANG\r
-element may contain various characters which aren't permitted in Java class names.\r
-Firstly whitespaces are trimmed from YANG name. Next the characters space, -, `\r
-are deleted and the subsequent letter is capitalized. At the end, first letter is\r
-capitalized.\r
-\r
-For example, \r
-`example-name_ without_capitalization` would map to\r
-`ExampleNameWithoutCapitalization`.\r
-\r
-===== Getter and setter names\r
-In some cases, YANG statements are converted to getter and/or setter methods.\r
-The process for getter is:\r
-\r
-. the name of YANG statement is converted to Java class name style as \r
- <<_class_and_interface_names,explained above>>.\r
-. the word `get` is added as prefix, if resulting type is `Boolean`, the name\r
- is prefixed with `is` prefix instead of `get`.\r
-. the return type of the getter method is set to Java type representing substatement\r
-\r
-The process for setter is:\r
-\r
-. the name of YANG statement is converted to Java class name style as\r
- <<_class_and_interface_names,explained above>>.\r
-. the word `set` is added as prefix\r
-. the input parameter name is set to element's name converted to Java parameter style\r
-. the return parameter is set to builder type\r
-\r
-==== Statement specific mapping\r
-\r
-===== module statement\r
-\r
-YANG `module` statement is converted to Java as two Java classes.\r
-Each of the classes is in the separate Java file. The names of Java files are\r
-composed as follows:\r
-`<module name><suffix>.java` where `<suffix>` is either data or service.\r
-\r
-====== Data Interface\r
-\r
-Data Interface has a mapping similar to container, but contains only top level\r
-nodes defined in module.\r
-\r
-Data interface serves only as marker interface for type-safe APIs of\r
-`InstanceIdentifier`.\r
-\r
-====== Service Interface\r
-\r
-Service Interface serves to describe RPC contract defined in the module.\r
-This RPC contract is defined by `rpc` statements.\r
-\r
-RPC implementation usually implement this interface and users of the RPCs\r
-use this interface to invoke RPCs.\r
-\r
-===== container statement\r
-YANG containers are mapped to Java interfaces which extend the Java DataObject and\r
-Augmentable<container-interface>, where container-interface is the name of the mapped\r
-interface.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-container cont {\r
-\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.Cont.java\r
-[source, java]\r
-----\r
-public interface Cont extends ChildOf<...>, Augmentable<Cont> {\r
-}\r
-----\r
-\r
-===== Leaf statement\r
-Each leaf has to contain at least one type substatement. The leaf is mapped to\r
-getter method of parent statement with return type equal to type substatement\r
-value.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-container cont {\r
- leaf lf {\r
- type string;\r
- }\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.Cont.java\r
-[source, java]\r
-----\r
-public interface Cont extends DataObject, Augmentable<Cont> {\r
- String getLf(); // <1>\r
-}\r
-----\r
-\r
-<1> Represents `leaf lf`\r
-\r
-===== leaf-list statement\r
-Each leaf-list has to contain one type substatement. The leaf-list is mapped\r
-to getter method of parent statement with return type equal to List of type\r
-substatement value.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-container cont {\r
- leaf-list lf-lst {\r
- type string;\r
- }\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.Cont.java\r
-[source, java]\r
-----\r
-public interface Cont extends DataObject, Augmentable<Cont> {\r
- List<String> getLfLst();\r
-}\r
-----\r
-\r
-===== list statement\r
-\r
-`list` statements are mapped to Java interfaces and a getter method is\r
-generated in the interface associated with it's parent statement.\r
-The return type of getter the method is a Java List of objects implementing\r
-the interface generated corresponding to the `list statement.\r
-Mapping of `list` substatement to Java:\r
-\r
-//[options="header"]\r
-//|===\r
-//|Substatement|Mapping to Java\r
-//|Key|Class\r
-//|===\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-container cont {\r
- list outter-list {\r
- key "leaf-in-list";\r
- leaf number {\r
- type uint64;\r
- }\r
- }\r
-}\r
-----\r
-\r
-The list statement `example-list` is mapped to the Java interface `ExampleList` and\r
-the `Cont` interface (parent of `ExampleList`) contains getter method with return\r
-type `List<ExampleList>`. The presence of a `key` statement, triggers generation\r
-of `ExampleListKey`, which may be used to identify item in list.\r
-\r
-The end result is this Java:\r
-\r
-.OutterList.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont;\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-import org.opendaylight.yangtools.yang.binding.Augmentable;\r
-import Java.util.List;\r
-import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.outter.list.ListInList;\r
-\r
-public interface OutterList extends DataObject, Augmentable<OutterList> {\r
-\r
- List<String> getLeafListInList();\r
-\r
- List<ListInList> getListInList();\r
-\r
- /*\r
- Returns Primary Key of Yang List Type\r
- */\r
- OutterListKey getOutterListKey();\r
-\r
-}\r
-----\r
-\r
-.OutterListKey.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont;\r
-\r
-import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.OutterListKey;\r
-import Java.math.BigInteger;\r
-\r
-public class OutterListKey {\r
-\r
- private BigInteger _leafInList;\r
-\r
- public OutterListKey(BigInteger _leafInList) {\r
- super();\r
- this_leafInList = _leafInList;\r
- }\r
-\r
- public BigInteger getLeafInList() {\r
- return _leafInList;\r
- }\r
-\r
- @Override\r
- public int hashCode() {\r
- final int prime = 31;\r
- int result = 1;\r
- result = prime * result + ((_leafInList == null) ? 0 : _leafInList.hashCode());\r
- return result;\r
- }\r
-\r
- @Override\r
- public boolean equals(Object obj) {\r
- if (this == obj) {\r
- return true;\r
- }\r
- if (obj == null) {\r
- return false;\r
- }\r
- if (getClass() != obj.getClass()) {\r
- return false;\r
- }\r
- OutterListKey other = (OutterListKey) obj;\r
- if (_leafInList == null) {\r
- if (other._LeafInList != null) {\r
- return false;\r
- }\r
- } else if(!_leafInList.equals(other._leafInList)) {\r
- return false;\r
- }\r
- return true;\r
- }\r
-\r
- @Override\r
- public String toString() {\r
- StringBuilder builder = new StringBuilder();\r
- builder.append("OutterListKey [_leafInList=");\r
- builder.append(_leafInList);\r
- builder.append("]");\r
- return builder.toString();\r
- }\r
-}\r
-----\r
-\r
-===== choice and case statements\r
-A `choice` element is mapped in mostly the same way a `list` element is. The\r
-`choice` element is mapped to and interface (marker interface) and a new getter\r
-method with the return type of a Java `List` of this marker interfaces is added\r
-to the interface corresponding to the parent statement. Any `case` \r
-substatements are mapped to Java interfaces which extend the marker interface.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-container cont {\r
- choice example-choice {\r
- case foo-case {\r
- leaf foo {\r
- type string;\r
- }\r
- }\r
- case bar-case {\r
- leaf bar {\r
- type string;\r
- }\r
- }\r
- }\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.Cont.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-import org.opendaylight.yangtools.yang.binding.Augmentable;\r
-import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.ChoiceTest;\r
-\r
-public interface Cont extends DataObject, Augmentable<Cont> {\r
-\r
- ExampleChoice getExampleChoice();\r
-\r
-}\r
-----\r
-\r
-.ExampleChoice.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont;\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-\r
-public interface ExampleChoice extends DataContainer {\r
-}\r
-----\r
-\r
-.FooCase.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.example.choice;\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-import org.opendaylight.yangtools.yang.binding.Augmentable;\r
-import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.ChoiceTest;\r
-\r
-public interface FooCase extends ExampleChoice, DataObject, Augmentable<FooCase> {\r
-\r
- String getFoo();\r
-\r
-}\r
-----\r
-\r
-.BarCase.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.example.choice;\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-import org.opendaylight.yangtools.yang.binding.Augmentable;\r
-import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.ChoiceTest;\r
-\r
-public interface BarCase extends ExampleChoice, DataObject, Augmentable<BarCase> {\r
-\r
- String getBar();\r
-\r
-}\r
-----\r
-\r
-===== grouping and uses statements\r
-`grouping`s are mapped to Java interfaces. `uses` statements in some element\r
-(using of concrete grouping) are mapped as extension of interface for this\r
-element with the interface which represents grouping.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG Model\r
-[source, yang]\r
-----\r
-grouping grp {\r
- leaf foo {\r
- type string;\r
- }\r
-}\r
-\r
-container cont {\r
- uses grp;\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.Grp.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-\r
-public interface Grp extends DataObject {\r
-\r
- String getFoo();\r
-\r
-}\r
-----\r
-\r
-.Cont.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-import org.opendaylight.yangtools.yang.binding.Augmentable;\r
-\r
-public interface Cont extends DataObject, Augmentable<Cont>, Grp {\r
-}\r
-----\r
-\r
-\r
-===== rpc, input and output statements\r
-An `rpc` statement is mapped to Java as method of class `ModuleService.java`.\r
-Any substatements of an `rpc` are mapped as follows:\r
-\r
-[options="header"]\r
-|===\r
-|Rpc Substatement|Mapping\r
-|input|presence of input statement triggers generation of interface\r
-|output|presence of output statement triggers generation of interface\r
-|===\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-rpc rpc-test1 {\r
- output {\r
- leaf lf-output {\r
- type string;\r
- }\r
- }\r
- input {\r
- leaf lf-input {\r
- type string;\r
- }\r
- }\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.ModuleService.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-\r
-import Java.util.concurrent.Future;\r
-import org.opendaylight.yangtools.yang.common.RpcResult;\r
-\r
-public interface ModuleService {\r
-\r
- Future<RpcResult<RpcTest1Output>> rpcTest1(RpcTest1Input input);\r
-\r
-}\r
-----\r
-\r
-.RpcTest1Input.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-\r
-public interface RpcTest1Input {\r
-\r
- String getLfInput();\r
-\r
-}\r
-----\r
-\r
-.RpcTest1Output.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-\r
-public interface RpcTest1Output {\r
-\r
- String getLfOutput();\r
-\r
-}\r
-----\r
-\r
-\r
-===== notification statement\r
-\r
-`notification` statements are mapped to Java interfaces which extend\r
-the Notification interface.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-notification notif {\r
- }\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.Notif.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-import org.opendaylight.yangtools.yang.binding.Augmentable;\r
-import org.opendaylight.yangtools.yang.binding.Notification;\r
-\r
-public interface Notif extends DataObject, Augmentable<Notif>, Notification {\r
-}\r
-----\r
-\r
-==== augment statement\r
-`augment` statements are mapped to Java interfaces. The interface starts with\r
-the same name as the name of augmented interface with a suffix corresponding to\r
-the order number of augmenting interface. The augmenting interface also extends\r
-`Augmentation<>` with actual type parameter equal to augmented interface.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG Model\r
-[source, yang]\r
-----\r
-container cont {\r
-}\r
-\r
-augment "/cont" {\r
- leaf additional-value {\r
- type string;\r
- }\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.Cont.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-import org.opendaylight.yangtools.yang.binding.Augmentable;\r
-\r
-public interface Cont extends DataObject, Augmentable<Cont> {\r
-\r
-}\r
-----\r
-\r
-.Cont1.java\r
-[source, java]\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-\r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-import org.opendaylight.yangtools.yang.binding.Augmentation;\r
-\r
-public interface Cont1 extends DataObject, Augmentation<Cont> {\r
-\r
-}\r
-----\r
-\r
-==== YANG Type mapping\r
-\r
-===== typedef statement\r
-YANG `typedef` statements are mapped to Java classes. A `typedef` may contain following\r
-substatements:\r
-\r
-[options="header"]\r
-|===\r
-|Substatement | Behaviour\r
-|type| determines wrapped type and how class will be generated\r
-|descripton| Javadoc description\r
-|units| is not mapped\r
-|default|is not mapped\r
-|===\r
-\r
-====== Valid Arguments Type\r
-\r
-Simple values of type argument are mapped as follows:\r
-\r
-[options="header"]\r
-|===\r
-|YANG Type | Java type\r
-|boolean| Boolean\r
-|empty| Boolean\r
-|int8| Byte\r
-|int16|Short\r
-|int32|Integer\r
-|int64|Long\r
-|string|String or, wrapper class (if pattern substatement is specified)\r
-|decimal64|Double\r
-|uint8|Short\r
-|uint16|Integer\r
-|uint32|Long\r
-|uint64|BigInteger\r
-|binary|byte[]\r
-|===\r
-\r
-Complex values of type argument are mapped as follows:\r
-\r
-[options="header"]\r
-|===\r
-|Argument Type| Java type\r
-|enumeration| generated java enum\r
-|bits| generated class for bits\r
-|leafref| same type as referenced leaf\r
-|identityref| Class\r
-|union| generated java class\r
-|instance-identifier| `org.opendaylight.yangtools.yang.binding.InstanceIdentifier`\r
-|===\r
-\r
-===== Enumeration Substatement Enum\r
-The YANG `enumeration` type has to contain some `enum` substatements. An `enumeration` is mapped as Java enum type (standalone class) and every YANG enum substatements is mapped to Java enum's predefined values.\r
-\r
-An `enum` statement can have following substatements:\r
-\r
-[options="header"]\r
-|===\r
-|Enum's Substatement | Java mapping\r
-|description|is not mapped in API\r
-|value| mapped as input parameter for every predefined value of enum\r
-|===\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-typedef typedef-enumeration {\r
- type enumeration {\r
- enum enum1 {\r
- description "enum1 description";\r
- value 18;\r
- }\r
- enum enum2 {\r
- value 16;\r
- }\r
- enum enum3 {\r
- }\r
- }\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.TypedefEnumeration.java\r
-[source, java]\r
-----\r
-public enum TypedefEnumeration {\r
- Enum1(18),\r
- Enum2(16),\r
- Enum3(19);\r
-\r
- int value;\r
-\r
- private TypedefEnumeration(int value) {\r
- this.value = value;\r
- }\r
-}\r
-----\r
-\r
-===== Bits's Substatement Bit\r
-The YANG `bits` type has to contain some bit substatements. YANG `bits` is mapped to\r
-a Java class (standalone class) and every YANG `bits` substatements is mapped to a\r
-boolean attribute of that class. In addition, the class provides overridden versions\r
-of the Object methods `hashCode`, `toString`, and `equals`.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG Model\r
-[source, yang]\r
-----\r
-typedef typedef-bits {\r
- type bits {\r
- bit first-bit {\r
- description "first-bit description";\r
- position 15;\r
- }\r
- bit second-bit;\r
- }\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.TypedefBits.java\r
-[source, java]\r
-----\r
-public class TypedefBits {\r
-\r
- private Boolean firstBit;\r
- private Boolean secondBit;\r
-\r
- public TypedefBits() {\r
- super();\r
- }\r
-\r
- public Boolean getFirstBit() {\r
- return firstBit;\r
- }\r
-\r
- public void setFirstBit(Boolean firstBit) {\r
- this.firstBit = firstBit;\r
- }\r
-\r
- public Boolean getSecondBit() {\r
- return secondBit;\r
- }\r
-\r
- public void setSecondBit(Boolean secondBit) {\r
- this.secondBit = secondBit;\r
- }\r
-\r
- @Override\r
- public int hashCode() {\r
- final int prime = 31;\r
- int result = 1;\r
- result = prime * result +\r
- ((firstBit == null) ? 0 : firstBit.hashCode());\r
- result = prime * result +\r
- ((secondBit == null) ? 0 : secondBit.hashCode());\r
- return result;\r
- }\r
-\r
- @Override\r
- public boolean equals(Object obj) {\r
- if (this == obj) {\r
- return true;\r
- }\r
- if (obj == null) {\r
- return false;\r
- }\r
- if (getClass() != obj.getClass()) {\r
- return false;\r
- }\r
- TypedefBits other = (TypedefBits) obj;\r
- if (firstBit == null) {\r
- if (other.firstBit != null) {\r
- return false;\r
- }\r
- } else if(!firstBit.equals(other.firstBit)) {\r
- return false;\r
- }\r
- if (secondBit == null) {\r
- if (other.secondBit != null) {\r
- return false;\r
- }\r
- } else if(!secondBit.equals(other.secondBit)) {\r
- return false;\r
- }\r
- return true;\r
- }\r
-\r
- @Override\r
- public String toString() {\r
- StringBuilder builder = new StringBuilder();\r
- builder.append("TypedefBits [firstBit=");\r
- builder.append(firstBit);\r
- builder.append(", secondBit=");\r
- builder.append(secondBit);\r
- builder.append("]");\r
- return builder.toString();\r
- }\r
-}\r
-----\r
-\r
-===== Union's Substatement Type\r
-If the type of a `typedef` is `union`, it has to contain `type` substatements.\r
-The `union typedef` is mapped to class and its `type` substatements are mapped\r
-to private class members. Every YANG union subtype gets its own Java constructor\r
-with a parameter which represent just that one attribute.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-typedef typedef-union {\r
- type union {\r
- type int32;\r
- type string;\r
- }\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.TypdefUnion.java\r
-[source, java]\r
-----\r
-public class TypedefUnion {\r
-\r
- private Integer int32;\r
- private String string;\r
-\r
- public TypedefUnion(Integer int32) {\r
- super();\r
- this.int32 = int32;\r
- }\r
-\r
- public TypedefUnion(String string) {\r
- super();\r
- this.string = string;\r
- }\r
-\r
- public Integer getInt32() {\r
- return int32;\r
- }\r
-\r
- public String getString() {\r
- return string;\r
- }\r
-\r
- @Override\r
- public int hashCode() {\r
- final int prime = 31;\r
- int result = 1;\r
- result = prime * result + ((int32 == null) ? 0 : int32.hashCode());\r
- result = prime * result + ((string == null) ? 0 : string.hashCode());\r
- return result;\r
- }\r
-\r
- @Override\r
- public boolean equals(Object obj) {\r
- if (this == obj) {\r
- return true;\r
- }\r
- if (obj == null) {\r
- return false;\r
- }\r
- if (getClass() != obj.getClass()) {\r
- return false;\r
- }\r
- TypedefUnion other = (TypedefUnion) obj;\r
- if (int32 == null) {\r
- if (other.int32 != null) {\r
- return false;\r
- }\r
- } else if(!int32.equals(other.int32)) {\r
- return false;\r
- }\r
- if (string == null) {\r
- if (other.string != null) {\r
- return false;\r
- }\r
- } else if(!string.equals(other.string)) {\r
- return false;\r
- }\r
- return true;\r
- }\r
-\r
- @Override\r
- public String toString() {\r
- StringBuilder builder = new StringBuilder();\r
- builder.append("TypedefUnion [int32=");\r
- builder.append(int32);\r
- builder.append(", string=");\r
- builder.append(string);\r
- builder.append("]");\r
- return builder.toString();\r
- }\r
-}\r
-----\r
-\r
-===== String Mapping\r
-The YANG `string` type can contain the substatements `length`\r
-and `pattern` which are mapped as follows:\r
-\r
-[options="header"]\r
-|===\r
-|Type substatements | Mapping to Java\r
-| length | not mapped\r
-| pattern |\r
-\r
-. list of string constants = list of patterns +\r
-. list of Pattern objects +\r
-. static initialization block where list of Patterns is initialized from list of string of constants\r
-|===\r
-\r
-For example, the following YANG:\r
-\r
-.YANG model\r
-[source, yang]\r
-----\r
-typedef typedef-string {\r
- type string {\r
- length 44;\r
- pattern "[a][.]*"\r
- }\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.TypedefString.java\r
-[source, java]\r
-----\r
-public class TypedefString {\r
-\r
- private static final List<Pattern> patterns = new ArrayList<Pattern>();\r
- public static final List<String> PATTERN`CONSTANTS = Arrays.asList("[a][.]*");\r
-\r
- static {\r
- for (String regEx : PATTERN`CONSTANTS) {\r
- patterns.add(Pattern.compile(regEx));\r
- }\r
- }\r
-\r
- private String typedefString;\r
-\r
- public TypedefString(String typedefString) {\r
- super();\r
- // Pattern validation\r
- this.typedefString = typedefString;\r
- }\r
-\r
- public String getTypedefString() {\r
- return typedefString;\r
- }\r
-\r
- @Override\r
- public int hashCode() {\r
- final int prime = 31;\r
- int result = 1;\r
- result = prime * result + ((typedefString == null) ? 0 : typedefString.hashCode());\r
- return result;\r
- }\r
-\r
- @Override\r
- public boolean equals(Object obj) {\r
- if (this == obj) {\r
- return true;\r
- }\r
- if (obj == null) {\r
- return false;\r
- }\r
- if (getClass() != obj.getClass()) {\r
- return false;\r
- }\r
- TypedefString other = (TypedefString) obj;\r
- if (typedefString == null) {\r
- if (other.typedefString != null) {\r
- return false;\r
- }\r
- } else if(!typedefString.equals(other.typedefString)) {\r
- return false;\r
- }\r
- return true;\r
- }\r
-\r
- @Override\r
- public String toString() {\r
- StringBuilder builder = new StringBuilder();\r
- builder.append("TypedefString [typedefString=");\r
- builder.append(typedefString);\r
- builder.append("]");\r
- return builder.toString();\r
- }\r
-}\r
-----\r
-\r
-==== identity statement\r
-The purpose of the `identity` statement is to define a new globally unique,\r
-abstract, and untyped value.\r
-\r
-The `base` substatement argument is the name of existing identity from which\r
-the new identity is derived.\r
-\r
-Given that, an `identity` statement is mapped to Java abstract class and\r
-any `base` substatements are mapped as `extends` Java keyword.\r
-The identity name is translated to class name.\r
-\r
-For example, the following YANG:\r
-\r
-.YANG Model\r
-[source, yang]\r
-----\r
-identity toast-type {\r
-\r
-}\r
-\r
-identity white-bread {\r
- base toast-type;\r
-}\r
-----\r
-\r
-is converted into this Java:\r
-\r
-.ToastType.java\r
-[source, java]\r
-----\r
-public abstract class ToastType extends BaseIdentity {\r
- protected ToastType() {\r
- super();\r
- }\r
-}\r
-----\r
-\r
-.WhiteBread.java\r
-[source, java]\r
-----\r
-public abstract class WhiteBread extends ToastType {\r
- protected WhiteBread() {\r
- super();\r
- }\r
-}\r
-----\r
== YANG Tools
-:rfc6020: https://tools.ietf.org/html/rfc6020
-:lhotka-yang-json: https://tools.ietf.org/html/draft-lhotka-netmod-yang-json-01
-=== Overview
-YANG Tools is set of libraries and tooling providing support for use
-{rfc6020}[YANG] for Java (or other JVM-based language) projects and
-applications.
-
-YANG Tools provides following features in OpenDaylight:
-
-- parsing of YANG sources and
-semantic inference of relationship across YANG models as defined in
-{rfc6020}[RFC6020]
-- representation of YANG-modeled data in Java
-** *Normalized Node* representation - DOM-like tree model, which uses conceptual
- meta-model more tailored to YANG and OpenDaylight use-cases than a standard XML
- DOM model allows for.
-** *Java Binding* - concrete data model and classes generated from YANG models,
- designed to provide compile-time safety when working with YANG-modeled data.
-- serialization / deserialization of YANG-modeled data driven by YANG
-models
-** XML - as defined in {rfc6020}[RFC6020]
-** JSON - as defined in {rfc6020}[draft-lhotka-netmod-yang-json-01]
-** Java Binding to Normalized Node and vice-versa
-- Integration of YANG model parsing into Maven build lifecycle and
-support for third-party generators processing YANG models.
-
-YANG Tools project consists of following logical subsystems:
-
-- *Commons* - Set of general purpose code, which is not specific to YANG, but
- is also useful outside YANG Tools implementation.
-- *YANG Model and Parser* - YANG semantic model and lexical and semantic parser
- of YANG models, which creates in-memory cross-referenced represenation of
- YANG models, which is used by other components to determine their behaviour
- based on the model.
-- *YANG Data* - Definition of Normalized Node APIs and Data Tree APIs, reference
- implementation of these APIs and implementation of XML and JSON codecs for
- Normalized Nodes.
-- *YANG Maven Plugin* - Maven plugin which integrates YANG parser into Maven
- build lifecycle and provides code-generation framework for components, which
- wants to generate code or other artefacts based on YANG model.
-- *YANG Java Binding* - Mapping of YANG model to generated Java APIs.
- Java Binding also references to set of compile-time and runtime components which
- implements this mapping, provides generation of classes and APIs based on
- YANG models and integrate these Java Binding objects with **YANG Data** APIs
- and components.
-
-* *Models* - Set of *IETF* and *YANG Tools* models, with generated Java Bindings
- so they could be simply consumed outside of *YANG Tools*.
-
-include::yang-java-binding-explained.adoc[]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/developer-guide/yang-tools.html
+++ /dev/null
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
- <parent>
- <groupId>org.opendaylight.docs</groupId>
- <artifactId>manuals</artifactId>
- <version>0.4.0-SNAPSHOT</version>
- <relativePath>../pom.xml</relativePath>
- </parent>
- <modelVersion>4.0.0</modelVersion>
- <artifactId>openstack</artifactId>
- <packaging>jar</packaging>
- <name>OpenDaylight Docs - Manuals - OpenStack Howto</name>
- <properties>
- <!-- This is set by Jenkins according to the branch. -->
- <release.path.name>local</release.path.name>
- <comments.enabled>1</comments.enabled>
- <bookname>openstack</bookname>
- </properties>
- <!-- ################################################ -->
- <!-- USE "mvn clean generate-sources" to run this POM -->
- <!-- ################################################ -->
- <build>
- <plugins>
- <plugin>
- <groupId>org.asciidoctor</groupId>
- <artifactId>asciidoctor-maven-plugin</artifactId>
- <version>${asciidoctor.version}</version>
- <executions>
- <execution>
- <id>output-docbook</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>process-asciidoc</goal>
- </goals>
- <configuration>
- <backend>docbook5</backend>
- <doctype>book</doctype>
- </configuration>
- </execution>
- </executions>
- <configuration>
- <sourceDirectory>src/main/asciidoc</sourceDirectory>
- <sourceDocumentName>${bookname}.adoc</sourceDocumentName>
- <imagesDir>./images</imagesDir>
- </configuration>
- </plugin>
- <plugin>
- <artifactId>maven-resources-plugin</artifactId>
- <version>2.6</version>
- <executions>
- <execution>
- <id>copy-resources</id>
- <phase>generate-resources</phase>
- <goals>
- <goal>copy-resources</goal>
- </goals>
- <configuration>
- <outputDirectory>${basedir}/target/generated-docs</outputDirectory>
- <resources>
- <resource>
- <directory>src/main/resources</directory>
- <includes>
- <include>**/*.*</include>
- </includes>
- </resource>
- </resources>
- </configuration>
- </execution>
- </executions>
- </plugin>
- <plugin>
- <groupId>com.inocybe.api</groupId>
- <artifactId>sdndocs-maven-plugin</artifactId>
- <version>0.1.0</version>
- <executions>
- <execution>
- <id>generate-webhelp</id>
- <goals>
- <goal>generate-webhelp</goal>
- </goals>
- <phase>compile</phase>
- <configuration>
- <profileAudience>enduser</profileAudience>
- <includes>target/generated-docs/${bookname}.xml</includes>
- <!-- <includes>bk-install-guide.xml</includes> -->
- <generateToc>
- appendix toc,title
- article/appendix nop
- article toc,title
- book toc,title,figure,table,example,equation
- chapter toc,title
- section toc
- part toc,title
- qandadiv toc
- qandaset toc
- reference toc,title
- set toc,title
- </generateToc>
- <webhelpDirname>${bookname}</webhelpDirname>
- <pdfFilenameBase>${bookname}</pdfFilenameBase>
- </configuration>
- </execution>
- </executions>
- <configuration>
- <profileAudience>enduser</profileAudience>
- <chapterAutolabel>1</chapterAutolabel>
- <sectionAutolabel>0</sectionAutolabel>
- <tocSectionDepth>1</tocSectionDepth>
- <formalProcedures>0</formalProcedures>
- <highlightSource>false</highlightSource>
- <xincludeSupported>true</xincludeSupported>
- <showXslMessages>true</showXslMessages>
- <sourceDirectory>.</sourceDirectory>
- <feedbackEmail>mlemay@inocybe.com</feedbackEmail>
- <branding>opendaylight</branding>
- <coverLogoLeft>2.6in</coverLogoLeft>
-<!-- <enableDisqus>${comments.enabled}</enableDisqus>
- <disqusShortname>os-user-guide</disqusShortname>
- <enableGoogleAnalytics>1</enableGoogleAnalytics>
- <googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
- --> <suppressFooterNavigation>0</suppressFooterNavigation>
- <canonicalUrlBase>http://docs.opendaylight.org/user-guide/content/</canonicalUrlBase>
- <glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-site-plugin</artifactId>
- <version>3.1</version>
- <configuration>
- <inputDirectory>${project.build.directory}/docbkx/webhelp</inputDirectory>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>org.apache.maven.wagon</groupId>
- <artifactId>wagon-webdav-jackrabbit</artifactId>
- <version>2.2</version>
- </dependency>
- <dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-api</artifactId>
- <version>1.6.1</version>
- </dependency>
- </dependencies>
- </plugin>
- </plugins>
- </build>
-</project>
+++ /dev/null
-=== OpenStack with GroupBasedPolicy
-
-This section is for Application Developers and Network Administrators
-who are looking to integrate Group Based Policy with OpenStack.
-
-To enable the *GBP* Neutron Mapper feature, at the karaf console:
-
- feature:install odl-groupbasedpolicy-neutronmapper
-
-Neutron Mapper has the following dependencies that are automatically loaded:
-
- odl-neutron-service
-
-Neutron Northbound implementing REST API used by OpenStack
-
- odl-groupbasedpolicy-base
-
-Base *GBP* feature set, such as policy resolution, data model etc.
-
- odl-groupbasedpolicy-ofoverlay
-
-For Lithium, *GBP* has one renderer, hence this is loaded by default.
-
-REST calls from OpenStack Neutron are by the Neutron NorthBound project.
-
-*GBP* provides the implementation of the http://developer.openstack.org/api-ref-networking-v2.html[Neutron V2.0 API].
-
-==== Features
-
-List of supported Neutron entities:
-
-* Port
-* Network
-** Standard Internal
-** External provider L2/L3 network
-* Subnet
-* Security-groups
-* Routers
-** Distributed functionality with local routing per compute
-** External gateway access per compute node (dedicated port required)
-** Multiple routers per tenant
-* FloatingIP NAT
-* IPv4/IPv6 support
-
-The mapping of Neutron entities to *GBP* entities is as follows:
-
-*Neutron Port*
-
-.Neutron Port
-image::groupbasedpolicy/neutronmapper-gbp-mapping-port.png[width=300]
-
-The Neutron port is mapped to an endpoint.
-
-The current implementation supports one IP address per Neutron port.
-
-An endpoint and L3-endpoint belong to multiple EndpointGroups if the Neutron port is in multiple Neutron Security Groups.
-
-The key for endpoint is L2-bridge-domain obtained as the parent of L2-flood-domain representing Neutron network. The MAC address is from the Neutron port.
-An L3-endpoint is created based on L3-context (the parent of the L2-bridge-domain) and IP address of Neutron Port.
-
-*Neutron Network*
-
-.Neutron Network
-image::groupbasedpolicy/neutronmapper-gbp-mapping-network.png[width=300]
-
-A Neutron network has the following characteristics:
-
-* defines a broadcast domain
-* defines a L2 transmission domain
-* defines a L2 name space.
-
-To represent this, a Neutron Network is mapped to multiple *GBP* entities.
-The first mapping is to an L2 flood-domain to reflect that the Neutron network is one flooding or broadcast domain.
-An L2-bridge-domain is then associated as the parent of L2 flood-domain. This reflects both the L2 transmission domain as well as the L2 addressing namespace.
-
-The third mapping is to L3-context, which represents the distinct L3 address space.
-The L3-context is the parent of L2-bridge-domain.
-
-*Neutron Subnet*
-
-.Neutron Subnet
-image::groupbasedpolicy/neutronmapper-gbp-mapping-subnet.png[width=300]
-
-Neutron subnet is associated with a Neutron network. The Neutron subnet is mapped to a *GBP* subnet where the parent of the subnet is L2-flood-domain representing the Neutron network.
-
-*Neutron Security Group*
-
-.Neutron Security Group and Rules
-image::groupbasedpolicy/neutronmapper-gbp-mapping-securitygroup.png[width=300]
-
-*GBP* entity representing Neutron security-group is EndpointGroup.
-
-*Infrastructure EndpointGroups*
-
-Neutron-mapper automatically creates EndpointGroups to manage key infrastructure items such as:
-
-* DHCP EndpointGroup - contains endpoints representing Neutron DHCP ports
-* Router EndpointGroup - contains endpoints representing Neutron router interfaces
-* External EndpointGroup - holds L3-endpoints representing Neutron router gateway ports, also associated with FloatingIP ports.
-
-*Neutron Security Group Rules*
-
-This mapping is most complicated among all others because Neutron security-group-rules are mapped to contracts with clauses,
-subjects, rules, action-refs, classifier-refs, etc.
-Contracts are used between endpoint groups representing Neutron Security Groups.
-For simplification it is important to note that Neutron security-group-rules are similar to a *GBP* rule containing:
-
-* classifier with direction
-* action of *allow*.
-
-
-*Neutron Routers*
-
-.Neutron Router
-image::groupbasedpolicy/neutronmapper-gbp-mapping-router.png[width=300]
-
-Neutron router is represented as a L3-context. This treats a router as a Layer3 namespace, and hence every network attached to it a part
-of that Layer3 namespace.
-
-This allows for multiple routers per tenant with complete isolation.
-
-The mapping of the router to an endpoint represents the router's interface or gateway port.
-
-The mapping to an EndpointGroup represents the internal infrastructure EndpointGroups created by the *GBP* Neutron Mapper
-
-When a Neutron router interface is attached to a network/subnet, that network/subnet and its associated endpoints or Neutron Ports are seamlessly added to the namespace.
-
-*Neutron FloatingIP*
-
-When associated with a Neutron Port, this leverages the *GBP* OfOverlay renderer's NAT capabilities.
-
-A dedicated _external_ interface on each Nova compute host allows for disitributed external access. Each Nova instance associated with a
-FloatingIP address can access the external network directly without having to route via the Neutron controller, or having to enable any form
-of Neutron distributed routing functionality.
-
-Assuming the gateway provisioned in the Neutron Subnet command for the external network is reachable, the combination of *GBP* Neutron Mapper and
-OfOverlay renderer will automatically ARP for this default gateway, requiring no user intervention.
-
-
-*Troubleshooting within GBP*
-
-Logging level for the mapping functionality can be set for package org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling TRACE logging level on karaf console:
-
- log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
-
-*Neutron mapping example*
-
-As an example for mapping can be used creation of Neutron network, subnet and port.
-When a Neutron network is created 3 *GBP* entities are created: l2-flood-domain, l2-bridge-domain, l3-context.
-
-.Neutron network mapping
-image::groupbasedpolicy/neutronmapper-gbp-mapping-network-example.png[width=500]
-
-After an subnet is created in the network mapping looks like this.
-
-.Neutron subnet mapping
-image::groupbasedpolicy/neutronmapper-gbp-mapping-subnet-example.png[width=500]
-
-If an Neutron port is created in the subnet an endpoint and l3-endpoint are created. The endpoint has key composed from l2-bridge-domain and MAC address from Neutron port. A key of l3-endpoint is compesed from l3-context and IP address. The network containment of endpoint and l3-endpoint points to the subnet.
-
-.Neutron port mapping
-image::groupbasedpolicy/neutronmapper-gbp-mapping-port-example.png[width=500]
-
-==== Configuring GBP Neutron
-
-No intervention passed initial OpenStack setup is required by the user.
-
-More information about configuration can be found in our DevStack demo environment on the https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)[*GBP* wiki].
-
-==== Administering or Managing GBP Neutron
-
-For consistencies sake, all provisioning should be performed via the Neutron API. (CLI or Horizon).
-
-The mapped policies can be augmented via the *GBP* UX,UX, to:
-
-* Enable Service Function Chaining
-* Add endpoints from outside of Neutron i.e. VMs/containers not provisioned in OpenStack
-* Augment policies/contracts derived from Security Group Rules
-* Overlay additional contracts or groupings
-
-==== Tutorials
-
-A DevStack demo environment can be found on the https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)[*GBP* wiki].
+++ /dev/null
-
- <author>
- <personname>
- <firstname>OpenDaylight</firstname>
- <surname>Community</surname>
- </personname>
- <email>documentation@opendaylight.org</email>
- <affiliation>
- <orgname>Linux Foundation</orgname>
- </affiliation>
- </author>
- <copyright>
- <year>2015</year>
- <holder>Linux Foundation</holder>
- </copyright>
- <releaseinfo>Beryllium</releaseinfo>
- <productname>OpenDaylight</productname>
- <pubdate></pubdate>
- <legalnotice role="license">
- <para> This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at <link xlink:href="http://www.eclipse.org/legal/epl-v10.html"/></para>
- </legalnotice>
- <abstract>
- <para>This guide describes how to use OpenDaylight with OpenStack.</para>
- </abstract>
- <revhistory>
- <revision>
- <date>2014-07-16</date>
- <revdescription>
- <itemizedlist spacing="compact">
- <listitem>
- <para>Initial Guide Creation</para>
- </listitem>
- </itemizedlist>
- </revdescription>
- </revision>
- </revhistory>
-
+++ /dev/null
-=== OpenStack with OVSDB
-
-*Prerequisites:* OpenDaylight requires Java 1.7.0.
-
-* On the control host, http://www.opendaylight.org/software/downloads[Download
- the latest OpenDaylight release] (at the time of writing, this is
- 0.2.1-Helium-SR1.1)
-* Uncompress it as root, and start OpenDaylight (you can start OpenDaylight
- by running karaf directly, but exiting from the shell will shut it down):
-+
-....
-$ tar xvfz distribution-karaf-0.2.1-Helium-SR1.1.tar.gz
-$ cd distribution-karaf-0.2.0-Helium
-$ ./bin/start # Start OpenDaylight as a server process
-....
-+
-* Connect to the Karaf shell, and install the odl-ovsdb-openstack bundle,
- dlux and their dependencies:
-+
-....
-$ ./bin/client # Connect to OpenDaylight with the client
-opendaylight-user@root> feature:install odl-base-all odl-aaa-authn odl-restconf odl-nsf-all odl-adsal-northbound odl-mdsal-apidocs \
-odl-ovsdb-openstack odl-ovsdb-northbound odl-dlux-core
-....
-+
-* If everything is installed correctly, you should now be able to log in to
- the dlux interface on `http://$CONTROL_HOST:8181/dlux/index.html` - the
- default username and password is "admin/admin" (see screenshot below)
-+
-image:dlux-default.png[width=500]
-
-==== Ensuring OpenStack network state is clean
-
-When using OpenDaylight as the Neutron back-end, ODL expects to be the only
-source of truth for Open vSwitch configuration. Because of this, it is
-necessary to remove existing OpenStack and Open vSwitch configurations to
-give OpenDaylight a clean slate.
-
-* Delete instances
-+
-....
-$ nova list
-$ nova delete <instance names>
-....
-+
-* Remove link from subnets to routers
-+
-....
-$ neutron subnet-list
-$ neutron router-list
-$ neutron router-port-list <router name>
-$ neutron router-interface-delete <router name> <subnet ID or name>
-....
-+
-* Delete subnets, nets, routers
-+
-....
-$ neutron subnet-delete <subnet name>
-$ neutron net-list
-$ neutron net-delete <net name>
-$ neutron router-delete <router name>
-....
-+
-* Check that all ports have been cleared - at this point, this should be an
- empty list
-+
-....
-$ neutron port-list
-....
-
-==== Ensure Neutron is stopped
-
-While Neutron is managing the OVS instances on compute and control nodes,
-OpenDaylight and Neutron can be in conflict. To prevent issues, we turn off
-Neutron server on the network controller, and Neutron's Open vSwitch agents
-on all hosts.
-
-* Turn off neutron-server on control node
-+
-....
-# systemctl stop neutron-server
-....
-+
-* On each node in the cluster, shut down and disable Neutron's agent services to ensure that they do not restart after a reboot:
-+
-....
-# systemctl stop neutron-openvswitch-agent
-# systemctl disable neutron-openvswitch-agent
-....
-
-==== Configuring Open vSwitch to be managed by OpenDaylight
-
-On each host (both compute and control nodes) we will clear the pre-existing
-Open vSwitch config and set OpenDaylight to manage the switch:
-
-* Stop the Open vSwitch service, and clear existing OVSDB (ODL expects to
-manage vSwitches completely)
-+
-....
-# systemctl stop openvswitch
-# rm -rf /var/log/openvswitch/*
-# rm -rf /etc/openvswitch/conf.db
-# systemctl start openvswitch
-....
-+
-* At this stage, your Open vSwitch configuration should be empty:
-+
-....
-[root@dneary-odl-compute2 ~]# ovs-vsctl show
-9f3b38cb-eefc-4bc7-828b-084b1f66fbfd
- ovs_version: "2.1.3"
-....
-+
-* Set OpenDaylight as the manager on all nodes
-+
-....
-# ovs-vsctl set-manager tcp:${CONTROL_HOST}:6640
-....
-+
-* You should now see a new section in your Open vSwitch configuration
- showing that you are connected to the OpenDaylight server, and OpenDaylight
- will automatically create a br-int bridge:
-+
-....
-[root@dneary-odl-compute2 ~]# ovs-vsctl show
-9f3b38cb-eefc-4bc7-828b-084b1f66fbfd
- Manager "tcp:172.16.21.56:6640"
- is_connected: true
- Bridge br-int
- Controller "tcp:172.16.21.56:6633"
- fail_mode: secure
- Port br-int
- Interface br-int
- ovs_version: "2.1.3"
-....
-+
-* (BUG WORKAROUND) If SELinux is enabled, you may not have a security
- context in place which allows Open vSwitch remote administration. If you
- do not see the result above (specifically, if you do not see
- "is_connected: true" in the Manager section), set SELinux to Permissive
- mode on all nodes and ensure it stays that way after boot:
-+
-....
-# setenforce 0
-# sed -i -e 's/SELINUX=enforcing/SELINUX=permissive/g' /etc/selinux/config
-....
-+
-* Make sure all nodes, including the control node, are connected to
- OpenDaylight
-* If you reload DLUX, you should now see that all of your Open vSwitch nodes
- are now connected to OpenDaylight
-+
-image:dlux-with-switches.png[width=500]
-+
-* If something has gone wrong, check <code>data/log/karaf.log</code> under
- the OpenDaylight distribution directory. If you do not see any interesting
- log entries, set logging for OVSDB to TRACE level inside Karaf and try again:
-+
-....
-log:set TRACE ovsdb
-....
-
-==== Configuring Neutron to use OpenDaylight
-
-Once you have configured the vSwitches to connect to OpenDaylight, you can
-now ensure that OpenStack Neutron is using OpenDaylight.
-
-First, ensure that port 8080 (which will be used by OpenDaylight to listen
-for REST calls) is available. By default, swift-proxy-service listens on the
-same port, and you may need to move it (to another port or another host), or
-disable that service. I moved it to port 8081 by editing
-<code>/etc/swift/proxy-server.conf</code> and
-<code>/etc/cinder/cinder.conf</code>, modifying iptables appropriately, and
-restarting swift-proxy-service and OpenDaylight.
-
-* Configure Neutron to use OpenDaylight's ML2 driver:
-+
-....
-crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 mechanism_drivers opendaylight
-crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 tenant_network_types vxlan
-
-cat <<EOT>> /etc/neutron/plugins/ml2/ml2_conf.ini
-[ml2_odl]
-password = admin
-username = admin
-url = http://${CONTROL_HOST}:8080/controller/nb/v2/neutron
-EOT
-....
-+
-* Reset Neutron's ML2 database
-+
-....
-mysql -e "drop database if exists neutron_ml2;"
-mysql -e "create database neutron_ml2 character set utf8;"
-mysql -e "grant all on neutron_ml2.* to 'neutron'@'%';"
-neutron-db-manage --config-file /usr/share/neutron/neutron-dist.conf --config-file /etc/neutron/neutron.conf \
---config-file /etc/neutron/plugin.ini upgrade head
-....
-+
-* Restart neutron-server:
-+
- systemctl start neutron-server
-
-==== Verifying it works
-
-* Verify that OpenDaylight's ML2 interface is working:
-+
-....
-curl -u admin:admin http://${CONTROL_HOST}:8080/controller/nb/v2/neutron/networks
-
-{
- "networks" : [ ]
-}
-....
-+
-If this does not work or gives an error, check Neutron's log file in
-<code>/var/log/neutron/server.log</code>. Error messages here should give
-some clue as to what the problem is in the connection with OpenDaylight
-+
-* Create a net, subnet, router, connect ports, and start an instance using
-the Neutron CLI:
-+
-....
-neutron router-create router1
-neutron net-create private
-neutron subnet-create private --name=private_subnet 10.10.5.0/24
-neutron router-interface-add router1 private_subnet
-nova boot --flavor <flavor> --image <image id> --nic net-id=<network id> test1
-nova boot --flavor <flavor> --image <image id> --nic net-id=<network id> test2
-....
-+
-At this point, you have confirmed that OpenDaylight is creating network
-end-points for instances on your network and managing traffic to them.
-
-Congratulations! You're done!
\ No newline at end of file
+++ /dev/null
-=== OpenStack with Virtual Tenant Network
-This section describes using OpenDaylight with the VTN manager feature providing network service for OpenStack. VTN manager utilizes the OVSDB southbound service and Neutron for this implementation. The below diagram depicts the communication of OpenDaylight and two virtual networks connected by an OpenFlow switch using this implementation.
-
-.OpenStack Architecture
-image::vtn/OpenStackDeveloperGuide.png["OpenStack Architecture",width=500]
-
-==== Configure OpenStack to work with OpenDaylight(VTN Feature) using PackStack
-
-===== Prerequisites to install OpenStack using PackStack
-* Fresh CentOS 7.1 minimal install
-* Use the below commands to disable and remove Network Manager in CentOS 7.1,
-+
-....
-# systemctl stop NetworkManager
-# systemctl disable NetworkManager
-....
-+
-* To make SELINUX as permissive, please open the file "/etc/sysconfig/selinux" and change it as "SELINUX=permissive".
-* After making selinux as permissive, please restart the CentOS 7.1 machine.
-
-===== Steps to install OpenStack PackStack in CentOS 7.1
-
-* To install OpenStack juno, use the following command,
-+
-....
-# yum update -y
-# yum -y install https://repos.fedorapeople.org/repos/openstack/openstack-juno/rdo-release-juno-1.noarch.rpm
-....
-+
-* To install the packstack installer, please use the below command,
-+
-....
-# yum -y install openstack-packstack
-....
-+
-* To create all-in-one setup, please use the below command,
-+
-....
-# packstack --allinone --provision-demo=n --provision-all-in-one-ovs-bridge=n
-....
-+
-* This will end up with Horizon started successfully message.
-
-===== Steps to install and deploy OpenDaylight in CentOS 7.1
-* Download the latest Beryllium distribution code in the below link,
-+
-....
-# wget https://nexus.opendaylight.org/content/groups/public/org/opendaylight/integration/distribution-karaf/0.4.0-Beryllium-SR1/distribution-karaf-0.4.0-Beryllium-SR1.zip
-....
-+
-* Unzip the Beryllium distribution code by using the below command,
-+
-....
-# unzip distribution-karaf-0.4.0-Beryllium-SR1.zip
-....
-+
-* Please do the below steps in the OpenDaylight to change jetty port,
-** Change the jetty port from 8080 to something else as swift proxy of OpenStack is using it.
-** Open the file "etc/jetty.xml" and change the jetty port from 8080 to 8910 (we have used 8910 as jetty port you can use any other number).
-** Start VTN Manager and install odl-vtn-manager-neutron in it.
-** Ensure all the required ports(6633/6653,6640 and 8910) are in the listen mode by using the command "netstat -tunpl" in OpenDaylight.
-
-===== Steps to reconfigure OpenStack in CentOS 7.1
-* Steps to stop Open vSwitch Agent and clean up ovs
-+
-....
-# sudo systemctl stop neutron-openvswitch-agent
-# sudo systemctl disable neutron-openvswitch-agent
-# sudo systemctl stop openvswitch
-# sudo rm -rf /var/log/openvswitch/*
-# sudo rm -rf /etc/openvswitch/conf.db
-# sudo systemctl start openvswitch
-# sudo ovs-vsctl show
-....
-+
-* Stop Neutron Server
-+
-....
-# systemctl stop neutron-server
-....
-+
-* Verify that OpenDaylight's ML2 interface is working:
-+
-....
-curl -v admin:admin http://{CONTROL_HOST}:{PORT}/controller/nb/v2/neutron/networks
-
-{
- "networks" : [ ]
-}
-....
-+
-If this does not work or gives an error, check Neutron's log file in
-+/var/log/neutron/server.log+. Error messages here should give
-some clue as to what the problem is in the connection with OpenDaylight
-+
-* Configure Neutron to use OpenDaylight's ML2 driver:
-+
-....
-# sudo crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 mechanism_drivers opendaylight
-# sudo crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 tenant_network_types local
-# sudo crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 type_drivers local
-# sudo crudini --set /etc/neutron/dhcp_agent.ini DEFAULT ovs_use_veth True
-
-# cat <<EOT | sudo tee -a /etc/neutron/plugins/ml2/ml2_conf.ini > /dev/null
- [ml2_odl]
- password = admin
- username = admin
- url = http://{CONTROL_HOST}:{PORT}/controller/nb/v2/neutron
- EOT
-....
-+
-* Reset Neutron's ML2 database
-+
-....
-# sudo mysql -e "drop database if exists neutron_ml2;"
-# sudo mysql -e "create database neutron_ml2 character set utf8;"
-# sudo mysql -e "grant all on neutron_ml2.* to 'neutron'@'%';"
-# sudo neutron-db-manage --config-file /usr/share/neutron/neutron-dist.conf --config-file /etc/neutron/neutron.conf --config-file /etc/neutron/plugin.ini upgrade head
-....
-+
-* Start Neutron Server
-+
-....
-# sudo systemctl start neutron-server
-....
-+
-* Restart the Neutron DHCP service
-+
-....
-# system restart neutron-dhcp-agent.service
-....
-+
-* At this stage, your Open vSwitch configuration should be empty:
-+
-....
-[root@dneary-odl-compute2 ~]# ovs-vsctl show
-686989e8-7113-4991-a066-1431e7277e1f
- ovs_version: "2.3.1"
-....
-+
-* Set OpenDaylight as the manager on all nodes
-+
-....
-# ovs-vsctl set-manager tcp:127.0.0.1:6640
-....
-+
-* You should now see a section in your Open vSwitch configuration
- showing that you are connected to the OpenDaylight server, and OpenDaylight
- will automatically create a br-int bridge:
-+
-....
-[root@dneary-odl-compute2 ~]# ovs-vsctl show
-686989e8-7113-4991-a066-1431e7277e1f
- Manager "tcp:127.0.0.1:6640"
- is_connected: true
- Bridge br-int
- Controller "tcp:127.0.0.1:6633"
- is_connected: true
- fail_mode: secure
- Port "ens33"
- Interface "ens33"
- ovs_version: "2.3.1"
-....
-+
-* Add the default flow to OVS to forward packets to controller when there is a table-miss,
-+
-....
-ovs-ofctl --protocols=OpenFlow13 add-flow br-int priority=0,actions=output:CONTROLLER
-....
-+
-* Please see the https://wiki.opendaylight.org/view/VTN:Beryllium:User_Guide:OpenStack_PackStack_Support[VTN OpenStack PackStack support guide on the wiki] to create VM's from OpenStack Horizon GUI.
-
-==== Implementation details
-
-===== VTN Manager:
-Install *odl-vtn-manager-neutron* feature which provides the integration with Neutron interface.
-
- feature:install odl-vtn-manager-neutron
-
-It subscribes to the events from Open vSwitch and also implements the Neutron requests received by OpenDaylight.
-
-===== Functional Behavior
-
-.StartUp:
-* The ML2 implementation for OpenDaylight will ensure that when Open vSwitch is started, the ODL_IP_ADDRESS configured will be set as manager.
-* When OpenDaylight receives the update of the Open vSwitch on port 6640 (manager port), VTN Manager handles the event and adds a bridge with required port mappings to the Open vSwitch at the OpenStack node.
-* When Neutron starts up, a new network create is POSTed to OpenDaylight, for which VTN Manager creates a Virtual Tenant Network.
-* *Network and Sub-Network Create:* Whenever a new sub network is created, VTN Manager will handle the same and create a vbridge under the VTN.
-* *VM Creation in OpenStack:* The interface mentioned as integration bridge in the configuration file will be added with more interfaces on creation of a new VM in OpenStack and the network is provisioned for it by the VTN Neutron feature. The addition of a new port is captured by the VTN Manager and it creates a vbridge interface with port mapping for the particular port. When the VM starts to communicate with other VMs, the VTN Manger will install flows in the Open vSwitch and other OpenFlow switches to facilitate communication between them.
-
-NOTE:
- To use this feature, VTN feature should be installed
-
-==== Reference
-
-https://wiki.opendaylight.org/images/5/5c/Integration_of_vtn_and_ovsdb_for_helium.pdf
+++ /dev/null
-= OpenDaylight and OpenStack
-:docinfo:
-
-[preface]
-== Overview
-http://www.openstack.org[OpenStack] is a popular open source Infrastructure
-as a service project, covering compute, storage and network management.
-OpenStack can use OpenDaylight as its network management provider through the
-Modular Layer 2 (ML2) north-bound plug-in. OpenDaylight manages the network
-flows for the OpenStack compute nodes via the OVSDB south-bound plug-in. This
-page describes how to set that up, and how to tell when everything is working.
-
-== Installing OpenStack
-
-Installing OpenStack is out of scope for this document, but to get started, it
-is useful to have a minimal multi-node OpenStack deployment.
-
-The reference deployment we will use for this document is a 3 node cluster:
-
-* One control node containing all of the management services for OpenStack
- (Nova, Neutron, Glance, Swift, Cinder, Keystone)
-* Two compute nodes running nova-compute
-* Neutron using the OVS back-end and vxlan for tunnels
-
-Once you have installed OpenStack, verify that it is working by connecting
-to Horizon and performing a few operations. To check the Neutron
-configuration, create two instances on a private subnet bridging to your
-public network, and verify that you can connect to them, and that they can
-see each other.
-
-== Installing OpenDaylight
-
-include::openstack-ovsdb.adoc[]
-
-include::odl-groupbasedpolicy-neutronmapper-user-guide.adoc[]
-
-include::openstack-vtn.adoc[]
-
-[[Category:Documentation]]
-[[Category:OpenStack]]
-
<module>readme</module> <!-- this is just to make sure readme builds -->
<module>developer-guide</module>
<module>user-guide</module>
- <module>howto-openstack</module>
</modules>
</project>
== Atrium User Guide
-=== Overview
-Project Atrium is an open source SDN distribution - a vertically integrated
-set of open source components which together form a complete SDN stack.
-It’s goals are threefold:
-
-* Close the large integration-gap of the elements that are needed to build an SDN stack -
- while there are multiple choices at each layer, there are missing pieces with poor or no integration.
-* Overcome a massive gap in interoperability - This exists both at the switch level,
- where existing products from different vendors have limited compatibility,
- making it difficult to connect an arbitrary switch and controller and at an API level,
- where its difficult to write a portable application across multiple controller platforms.
-* Work closely with network operators on deployable use-cases, so that they could download
- near production quality code from one location, and get started with functioning
- software defined networks on real hardware.
-
-=== Architecture
-The key components of Atrium BGP Peering Router Application are as follows:
-
-* Data Plane Switch - Data plane switch is the entity that uses flow table entries installed by
- BGP Routing Application through SDN controller. In the simplest form data plane switch with
- the installed flows act like a BGP Router.
-* OpenDaylight Controller - OpenDaylight SDN controller has many utility applications or plugins
- which are leveraged by the BGP Router application to manage the control plane information.
-* BGP Routing Application - An application running within the OpenDaylight runtime environment
- to handle I-BGP updates.
-* <<_didm_user_guide,DIDM>> - DIDM manages the drivers specific to each data plane switch connected to the controller.
- The drivers are created primarily to hide the underlying complexity of the devices
- and to expose a uniform API to applications.
-* Flow Objectives API - The driver implementation provides a pipeline abstraction and
- exposes Flow Objectives API. This means applications need to be aware of only the
- Flow Objectives API without worrying about the Table IDs or the pipelines.
-* Control Plane Switch - This component is primarily used to connect the OpenDaylight SDN controller
- with the Quagga Soft-Router and establish a path for forwarding E-BGP packets to and from Quagga.
-* Quagga soft router - An open source routing software that handles E-BGP updates.
-
-=== Running Atrium
-* To run the Atrium BGP Routing Application in OpenDaylight distribution,
- simply install the `odl-atrium-all` feature.
-+
- feature:install odl-atrium-all
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/atrium-user-guide.html
include::core-release-notes.adoc[OpenDaylight Release Notes]
/////
-= Getting Started with OpenDaylight
+A significant amount of this guide has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/index.html
-[partintro]
-
-This first part of the user guide covers the basic user operations of the OpenDaylight Release using the generic base functionality.
-
-include::ch-introduction.adoc[OpenDaylight Controller Overview]
-
-include::ch-dlux.adoc[]
-
-include::ch-xsql-commands.adoc[]
-
-include::ch-clustering.adoc[]
+Please look there as well as here for any content.
= Applications and Plugins
-[partintro]
-
-This second part of the user guide covers project specific usage instructions.
-
include::alto/alto-user-guide.adoc[ALTO]
include::aaa/aaa.adoc[AAA]
+++ /dev/null
-== Setting Up Clustering
-
-=== Clustering Overview
-
-Clustering is a mechanism that enables multiple processes and programs to work
-together as one entity. For example, when you search for something on
-google.com, it may seem like your search request is processed by only one web
-server. In reality, your search request is processed by may web servers
-connected in a cluster. Similarly, you can have multiple instances of
-OpenDaylight working together as one entity.
-
-Advantages of clustering are:
-
-* Scaling: If you have multiple instances of OpenDaylight running, you can
- potentially do more work and store more data than you could with only one
- instance. You can also break up your data into smaller chunks (shards) and
- either distribute that data across the cluster or perform certain operations
- on certain members of the cluster.
-* High Availability: If you have multiple instances of OpenDaylight running and
- one of them crashes, you will still have the other instances working and
- available.
-* Data Persistence: You will not lose any data stored in OpenDaylight after a
- manual restart or a crash.
-
-The following sections describe how to set up clustering on both individual and
-multiple OpenDaylight instances.
-
-=== Single Node Clustering
-
-To enable clustering on a single instance of OpenDaylight, perform the
-following steps:
-
-. Download, unzip, and run the OpenDaylight distribution
-. Install the clustering feature:
-+
- feature:install odl-mdsal-clustering
-
-NOTE: This will enabled the cluster-ready version of the MD-SAL data store, but
- will not actually create a cluster of multiple instances. The result is
- that you will get data persistence, but not the scaling or high
- availability advantages.
-
-=== Multiple Node Clustering
-
-The following sections describe how to set up multiple node clusters in OpenDaylight.
-
-==== Deployment Considerations
-
-To implement clustering, the deployment considerations are as follows:
-
-* To set up a cluster with multiple nodes, we recommend that you use a minimum
- of three machines. You can set up a cluster with just two nodes. However, if
- one of the two nodes fail, the cluster will not be operational.
-+
-NOTE: This is because clustering in OpenDaylight requires a majority of the
- nodes to be up and one node cannot be a majority of two nodes.
-+
-* Every device that belongs to a cluster needs to have an identifier.
- OpenDaylight uses the node's +role+ for this purpose. After you define the
- first node's role as _member-1_ in the +akka.conf+ file, OpenDaylight uses
- _member-1_ to identify that node.
-
-* Data shards are used to contain all or a certain segment of a OpenDaylight's
- MD-SAL datastore. For example, one shard can contain all the inventory data
- while another shard contains all of the topology data.
-+
-If you do not specify a module in the +modules.conf+ file and do not specify
-a shard in +module-shards.conf+, then (by default) all the data is placed in
-the default shard (which must also be defined in +module-shards.conf+ file).
-Each shard has replicas configured. You can specify the details of where the
-replicas reside in +module-shards.conf+ file.
-
-* If you have a three node cluster and would like to be able to tolerate any
- single node crashing, a replica of every defined data shard must be running
- on all three cluster nodes.
-+
-NOTE: This is because OpenDaylight's clustering implementation requires a
- majority of the defined shard replicas to be running in order to
- function. If you define data shard replicas on two of the cluster nodes
- and one of those nodes goes down, the corresponding data shards will not
- function.
-+
-* If you have a three node cluster and have defined replicas for a data shard
- on each of those nodes, that shard will still function even if only two of
- the cluster nodes are running. Note that if one of those remaining two nodes
- goes down, the shard will not be operational.
-
-* It is recommended that you have multiple seed nodes configured. After a
- cluster member is started, it sends a message to all of its seed nodes.
- The cluster member then sends a join command to the first seed node that
- responds. If none of its seed nodes reply, the cluster member repeats this
- process until it successfully establishes a connection or it is shut down.
-
-* After a node is unreachable, it remains down for configurable period of time
- (10 seconds, by default). Once a node goes down, you need to restart it so
- that it can rejoin the cluster. Once a restarted node joins a cluster, it
- will synchronize with the lead node automatically.
-
-==== Setting Up a Multiple Node Cluster
-
-To run OpenDaylight in a three node cluster, perform the following:
-
-First, determine the three machines that will make up the cluster. After that,
-do the following on each machine:
-
-. Copy the OpenDaylight distribution zip file to the machine.
-. Unzip the distribution.
-. Open the following .conf files:
-** configuration/initial/akka.conf
-** configuration/initial/module-shards.conf
-. In each configuration file, make the following changes:
-.. Find every instance of the following lines and replace _127.0.0.1_ with the
- hostname or IP address of the machine on which this file resides and
- OpenDaylight will run:
-+
- netty.tcp {
- hostname = "127.0.0.1"
-+
-NOTE: The value you need to specify will be different for each node in the
- cluster.
-+
-.. Find the following lines and replace _127.0.0.1_ with the hostname or IP
- address of any of the machines that will be part of the cluster:
-+
- cluster {
- seed-nodes = ["akka.tcp://opendaylight-cluster-data@127.0.0.1:2550"]
-+
-.. Find the following section and specify the role for each member node. Here
- we assign the first node with the _member-1_ role, the second node with the
- _member-2_ role, and the third node with the _member-3_ role:
-+
- roles = [
- "member-1"
- ]
-+
-NOTE: This step should use a different role on each node.
-+
-.. Open the configuration/initial/module-shards.conf file and update the
- replicas so that each shard is replicated to all three nodes:
-+
- replicas = [
- "member-1",
- "member-2",
- "member-3"
- ]
-+
-For reference, view a sample config files <<_sample_config_files,below>>.
-+
-. Move into the +<karaf-distribution-directory>/bin+ directory.
-. Run the following command:
-+
- JAVA_MAX_MEM=4G JAVA_MAX_PERM_MEM=512m ./karaf
-+
-. Enable clustering by running the following command at the Karaf command line:
-+
- feature:install odl-mdsal-clustering
-
-OpenDaylight should now be running in a three node cluster. You can use any of
-the three member nodes to access the data residing in the datastore.
-
-// This doesn't work at the moment. The install -s command fails.
-//===== Debugging Clustering
-//
-//To debug clustering first install Jolokia by entering the following command:
-//
-// install -s mvn:org.jolokia/jolokia-osgi/1.1.5
-//
-//After that, you can view specific information about the cluster. For example,
-//to view information about shard designated as _member-1_ on a node, query the
-//shard's data by sending the following HTTP request:
-//
-//*GET http://_<host>_:8181/jolokia/read/org.opendaylight.controller:Category=Shards,name=member-1-shard-inventory-config,type=DistributedConfigDatastore*
-//
-//NOTE: If prompted, enter your credentials for OpenDaylight. The default
-// credentials are a username and password of _admin_.
-//
-//This request should return the following information:
-//
-// {
-// "timestamp": 1410524741,
-// "status": 200,
-// "request": {
-// "mbean": "org.opendaylight.controller:Category=Shards,name=member-1-shard-inventory-config,type=DistributedConfigDatastore",
-// "type": "read"
-// },
-// "value": {
-// "ReadWriteTransactionCount": 0,
-// "LastLogIndex": -1,
-// "MaxNotificationMgrListenerQueueSize": 1000,
-// "ReadOnlyTransactionCount": 0,
-// "LastLogTerm": -1,
-// "CommitIndex": -1,
-// "CurrentTerm": 1,
-// "FailedReadTransactionsCount": 0,
-// "Leader": "member-1-shard-inventory-config",
-// "ShardName": "member-1-shard-inventory-config",
-// "DataStoreExecutorStats": {
-// "activeThreadCount": 0,
-// "largestQueueSize": 0,
-// "currentThreadPoolSize": 1,
-// "maxThreadPoolSize": 1,
-// "totalTaskCount": 1,
-// "largestThreadPoolSize": 1,
-// "currentQueueSize": 0,
-// "completedTaskCount": 1,
-// "rejectedTaskCount": 0,
-// "maxQueueSize": 5000
-// },
-// "FailedTransactionsCount": 0,
-// "CommittedTransactionsCount": 0,
-// "NotificationMgrExecutorStats": {
-// "activeThreadCount": 0,
-// "largestQueueSize": 0,
-// "currentThreadPoolSize": 0,
-// "maxThreadPoolSize": 20,
-// "totalTaskCount": 0,
-// "largestThreadPoolSize": 0,
-// "currentQueueSize": 0,
-// "completedTaskCount": 0,
-// "rejectedTaskCount": 0,
-// "maxQueueSize": 1000
-// },
-// "LastApplied": -1,
-// "AbortTransactionsCount": 0,
-// "WriteOnlyTransactionCount": 0,
-// "LastCommittedTransactionTime": "1969-12-31 16:00:00.000",
-// "RaftState": "Leader",
-// "CurrentNotificationMgrListenerQueueStats": []
-// }
-// }
-//
-//The key information is the name of the shard. Shard names are structured as follows:
-//
-//_<member-name>_-shard-_<shard-name-as-per-configuration>_-_<store-type>_
-//
-//Here are a couple sample data short names:
-//
-//* member-1-shard-topology-config
-//* member-2-shard-default-operational
-
-===== Sample Config Files
-
-.Sample +akka.conf+ file
-----
-odl-cluster-data {
- bounded-mailbox {
- mailbox-type = "org.opendaylight.controller.cluster.common.actor.MeteredBoundedMailbox"
- mailbox-capacity = 1000
- mailbox-push-timeout-time = 100ms
- }
-
- metric-capture-enabled = true
-
- akka {
- loglevel = "DEBUG"
- loggers = ["akka.event.slf4j.Slf4jLogger"]
-
- actor {
-
- provider = "akka.cluster.ClusterActorRefProvider"
- serializers {
- java = "akka.serialization.JavaSerializer"
- proto = "akka.remote.serialization.ProtobufSerializer"
- }
-
- serialization-bindings {
- "com.google.protobuf.Message" = proto
-
- }
- }
- remote {
- log-remote-lifecycle-events = off
- netty.tcp {
- hostname = "10.194.189.96"
- port = 2550
- maximum-frame-size = 419430400
- send-buffer-size = 52428800
- receive-buffer-size = 52428800
- }
- }
-
- cluster {
- seed-nodes = ["akka.tcp://opendaylight-cluster-data@10.194.189.96:2550"]
-
- auto-down-unreachable-after = 10s
-
- roles = [
- "member-1"
- ]
-
- }
- }
-}
-
-odl-cluster-rpc {
- bounded-mailbox {
- mailbox-type = "org.opendaylight.controller.cluster.common.actor.MeteredBoundedMailbox"
- mailbox-capacity = 1000
- mailbox-push-timeout-time = 100ms
- }
-
- metric-capture-enabled = true
-
- akka {
- loglevel = "INFO"
- loggers = ["akka.event.slf4j.Slf4jLogger"]
-
- actor {
- provider = "akka.cluster.ClusterActorRefProvider"
-
- }
- remote {
- log-remote-lifecycle-events = off
- netty.tcp {
- hostname = "10.194.189.96"
- port = 2551
- }
- }
-
- cluster {
- seed-nodes = ["akka.tcp://opendaylight-cluster-rpc@10.194.189.96:2551"]
-
- auto-down-unreachable-after = 10s
- }
- }
-}
-----
-
-.Sample +module-shards.conf+ file
-----
-module-shards = [
- {
- name = "default"
- shards = [
- {
- name="default"
- replicas = [
- "member-1",
- "member-2",
- "member-3"
- ]
- }
- ]
- },
- {
- name = "topology"
- shards = [
- {
- name="topology"
- replicas = [
- "member-1",
- "member-2",
- "member-3"
- ]
- }
- ]
- },
- {
- name = "inventory"
- shards = [
- {
- name="inventory"
- replicas = [
- "member-1",
- "member-2",
- "member-3"
- ]
- }
- ]
- },
- {
- name = "toaster"
- shards = [
- {
- name="toaster"
- replicas = [
- "member-1",
- "member-2",
- "member-3"
- ]
- }
- ]
- }
-]
-----
\ No newline at end of file
+++ /dev/null
-== Using the OpenDaylight User Interface (DLUX)
-
-This section introduces you to the OpenDaylight User Experience (DLUX) application.
-
-=== Getting Started with DLUX
-
-DLUX provides a number of different Karaf features, which you can enable and disable separately. In Beryllum they are:
-. odl-dlux-core
-. odl-dlux-node
-. odl-dlux-yangui
-. odl-dlux-yangvisualizer
-
-=== Logging In
-
-To log in to DLUX, after installing the application:
-
-. Open a browser and enter the login URL http://<your-karaf-ip>:8181/index.html in your browser (Chrome is recommended).
-. Login to the application with your username and password credentials.
-
-NOTE: OpenDaylight's default credentials are _admin_ for both the username and password.
-
-=== Working with DLUX
-
-After you login to DLUX, if you enable only odl-dlux-core feature, you will see only topology application available in the left pane.
-
-NOTE: To make sure topology displays all the details, enable the odl-l2switch-switch feature in Karaf.
-
-DLUX has other applications such as node, yang UI and those apps won't show up, until you enable their features odl-dlux-node and odl-dlux-yangui respectively in the Karaf distribution.
-
-.DLUX Modules
-image::dlux-login.png["DLUX Page",width=500]
-
-NOTE: If you install your application in dlux, they will also show up on the left hand navigation after browser page refresh.
-
-=== Viewing Network Statistics
-
-The *Nodes* module on the left pane enables you to view the network statistics and port information for the switches in the network.
-
-To use the *Nodes* module:
-
-'''
-
-. Select *Nodes* on the left pane.
- The right pane displays atable that lists all the nodes, node connectors and the statistics.
-. Enter a node ID in the *Search Nodes* tab to search by node connectors.
-. Click on the *Node Connector* number to view details such as port ID, port name, number of ports per switch, MAC Address, and so on.
-. Click *Flows* in the Statistics column to view Flow Table Statistics for the particular node like table ID, packet match, active flows and so on.
-. Click *Node Connectors* to view Node Connector Statistics for the particular node ID.
-
-'''
-
-=== Viewing Network Topology
-
-The Topology tab displays a graphical representation of network topology created.
-
-NOTE: DLUX does not allow for editing or adding topology information. The topology is generated and edited in other modules, e.g., the OpenFlow plugin. OpenDaylight stores this information in the MD-SAL datastore where DLUX can read and display it.
-
-To view network topology:
-
-. Select *Topology* on the left pane. You will view the graphical representation on the right pane.
- In the diagram blue boxes represent the switches, the black represents the hosts available, and lines represents how the switches and hosts are connected.
-. Hover your mouse on hosts, links, or switches to view source and destination ports.
-. Zoom in and zoom out using mouse scroll to verify topology for larger topologies.
-
-.Topology Module
-image::dlux-topology.png["DLUX Topology Page",width=500]
-
-=== Interacting with the YANG-based MD-SAL datastore
-
-The *Yang UI* module enables you to interact with the YANG-based MD-SAL datastore. For more information about YANG and how it interacts with the MD-SAL datastore, see the _Controller_ and _YANG Tools_ section of the _OpenDaylight Developer Guide_.
-
-.Yang UI
-image::dlux-yang-ui-screen.png["DLUX Yang UI Page",width=500]
-
-To use Yang UI:
-
-. Select *Yang UI* on the left pane. The right pane is divided in two parts.
-. The top part displays a tree of APIs, subAPIs, and buttons to call possible functions (GET, POST, PUT, and DELETE).
-+
-NOTE: Not every subAPI can call every function. For example, subAPIs in the _operational_ store have GET functionality only.
-+
-Inputs can be filled from OpenDaylight when existing data from OpenDaylight is displayed or can be filled by user on the page and sent to OpenDaylight.
-+
-Buttons under the API tree are variable. It depends on subAPI specifications. Common buttons are:
-+
-* GET to get data from OpenDaylight,
-* PUT and POST for sending data to OpenDaylight for saving
-* DELETE for sending data to OpenDaylight for deleting.
-+
-You must specify the xpath for all these operations. This path is displayed in the same row before buttons and it may include text inputs for specific path element identifiers.
-+
-.Yang API Specification
-image::dlux-yang-api-specification.png["DLUX Yang UI API Specification Page",width=500]
-. The bottom part of the right pane displays inputs according to the chosen subAPI.
-+
-* Lists are handled as a special case. For example, a device can store multiple flows. In this case "flow" is name of the list and every list element is identified by a unique key value. Elements of a list can, in turn, contain other lists.
-* In Yang UI, each list element is rendered with the name of the list it belongs to, its key, its value, and a button for removing it from the list.
-+
-.Yang UI API Specification
-image::dlux-yang-sub-api-screen.png["DLUX Yang UI Sub API Specification Page",width=500]
-+
-. After filling in the relevant inputs, click the *Show Preview* button under the API tree to display request that will be sent to OpenDaylight.
- A pane is displayed on the right side with text of request when some input is filled.
-
-==== Displaying Topology on the *Yang UI*
-
-To display topology:
-
-. Select subAPI network-topology <topology revision number> == > operational == > network-topology.
-. Get data from OpenDaylight by clicking on the "GET" button.
-. Click *Display Topology*.
-
-.DLUX Yang Topology
-image::dlux-yang-topology.png["DLUX Yang Topology Page",width=500]
-
-==== Configuring List Elements on the *Yang UI*
-
-Lists in Yang UI are displayed as trees. To expand or collapse a list, click the arrow before name of the list. To configure list elements in Yang UI:
-
-. To add a new list element with empty inputs use the plus icon-button **+** that is provided after list name.
-. To remove several list elements, use the *X* button that is provided after every list element.
-+
-.DLUX List Elements
-image::dlux-yang-list-elements.png[DLUX list elements,width=500]
-+
-. In the YANG-based data store all elements of a list must have a unique key. If you try to assign two or more elements the same key, a warning icon *!* is displayed near their name buttons.
-+
-.DLUX List Warnings
-image::dlux-yang-list-warning.png[DLUX list warnings,width=500]
-+
-. When the list contains at least one list element, after the *+* icon, there are buttons to select each individual list element. You can choose one of them by clicking on it. In addition, to the right of the list name, there is a button which will display a vertically scrollable pane with all the list elements.
-+
-.DLUX List Button1
-image::dlux-yang-list-button1.png[DLUX list button1,width=500]
+++ /dev/null
-== OpenDaylight Controller Overview
-
-The OpenDaylight controller is JVM software and can be run from any operating system and hardware as long as it supports Java. The controller is an implementation of the Software Defined Network (SDN) concept and makes use of the following tools:
-
-* *Maven*: OpenDaylight uses Maven for easier build automation. Maven uses pom.xml (Project Object Model) to script the dependencies between bundle and also to describe what bundles to load and start.
-
-* *OSGi*: This framework is the back-end of OpenDaylight as it allows dynamically loading bundles and packages JAR files, and binding bundles together for exchanging information.
-* *JAVA interfaces*: Java interfaces are used for event listening, specifications, and forming patterns. This is the main way in which specific bundles implement call-back functions for events and also to indicate awareness of specific state.
-* *REST APIs*: These are northbound APIs such as topology manager, host tracker, flow programmer, static routing, and so on.
-
-The controller exposes open northbound APIs which are used by applications. The OSGi framework and bidirectional REST are supported for the northbound APIs. The OSGi framework is used for applications that run in the same address space as the controller while the REST (web-based) API is used for applications that do not run in the same address space (or even the same system) as the controller. The business logic and algorithms reside in the applications. These applications use the controller to gather network intelligence, run its algorithm to do analytics, and then orchestrate the new rules throughout the network.
-On the southbound, multiple protocols are supported as plugins, e.g. OpenFlow 1.0, OpenFlow 1.3, BGP-LS, and so on. The OpenDaylight controller starts with an OpenFlow 1.0 southbound plugin. Other OpenDaylight contributors begin adding to the controller code. These modules are linked dynamically into a *Service Abstraction Layer* (SAL).
-
-The SAL exposes services to which the modules north of it are written. The SAL figures out how to fulfill the requested service irrespective of the underlying protocol used between the controller and the network devices. This provides investment protection to the applications as OpenFlow and other protocols evolve over time. For the controller to control devices in its domain, it needs to know about the devices, their capabilities, reachability, and so on. This information is stored and managed by the *Topology Manager*. The other components like ARP handler, Host Tracker, Device Manager, and Switch Manager help in generating the topology database for the Topology Manager.
-
-For a more detailed overview of the OpenDaylight controller, see the _OpenDaylight Developer Guide_.
\ No newline at end of file
+++ /dev/null
-== Running XSQL Console Commands and Queries
-
-//* <<XSQL Overview>>
-//* <<Installing XSQL>>
-//* <<XSQL Console Commands>>
-//* <<XSQL Queries>>
-//** <<Example: skip Criteria Operator>>
-:toc:
-
-=== XSQL Overview
-
-XSQL is an XML-based query language that describes simple stored procedures
-which parse XML data, query or update database tables, and compose XML output.
-XSQL allows you to query tree models like a sequential database. For example,
-you could run a query that lists all of the ports configured on a particular
-module and their attributes.
-
-The following sections cover the XSQL installation process, supported XSQL
-commands, and the way to structure queries.
-
-=== Installing XSQL
-
-To run commands from the XSQL console, you must first install XSQL on your
-system:
-
-. Navigate to the directory in which you unzipped OpenDaylight
-. Start Karaf:
-+
- ./bin/karaf
-+
-. Install XSQL:
-+
- feature:install odl-mdsal-xsql
-
-=== XSQL Console Commands
-
-To enter a command in the XSQL console, structure the command as follows:
-*odl:xsql* _<XSQL command>_
-
-The following table describes the commands supported in this OpenDaylight
-release.
-
-.Supported XSQL Console Commands
-[cols="30%,70%",options="headers"]
-|==============================================
-| *Command* | *Description*
-| *r*
-| Repeats the last command you executed.
-| *list vtables*
-| Lists the schema node containers that are currently installed. Whenever an
-OpenDaylight module is installed, its YANG model is placed in the schema
-context. At that point, the XSQL receives a notification, confirms that the
-module's YANG model resides in the schema context and then maps the model to
-XSQL by setting up the necessary vtables and vfields. This command is useful
-when you need to determine vtable information for a query.
-| *list vfields* _<vtable name>_
-| Lists the vfields present in a specific vtable. This command is useful when
-you need to determine vfields information for a query.
-| *jdbc* _<ip address>_
-| When the ODL server is behind a firewall, and the JDBC client cannot connect
-to the JDBC server, run this command to start the client as a server and
-establish a connection.
-| *exit*
-| Closes the console.
-| *tocsv*
-| Enables or disables the forwarding of query output as a .csv file.
-| *filename* _<filename>_
-| Specifies the .tocsv file to which the query data is exported. If you do not
-specify a value for this option when the toccsv option is enabled, the filename
-for the query data file is generated automatically.
-|==============================================
-
-=== XSQL Queries
-
-You can run a query to extract information that meets the criteria you specify
-using the information provided by the *list vtables* and *list vfields*
-_<vtable name>_ commands. Any query you run should be structured as follows:
-
-*select* _<vfields you want to search for, separated by a comma and a space>_
-*from* _<vtables you want to search in, separated by a comma and a space>_
-*where* _<criteria>_ *'*_<criteria operator>_*';*
-
-For example, if you want to search the nodes/node ID field in the
-nodes/node-connector table and find every instance of the Hardware-Address
-object that contains _BA_ in its text string, enter the following query:
-
- select nodes/node.ID from nodes/node-connector where Hardware-Address like '%BA%';
-
-The following criteria operators are supported:
-
-.Supported XSQL Query Criteria Operators
-[cols="20%,80%",options="headers"]
-|==============================================
-| *Criteria Operators* | *Description*
-| *=* | Lists results that equal the value you specify.
-| *!=* | Lists results that do not equal the value you specify.
-| *like* | Lists results that contain the substring you specify. For
- example, if you specify *like %BC%*, every string that contains
- that particular substring is displayed.
-| *<* | Lists results that are less than the value you specify.
-| *>* | Lists results that are more than the value you specify.
-| *and* | Lists results that match both values you specify.
-| *or* | Lists results that match either of the two values you specify.
-| *>=* | Lists results that are more than or equal to the value you specify.
-| *<=* | Lists results that are less than or equal to the value you specify.
-| *is null* | Lists results for which no value is assigned.
-| *not null* | Lists results for which any value is assigned.
-| *skip* | Use this operator to list matching results from a child node,
- even if its parent node does not meet the specified criteria.
- See the following example for more information.
-|==============================================
-
-==== Example: Skip Criteria Operator
-
-If you are looking at the following structure and want to determine all of the
-ports that belong to a YY type module:
-
-* Network Element 1
-** Module 1, Type XX
-*** Module 1.1, Type YY
-**** Port 1
-**** Port 2
-** Module 2, Type YY
-*** Port 1
-*** Port 2
-
-If you specify *Module.Type='YY'* in your query criteria, the ports associated
-with module 1.1 will not be returned since its parent module is type XX.
-Instead, enter *Module.Type='YY' or skip Module!='YY'*. This tells XSQL to
-disregard any parent module data that does not meet the type YY criteria and
-collect results for any matching child modules. In this example, you are
-instructing the query to skip module 1 and collect the relevant data from
-module 1.1.
-
== DIDM User Guide
-=== Overview
-The Device Identification and Driver Management (DIDM) project addresses the
-need to provide device-specific functionality. Device-specific functionality is
-code that performs a feature, and the code is knowledgeable of the capability
-and limitations of the device. For example, configuring VLANs and adjusting
-FlowMods are features, and there may be different implementations for different
-device types. Device-specific functionality is implemented as Device Drivers.
-Device Drivers need to be associated with the devices they can be used with. To
-determine this association requires the ability to identify the device type.
-
-=== DIDM Architecture
-The DIDM project creates the infrastructure to support the following functions:
-
- * *Discovery* - Determination that a device exists in the controller
- management domain and connectivity to the device can be established. For
- devices that support the OpenFlow protocol, the existing discovery
- mechanism in OpenDaylight suffices. Devices that do not support OpenFlow
- will be discovered through manual means such as the operator entering
- device information via GUI or REST API.
- * *Identification* – Determination of the device type.
- * *Driver Registration* – Registration of Device Drivers as routed RPCs.
- * *Synchronization* – Collection of device information, device configuration,
- and link (connection) information.
- * *Data Models for Common Features* – Data models will be defined to
- perform common features such as VLAN configuration. For example,
- applications can configure a VLAN by writing the VLAN data to the data store
- as specified by the common data model.
- * *RPCs for Common Features* – Configuring VLANs and adjusting
- FlowMods are example of features. RPCs will be defined that specify the
- APIs for these features. Drivers implement features for specific devices and
- support the APIs defined by the RPCs. There may be different Driver
- implementations for different device types.
-
-=== Atrium Support
-
-The Atrium implements an open source router that speaks BGP
-to other routers, and forwards packets received on one port/vlan to another,
-based on the next-hop learnt via BGP peering. A BGP peering application for the
-Open Daylight Controller and a new model for flow objective drivers for switches
-integrated with the Open Daylight Atrium distribution was developed for this
-project. The implementation has the same level of feature partly that was
-introduced by the Atrium 2015/A distribution on the ONOS controller. An overview
-of the architecture is available at here (https://github.com/onfsdn/atrium-docs/wiki/ODL-Based-Atrium-Router-16A).
-
-Atrium stack is implemented in OpenDaylight using Atrium and DIDM project.
-Atrium project provides the application implementation for BGP
-peering and the DIDM project provides implementation for FlowObjectives.
-FlowObjective provides an abstraction layer and present the pipeline agnostic
-api to application to consume.
-
-==== FlowObjective
-Flow Objectives describe an SDN application’s objective (or intention) behind a
-flow it is sending to a device.
-
-Application communicates the flow installation requirement using Flow
-Objectives. DIDM drivers translates the Flow Objectives to device specific flows
-as per the device pipeline.
-
-There are three FlowObjectives (already implemented in ONOS controller) :
-
-* Filtering Objective
-* Next Objective
-* Forwarding Objective
-
-=== Installing DIDM
-
-To install DIDM, download OpenDaylight and use the Karaf console to install the following features:
-
-* odl-openflowplugin-all
-* odl-didm-all
-
-odl-didm-all installs the following required features:
-
-* odl-didm-ovs-all
-* odl-didm-ovs-impl
-* odl-didm-util
-* odl-didm-identification
-* odl-didm-drivers
-* odl-didm-hp-all
-
-=== Configuring DIDM
-
-This section shows an example configuration steps for installing a driver (HP 3800 OpenFlow switch driver).
-
-=== Install DIDM features:
-
-----
-feature:install odl-didm-identification-api
-feature:install odl-didm-drivers
-----
-
-In order to identify the device, device driver needs to be installed first.
-Identification Manager will be notified when a new device connects to the controller.
-
-=== Install HP driver
-
-feature:install odl-didm-hp-all installs the following features
-
-* odl-didm-util
-* odl-didm-identification
-* odl-didm-drivers
-* odl-didm-hp-all
-* odl-didm-hp-impl
-
-Now at this point, the driver has written all of the identification information in to the MD-SAL datastore.
-The identification manager should have that information so that it can try to identify the HP 3800 device when it connects to the controller.
-
-Configure the switch and connect it to the controller from the switch CLI.
-
-=== Run REST GET command to verify the device details:
-
-http://<CONTROLLER-IP:8181>/restconf/operational/opendaylight-inventory:nodes
-
-=== Run REST adjust-flow command to adjust flows and push to the device
-
-.Flow mod driver for HP 3800 device is added in Beryllium release
-This driver adjusts the flows and push the same to the device.
-This API takes the flow to be adjusted as input and displays the adjusted flow as output in the REST output container.
-Here is the REST API to adjust and push flows to HP 3800 device:
-
-http://<CONTROLLER-IP:8181>/restconf/operations/openflow-feature:adjust-flow
-
-=== FlowObjectives API
-
-FlowObjective presents the OpenFlow pipeline agnostic API to Application to
-consume. Application communicate their intent behind installation of flow to
-Drivers using the FlowObjective. Driver translates the FlowObjective in device
-specific flows and uses the OpenFlowPlugin to install the flows to the device.
-
-==== Filter Objective
-
-http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:filter
-
-==== Next Objective
-
-http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:next
-
-==== Forward Objective
-
-http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:forward
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/didm-user-guide.html
+++ /dev/null
-==== Overview
-
-The FaaS renderer feature enables leveraging the FaaS project as a GBP renderer.
-
-===== Installing and Pre-requisites
-
-From the Karaf console in OpenDaylight:
-
- feature:install odl-groupbasedpolicy-faas
-
-More information about FaaS can be found here: https://wiki.opendaylight.org/view/FaaS:GBPIntegration
+++ /dev/null
-==== Overview
-
-The IO Visor renderer feature enables container endpoints (e.g. Docker, LXC) to leverage GBP policies.
-
-The renderer interacts with a IO Visor module from the Linux Foundation IO Visor project.
-
-===== Installing and Pre-requisites
-
-From the Karaf console in OpenDaylight:
-
- feature:install odl-groupbasedpolicy-iovisor odl-restconf
-
-Installation details, usage, and other information for the IO Visor GBP module can be found here: https://github.com/iovisor/iomodules[*IO Visor* github repo for IO Modules]
+++ /dev/null
-==== Overview
-This section is for Application Developers and Network Administrators
-who are looking to integrate Group Based Policy with OpenStack.
-
-To enable the *GBP* Neutron Mapper feature, at the Karaf console:
-
- feature:install odl-groupbasedpolicy-neutronmapper
-
-Neutron Mapper has the following dependencies that are automatically loaded:
-
- odl-neutron-service
-
-Neutron Northbound implementing REST API used by OpenStack
-
- odl-groupbasedpolicy-base
-
-Base *GBP* feature set, such as policy resolution, data model etc.
-
- odl-groupbasedpolicy-ofoverlay
-
-// For Lithium, *GBP* has one renderer, hence this is loaded by default.
-
-REST calls from OpenStack Neutron are by the Neutron NorthBound project.
-
-*GBP* provides the implementation of the http://developer.openstack.org/api-ref-networking-v2.html[Neutron V2.0 API].
-
-==== Features
-
-List of supported Neutron entities:
-
-* Port
-* Network
-** Standard Internal
-** External provider L2/L3 network
-* Subnet
-* Security-groups
-* Routers
-** Distributed functionality with local routing per compute
-** External gateway access per compute node (dedicated port required)
-** Multiple routers per tenant
-* FloatingIP NAT
-* IPv4/IPv6 support
-
-The mapping of Neutron entities to *GBP* entities is as follows:
-
-*Neutron Port*
-
-.Neutron Port
-image::groupbasedpolicy/neutronmapper-gbp-mapping-port.png[width=300]
-
-The Neutron port is mapped to an endpoint.
-
-The current implementation supports one IP address per Neutron port.
-
-An endpoint and L3-endpoint belong to multiple EndpointGroups if the Neutron port is in multiple Neutron Security Groups.
-
-The key for endpoint is L2-bridge-domain obtained as the parent of L2-flood-domain representing Neutron network. The MAC address is from the Neutron port.
-An L3-endpoint is created based on L3-context (the parent of the L2-bridge-domain) and IP address of Neutron Port.
-
-*Neutron Network*
-
-.Neutron Network
-image::groupbasedpolicy/neutronmapper-gbp-mapping-network.png[width=300]
-
-A Neutron network has the following characteristics:
-
-* defines a broadcast domain
-* defines a L2 transmission domain
-* defines a L2 name space.
-
-To represent this, a Neutron Network is mapped to multiple *GBP* entities.
-The first mapping is to an L2 flood-domain to reflect that the Neutron network is one flooding or broadcast domain.
-An L2-bridge-domain is then associated as the parent of L2 flood-domain. This reflects both the L2 transmission domain as well as the L2 addressing namespace.
-
-The third mapping is to L3-context, which represents the distinct L3 address space.
-The L3-context is the parent of L2-bridge-domain.
-
-*Neutron Subnet*
-
-.Neutron Subnet
-image::groupbasedpolicy/neutronmapper-gbp-mapping-subnet.png[width=300]
-
-Neutron subnet is associated with a Neutron network. The Neutron subnet is mapped to a *GBP* subnet where the parent of the subnet is L2-flood-domain representing the Neutron network.
-
-*Neutron Security Group*
-
-.Neutron Security Group and Rules
-image::groupbasedpolicy/neutronmapper-gbp-mapping-securitygroup.png[width=300]
-
-*GBP* entity representing Neutron security-group is EndpointGroup.
-
-*Infrastructure EndpointGroups*
-
-Neutron-mapper automatically creates EndpointGroups to manage key infrastructure items such as:
-
-* DHCP EndpointGroup - contains endpoints representing Neutron DHCP ports
-* Router EndpointGroup - contains endpoints representing Neutron router interfaces
-* External EndpointGroup - holds L3-endpoints representing Neutron router gateway ports, also associated with FloatingIP ports.
-
-*Neutron Security Group Rules*
-
-This is the most involved amongst all the mappings because Neutron security-group-rules are mapped to contracts with clauses,
-subjects, rules, action-refs, classifier-refs, etc.
-Contracts are used between EndpointGroups representing Neutron Security Groups.
-For simplification it is important to note that Neutron security-group-rules are similar to a *GBP* rule containing:
-
-* classifier with direction
-* action of *allow*.
-
-
-*Neutron Routers*
-
-.Neutron Router
-image::groupbasedpolicy/neutronmapper-gbp-mapping-router.png[width=300]
-
-Neutron router is represented as a L3-context. This treats a router as a Layer3 namespace, and hence every network attached to it a part
-of that Layer3 namespace.
-
-This allows for multiple routers per tenant with complete isolation.
-
-The mapping of the router to an endpoint represents the router's interface or gateway port.
-
-The mapping to an EndpointGroup represents the internal infrastructure EndpointGroups created by the *GBP* Neutron Mapper
-
-When a Neutron router interface is attached to a network/subnet, that network/subnet and its associated endpoints or Neutron Ports are seamlessly added to the namespace.
-
-*Neutron FloatingIP*
-
-When associated with a Neutron Port, this leverages the <<OfOverlay,OfOverlay>> renderer's NAT capabilities.
-
-A dedicated _external_ interface on each Nova compute host allows for disitributed external access. Each Nova instance associated with a
-FloatingIP address can access the external network directly without having to route via the Neutron controller, or having to enable any form
-of Neutron distributed routing functionality.
-
-Assuming the gateway provisioned in the Neutron Subnet command for the external network is reachable, the combination of *GBP* Neutron Mapper and
-<<OfOverlay,OfOverlay renderer>> will automatically ARP for this default gateway, requiring no user intervention.
-
-
-*Troubleshooting within GBP*
-
-Logging level for the mapping functionality can be set for package org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling TRACE logging level on Karaf console:
-
- log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
-
-*Neutron mapping example*
-
-As an example for mapping can be used creation of Neutron network, subnet and port.
-When a Neutron network is created 3 *GBP* entities are created: l2-flood-domain, l2-bridge-domain, l3-context.
-
-.Neutron network mapping
-image::groupbasedpolicy/neutronmapper-gbp-mapping-network-example.png[width=500]
-
-After an subnet is created in the network mapping looks like this.
-
-.Neutron subnet mapping
-image::groupbasedpolicy/neutronmapper-gbp-mapping-subnet-example.png[width=500]
-
-If an Neutron port is created in the subnet an endpoint and l3-endpoint are created. The endpoint has key composed from l2-bridge-domain and MAC address from Neutron port. A key of l3-endpoint is compesed from l3-context and IP address. The network containment of endpoint and l3-endpoint points to the subnet.
-
-.Neutron port mapping
-image::groupbasedpolicy/neutronmapper-gbp-mapping-port-example.png[width=500]
-
-==== Configuring GBP Neutron
-
-No intervention passed initial OpenStack setup is required by the user.
-
-More information about configuration can be found in our DevStack demo environment on the https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)[*GBP* wiki].
-
-==== Administering or Managing GBP Neutron
-
-For consistencies sake, all provisioning should be performed via the Neutron API. (CLI or Horizon).
-
-The mapped policies can be augmented via the *GBP* <<UX,UX>>, to:
-
-* Enable <<SFC,Service Function Chaining>>
-* Add endpoints from outside of Neutron i.e. VMs/containers not provisioned in OpenStack
-* Augment policies/contracts derived from Security Group Rules
-* Overlay additional contracts or groupings
-
-==== Tutorials
-
-A DevStack demo environment can be found on the https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)[*GBP* wiki].
+++ /dev/null
-==== Overview
-
-The OpenFlow Overlay (OfOverlay) feature enables the OpenFlow Overlay
-renderer, which creates a network virtualization solution across nodes
-that host Open vSwitch software switches.
-
-===== Installing and Pre-requisites
-
-From the Karaf console in OpenDaylight:
-
- feature:install odl-groupbasedpolicy-ofoverlay
-
-This renderer is designed to work with OpenVSwitch (OVS) 2.1+ (although 2.3 is strongly recommended) and OpenFlow 1.3.
-
-When used in conjunction with the <<Neutron,Neutron Mapper feature>> no extra OfOverlay specific setup is required.
-
-When this feature is loaded "standalone", the user is required to configure infrastructure, such as
-
-* instantiating OVS bridges,
-* attaching hosts to the bridges,
-* and creating the VXLAN/VXLAN-GPE tunnel ports on the bridges.
-
-[[offset]]
-The *GBP* OfOverlay renderer also supports a table offset option, to offset the pipeline post-table 0.
-The value of table offset is stored in the config datastore and it may be rewritten at runtime.
-
-----
-PUT http://{{controllerIp}}:8181/restconf/config/ofoverlay:of-overlay-config
-{
- "of-overlay-config": {
- "gbp-ofoverlay-table-offset": 6
- }
-}
-----
-
-The default value is set by changing:
- <gbp-ofoverlay-table-offset>0</gbp-ofoverlay-table-offset>
-
-in file:
-distribution-karaf/target/assembly/etc/opendaylight/karaf/15-groupbasedpolicy-ofoverlay.xml
-
-To avoid overwriting runtime changes, the default value is used only when the OfOverlay renderer starts and no other
-value has been written before.
-
-==== OpenFlow Overlay Architecture
-
-These are the primary components of *GBP*. The OfOverlay components are highlighted in red.
-
-.OfOverlay within *GBP*
-image::groupbasedpolicy/ofoverlay-1-components.png[align="center",width=500]
-
-In terms of the inner components of the *GBP* OfOverlay renderer:
-
-.OfOverlay expanded view:
-image::groupbasedpolicy/ofoverlay-2-components.png[align="center",width=500]
-
-*OfOverlay Renderer*
-
-Launches components below:
-
-*Policy Resolver*
-
-Policy resolution is completely domain independent, and the OfOverlay leverages process policy information internally. See <<policyresolution,Policy Resolution process>>.
-
-It listens to inputs to the _Tenants_ configuration datastore, validates tenant input, then writes this to the Tenants operational datastore.
-
-From there an internal notification is generated to the PolicyManager.
-
-In the next release, this will be moving to a non-renderer specific location.
-
-*Endpoint Manager*
-
-The endpoint repository operates in *orchestrated* mode. This means the user is responsible for the provisioning of endpoints via:
-
-* <<UX,UX/GUI>>
-* REST API
-
-NOTE: When using the <<Neutron,Neutron mapper>> feature, everything is managed transparently via Neutron.
-
-The Endpoint Manager is responsible for listening to Endpoint repository updates and notifying the Switch Manager when a valid Endpoint has been registered.
-
-It also supplies utility functions to the flow pipeline process.
-
-*Switch Manager*
-
-The Switch Manager is purely a state manager.
-
-Switches are in one of 3 states:
-
-* DISCONNECTED
-* PREPARING
-* READY
-
-*Ready* is denoted by a connected switch:
-
-* having a tunnel interface
-* having at least one endpoint connected.
-
-In this way *GBP* is not writing to switches it has no business to.
-
-*Preparing* simply means the switch has a controller connection but is missing one of the above _complete and necessary_ conditions
-
-*Disconnected* means a previously connected switch is no longer present in the Inventory operational datastore.
-
-.OfOverlay Flow Pipeline
-image::groupbasedpolicy/ofoverlay-3-flowpipeline.png[align="center",width=500]
-
-The OfOverlay leverages Nicira registers as follows:
-
-* REG0 = Source EndpointGroup + Tenant ordinal
-* REG1 = Source Conditions + Tenant ordinal
-* REG2 = Destination EndpointGroup + Tenant ordinal
-* REG3 = Destination Conditions + Tenant ordinal
-* REG4 = Bridge Domain + Tenant ordinal
-* REG5 = Flood Domain + Tenant ordinal
-* REG6 = Layer 3 Context + Tenant ordinal
-
-*Port Security*
-
-Table 0 of the OpenFlow pipeline. Responsible for ensuring that only valid connections can send packets into the pipeline:
-
- cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
- cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
- cookie=0x0, <snip> , priority=121,arp,in_port=5,dl_src=fa:16:3e:d5:b9:8d,arp_spa=10.1.1.3 actions=goto_table:2
- cookie=0x0, <snip> , priority=120,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_src=10.1.1.3 actions=goto_table:2
- cookie=0x0, <snip> , priority=115,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_dst=255.255.255.255 actions=goto_table:2
- cookie=0x0, <snip> , priority=112,ipv6 actions=drop
- cookie=0x0, <snip> , priority=111, ip actions=drop
- cookie=0x0, <snip> , priority=110,arp actions=drop
- cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
- cookie=0x0, <snip> , priority=1 actions=drop
-
-Ingress from tunnel interface, go to Table _Source Mapper_:
-
- cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
-
-Ingress from outside, goto Table _Ingress NAT Mapper_:
-
- cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
-
-ARP from Endpoint, go to Table _Source Mapper_:
-
- cookie=0x0, <snip> , priority=121,arp,in_port=5,dl_src=fa:16:3e:d5:b9:8d,arp_spa=10.1.1.3 actions=goto_table:2
-
-IPv4 from Endpoint, go to Table _Source Mapper_:
-
- cookie=0x0, <snip> , priority=120,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_src=10.1.1.3 actions=goto_table:2
-
-DHCP DORA from Endpoint, go to Table _Source Mapper_:
-
- cookie=0x0, <snip> , priority=115,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_dst=255.255.255.255 actions=goto_table:2
-
-Series of DROP tables with priority set to capture any non-specific traffic that should have matched above:
-
- cookie=0x0, <snip> , priority=112,ipv6 actions=drop
- cookie=0x0, <snip> , priority=111, ip actions=drop
- cookie=0x0, <snip> , priority=110,arp actions=drop
-
-"L2" catch all traffic not identified above:
-
- cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
-
-Drop Flow:
-
- cookie=0x0, <snip> , priority=1 actions=drop
-
-
-*Ingress NAT Mapper*
-
-Table <<offset,_offset_>>+1.
-
-ARP responder for external NAT address:
-
- cookie=0x0, <snip> , priority=150,arp,arp_tpa=192.168.111.51,arp_op=1 actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],set_field:fa:16:3e:58:c3:dd->eth_src,load:0x2->NXM_OF_ARP_OP[],move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],load:0xfa163e58c3dd->NXM_NX_ARP_SHA[],move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],load:0xc0a86f33->NXM_OF_ARP_SPA[],IN_PORT
-
-Translate from Outside to Inside and perform same functions as SourceMapper.
-
- cookie=0x0, <snip> , priority=100,ip,nw_dst=192.168.111.51 actions=set_field:10.1.1.2->ip_dst,set_field:fa:16:3e:58:c3:dd->eth_dst,load:0x2->NXM_NX_REG0[],load:0x1->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],load:0x3->NXM_NX_TUN_ID[0..31],goto_table:3
-
-*Source Mapper*
-
-Table <<offset,_offset_>>+2.
-
-Determines based on characteristics from the ingress port, which:
-
-* EndpointGroup(s) it belongs to
-* Forwarding context
-* Tunnel VNID ordinal
-
-Establishes tunnels at valid destination switches for ingress.
-
-Ingress Tunnel established at remote node with VNID Ordinal that maps to Source EPG, Forwarding Context etc:
-
- cookie=0x0, <snip>, priority=150,tun_id=0xd,in_port=3 actions=load:0xc->NXM_NX_REG0[],load:0xffffff->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],goto_table:3
-
-Maps endpoint to Source EPG, Forwarding Context based on ingress port, and MAC:
-
- cookie=0x0, <snip> , priority=100,in_port=5,dl_src=fa:16:3e:b4:b4:b1 actions=load:0xc->NXM_NX_REG0[],load:0x1->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],load:0xd->NXM_NX_TUN_ID[0..31],goto_table:3
-
-Generic drop:
-
- cookie=0x0, duration=197.622s, table=2, n_packets=0, n_bytes=0, priority=1 actions=drop
-
-*Destination Mapper*
-
-Table <<offset,_offset_>>+3.
-
-Determines based on characteristics of the endpoint:
-
-* EndpointGroup(s) it belongs to
-* Forwarding context
-* Tunnel Destination value
-
-Manages routing based on valid ingress nodes ARP'ing for their default gateway, and matches on either gateway MAC or destination endpoint MAC.
-
-ARP for default gateway for the 10.1.1.0/24 subnet:
-
- cookie=0x0, <snip> , priority=150,arp,reg6=0x7,arp_tpa=10.1.1.1,arp_op=1 actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],set_field:fa:16:3e:28:4c:82->eth_src,load:0x2->NXM_OF_ARP_OP[],move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],load:0xfa163e284c82->NXM_NX_ARP_SHA[],move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],load:0xa010101->NXM_OF_ARP_SPA[],IN_PORT
-
-Broadcast traffic destined for GroupTable:
-
- cookie=0x0, <snip> , priority=140,reg5=0x5,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00 actions=load:0x5->NXM_NX_TUN_ID[0..31],group:5
-
-Layer3 destination matching flows, where priority=100+masklength. Since *GBP* now support L3Prefix endpoint, we can set default routes etc:
-
- cookie=0x0, <snip>, priority=132,ip,reg6=0x7,dl_dst=fa:16:3e:b4:b4:b1,nw_dst=10.1.1.3 actions=load:0xc->NXM_NX_REG2[],load:0x1->NXM_NX_REG3[],load:0x5->NXM_NX_REG7[],set_field:fa:16:3e:b4:b4:b1->eth_dst,dec_ttl,goto_table:4
-
-Layer2 destination matching flows, designed to be caught only after last IP flow (lowest priority IP flow is 100):
-
- cookie=0x0, duration=323.203s, table=3, n_packets=4, n_bytes=168, priority=50,reg4=0x4,dl_dst=fa:16:3e:58:c3:dd actions=load:0x2->NXM_NX_REG2[],load:0x1->NXM_NX_REG3[],load:0x2->NXM_NX_REG7[],goto_table:4
-
-General drop flow:
- cookie=0x0, duration=323.207s, table=3, n_packets=6, n_bytes=588, priority=1 actions=drop
-
-*Policy Enforcer*
-
-Table <<offset,_offset_>>+4.
-
-Once the Source and Destination EndpointGroups are assigned, policy is enforced based on resolved rules.
-
-In the case of <<SFC,Service Function Chaining>>, the encapsulation and destination for traffic destined to a chain, is discovered and enforced.
-
-Policy flow, allowing IP traffic between EndpointGroups:
-
- cookie=0x0, <snip> , priority=64998,ip,reg0=0x8,reg1=0x1,reg2=0xc,reg3=0x1 actions=goto_table:5
-
-*Egress NAT Mapper*
-
-Table <<offset,_offset_>>+5.
-
-Performs NAT function before Egressing OVS instance to the underlay network.
-
-Inside to Outside NAT translation before sending to underlay:
-
- cookie=0x0, <snip> , priority=100,ip,reg6=0x7,nw_src=10.1.1.2 actions=set_field:192.168.111.51->ip_src,goto_table:6
-
-*External Mapper*
-
-Table <<offset,_offset_>>+6.
-
-Manages post-policy enforcement for endpoint specific destination effects. Specifically for <<SFC,Service Function Chaining>>, which is why we can support both symmetric and asymmetric chains
-and distributed ingress/egress classification.
-
-Generic allow:
-
- cookie=0x0, <snip>, priority=100 actions=output:NXM_NX_REG7[]
-
-==== Configuring OpenFlow Overlay via REST
-
-NOTE: Please see the <<UX,UX>> section on how to configure *GBP* via the GUI.
-
-*Endpoint*
-
-----
-POST http://{{controllerIp}}:8181/restconf/operations/endpoint:register-endpoint
-{
- "input": {
- "endpoint-group": "<epg0>",
- "endpoint-groups" : ["<epg1>","<epg2>"],
- "network-containment" : "<fowarding-model-context1>",
- "l2-context": "<bridge-domain1>",
- "mac-address": "<mac1>",
- "l3-address": [
- {
- "ip-address": "<ipaddress1>",
- "l3-context": "<l3_context1>"
- }
- ],
- "*ofoverlay:port-name*": "<ovs port name>",
- "tenant": "<tenant1>"
- }
-}
-----
-
-NOTE: The usage of "port-name" preceded by "ofoverlay". In OpenDaylight, base datastore objects can be _augmented_. In *GBP*, the base endpoint model has no renderer
-specifics, hence can be leveraged across multiple renderers.
-
-*OVS Augmentations to Inventory*
-
-----
-PUT http://{{controllerIp}}:8181/restconf/config/opendaylight-inventory:nodes/
-{
- "opendaylight-inventory:nodes": {
- "node": [
- {
- "id": "openflow:123456",
- "ofoverlay:tunnel": [
- {
- "tunnel-type": "overlay:tunnel-type-vxlan",
- "ip": "<ip_address_of_ovs>",
- "port": 4789,
- "node-connector-id": "openflow:123456:1"
- }
- ]
- },
- {
- "id": "openflow:654321",
- "ofoverlay:tunnel": [
- {
- "tunnel-type": "overlay:tunnel-type-vxlan",
- "ip": "<ip_address_of_ovs>",
- "port": 4789,
- "node-connector-id": "openflow:654321:1"
- }
- ]
- }
- ]
- }
-}
-----
-
-*Tenants* see <<policyresolution,Policy Resolution>> and <<forwarding,Forwarding Model>> for details:
-
-----
-{
- "policy:tenant": {
- "contract": [
- {
- "clause": [
- {
- "name": "allow-http-clause",
- "subject-refs": [
- "allow-http-subject",
- "allow-icmp-subject"
- ]
- }
- ],
- "id": "<id>",
- "subject": [
- {
- "name": "allow-http-subject",
- "rule": [
- {
- "classifier-ref": [
- {
- "direction": "in",
- "name": "http-dest"
- },
- {
- "direction": "out",
- "name": "http-src"
- }
- ],
- "action-ref": [
- {
- "name": "allow1",
- "order": 0
- }
- ],
- "name": "allow-http-rule"
- }
- ]
- },
- {
- "name": "allow-icmp-subject",
- "rule": [
- {
- "classifier-ref": [
- {
- "name": "icmp"
- }
- ],
- "action-ref": [
- {
- "name": "allow1",
- "order": 0
- }
- ],
- "name": "allow-icmp-rule"
- }
- ]
- }
- ]
- }
- ],
- "endpoint-group": [
- {
- "consumer-named-selector": [
- {
- "contract": [
- "<id>"
- ],
- "name": "<name>"
- }
- ],
- "id": "<id>",
- "provider-named-selector": []
- },
- {
- "consumer-named-selector": [],
- "id": "<id>",
- "provider-named-selector": [
- {
- "contract": [
- "<id>"
- ],
- "name": "<name>"
- }
- ]
- }
- ],
- "id": "<id>",
- "l2-bridge-domain": [
- {
- "id": "<id>",
- "parent": "<id>"
- }
- ],
- "l2-flood-domain": [
- {
- "id": "<id>",
- "parent": "<id>"
- },
- {
- "id": "<id>",
- "parent": "<id>"
- }
- ],
- "l3-context": [
- {
- "id": "<id>"
- }
- ],
- "name": "GBPPOC",
- "subject-feature-instances": {
- "classifier-instance": [
- {
- "classifier-definition-id": "<id>",
- "name": "http-dest",
- "parameter-value": [
- {
- "int-value": "6",
- "name": "proto"
- },
- {
- "int-value": "80",
- "name": "destport"
- }
- ]
- },
- {
- "classifier-definition-id": "<id>",
- "name": "http-src",
- "parameter-value": [
- {
- "int-value": "6",
- "name": "proto"
- },
- {
- "int-value": "80",
- "name": "sourceport"
- }
- ]
- },
- {
- "classifier-definition-id": "<id>",
- "name": "icmp",
- "parameter-value": [
- {
- "int-value": "1",
- "name": "proto"
- }
- ]
- }
- ],
- "action-instance": [
- {
- "name": "allow1",
- "action-definition-id": "<id>"
- }
- ]
- },
- "subnet": [
- {
- "id": "<id>",
- "ip-prefix": "<ip_prefix>",
- "parent": "<id>",
- "virtual-router-ip": "<ip address>"
- },
- {
- "id": "<id>",
- "ip-prefix": "<ip prefix>",
- "parent": "<id>",
- "virtual-router-ip": "<ip address>"
- }
- ]
- }
-}
-----
-
-
-==== Tutorials[[Demo]]
-
-Comprehensive tutorials, along with a demonstration environment leveraging Vagrant
-can be found on the https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)[*GBP* wiki]
-
+++ /dev/null
-==== Overview
-
-Please refer to the Service Function Chaining project for specifics on SFC provisioning and theory.
-
-*GBP* allows for the use of a chain, by name, in policy.
-
-This takes the form of an _action_ in *GBP*.
-
-Using the <<demo,*GBP* demo and development environment>> as an example:
-
-.GBP and SFC integration environment
-image::groupbasedpolicy/sfc-1-topology.png[align="center",width=500]
-
-In the topology above, a symmetrical chain between H35_2 and H36_3 could take path:
-
-H35_2 to sw1 to sff1 to sf1 to sff1 to sff2 to sf2 to sff2 to sw6 to H36_3
-
-If symmetric chaining was desired, the return path is:
-
-.GBP and SFC symmetric chain environment
-image::groupbasedpolicy/sfc-2-symmetric.png[align="center",width=500]
-
-
-If asymmetric chaining was desired, the return path could be direct, or an *entirely different chain*.
-
-.GBP and SFC assymmetric chain environment
-image::groupbasedpolicy/sfc-3-asymmetric.png[align="center",width=500]
-
-
-All these scenarios are supported by the integration.
-
-In the *Subject Feature Instance* section of the tenant config, we define the instances of the classifier definitions for ICMP and HTTP:
-----
- "subject-feature-instances": {
- "classifier-instance": [
- {
- "name": "icmp",
- "parameter-value": [
- {
- "name": "proto",
- "int-value": 1
- }
- ]
- },
- {
- "name": "http-dest",
- "parameter-value": [
- {
- "int-value": "6",
- "name": "proto"
- },
- {
- "int-value": "80",
- "name": "destport"
- }
- ]
- },
- {
- "name": "http-src",
- "parameter-value": [
- {
- "int-value": "6",
- "name": "proto"
- },
- {
- "int-value": "80",
- "name": "sourceport"
- }
- ]
- }
- ],
-----
-
-Then the action instances to associate to traffic that matches classifiers are defined.
-
-Note the _SFC chain name_ must exist in SFC, and is validated against
-the datastore once the tenant configuration is entered, before entering a valid tenant configuration into the operational datastore (which triggers policy resolution).
-
-----
- "action-instance": [
- {
- "name": "chain1",
- "parameter-value": [
- {
- "name": "sfc-chain-name",
- "string-value": "SFCGBP"
- }
- ]
- },
- {
- "name": "allow1",
- }
- ]
- },
-----
-
-When ICMP is matched, allow the traffic:
-
-----
-
- "contract": [
- {
- "subject": [
- {
- "name": "icmp-subject",
- "rule": [
- {
- "name": "allow-icmp-rule",
- "order" : 0,
- "classifier-ref": [
- {
- "name": "icmp"
- }
- ],
- "action-ref": [
- {
- "name": "allow1",
- "order": 0
- }
- ]
- }
-
- ]
- },
-----
-
-When HTTP is matched, *in* to the provider of the contract with a TCP destination port of 80 (HTTP) or the HTTP request. The chain action is triggered, and similarly
-*out* from the provider for traffic with TCP source port of 80 (HTTP), or the HTTP response.
-
-----
- {
- "name": "http-subject",
- "rule": [
- {
- "name": "http-chain-rule-in",
- "classifier-ref": [
- {
- "name": "http-dest",
- "direction": "in"
- }
- ],
- "action-ref": [
- {
- "name": "chain1",
- "order": 0
- }
- ]
- },
- {
- "name": "http-chain-rule-out",
- "classifier-ref": [
- {
- "name": "http-src",
- "direction": "out"
- }
- ],
- "action-ref": [
- {
- "name": "chain1",
- "order": 0
- }
- ]
- }
- ]
- }
-----
-
-To enable asymmetrical chaining, for instance, the user desires that HTTP requests traverse the chain, but the HTTP response does not, the HTTP response is set to _allow_ instead of chain:
-
-----
-
- {
- "name": "http-chain-rule-out",
- "classifier-ref": [
- {
- "name": "http-src",
- "direction": "out"
- }
- ],
- "action-ref": [
- {
- "name": "allow1",
- "order": 0
- }
- ]
- }
-----
-
+++ /dev/null
-==== Overview
-
-These following components make up this application and are described in more detail in following sections:
-
-* Basic view
-* Governance view
-* Policy Expression view
-* Wizard view
-
-The *GBP* UX is access via:
-
- http://<odl controller>:8181/index.html
-
-==== Basic view
-
-Basic view contains 5 navigation buttons which switch user to the desired section of application:
-
-* Governance – switch to the Governance view (middle of graphic has the same function)
-* Renderer configuration – switch to the Policy expression view with Renderers section expanded
-* Policy expression – switch to the Policy expression view with Policy section expanded
-* Operational constraints – placeholder for development in next release
-
-.Basic view
-image::groupbasedpolicy/ui-1-basicview.png[align="center",width=500]
-
-
-==== Governance view
-
-Governance view consists from three columns.
-
-.Governance view
-image::groupbasedpolicy/ui-2-governanceview.png[align="center",width=500]
-
-*Governance view – Basic view – Left column*
-
-In the left column is Health section with Exception and Conflict buttons with no functionality yet. This is a placeholder for development in further releases.
-
-*Governance view – Basic view – Middle column*
-
-In the top half of this section is select box with list of tenants for select. Once the tenant is selected, all sub sections in application operate and display data with actual selected tenant.
-
-Below the select box are buttons which display Expressed or Delivered policy of Governance section. In the bottom half of this section is select box with list of renderers for select. There is currently only <<OfOverlay,OfOverlay>> renderer available.
-
-Below the select box is Renderer configuration button, which switch the app into the Policy expression view with Renderers section expanded for performing CRUD operations. Renderer state button display Renderer state view.
-
-*Governance view – Basic view – Right column*
-
-In the bottom part of the right section of Governance view is Home button which switch the app to the Basic view.
-
-In the top part is situated navigation menu with four main sections.
-
-Policy expression button expand/collapse sub menu with three main parts of Policy expression. By clicking on sub menu buttons, user will be switched into the Policy expressions view with appropriate section expanded for performing CRUD operations.
-
-Renderer configuration button switches user into the Policy expressions view.
-
-Governance button expand/collapse sub menu with four main parts of Governance section. Sub menu buttons of Governance section display appropriate section of Governance view.
-
-Operational constraints have no functionality yet, and is a placeholder for development in further releases.
-
-Below the menu is place for view info section which displays info about actual selected element from the topology (explained below).
-
-
-*Governance view – Expressed policy*
-
-In this view are displayed contracts with their consumed and provided EndpointGroups of actual selected tenant, which can be changed in select box in the upper left corner.
-
-By single-clicking on any contract or EPG, the data of actual selected element will be shown in the right column below the menu. A Manage button launches a display wizard window for managing configuration of items such as <<SFC,Service Function Chaining>>.
-
-
-.Expressed policy
-image::groupbasedpolicy/ui-3-governanceview-expressed.png[align="center",width=500]
-
-
-*Governance view – Delivered policy*
-In this view are displayed subjects with their consumed and provided EndpointGroups of actual selected tenant, which can be changed in select box in the upper left corner.
-
-By single-clicking on any subject or EPG, the data of actual selected element will be shown in the right column below the menu.
-
-By double-click on subject the subject detail view will be displayed with subject’s rules of actual selected subject, which can be changed in select box in the upper left corner.
-
-By single-clicking on rule or subject, the data of actual selected element will be shown in the right column below the menu.
-
-By double-clicking on EPG in Delivered policy view, the EPG detail view will be displayed with EPG’s endpoints of actual selected EPG, which can be changed in select box in the upper left corner.
-
-By single-clicking on EPG or endpoint the data of actual selected element will be shown in the right column below the menu.
-
-
-.Delivered policy
-image::groupbasedpolicy/ui-4-governanceview-delivered-0.png[align="center",width=500]
-
-
-
-.Subject detail
-image::groupbasedpolicy/ui-4-governanceview-delivered-1-subject.png[align="center",width=500]
-
-
-.EPG detail
-image::groupbasedpolicy/ui-4-governanceview-delivered-2-epg.png[align="center",width=500]
-
-*Governance view – Renderer state*
-
-In this part are displayed Subject feature definition data with two main parts: Action definition and Classifier definition.
-
-By clicking on the down/right arrow in the circle is possible to expand/hide data of appropriate container or list. Next to the list node are displayed names of list’s elements where one is always selected and element’s data are shown (blue line under the name).
-
-By clicking on names of children nodes is possible to select desired node and node’s data will be displayed.
-
-
-.Renderer state
-image::groupbasedpolicy/ui-4-governanceview-renderer.png[align="center",width=500]
-
-==== Policy expression view
-
-In the left part of this view is placed topology of actual selected elements with the buttons for switching between types of topology at the bottom.
-
-Right column of this view contains four parts. At the top of this column are displayed breadcrumbs with actual position in the application.
-
-Below the breadcrumbs is select box with list of tenants for select. In the middle part is situated navigation menu, which allows switch to the desired section for performing CRUD operations.
-
-At the bottom is quick navigation menu with Access Model Wizard button which display Wizard view, Home button which switch application to the Basic view and occasionally Back button, which switch application to the upper section.
-
-*Policy expression - Navigation menu*
-
-To open Policy expression, select Policy expression from the GBP Home screen.
-
-In the top of navigation box you can select the tenant from the tenants list to activate features addicted to selected tenant.
-
-In the right menu, by default, the Policy menu section is expanded. Subitems of this section are modules for CRUD (creating, reading, updating and deleting) of tenants, EndpointGroups, contracts, L2/L3 objects.
-
-* Section Renderers contains CRUD forms for Classifiers and Actions.
-* Section Endpoints contains CRUD forms for Endpoint and L3 prefix endpoint.
-
-.Navigation menu
-image::groupbasedpolicy/ui-5-expresssion-1.png[height=400]
-
-.CRUD operations
-image::groupbasedpolicy/ui-5-expresssion-2.png[height=400]
-
-
-*Policy expression - Types of topology*
-
-There are three different types of topology:
-
-* Configured topology - EndpointGroups and contracts between them from CONFIG datastore
-* Operational topology - displays same information but is based on operational data.
-* L2/L3 - displays relationships between L3Contexts, L2 Bridge domains, L2 Flood domains and Subnets.
-
-
-.L2/L3 Topology
-image::groupbasedpolicy/ui-5-expresssion-3.png[align="center",width=500]
-
-
-.Config Topology
-image::groupbasedpolicy/ui-5-expresssion-4.png[align="center",width=500]
-
-
-*Policy expression - CRUD operations*
-
-In this part are described basic flows for viewing, adding, editing and deleting system elements like tenants, EndpointGroups etc.
-
-==== Tenants
-
-To edit tenant objects click the Tenants button in the right menu. You can see the CRUD form containing tenants list and control buttons.
-
-To add new tenant, click the Add button This will display the form for adding a new tenant. After filling tenant attributes Name and Description click Save button. Saving of any object can be performed only if all the object attributes are filled correctly. If some attribute doesn't have correct value, exclamation mark with mouse-over tooltip will be displayed next to the label for the attribute. After saving of tenant the form will be closed and the tenants list will be set to default value.
-
-To view an existing tenant, select the tenant from the select box Tenants list. The view form is read-only and can be closed by clicking cross mark in the top right of the form.
-
-To edit selected tenant, click the Edit button, which will display the edit form for selected tenant. After editing the Name and Description of selected tenant click the Save button to save selected tenant. After saving of tenant the edit form will be closed and the tenants list will be set to default value.
-
-To delete tenant select the tenant from the Tenants list and click Delete button.
-
-To return to the Policy expression click Back button on the bottom of window.
-
-*EndpointGroups*
-
-For managing EndpointGroups (EPG) the tenant from the top Tenants list must be selected.
-
-To add new EPG click Add button and after filling required attributes click Save button. After adding the EPG you can edit it and assign Consumer named selector or Provider named selector to it.
-
-To edit EPG click the Edit button after selecting the EPG from Group list.
-
-To add new Consumer named selector (CNS) click the Add button next to the Consumer named selectors list. While CNS editing you can set one or more contracts for current CNS pressing the Plus button and selecting the contract from the Contracts list. To remove the contract, click on the cross mark next to the contract. Added CNS can be viewed, edited or deleted by selecting from the Consumer named selectors list and clicking the Edit and Delete buttons like with the EPG or tenants.
-
-To add new Provider named selector (PNS) click the Add button next to the Provider named selectors list. While PNS editing you can set one or more contracts for current PNS pressing the Plus button and selecting the contract from the Contracts list. To remove the contract, click on the cross mark next to the contract. Added PNS can be viewed, edited or deleted by selecting from the Provider named selectors list and clicking the Edit and Delete buttons like with the EPG or tenants.
-
-To delete EPG, CNS or PNS select it in selectbox and click the Delete button next to the selectbox.
-
-*Contracts*
-
-For managing contracts the tenant from the top Tenants list must be selected.
-
-To add new Contract click Add button and after filling required fields click Save button.
-
-After adding the Contract user can edit it by selecting in the Contracts list and clicking Edit button.
-
-To add new Clause click Add button next to the Clause list while editing the contract. While editing the Clause after selecting clause from the Clause list user can assign clause subjects by clicking the Plus button next to the Clause subjects label. Adding and editing action must be submitted by pressing Save button. To manage Subjects you can use CRUD form like with the Clause list.
-
-*L2/L3*
-
-For managing L2/L3 the tenant from the top Tenants list must be selected.
-
-To add L3 Context click the Add button next to the L3 Context list ,which will display the form for adding a new L3 Context. After filling L3 Context attributes click Save button. After saving of L3 Context, form will be closed and the L3 Context list will be set to default value.
-
-To view an existing L3 Context, select the L3 Context from the select box L3 Context list. The view form is read-only and can be closed by clicking cross mark in the top right of the form.
-
-If user wants to edit selected L3 Context, click the Edit button, which will display the edit form for selected L3 Context. After editing click the Save button to save selected L3 Context. After saving of L3 Context, the edit form will be closed and the L3 Context list will be set to default value.
-
-To delete L3 Context, select it from the L3 Context list and click Delete button.
-
-To add L2 Bridge Domain, click the Add button next to the L2 Bridge Domain list. This will display the form for adding a new L2 Bridge Domain. After filling L2 Bridge Domain attributes click Save button. After saving of L2 Bridge Domain, form will be closed and the L2 Bridge Domain list will be set to default value.
-
-To view an existing L2 Bridge Domain, select the L2 Bridge Domain from the select box L2 Bridge Domain list. The view form is read-only and can be closed by clicking cross mark in the top right of the form.
-
-If user wants to edit selected L2 Bridge Domain, click the Edit button, which will display the edit form for selected L2 Bridge Domain. After editing click the Save button to save selected L2 Bridge Domain. After saving of L2 Bridge Domain the edit form will be closed and the L2 Bridge Domain list will be set to default value.
-
-To delete L2 Bridge Domain select it from the L2 Bridge Domain list and click Delete button.
-
-To add L3 Flood Domain, click the Add button next to the L3 Flood Domain list. This will display the form for adding a new L3 Flood Domain. After filling L3 Flood Domain attributes click Save button. After saving of L3 Flood Domain, form will be closed and the L3 Flood Domain list will be set to default value.
-
-To view an existing L3 Flood Domain, select the L3 Flood Domain from the select box L3 Flood Domain list. The view form is read-only and can be closed by clicking cross mark in the top right of the form.
-
-If user wants to edit selected L3 Flood Domain, click the Edit button, which will display the edit form for selected L3 Flood Domain. After editing click the Save button to save selected L3 Flood Domain. After saving of L3 Flood Domain the edit form will be closed and the L3 Flood Domain list will be set to default value.
-
-To delete L3 Flood Domain select it from the L3 Flood Domain list and click Delete button.
-
-To add Subnet click the Add button next to the Subnet list. This will display the form for adding a new Subnet. After filling Subnet attributes click Save button. After saving of Subnet, form will be closed and the Subnet list will be set to default value.
-
-To view an existing Subnet, select the Subnet from the select box Subnet list. The view form is read-only and can be closed by clicking cross mark in the top right of the form.
-
-If user wants to edit selected Subnet, click the Edit button, which will display the edit form for selected Subnet. After editing click the Save button to save selected Subnet. After saving of Subnet the edit form will be closed and the Subnet list will be set to default value.
-
-To delete Subnet select it from the Subnet list and click Delete button.
-
-*Classifiers*
-
-To add Classifier, click the Add button next to the Classifier list. This will display the form for adding a new Classifier. After filling Classifier attributes click Save button. After saving of Classifier, form will be closed and the Classifier list will be set to default value.
-
-To view an existing Classifier, select the Classifier from the select box Classifier list. The view form is read-only and can be closed by clicking cross mark in the top right of the form.
-
-If you want to edit selected Classifier, click the Edit button, which will display the edit form for selected Classifier. After editing click the Save button to save selected Classifier. After saving of Classifier the edit form will be closed and the Classifier list will be set to default value.
-
-To delete Classifier select it from the Classifier list and click Delete button.
-
-*Actions*
-
-To add Action, click the Add button next to the Action list. This will display the form for adding a new Action. After filling Action attributes click Save button. After saving of Action, form will be closed and the Action list will be set to default value.
-
-To view an existing Action, select the Action from the select box Action list. The view form is read-only and can be closed by clicking cross mark in the top right of the form.
-
-If user wants to edit selected Action, click the Edit button, which will display the edit form for selected Action. After editing click the Save button to save selected Action. After saving of Action the edit form will be closed and the Action list will be set to default value.
-
-To delete Action select it from the Action list and click Delete button.
-
-*Endpoint*
-
-To add Endpoint, click the Add button next to the Endpoint list. This will display the form for adding a new Endpoint. To add EndpointGroup assignment click the Plus button next to the label EndpointGroups. To add Condition click Plus button next to the label Condition. To add L3 Address click the Plus button next to the L3 Addresses label. After filling Endpoint attributes click Save button. After saving of Endpoint, form will be closed and the Endpoint list will be set to default value.
-
-To view an existing Endpoint just, the Endpoint from the select box Endpoint list. The view form is read-only and can be closed by clicking cross mark in the top right of the form.
-
-If you want to edit selected Endpoint, click the Edit button, which will display the edit form for selected Endpoint. After editing click the Save button to save selected Endpoint. After saving of Endpoint the edit form will be closed and the Endpoint list will be set to default value.
-
-To delete Endpoint select it from the Endpoint list and click Delete button.
-
-*L3 prefix endpoint*
-
-To add L3 prefix endpoint, click the Add button next to the L3 prefix endpoint list. This will display the form for adding a new Endpoint. To add EndpointGroup assignment, click the Plus button next to the label EndpointGroups. To add Condition, click Plus button next to the label Condition. To add L2 gateway click the Plus button next to the L2 gateways label. To add L3 gateway, click the Plus button next to the L3 gateways label. After filling L3 prefix endpoint attributes click Save button. After saving of L3 prefix endpoint, form will be closed and the Endpoint list will be set to default value.
-
-To view an existing L3 prefix endpoint, select the Endpoint from the select box L3 prefix endpoint list. The view form is read-only and can be closed by clicking cross mark in the top right of the form.
-
-If you want to edit selected L3 prefix endpoint, click the Edit button, which will display the edit form for selected L3 prefix endpoint. After editing click the Save button to save selected L3 prefix endpoint. After saving of Endpoint the edit form will be closed and the Endpoint list will be set to default value.
-
-To delete Endpoint select it from the L3 prefix endpoint list and click Delete button.
-
-==== Wizard
-
-Wizard provides quick method to send basic data to controller necessary for basic usage of GBP application. It is useful in the case that there aren’t any data in controller. In the first tab is form for create tenant. The second tab is for CRUD operations with contracts and their sub elements such as subjects, rules, clauses, action refs and classifier refs. The last tab is for CRUD operations with EndpointGroups and their CNS and PNS. Created structure of data is possible to send by clicking on Submit button.
-
-
-.Wizard
-image::groupbasedpolicy/ui-6-wizard.png[align="center",width=500]
-
== Group Based Policy User Guide
-=== Overview
-OpenDaylight Group Based Policy allows users to express network configuration in a declarative versus imperative way.
-
-This is often described as asking for *"what you want"*, rather than *"how to do it"*.
-
-In order to achieve this Group Based Policy (herein referred to as *GBP*) is an implementation of an *Intent System*.
-
-An *Intent System*:
-
-* is a process around an intent driven data model
-* contains no domain specifics
-* is capable of addressing multiple semantic definitions of intent
-
-To this end, *GBP* Policy views an *Intent System* visually as:
-
-.Intent System Process and Policy Surfaces
-image::groupbasedpolicy/IntentSystemPolicySurfaces.png[align="center",width=500]
-
-* *expressed intent* is the entry point into the system.
-* *operational constraints* provide policy for the usage of the system which modulates how the system is consumed. For instance _"All Financial applications must use a specific encryption standard"_.
-* *capabilities and state* are provided by _renderers_. _Renderers_ dynamically provide their capabilities to the core model, allowing the core model to remain non-domain specific.
-* *governance* provides feedback on the delivery of the _expressed intent_. i.e. _"Did we do what you asked us?"_
-
-In summary *GBP is about the Automation of Intent*.
-
-By thinking of *Intent Systems* in this way, it enables:
-
-* *automation of intent*
-+
-By focusing on *Model. Process. Automation*, a consistent policy resolution process enables for mapping between the *expressed intent* and renderers responsible for providing the capabilities of implementing that intent.
-
-* recursive/intent level-independent behaviour.
-+
-Where _one person's concrete is another's abstract_, intent can be fulfilled through a hierarchical implementation of non-domain specific policy resolution. Domain specifics are provided by the _renderers_, and exposed via the API, at each policy resolution instance.
-For example:
-
-** To DNS: The name "www.foo.com" is _abstract_, and it's IPv4 address 10.0.0.10 is _concrete_,
-** To an IP stack: 10.0.0.10 is _abstract_ and the MAC 08:05:04:03:02:01 is _concrete_,
-** To an Ethernet switch: The MAC 08:05:04:03:02:01 is _abstract_, the resolution to a port in it's CAM table is _concrete_,
-** To an optical network: The port maybe _abstract_, yet the optical wavelength is _concrete_.
-
-NOTE: _This is a very domain specific analogy, tied to something most readers will understand. It in no way implies the *GBP* should be implemented in an OSI type fashion.
-The premise is that by implementing a full *Intent System*, the user is freed from a lot of the constraints of how the expressed intent is realised._
-
-It is important to show the overall philosophy of *GBP* as it sets the project's direction.
-
-In the Beryllium release of OpenDaylight, *GBP* focused on *expressed intent*, *refactoring of how renderers consume and publish Subject Feature Definitions for multi-renderer support*.
-
-=== GBP Base Architecture and Value Proposition
-==== Terminology
-In order to explain the fundamental value proposition of *GBP*, an illustrated example is given. In order to do that some terminology must be defined.
-
-The Access Model is the core of the *GBP* Intent System policy resolution process.
-
-.GBP Access Model Terminology - Endpoints, EndpointGroups, Contract
-image::groupbasedpolicy/GBPTerminology1.png[align="center",width=500]
-
-.GBP Access Model Terminology - Subject, Classifier, Action
-image::groupbasedpolicy/GBPTerminology2.png[align="center",width=500]
-
-.GBP Forwarding Model Terminology - L3 Context, L2 Bridge Context, L2 Flood Context/Domain, Subnet
-image::groupbasedpolicy/GBPTerminology3.png[align="center",width=500]
-
-* Endpoints:
-+
-Define concrete uniquely identifiable entities. In Beryllium, examples could be a Docker container, or a Neutron port
-* EndpointGroups:
-+
-EndpointGroups are sets of endpoints that share a common set of policies. EndpointGroups can participate in contracts that determine the kinds of communication that are allowed. EndpointGroups _consume_ and _provide_ contracts.
-They also expose both _requirements and capabilities_, which are labels that help to determine how contracts will be applied. An EndpointGroup can specify a parent EndpointGroup from which it inherits.
-
-* Contracts:
-+
-Contracts determine which endpoints can communicate and in what way. Contracts between pairs of EndpointGroups are selected by the contract selectors defined by the EndpointGroup.
-Contracts expose qualities, which are labels that can help EndpointGroups to select contracts. Once the contract is selected,
-contracts have clauses that can match against requirements and capabilities exposed by EndpointGroups, as well as any conditions
-that may be set on endpoints, in order to activate subjects that can allow specific kinds of communication. A contract is allowed to specify a parent contract from which it inherits.
-
-* Subject
-+
-Subjects describe some aspect of how two endpoints are allowed to communicate. Subjects define an ordered list of rules that will match against the traffic and perform any necessary actions on that traffic.
-No communication is allowed unless a subject allows that communication.
-
-* Clause
-+
-Clauses are defined as part of a contract. Clauses determine how a contract should be applied to particular endpoints and EndpointGroups. Clauses can match against requirements and capabilities exposed by EndpointGroups,
-as well as any conditions that may be set on endpoints. Matching clauses define some set of subjects which can be applied to the communication between the pairs of endpoints.
-
-==== Architecture and Value Proposition
-
-*GBP* offers an intent based interface, accessed via the <<UX,UX>>, via the <<REST,REST API>> or directly from a domain-specific-language such as <<Neutron,Neutron>> through a mapping interface.
-
-There are two models in *GBP*:
-
-* the access (or core) model
-* the forwarding model
-
-.GBP Access (or Core) Model
-image::groupbasedpolicy/GBP_AccessModel_simple.png[align="center",width=500]
-
-The _classifier_ and _action_ portions of the model can be thought of as hooks, with their definition provided by each _renderer_ about its domain specific capabilities. In *GBP* Beryllium, there is one renderer,
-the _<<OfOverlay,OpenFlow Overlay renderer (OfOverlay).>>_
-
-These hooks are filled with _definitions_ of the types of _features_ the renderer can provide the _subject_, and are called *subject-feature-definitions*.
-
-This means an _expressed intent_ can be fulfilled by, and across, multiple renderers simultaneously, without any specific provisioning from the consumer of *GBP*.
-
-[[forwarding]]
-Since *GBP* is implemented in OpenDaylight, which is an SDN controller, it also must address networking. This is done via the _forwarding model_, which is domain specific to networking, but could be applied to many different _types_ of networking.
-
-.GBP Forwarding Model
-image::groupbasedpolicy/GBP_ForwardingModel_simple.png[align="center",width=500]
-
-Each endpoint is provisioned with a _network-containment_. This can be a:
-
-* subnet
-+
-** normal IP stack behaviour, where ARP is performed in subnet, and for out of subnet, traffic is sent to default gateway.
-** a subnet can be a child of any of the below forwarding model contexts, but typically would be a child of a flood-domain
-* L2 flood-domain
-** allows flooding behaviour.
-** is a n:1 child of a bridge-domain
-** can have multiple children
-* L2 bridge-domain
-** is a layer2 namespace
-** is the realm where traffic can be sent at layer 2
-** is a n:1 child of a L3 context
-** can have multiple children
-* L3 context
-** is a layer3 namespace
-** is the realm where traffic is passed at layer 3
-** is a n:1 child of a tenant
-** can have multiple children
-
-A simple example of how the access and forwarding models work is as follows:
-
-.GBP Endpoints, EndpointGroups and Contracts
-image::groupbasedpolicy/GBP_Endpoint_EPG_Contract.png[align="center",width=300]
-
-In this example, the *EPG:webservers* is _providing_ the _web_ and _ssh_ contracts. The *EPG:client* is consuming those contracts. *EPG:client* is providing the _any_ contract, which is consumed by *EPG:webservers*.
-
-The _direction_ keyword is always from the perspective of the _provider_ of the contract. In this case contract _web_, being _provided_ by *EPG:webservers*, with the classifier to match TCP destination port 80, means:
-
-* packets with a TCP destination port of 80
-* sent to (_in_) endpoints in the *EPG:webservers*
-* will be _allowed_.
-
-.GBP Endpoints and the Forwarding Model
-image::groupbasedpolicy/GBP_Endpoint_EPG_Forwarding.png[align="center",width=300]
-
-When the forwarding model is considered in the figure above, it can be seen that even though all endpoints are communicating using a common set of contracts,
-their forwarding is _contained_ by the forwarding model contexts or namespaces.
-In the example shown, the endpoints associated with a _network-containment_ that has an ultimate parent of _L3Context:Sales_ can only communicate with other endpoints within this L3Context.
-In this way L3VPN services can be implemented without any impact to the *Intent* of the contract.
-
-===== High-level implementation Architecture
-
-The overall architecture, including _<<Neutron,Neutron>>_ domain specific mapping, and the <<OfOverlay,OpenFlow Overlay renderer>> looks as so:
-
-.GBP High Level Beryllium Architecture
-image::groupbasedpolicy/GBP_High-levelBerylliumArchitecture.png[align="center",width=300]
-
-The major benefit of this architecture is that the mapping of the domain-specific-language is completely separate and independent of the underlying renderer implementation.
-
-For instance, using the <<Neutron,Neutron Mapper>>, which maps the Neutron API to the *GBP* core model, any contract automatically generated from this mapping can be augmented via the <<UX,UX>>
-to use <<SFC,Service Function Chaining>>, a capability not currently available in OpenStack Neutron.
-
-When another renderer is added, for instance, NetConf, the same policy can now be leveraged across NetConf devices simultaneously:
-
-.GBP High Level Beryllium Architecture - adding a renderer
-image::groupbasedpolicy/GBP_High-levelExtraRenderer.png[align="center",width=300]
-
-As other domain-specific mappings occur, they too can leverage the same renderers, as the renderers only need to implement the *GBP* access and forwarding models, and the domain-specific mapping need only manage mapping to the access and forwarding models. For instance:
-
-.GBP High Level Beryllium Architecture - adding a renderer
-image::groupbasedpolicy/High-levelBerylliumArchitectureEvolution2.png[align="center",width=300]
-
-In summary, the *GBP* architecture:
-
-* separates concerns: the Expressed Intent is kept completely separated from the underlying renderers.
-* is cohesive: each part does it's part and it's part only
-* is scalable: code can be optimised around model mapping/implementation, and functionality re-used
-
-==== Policy Resolution [[policyresolution]]
-
-===== Contract Selection
-
-The first step in policy resolution is to select the contracts that are in scope.
-
-EndpointGroups participate in contracts either as a _provider_ or as a _consumer_ of a contract. Each EndpointGroup can participate in many contracts at the same time, but for each contract it can be in only one role at a time.
-In addition, there are two ways for an EndpointGroup to select a contract: either with either a:
-
-* _named selector_
-+
-Named selectors simply select a specific contract by its contract ID.
-* target selector.
-+
-Target selectors allow for additional flexibility by matching against _qualities_ of the contract's _target._
-
-Thus, there are a total of 4 kinds of contract selector:
-
-* provider named selector
-+
-Select a contract by contract ID, and participate as a provider.
-
-* provider target selector
-+
-Match against a contract's target with a quality matcher, and participate as a provider.
-
-* consumer named selector
-+
-Select a contract by contract ID, and participate as a consumer.
-
-* consumer target selector
-+
-Match against a contract's target with a quality matcher, and participate as a consumer.
-
-To determine which contracts are in scope, contracts are found where either the source EndpointGroup selects a contract as either a provider or consumer,
-while the destination EndpointGroup matches against the same contract in the corresponding role. So if endpoint _x_ in EndpointGroup _X_ is communicating with endpoint _y_
-in EndpointGroup _Y_, a contract _C_ is in scope if either _X_ selects _C_ as a provider and _Y_ selects _C_ as a consumer, or vice versa.
-
-The details of how quality matchers work are described further in <<Matchers,Matchers>>.
-Quality matchers provide a flexible mechanism for contract selection based on labels.
-
-The end result of the contract selection phase can be thought of as a set of tuples representing selected contract scopes. The fields of the tuple are:
-
-* Contract ID
-* The provider EndpointGroup ID
-* The name of the selector in the provider EndpointGroup that was used to select the contract, called the _matching provider selector._
-* The consumer EndpointGroup ID
-* The name of the selector in the consumer EndpointGroup that was used to select the contract, called the _matching consumer selector._
-
-The result is then stored in the datastore under *Resolved Policy*.
-
-===== Subject Selection
-
-The second phase in policy resolution is to determine which subjects are in scope.
-The subjects define what kinds of communication are allowed between endpoints in the EndpointGroups.
-For each of the selected contract scopes from the contract selection phase, the subject selection procedure is applied.
-
-Labels called, capabilities, requirements and conditions are matched against to bring a Subject _into scope_.
-EndpointGroups have capabilities and requirements, while endpoints have conditions.
-
-===== Requirements and Capabilities
-
-When acting as a _provider_, EndpointGroups expose _capabilities,_ which are labels representing specific pieces of functionality that can be exposed to other
-EndpointGroups that may meet functional requirements of those EndpointGroups.
-
-When acting as a _consumer_, EndpointGroups expose _requirements_, which are labels that represent that the EndpointGroup requires some specific piece of functionality.
-
-As an example, we might create a capability called "user-database" which indicates that an EndpointGroup contains endpoints that implement a database of users.
-
-We might create a requirement also called "user-database" to indicate an EndpointGroup contains endpoints that will need to communicate with the endpoints that expose this service.
-
-Note that in this example the requirement and capability have the same name, but the user need not follow this convention.
-
-The matching provider selector (that was used by the provider EndpointGroup to select the contract) is examined to determine the capabilities exposed by the provider EndpointGroup for this contract scope.
-
-The provider selector will have a list of capabilities either directly included in the provider selector or inherited from a parent selector or parent EndpointGroup. (See <<Inheritance,Inheritance>>).
-
-Similarly, the matching consumer selector will expose a set of requirements.
-
-===== Conditions
-
-Endpoints can have _conditions_, which are labels representing some relevant piece of operational state related to the endpoint.
-
-An example of a condition might be "malware-detected," or "authentication-succeeded." Conditions are used to affect how that particular endpoint can communicate.
-
-To continue with our example, the "malware-detected" condition might cause an endpoint's connectivity to be cut off, while "authentication-succeeded" might open up communication with services
-that require an endpoint to be first authenticated and then forward its authentication credentials.
-
-===== Clauses
-
-Clauses perform the actual selection of subjects.
-A clause has lists of matchers in two categories. In order for a clause to become active, all lists of matchers must match.
-A matching clause will select all the subjects referenced by the clause.
-Note that an empty list of matchers counts as a match.
-
-The first category is the consumer matchers, which match against the consumer EndpointGroup and endpoints. The consumer matchers are:
-
-* Group Idenfication Constraint: Requirement matchers
-+
-Matches against requirements in the matching consumer selector.
-
-* Group Identification Constraint: GroupName
-+
-Matches against the group name
-
-* Consumer condition matchers
-+
-Matches against conditions on endpoints in the consumer EndpointGroup
-
-* Consumer Endpoint Identification Constraint
-+
-Label based criteria for matching against endpoints. In Beryllium this can be used to label endpoints based on IpPrefix.
-
-The second category is the provider matchers, which match against the provider EndpointGroup and endpoints. The provider matchers are:
-
-* Group Idenfication Constraint: Capability matchers
-+
-Matches against capabilities in the matching provider selector.
-
-* Group Identification Constraint: GroupName
-+
-Matches against the group name
-
-* Consumer condition matchers
-+
-Matches against conditions on endpoints in the provider EndpointGroup
-
-* Consumer Endpoint Identification Constraint
-+
-Label based criteria for matching against endpoints. In Beryllium this can be used to label endpoints based on IpPrefix.
-
-Clauses have a list of subjects that apply when all the matchers in the clause match. The output of the subject selection phase logically is a set of subjects that are in scope for any particular pair of endpoints.
-
-===== Rule Application
-
-Now subjects have been selected that apply to the traffic between a particular set of endpoints, policy can be applied to allow endpoints to communicate.
-The applicable subjects from the previous step will each contain a set of rules.
-
-Rules consist of a set of _classifiers_ and a set of _actions_. Classifiers match against traffic between two endpoints.
-An example of a classifier would be something that matches against all TCP traffic on port 80, or one that matches against HTTP traffic containing a particular cookie.
-Actions are specific actions that need to be taken on the traffic before it reaches its destination.
-Actions could include tagging or encapsulating the traffic in some way, redirecting the traffic, or applying a <<SFC,service function chain>>.
-
-Rules, subjects, and actions have an _order_ parameter, where a lower order value means that a particular item will be applied first.
-All rules from a particular subject will be applied before the rules of any other subject, and all actions from a particular rule will be applied before the actions from another rule.
-If more than item has the same order parameter, ties are broken with a lexicographic ordering of their names, with earlier names having logically lower order.
-
-====== Matchers [[Matchers]]
-
-Matchers specify a set of labels (which include requirements, capabilities, conditions, and qualities) to match against.
-There are several kinds of matchers that operate similarly:
-
-* Quality matchers
-+
-used in target selectors during the contract selection phase. Quality matchers provide a more advanced and flexible way to select contracts compared to a named selector.
-
-* Requirement and capability matchers
-+
-used in clauses during the subject selection phase to match against requirements and capabilities on EndpointGroups
-
-* Condition matchers
-+
-used in clauses during the subject selection phase to match against conditions on endpoints
-
-A matcher is, at its heart, fairly simple. It will contain a list of label names, along with a _match type_.
-The match type can be either:
-
-* "all"
-+
-which means the matcher matches when all of its labels match
-
-* "any"
-+
-which means the matcher matches when any of its labels match,
-* "none"
-+
-which means the matcher matches when none of its labels match.
-
-Note a _match all_ matcher can be made by matching against an empty set of labels with a match type of "all."
-
-Additionally each label to match can optionally include a relevant name field. For quality matchers, this is a target name.
-For capability and requirement matchers, this is a selector name. If the name field is specified, then the matcher will only match against targets or selectors with that name, rather than any targets or selectors.
-
-===== Inheritance [[Inheritance]]
-
-Some objects in the system include references to parents, from which they will inherit definitions.
-The graph of parent references must be loop free. When resolving names, the resolution system must detect loops and raise an exception.
-Objects that are part of these loops may be considered as though they are not defined at all.
-Generally, inheritance works by simply importing the objects in the parent into the child object. When there are objects with the same name in the child object,
-then the child object will override the parent object according to rules which are specific to the type of object. We'll next explore the detailed rules for inheritance for each type of object
-
-*EndpointGroups*
-
-EndpointGroups will inherit all their selectors from their parent EndpointGroups. Selectors with the same names as selectors in the parent EndpointGroups will inherit their behavior as defined below.
-
-*Selectors*
-
-Selectors include provider named selectors, provider target selectors, consumer named selectors, and consumer target selectors. Selectors cannot themselves have parent selectors, but when selectors have the same name as a selector of the same type in the parent EndpointGroup, then they will inherit from and override the behavior of the selector in the parent EndpointGroup.
-
-*Named Selectors*
-
-Named selectors will add to the set of contract IDs that are selected by the parent named selector.
-
-*Target Selectors*
-
-A target selector in the child EndpointGroup with the same name as a target selector in the parent EndpointGroup will inherit quality matchers from the parent. If a quality matcher in the child has the same name as a quality matcher in the parent, then it will inherit as described below under Matchers.
-
-*Contracts*
-
-Contracts will inherit all their targets, clauses and subjects from their parent contracts. When any of these objects have the same name as in the parent contract, then the behavior will be as defined below.
-
-*Targets*
-
-Targets cannot themselves have a parent target, but it may inherit from targets with the same name as the target in a parent contract. Qualities in the target will be inherited from the parent. If a quality with the same name is defined in the child, then this does not have any semantic effect except if the quality has its inclusion-rule parameter set to "exclude." In this case, then the label should be ignored for the purpose of matching against this target.
-
-*Subjects*
-
-Subjects cannot themselves have a parent subject, but it may inherit from a subject with the same name as the subject in a parent contract.
-The order parameter in the child subject, if present, will override the order parameter in the parent subject.
-The rules in the parent subject will be added to the rules in the child subject. However, the rules will not override rules of the same name. Instead, all rules in the parent subject will be considered to run with a higher order than all rules in the child; that is all rules in the child will run before any rules in the parent. This has the effect of overriding any rules in the parent without the potentially-problematic semantics of merging the ordering.
-
-*Clauses*
-
-Clauses cannot themselves have a parent clause, but it may inherit from a clause with the same name as the clause in a parent contract.
-The list of subject references in the parent clause will be added to the list of subject references in the child clause. This is just a union operation.
-A subject reference that refers to a subject name in the parent contract might have that name overridden in the child contract.
-Each of the matchers in the clause are also inherited by the child clause.
-Matchers in the child of the same name and type as a matcher from the parent will inherit from and override the parent matcher. See below under Matchers for more information.
-
-*Matchers*
-
-Matchers include quality matchers, condition matchers, requirement matchers, and capability matchers.
-Matchers cannot themselves have parent matchers, but when there is a matcher of the same name and type in the parent object,
-then the matcher in the child object will inherit and override the behavior of the matcher in the parent object.
-The match type, if specified in the child, overrides the value specified in the parent.
-Labels are also inherited from the parent object. If there is a label with the same name in the child object, this does not have any semantic effect except if the label has its inclusion-rule parameter set to "exclude."
-In this case, then the label should be ignored for the purpose of matching. Otherwise, the label with the same name will completely override the label from the parent.
-
-=== Using the GBP UX interface [[UX]]
-
-include::odl-groupbasedpolicy-ui-user-guide.adoc[]
-
-=== Using the GBP API [[REST]]
-
-Please see:
-
-* <<OfOverlay,Using the GBP OpenFlow Overlay (OfOverlay) renderer>>
-* <<policyresolution, Policy Resolution>>
-* <<forwarding, Forwarding Model>>
-* <<demo, the *GBP* demo and development environments for tips>>
-
-It is recommended to use either:
-
-* <<Neutron, Neutron mapper>>
-* <<UX, the UX>>
-
-If the REST API must be used, and the above resources are not sufficient:
-
-* feature:install odl-dlux-yangui
-* browse to: http://<odl-controller>:8181/index.html and select YangUI from the left menu.
-
-to explore the various *GBP* REST options
-
-
-=== Using OpenStack with GBP [[Neutron]]
-
-
-include::odl-groupbasedpolicy-neutronmapper-user-guide.adoc[]
-
-
-=== Using the GBP OpenFlow Overlay (OfOverlay) renderer [[OfOverlay]]
-
-
-include::odl-groupbasedpolicy-ofoverlay-user-guide.adoc[]
-
-
-=== Using the GBP eBPF IO Visor Agent renderer [[IoVisor]]
-
-
-include::odl-groupbasedpolicy-iovisor-user-guide.adoc[]
-
-
-=== Using the GBP FaaS renderer [[FaaS]]
-
-
-include::odl-groupbasedpolicy-faas-user-guide.adoc[]
-
-
-=== Using Service Function Chaining (SFC) with GBP Neutron Mapper and OfOverlay [[SFC]]
-
-
-include::odl-groupbasedpolicy-sfc-user-guide.adoc[]
-
-
-=== Demo/Development environment[[demo]]
-
-The *GBP* project for Beryllium has two demo/development environments.
-
-* Docker based GBP and GBP+SFC integration Vagrant environment
-* DevStack based GBP+Neutron integration Vagrant environment
-
-https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)/Consumability/Demo[Demo @ GBP wiki]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/group-based-policy-user-guide.html
== L2Switch User Guide
-=== Overview
-The L2Switch project provides Layer2 switch functionality.
-
-=== L2Switch Architecture
-* Packet Handler
- ** Decodes the packets coming to the controller and dispatches them appropriately
-* Loop Remover
- ** Removes loops in the network
-* Arp Handler
- ** Handles the decoded ARP packets
-* Address Tracker
- ** Learns the Addresses (MAC and IP) of entities in the network
-* Host Tracker
- ** Tracks the locations of hosts in the network
-* L2Switch Main
- ** Installs flows on each switch based on network traffic
-
-=== Configuring L2Switch
-This sections below give details about the configuration settings for the components that can be configured.
-
-//The base distribution configuration files are located in distribution/base/target/distributions-l2switch-base-0.1.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial
-
-//The karaf distribution configuration files are located in distribution/karaf/target/assembly/etc/opendaylight/karaf
-
-=== Configuring Loop Remover
-* 52-loopremover.xml
- ** is-install-lldp-flow
- *** "true" means a flow that sends all LLDP packets to the controller will be installed on each switch
- *** "false" means this flow will not be installed
- ** lldp-flow-table-id
- *** The LLDP flow will be installed on the specified flow table of each switch
- *** This field is only relevant when "is-install-lldp-flow" is set to "true"
- ** lldp-flow-priority
- *** The LLDP flow will be installed with the specified priority
- *** This field is only relevant when "is-install-lldp-flow" is set to "true"
- ** lldp-flow-idle-timeout
- *** The LLDP flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
- *** This field is only relevant when "is-install-lldp-flow" is set to "true"
- ** lldp-flow-hard-timeout
- *** The LLDP flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
- *** This field is only relevant when "is-install-lldp-flow" is set to "true"
- ** graph-refresh-delay
- *** A graph of the network is maintained and gets updated as network elements go up/down (i.e. links go up/down and switches go up/down)
- *** After a network element going up/down, it waits _graph-refresh-delay_ seconds before recomputing the graph
- *** A higher value has the advantage of doing less graph updates, at the potential cost of losing some packets because the graph didn't update immediately.
- *** A lower value has the advantage of handling network topology changes quicker, at the cost of doing more computation.
-
-=== Configuring Arp Handler
-* 54-arphandler.xml
- ** is-proactive-flood-mode
- *** "true" means that flood flows will be installed on each switch. With this flood flow, each switch will flood a packet that doesn't match any other flows.
- **** Advantage: Fewer packets are sent to the controller because those packets are flooded to the network.
- **** Disadvantage: A lot of network traffic is generated.
- *** "false" means the previously mentioned flood flows will not be installed. Instead an ARP flow will be installed on each switch that sends all ARP packets to the controller.
- **** Advantage: Less network traffic is generated.
- **** Disadvantage: The controller handles more packets (ARP requests & replies) and the ARP process takes longer than if there were flood flows.
- ** flood-flow-table-id
- *** The flood flow will be installed on the specified flow table of each switch
- *** This field is only relevant when "is-proactive-flood-mode" is set to "true"
- ** flood-flow-priority
- *** The flood flow will be installed with the specified priority
- *** This field is only relevant when "is-proactive-flood-mode" is set to "true"
- ** flood-flow-idle-timeout
- *** The flood flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
- *** This field is only relevant when "is-proactive-flood-mode" is set to "true"
- ** flood-flow-hard-timeout
- *** The flood flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
- *** This field is only relevant when "is-proactive-flood-mode" is set to "true"
- ** arp-flow-table-id
- *** The ARP flow will be installed on the specified flow table of each switch
- *** This field is only relevant when "is-proactive-flood-mode" is set to "false"
- ** arp-flow-priority
- *** The ARP flow will be installed with the specified priority
- *** This field is only relevant when "is-proactive-flood-mode" is set to "false"
- ** arp-flow-idle-timeout
- *** The ARP flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
- *** This field is only relevant when "is-proactive-flood-mode" is set to "false"
- ** arp-flow-hard-timeout
- *** The ARP flow will timeout (removed from the switch) after _arp-flow-hard-timeout_ seconds, regardless of how many packets it is forwarding
- *** This field is only relevant when "is-proactive-flood-mode" is set to "false"
-
-=== Configuring Address Tracker
-* 56-addresstracker.xml
- ** timestamp-update-interval
- *** A last-seen timestamp is associated with each address. This last-seen timestamp will only be updated after _timestamp-update-interval_ milliseconds.
- *** A higher value has the advantage of performing less writes to the database.
- *** A lower value has the advantage of knowing how fresh an address is.
- ** observe-addresses-from
- *** IP and MAC addresses can be observed/learned from ARP, IPv4, and IPv6 packets. Set which packets to make these observations from.
-
-=== Configuring L2Switch Main
-* 58-l2switchmain.xml
- ** is-install-dropall-flow
- *** "true" means a drop-all flow will be installed on each switch, so the default action will be to drop a packet instead of sending it to the controller
- *** "false" means this flow will not be installed
- ** dropall-flow-table-id
- *** The dropall flow will be installed on the specified flow table of each switch
- *** This field is only relevant when "is-install-dropall-flow" is set to "true"
- ** dropall-flow-priority
- *** The dropall flow will be installed with the specified priority
- *** This field is only relevant when "is-install-dropall-flow" is set to "true"
- ** dropall-flow-idle-timeout
- *** The dropall flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
- *** This field is only relevant when "is-install-dropall-flow" is set to "true"
- ** dropall-flow-hard-timeout
- *** The dropall flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
- *** This field is only relevant when "is-install-dropall-flow" is set to "true"
- ** is-learning-only-mode
- *** "true" means that the L2Switch will only be learning addresses. No additional flows to optimize network traffic will be installed.
- *** "false" means that the L2Switch will react to network traffic and install flows on the switches to optimize traffic. Currently, MAC-to-MAC flows are installed.
- ** reactive-flow-table-id
- *** The reactive flow will be installed on the specified flow table of each switch
- *** This field is only relevant when "is-learning-only-mode" is set to "false"
- ** reactive-flow-priority
- *** The reactive flow will be installed with the specified priority
- *** This field is only relevant when "is-learning-only-mode" is set to "false"
- ** reactive-flow-idle-timeout
- *** The reactive flow will timeout (removed from the switch) if the flow doesn't forward a packet for _x_ seconds
- *** This field is only relevant when "is-learning-only-mode" is set to "false"
- ** reactive-flow-hard-timeout
- *** The reactive flow will timeout (removed from the switch) after _x_ seconds, regardless of how many packets it is forwarding
- *** This field is only relevant when "is-learning-only-mode" is set to "false"
-
-=== Running the L2Switch project
-
-To run the L2 Switch inside the Lithium OpenDaylight distribution simply install the `odl-l2switch-switch-ui` feature;
-
- feature:install odl-l2switch-switch-ui
-
-//==== Check out the project using git
-// git clone https://git.opendaylight.org/gerrit/p/l2switch.git
-//
-//The above command will create a directory called "l2switch" with the project.
-//
-//==== Run the distribution
-//To run the base distribution, you can use the following command
-//
-// ./distribution/base/target/distributions-l2switch-base-0.1.0-SNAPSHOT-osgipackage/opendaylight/run.sh
-//
-//If you need additional resources, you can use these command line arguments:
-//
-// -Xms1024m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=1024m'
-//
-//To run the karaf distribution, you can use the following command:
-//
-// ./distribution/karaf/target/assembly/bin/karaf
-
-=== Create a network using mininet
- sudo mn --controller=remote,ip=<Controller IP> --topo=linear,3 --switch ovsk,protocols=OpenFlow13
- sudo mn --controller=remote,ip=127.0.0.1 --topo=linear,3 --switch ovsk,protocols=OpenFlow13
-
-The above command will create a virtual network consisting of 3 switches.
-Each switch will connect to the controller located at the specified IP, i.e. 127.0.0.1
-
- sudo mn --controller=remote,ip=127.0.0.1 --mac --topo=linear,3 --switch ovsk,protocols=OpenFlow13
-
-The above command has the "mac" option, which makes it easier to distinguish between Host MAC addresses and Switch MAC addresses.
-
-=== Generating network traffic using mininet
- h1 ping h2
-
-The above command will cause host1 (h1) to ping host2 (h2)
-
- pingall
-
-'pingall' will cause each host to ping every other host.
-
-=== Checking Address Observations
-Address Observations are added to the Inventory data tree.
-
-The Address Observations on a Node Connector can be checked through a browser or a REST Client.
-
- http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
-
-.Address Observations
-image::l2switch-address-observations.png["AddressObservations image",width=500]
-
-=== Checking Hosts
-Host information is added to the Topology data tree.
-
-* Host address
-* Attachment point (link) to a node/switch
-
-This host information and attachment point information can be checked through a browser or a REST Client.
-
- http://10.194.126.91:8080/restconf/operational/network-topology:network-topology/topology/flow:1/
-
-.Hosts
-image::l2switch-hosts.png["Hosts image",width=500]
-
-=== Checking STP status of each link
-STP Status information is added to the Inventory data tree.
-
-* A status of "forwarding" means the link is active and packets are flowing on it.
-* A status of "discarding" means the link is inactive and packets are not sent over it.
-
-The STP status of a link can be checked through a browser or a REST Client.
-
- http://10.194.126.91:8080/restconf/operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:2
-
-.STP status
-image::l2switch-stp-status.png["STPStatus image",width=500]
-
-=== Miscellaneous mininet commands
- link s1 s2 down
-
-This will bring the link between switch1 (s1) and switch2 (s2) down
-
- link s1 s2 up
-
-This will bring the link between switch1 (s1) and switch2 (s2) up
-
- link s1 h1 down
-
-This will bring the link between switch1 (s1) and host1 (h1) down
-
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/l2switch-user-guide.html
== Link Aggregation Control Protocol User Guide
-=== Overview
-This section contains information about how to use the LACP plugin project with OpenDaylight, including configurations.
-
-=== Link Aggregation Control Protocol Architecture
-The LACP Project within OpenDaylight implements Link Aggregation Control Protocol (LACP) as an MD-SAL service module and will be used to auto-discover and aggregate multiple links between an OpenDaylight controlled network and LACP-enabled endpoints or switches. The result is the creation of a logical channel, which represents the aggregation of the links. Link aggregation provides link resiliency and bandwidth aggregation. This implementation adheres to IEEE Ethernet specification link:http://www.ieee802.org/3/hssg/public/apr07/frazier_01_0407.pdf[802.3ad].
-
-=== Configuring Link Aggregation Control Protocol
-
-This feature can be enabled in the Karaf console of the OpenDaylight Karaf distribution by issuing the following command:
-
- feature:install odl-lacp-ui
-
-[NOTE]
-====
-1. Ensure that legacy (non-OpenFlow) switches are configured with LACP mode active with a long timeout to allow for the LACP plugin in OpenDaylight to respond to its messages.
-2. Flows that want to take advantage of LACP-configured Link Aggregation Groups (LAGs) must explicitly use a OpenFlow group table entry created by the LACP plugin. The plugin only creates group table entries, it does not program any flows on its own.
-====
-
-=== Administering or Managing Link Aggregation Control Protocol
-LACP-discovered network inventory and network statistics can be viewed using the following REST APIs.
-
-1. List of aggregators available for a node:
-+
- http://<ControllerIP>:8181/restconf/operational/opendaylight-inventory:nodes/node/<node-id>
-+
-Aggregator information will appear within the +<lacp-aggregators>+ XML tag.
-
-2. To view only the information of an aggregator:
-+
- http://<ControllerIP>:8181/restconf/operational/opendaylight-inventory:nodes/node/<node-id>/lacp-aggregators/<agg-id>
-+
-The group ID associated with the aggregator can be found inside the +<lag-groupid>+ XML tag.
-+
-The group table entry information for the +<lag-groupid>+ added for the aggregator is also available in the +opendaylight-inventory+ node database.
-
-3. To view physical port information.
-+
- http://<ControllerIP>:8181/restconf/operational/opendaylight-inventory:nodes/node/<node-id>/node-connector/<node-connector-id>
-+
-Ports that are associated with an aggregator will have the tag +<lacp-agg-ref>+ updated with valid aggregator information.
-
-=== Tutorials
-The below tutorial demonstrates LACP LAG creation for a sample mininet topology.
-
-==== Sample LACP Topology creation on Mininet
- sudo mn --controller=remote,ip=<Controller IP> --topo=linear,1 --switch ovsk,protocols=OpenFlow13
-
-The above command will create a virtual network consisting of a switch and a host. The switch will be connected to the controller.
-
-Once the topology is discovered, verify the presence of a flow entry with "dl_type" set to "0x8809" to handle LACP packets using the below ovs-ofctl command:
-
- ovs-ofctl -O OpenFlow13 dump-flows s1
- OFPST_FLOW reply (OF1.3) (xid=0x2):
- cookie=0x300000000000001e, duration=60.067s, table=0, n_packets=0, n_bytes=0, priority=5,dl_dst=01:80:c2:00:00:02,dl_type=0x8809 actions=CONTROLLER:65535
-
-Configure an additional link between the switch (s1) and host (h1) using the below command on mininet shell to aggregate 2 links:
-
- mininet> py net.addLink(s1, net.get('h1'))
- mininet> py s1.attach('s1-eth2')
-
-The LACP module will listen for LACP control packets that are generated from legacy switch (non-OpenFlow enabled). In our example, host (h1) will act as a LACP packet generator.
-In order to generate the LACP control packets, a bond interface has to be created on the host (h1) with mode type set to LACP with long-timeout. To configure bond interface, create a new file bonding.conf under the /etc/modprobe.d/ directory and insert the below lines in this new file:
-
- alias bond0 bonding
- options bonding mode=4
-
-Here mode=4 is referred to LACP and the default timeout is set to long.
-
-Enable bond interface and associate both physical interface h1-eth0 & h1-eth1 as members of the bond interface on host (h1) using the below commands on the mininet shell:
-
- mininet> py net.get('h1').cmd('modprobe bonding')
- mininet> py net.get('h1').cmd('ip link add bond0 type bond')
- mininet> py net.get('h1').cmd('ip link set bond0 address <bond-mac-address>')
- mininet> py net.get('h1').cmd('ip link set h1-eth0 down')
- mininet> py net.get('h1').cmd('ip link set h1-eth0 master bond0')
- mininet> py net.get('h1').cmd('ip link set h1-eth1 down')
- mininet> py net.get('h1').cmd('ip link set h1-eth1 master bond0')
- mininet> py net.get('h1').cmd('ip link set bond0 up')
-
-Once the bond0 interface is up, the host (h1) will send LACP packets to the switch (s1). The LACP Module will then create a LAG through exchange of LACP packets between the host (h1) and switch (s1). To view the bond interface output on the host (h1) side:
-
- mininet> py net.get('h1').cmd('cat /proc/net/bonding/bond0')
- Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011)
- Bonding Mode: IEEE 802.3ad Dynamic link aggregation
- Transmit Hash Policy: layer2 (0)
- MII Status: up
- MII Polling Interval (ms): 100
- Up Delay (ms): 0
- Down Delay (ms): 0
- 802.3ad info
- LACP rate: slow
- Min links: 0
- Aggregator selection policy (ad_select): stable
- Active Aggregator Info:
- Aggregator ID: 1
- Number of ports: 2
- Actor Key: 33
- Partner Key: 27
- Partner Mac Address: 00:00:00:00:01:01
-
- Slave Interface: h1-eth0
- MII Status: up
- Speed: 10000 Mbps
- Duplex: full
- Link Failure Count: 0
- Permanent HW addr: 00:00:00:00:00:11
- Aggregator ID: 1
- Slave queue ID: 0
-
- Slave Interface: h1-eth1
- MII Status: up
- Speed: 10000 Mbps
- Duplex: full
- Link Failure Count: 0
- Permanent HW addr: 00:00:00:00:00:12
- Aggregator ID: 1
- Slave queue ID: 0
-
-A corresponding group table entry would be created on the OpenFlow switch (s1) with "type" set to "select" to perform the LAG functionality. To view the group entries:
-
- mininet>ovs-ofctl -O Openflow13 dump-groups s1
- OFPST_GROUP_DESC reply (OF1.3) (xid=0x2):
- group_id=60169,type=select,bucket=weight:0,actions=output:1,output:2
-
-To apply the LAG functionality on the switches, the flows should be configured with action set to GroupId instead of output port. A sample add-flow configuration with output action set to GroupId:
-
- sudo ovs-ofctl -O Openflow13 add-flow s1 dl_type=0x0806,dl_src=SRC_MAC,dl_dst=DST_MAC,actions=group:60169
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/link-aggregation-control-protocol-user-guide.html
+++ /dev/null
-=== Clustering in LISP Flow Mapping
-Documentation regarding setting up a 3-node OpenDaylight cluster is described at following https://wiki.opendaylight.org/view/Running_and_testing_an_OpenDaylight_Cluster#Three-node_cluster[odl wiki page].
-
-To turn on clustering in LISP Flow Mapping it is necessary:
-
-* run script *deploy.py* script. This script is in https://git.opendaylight.org/gerrit/integration/test[integration-test] project placed at _tools/clustering/cluster-deployer/deploy.py_. A whole deploy.py command can looks like:
-=======
-{path_to_integration_test_project}/tools/clustering/cluster-deployer/*deploy.py* +
---*distribution* {path_to_distribution_in_zip_format} +
---*rootdir* {dir_at_remote_host_where_copy_odl_distribution} +
---*hosts* {IP1},{IP2},{IP3} +
---*clean* +
---*template* lispflowmapping +
---*rf* 3 +
---*user* {user_name_of_remote_hosts} +
---*password* {password_to_remote_hosts}
-=======
-Running this script will cause that specified *distribution* to be deployed to remote *hosts* specified through their IP adresses with using credentials (*user* and *password*). The distribution will be copied to specified *rootdir*. As part of the deployment, a *template* which contains a set of controller files which are different from standard ones. In this case it is specified in +
-_{path_to_integration_test_project}/tools/clustering/cluster-deployer/lispflowmapping_ directory. +
-Lispflowmapping templates are part of integration-test project. There are 5 template files: +
-
-* akka.conf.template
-* jolokia.xml.template
-* module-shards.conf.template
-* modules.conf.template
-* org.apache.karaf.features.cfg.template
-
-After copying the distribution, it is unzipped and started on all of specified *hosts* in cluster aware manner.
-
-==== Remarks
-It is necessary to have:
-
-* *unzip* program installed on all of the host
-* set all remote hosts /etc/sudoers files to not *requiretty* (should only matter on debian hosts)
== LISP Flow Mapping User Guide
-=== Overview
-
-==== Locator/ID Separation Protocol
-
-http://tools.ietf.org/html/rfc6830[Locator/ID Separation Protocol (LISP)] is a
-technology that provides a flexible map-and-encap framework that can be used
-for overlay network applications such as data center network virtualization and
-Network Function Virtualization (NFV).
-
-LISP provides the following name spaces:
-
-* http://tools.ietf.org/html/rfc6830#page-6[Endpoint Identifiers (EIDs)]
-* http://tools.ietf.org/html/rfc6830#section-3[Routing Locators (RLOCs)]
-
-In a virtualization environment EIDs can be viewed as virtual address space and
-RLOCs can be viewed as physical network address space.
-
-The LISP framework decouples network control plane from the forwarding plane by
-providing:
-
-* A data plane that specifies how the virtualized network addresses are
- encapsulated in addresses from the underlying physical network.
-* A control plane that stores the mapping of the virtual-to-physical address
- spaces, the associated forwarding policies and serves this information to
- the data plane on demand.
-
-Network programmability is achieved by programming forwarding policies such as
-transparent mobility, service chaining, and traffic engineering in the mapping
-system; where the data plane elements can fetch these policies on demand as new
-flows arrive. This chapter describes the LISP Flow Mapping project in
-OpenDaylight and how it can be used to enable advanced SDN and NFV use cases.
-
-LISP data plane Tunnel Routers are available at
-http://LISPmob.org/[LISPmob.org] in the open source community on the following
-platforms:
-
-* Linux
-* Android
-* OpenWRT
-
-For more details and support for LISP data plane software please visit
-http://LISPmob.org/[the LISPmob web site].
-
-==== LISP Flow Mapping Service
-
-The LISP Flow Mapping service provides LISP Mapping System services. This
-includes LISP Map-Server and LISP Map-Resolver services to store and serve
-mapping data to data plane nodes as well as to OpenDaylight applications.
-Mapping data can include mapping of virtual addresses to physical network
-address where the virtual nodes are reachable or hosted at. Mapping data can
-also include a variety of routing policies including traffic engineering and
-load balancing. To leverage this service, OpenDaylight applications and
-services can use the northbound REST API to define the mappings and policies in
-the LISP Mapping Service. Data plane devices capable of LISP control protocol
-can leverage this service through a southbound LISP plugin. LISP-enabled
-devices must be configured to use this OpenDaylight service as their Map Server
-and/or Map Resolver.
-
-The southbound LISP plugin supports the LISP control protocol (Map-Register,
-Map-Request, Map-Reply messages), and can also be used to register mappings in
-the OpenDaylight mapping service.
-
-=== LISP Flow Mapping Architecture
-
-The following figure shows the various LISP Flow Mapping modules.
-
-.LISP Mapping Service Internal Architecture
-
-image::ODL_lfm_Be_component.jpg["LISP Mapping Service Internal Architecture", width=460]
-
-A brief description of each module is as follows:
-
-* *DAO (Data Access Object):* This layer separates the LISP logic from the
- database, so that we can separate the map server and map resolver from the
- specific implementation of the mapping database. Currently we have an
- implementation of this layer with an in-memory HashMap, but it can be switched
- to any other key/value store and you only need to implement the ILispDAO
- interface.
-
-* *Map Server:* This module processes the adding or registration of
- authentication tokens (keys) and mappings. For a detailed specification of
- LISP Map Server, see http://tools.ietf.org/search/rfc6830[LISP].
-* *Map Resolver:* This module receives and processes the mapping lookup queries
- and provides the mappings to requester. For a detailed specification of LISP
- Map Server, see http://tools.ietf.org/search/rfc6830[LISP].
-* *RPC/RESTCONF:* This is the auto-generated RESTCONF-based northbound API. This
- module enables defining key-EID associations as well as adding mapping
- information through the Map Server. Key-EID associations and mappings can also
- be queried via this API.
-* *GUI:* This module enables adding and querying the mapping service through a
- GUI based on ODL DLUX.
-* *Neutron:* This module implements the OpenDaylight Neutron Service APIs. It
- provides integration between the LISP service and the OpenDaylight Neutron
- service, and thus OpenStack.
-* *Java API:* The API module exposes the Map Server and Map Resolver
- capabilities via a Java API.
-* *LISP Proto:* This module includes LISP protocol dependent data types and
- associated processing.
-* *In Memory DB:* This module includes the in memory database implementation of
- the mapping service.
-* *LISP Southbound Plugin:* This plugin enables data plane devices that support
- LISP control plane protocol (see http://tools.ietf.org/search/rfc6830[LISP])
- to register and query mappings to the
- LISP Flow Mapping via the LISP control plane protocol.
-
-
-=== Configuring LISP Flow Mapping
-
-In order to use the LISP mapping service for registering EID to RLOC mappings
-from northbound or southbound, keys have to be defined for the EID prefixes first. Once a key
-is defined for an EID prefix, it can be used to add mappings for that EID
-prefix multiple times. If the service is going to be used to process Map-Register
-messages from the southbound LISP plugin, the same key must be used by
-the data plane device to create the authentication data in the Map-Register
-messages for the associated EID prefix.
-
-The +etc/custom.properties+ file in the Karaf distribution allows configuration
-of several OpenDaylight parameters. The LISP service has the following properties
-that can be adjusted:
-
-*lisp.mappingOverwrite* (default: 'true')::
- Configures handling of mapping updates. When set to 'true' (default) a
- mapping update (either through the southbound plugin via a Map-Register
- message or through a northbound API PUT REST call) the existing RLOC set
- associated to an EID prefix is overwritten. When set to 'false', the RLOCs
- of the update are merged to the existing set.
-
-*lisp.smr* (default: 'false')::
- Enables/disables the
- http://tools.ietf.org/html/rfc6830#section-6.6.2[Solicit-Map-Request (SMR)]
- functionality. SMR is a method to notify changes in an EID-to-RLOC mapping
- to "subscribers". The LISP service considers all Map-Request's source RLOC
- as a subscriber to the requested EID prefix, and will send an SMR control
- message to that RLOC if the mapping changes.
-
-*lisp.elpPolicy* (default: 'default')::
- Configures how to build a Map-Reply southbound message from a mapping
- containing an Explicit Locator Path (ELP) RLOC. It is used for
- compatibility with dataplane devices that don't understand the ELP LCAF
- format. The 'default' setting doesn't alter the mapping, returning all
- RLOCs unmodified. The 'both' setting adds a new RLOC to the mapping, with
- a lower priority than the ELP, that is the next hop in the service chain.
- To determine the next hop, it searches the source RLOC of the Map-Request
- in the ELP, and chooses the next hop, if it exists, otherwise it chooses
- the first hop. The 'replace' setting adds a new RLOC using the same
- algorithm as the 'both' setting, but using the origin priority of the ELP
- RLOC, which is removed from the mapping.
-*lisp.lookupPolicy* (default: 'northboundFirst')::
- Configures the mapping lookup algorithm. When set to 'northboundFirst'
- mappings programmed through the northbound API will take precedence. If
- no northbound programmed mappings exist, then the mapping service will
- return mappings registered through the southbound plugin, if any exists.
- When set to 'northboundAndSouthbound' the mapping programmed by the
- northbound is returned, updated by the up/down status of these mappings
- as reported by the southbound (if existing).
-*lisp.mappingMerge* (default: 'false')::
- Configures the merge policy on the southbound registrations through the
- LISP SB Plugin. When set to 'false', only the latest mapping registered
- through the SB plugin is valid in the southbound mapping database,
- independent of which device it came from. When set to 'true', mappings
- for the same EID registered by different devices are merged together and
- a union of the locators is maintained as the valid mapping for that EID.
-
-=== Textual Conventions for LISP Address Formats
-
-In addition to the more common IPv4, IPv6 and MAC address data types, the LISP
-control plane supports arbitrary
-http://www.iana.org/assignments/address-family-numbers[Address Family
-Identifiers] assigned by IANA, and in addition to those the
-https://tools.ietf.org/html/draft-ietf-lisp-lcaf[LISP Canoncal Address Format
-(LCAF)].
-
-The LISP Flow Mapping project in OpenDaylight implements support for many of
-these different address formats, the full list being summarized in the
-following table. While some of the address formats have well defined and
-widely used textual representation, many don't. It became necessary to define
-a convention to use for text rendering of all implemented address types in
-logs, URLs, input fields, etc. The below table lists the supported formats,
-along with their AFI number and LCAF type, including the prefix used for
-disambiguation of potential overlap, and examples output.
-
-.LISP Address Formats
-[align="right",options="header",cols="<2s,>,>,<,<4l"]
-|=====
-| Name | AFI | LCAF | Prefix | Text Rendering
-| No Address | 0 | - | no: | No Address Present
-| IPv4 Prefix | 1 | - | ipv4: | 192.0.2.0/24
-| IPv6 Prefix | 2 | - | ipv6: | 2001:db8::/32
-| MAC Address | 16389 | - | mac: | 00:00:5E:00:53:00
-| Distinguished Name | 17 | - | dn: | stringAsIs
-| AS Number | 18 | - | as: | AS64500
-| AFI List | 16387 | 1 | list: | {192.0.2.1,192.0.2.2,2001:db8::1}
-| Instance ID | 16387 | 2 | - | [223] 192.0.2.0/24
-| Application Data | 16387 | 4 | appdata: | 192.0.2.1!128!17!80-81!6667-7000
-| Explicit Locator Path | 16387 | 10 | elp: | {192.0.2.1->192.0.2.2\|lps->192.0.2.3}
-| Source/Destination Key | 16387 | 12 | srcdst: | 192.0.2.1/32\|192.0.2.2/32
-| Key/Value Address Pair | 16387 | 15 | kv: | 192.0.2.1=>192.0.2.2
-| Service Path | 16387 | N/A | sp: | 42(3)
-|=====
-
-Please note that the forward slash character `/` typically separating IPv4 and
-IPv6 addresses from the mask length is transformed into `%2f` when used in a
-URL.
-
-=== Karaf commands
-
-In this section we will discuss two types of Karaf commands: built-in, and
-LISP specific. Some built-in commands are quite useful, and are needed for the
-tutorial, so they will be discussed here. A reference of all LISP specific
-commands, added by the LISP Flow Mapping project is also included. They are
-useful mostly for debugging.
-
-==== Useful built-in commands
-
-+help+::
- Lists all available command, with a short description of each.
-
-+help <command_name>+::
- Show detailed help about a specific command.
-
-+feature:list [-i]+::
- Show all locally available features in the Karaf container. The `-i`
- option lists only features that are currently installed. It is possible to
- use `| grep` to filter the output (for all commands, not just this one).
-
-+feature:install <feature_name>+::
- Install feature `feature_name`.
-
-+log:set <level> <class>+::
- Set the log level for `class` to `level`. The default log level for all
- classes is INFO. For debugging, or learning about LISP internals it is
- useful to run `log:set TRACE org.opendaylight.lispflowmapping` right after
- Karaf starts up.
-
-+log:display+::
- Outputs the log file to the console, and returns control to the user.
-
-+log:tail+::
- Continuously shows log output, requires `Ctrl+C` to return to the console.
-
-==== LISP specific commands
-
-The available lisp commands can always be obtained by `help mappingservice`.
-Currently they are:
-
-+mappingservice:addkey+::
- Add the default password `password` for the IPv4 EID prefix 0.0.0.0/0 (all
- addresses). This is useful when experimenting with southbound devices,
- and using the REST interface would be combersome for whatever reason.
-
-+mappingservice:mappings+::
- Show the list of all mappings stored in the internal non-persistent data
- store (the DAO), listing the full data structure. The output is not human
- friendly, but can be used for debugging.
-
-
-=== LISP Flow Mapping Karaf Features
-
-LISP Flow Mapping has the following Karaf features that can be installed from
-the Karaf console:
-
-+odl-lispflowmapping-msmr+::
- This includes the core features required to use the LISP Flow Mapping Service
- such as mapping service and the LISP southbound plugin.
-
-+odl-lispflowmapping-ui+::
- This includes the GUI module for the LISP Mapping Service.
-
-+odl-lispflowmapping-neutron+::
- This is the experimental Neutron provider module for LISP mapping service.
-
-
-=== Tutorials
-
-This section provides a tutorial demonstrating various features in this service.
-
-==== Creating a LISP overlay
-
-This section provides instructions to set up a LISP network of three nodes (one
-"client" node and two "server" nodes) using LISPmob as data plane LISP nodes
-and the LISP Flow Mapping project from OpenDaylight as the LISP programmable
-mapping system for the LISP network.
-
-===== Overview
-
-The steps shown below will demonstrate setting up a LISP network between a
-client and two servers, then performing a failover between the two "server"
-nodes.
-
-===== Prerequisites
-
-* *OpenDaylight Beryllium*
-* *The Postman Chrome App*: the most convenient way to follow along this
- tutorial is to use the
- https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en[Postman
- Chrome App] to edit and send the requests. The project git repository hosts
- a collection of the requests that are used in this tutorial in the
- +resources/tutorial/Beryllium_Tutorial.json.postman_collection+ file. You can
- import this file to Postman by clicking 'Import' at the top, choosing
- 'Download from link' and then entering the following URL:
- +https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/Beryllium_Tutorial.json.postman_collection;hb=refs/heads/stable/beryllium+.
- Alternatively, you can save the file on your machine, or if you have the
- repository checked out, you can import from there. You will need to create a
- new Postman Environment and define some variables within: +controllerHost+
- set to the hostname or IP address of the machine running the ODL instance,
- and +restconfPort+ to 8181, if you didn't modify the default controller
- settings.
-* *LISPmob version 0.5.x* The README.md lists the dependencies needed to
- build it from source.
-* *A virtualization platform*
-
-===== Target Environment
-
-The three LISP data plane nodes and the LISP mapping system are assumed to be
-running in Linux virtual machines, which have the +eth0+ interface in NAT mode
-to allow outside internet access and +eth1+ connected to a host-only network,
-with the following IP addresses (please adjust configuration files, JSON
-examples, etc. accordingly if you're using another addressing scheme):
-
-.Nodes in the tutorial
-[align="right",options="header"]
-|===
-| Node | Node Type | IP Address
-| *controller* | OpenDaylight | 192.168.16.11
-| *client* | LISPmob | 192.168.16.30
-| *server1* | LISPmob | 192.168.16.31
-| *server2* | LISPmob | 192.168.16.32
-| *service-node* | LISPmob | 192.168.16.33
-|===
-
-NOTE: While the tutorial uses LISPmob as the data plane, it could be any
- LISP-enabled hardware or software router (commercial/open source).
-
-===== Instructions
-
-The below steps use the command line tool cURL to talk to the LISP Flow
-Mapping RPC REST API. This is so that you can see the actual request URLs and
-body content on the page.
-
- . Install and run OpenDaylight Beryllium release on the controller VM. Please
- follow the general OpenDaylight Beryllium Installation Guide for this step.
- Once the OpenDaylight controller is running install the
- 'odl-lispflowmapping-msmr' feature from the Karaf CLI:
-
- feature:install odl-lispflowmapping-msmr
-+
-It takes quite a while to load and initialize all features and their
-dependencies. It's worth running the command +log:tail+ in the Karaf console
-to see when the log output is winding down, and continue with the tutorial
-after that.
-
- . Install LISPmob on the *client*, *server1*, *server2*, and *service-node*
- VMs following the installation instructions
- https://github.com/LISPmob/lispmob#software-prerequisites[from the LISPmob
- README file].
-
- . Configure the LISPmob installations from the previous step. Starting from
- the +lispd.conf.example+ file in the distribution, set the EID in each
- +lispd.conf+ file from the IP address space selected for your virtual/LISP
- network. In this tutorial the EID of the *client* is set to 1.1.1.1/32, and
- that of *server1* and *server2* to 2.2.2.2/32.
-
- . Set the RLOC interface to +eth1+ in each +lispd.conf+ file. LISP will
- determine the RLOC (IP address of the corresponding VM) based on this
- interface.
-
- . Set the Map-Resolver address to the IP address of the *controller*, and on
- the *client* the Map-Server too. On *server1* and *server2* set the
- Map-Server to something else, so that it doesn't interfere with the
- mappings on the controller, since we're going to program them manually.
-
- . Modify the "key" parameter in each +lispd.conf+ file to a key/password of
- your choice ('password' in this tutorial).
-+
-NOTE: The +resources/tutorial+ directory in the 'stable/beryllium' branch of the
- project git repository has the files used in the tutorial
- https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial;hb=refs/heads/stable/beryllium[checked
- in], so you can just copy the files to +/root/lispd.conf+ on the
- respective VMs. You will also find the JSON files referenced below in
- the same directory.
-+
- . Define a key and EID prefix association in OpenDaylight using the RPC REST
- API for the *client* EID (1.1.1.1/32) to allow registration from the
- southbound. Since the mappings for the server EID will be configured from
- the REST API, no such association is necessary. Run the below command on
- the *controller* (or any machine that can reach *controller*, by replacing
- 'localhost' with the IP address of *controller*).
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:add-key \
- --data @add-key.json
-
-+
-where the content of the 'add-key.json' file is the following:
-+
-[source,json]
-----
-{
- "input": {
- "eid": {
- "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
- "ipv4-prefix": "1.1.1.1/32"
- },
- "mapping-authkey": {
- "key-string": "password",
- "key-type": 1
- }
- }
-}
-----
-
- . Verify that the key is added properly by requesting the following URL:
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:get-key \
- --data @get1.json
-
-+
-where the content of the 'get1.json' file can be derived from the
-'add-key.json' file by removing the 'mapping-authkey' field. The output the
-above invocation should look like this:
-
- {"output":{"mapping-authkey":{"key-type":1,"key-string":"password"}}}
-
- . Run the +lispd+ LISPmob daemon on all VMs:
-
- lispd -f /root/lispd.conf
-
- . The *client* LISPmob node should now register its EID-to-RLOC mapping in
- OpenDaylight. To verify you can lookup the corresponding EIDs via the REST
- API
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
- --data @get1.json
-
-+
-An alternative way for retrieving mappings from ODL using the southbound
-interface is using the https://github.com/davidmeyer/lig[+lig+] open source
-tool.
-
- . Register the EID-to-RLOC mapping of the server EID 2.2.2.2/32 to the
- controller, pointing to *server1* and *server2* with a higher priority for
- *server1*
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
- --data @mapping.json
-+
-where the 'mapping.json' file looks like this:
-+
-[source,json]
-----
-{
- "input": {
- "mapping-record": {
- "recordTtl": 1440,
- "action": "NoAction",
- "authoritative": true,
- "eid": {
- "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
- "ipv4-prefix": "2.2.2.2/32"
- },
- "LocatorRecord": [
- {
- "locator-id": "server1",
- "priority": 1,
- "weight": 1,
- "multicastPriority": 255,
- "multicastWeight": 0,
- "localLocator": true,
- "rlocProbed": false,
- "routed": true,
- "rloc": {
- "address-type": "ietf-lisp-address-types:ipv4-afi",
- "ipv4": "192.168.16.31"
- }
- },
- {
- "locator-id": "server2",
- "priority": 2,
- "weight": 1,
- "multicastPriority": 255,
- "multicastWeight": 0,
- "localLocator": true,
- "rlocProbed": false,
- "routed": true,
- "rloc": {
- "address-type": "ietf-lisp-address-types:ipv4-afi",
- "ipv4": "192.168.16.32"
- }
- }
- ]
- }
- }
-}
-----
-+
-Here the priority of the second RLOC (192.168.16.32 - *server2*) is 2, a higher
-numeric value than the priority of 192.168.16.31, which is 1. This policy is
-saying that *server1* is preferred to *server2* for reaching EID 2.2.2.2/32.
-Note that lower priority value has higher preference in LISP.
-
- . Verify the correct registration of the 2.2.2.2/32 EID:
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
- --data @get2.json
-
-+
-where 'get2.json' can be derived from 'get1.json' by changing the content of
-the 'Ipv4Address' field from '1.1.1.1' to '2.2.2.2'.
-
- . Now the LISP network is up. To verify, log into the *client* VM and ping the server EID:
-
- ping 2.2.2.2
-
- . Let's test fail-over now. Suppose you had a service on *server1* which
- became unavailable, but *server1* itself is still reachable. LISP will not
- automatically fail over, even if the mapping for 2.2.2.2/32 has two
- locators, since both locators are still reachable and uses the one with the
- higher priority (lowest priority value). To force a failover, we need to
- set the priority of *server2* to a lower value. Using the file mapping.json
- above, swap the priority values between the two locators (lines 14 and 28
- in 'mapping.json') and repeat the request from step 11. You can also
- repeat step 12 to see if the mapping is correctly registered. If you leave
- the ping on, and monitor the traffic using wireshark, you can see that the
- ping traffic to 2.2.2.2 will be diverted from the *server1* RLOC to the
- *server2* RLOC.
-+
-With the default OpenDaylight configuration the failover should be near
-instantaneous (we observed 3 lost pings in the worst case), because of the
-LISP http://tools.ietf.org/html/rfc6830#section-6.6.2[Solicit-Map-Request
-(SMR) mechanism] that can ask a LISP data plane element to update its mapping
-for a certain EID (enabled by default). It is controlled by the +lisp.smr+
-variable in +etc/custom.porperties+. When enabled, any mapping change from the
-RPC interface will trigger an SMR packet to all data plane elements that have
-requested the mapping in the last 24 hours (this value was chosen because it's
-the default TTL of Cisco IOS xTR mapping registrations). If disabled, ITRs
-keep their mappings until the TTL specified in the Map-Reply expires.
-
- . To add a service chain into the path from the client to the server, we can
- use an Explicit Locator Path, specifying the *service-node* as the first
- hop and *server1* (or *server2*) as the second hop. The following will
- achieve that:
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
- --data @elp.json
-+
-where the 'elp.json' file is as follows:
-+
-[source,json]
-----
-{
- "input": {
- "mapping-record": {
- "recordTtl": 1440,
- "action": "NoAction",
- "authoritative": true,
- "eid": {
- "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
- "ipv4-prefix": "2.2.2.2/32"
- },
- "LocatorRecord": [
- {
- "locator-id": "ELP",
- "priority": 1,
- "weight": 1,
- "multicastPriority": 255,
- "multicastWeight": 0,
- "localLocator": true,
- "rlocProbed": false,
- "routed": true,
- "rloc": {
- "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
- "explicit-locator-path": {
- "hop": [
- {
- "hop-id": "service-node",
- "address": "192.168.16.33",
- "lrs-bits": "strict"
- },
- {
- "hop-id": "server1",
- "address": "192.168.16.31",
- "lrs-bits": "strict"
- }
- ]
- }
- }
- }
- ]
- }
- }
-}
-----
-+
-After the mapping for 2.2.2.2/32 is updated with the above, the ICMP traffic
-from *client* to *server1* will flow through the *service-node*. You can
-confirm this in the LISPmob logs, or by sniffing the traffic on either the
-*service-node* or *server1*. Note that service chains are unidirectional, so
-unless another ELP mapping is added for the return traffic, packets will go
-from *server1* to *client* directly.
-
- . Suppose the *service-node* is actually a firewall, and traffic is diverted
- there to support access control lists (ACLs). In this tutorial that can be
- emulated by using +iptables+ firewall rules in the *service-node* VM. To
- deny traffic on the service chain defined above, the following rule can be
- added:
-
- iptables -A OUTPUT --dst 192.168.16.31 -j DROP
-
-+
-The ping from the *client* should now have stopped.
-+
-In this case the ACL is done on the destination RLOC. There is an effort underway in the LISPmob
-community to allow filtering on EIDs, which is the more logical place to apply
-ACLs.
-
- . To delete the rule and restore connectivity on the service chain, delete
- the ACL by issuing the following command:
-
- iptables -D OUTPUT --dst 192.168.16.31 -j DROP
-
-+
-which should restore connectivity.
-
-=== LISP Flow Mapping Support
-
-For support the lispflowmapping project can be reached by emailing the
-developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on the
-#opendaylight-lispflowmapping IRC channel on irc.freenode.net.
-
-Additional information is also available on the https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main[Lisp Flow Mapping wiki]
-
-include::lispflowmapping-clustering-user.adoc[Clustering in lispflowmapping]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/lisp-flow-mapping-user-guide.html
== Neutron Service User Guide
-=== Overview
-This Karaf feature (`odl-neutron-service`) provides integration support for OpenStack Neutron
-via the OpenDaylight ML2 mechanism driver. The Neutron Service is only one of the
-components necessary for OpenStack integration. For those related components
-please refer to documentations of each component:
-
-* https://wiki.openstack.org/wiki/Neutron
-* https://launchpad.net/networking-odl
-* http://git.openstack.org/cgit/openstack/networking-odl/
-* https://wiki.opendaylight.org/view/NeutronNorthbound:Main
-
-==== Use cases and who will use the feature
-If you want OpenStack integration with OpenDaylight, you will need
-this feature with an OpenDaylight provider feature like ovsdb/netvirt, group based
-policy, VTN, and lisp mapper. For provider configuration, please refer
-to each individual provider's documentation. Since the Neutron service only provides the northbound
-API for the OpenStack Neutron ML2 mechanism driver. Without those provider
-features, the Neutron service itself isn't useful.
-
-=== Neutron Service feature Architecture
-The Neutron service provides northbound API for OpenStack Neutron via
-RESTCONF and also its dedicated REST API.
-It communicates through its YANG model with providers.
-
-image::neutron/odl-neutron-service-architecture.png[height="450px", width="550px", title="Neutron Service Architecture"]
-// image original https://docs.google.com/drawings/d/14CWAo1WQrCMHzNGDeg57P9CiqpkiAE4_njr_0OgAUsw/edit?usp=sharing
-
-
-=== Configuring Neutron Service feature
-As the Karaf feature includes everything necessary for communicating
-northbound, no special configuration is needed.
-Usually this feature is used with an OpenDaylight southbound plugin that implements
-actual network virtualization functionality and OpenStack Neutron.
-The user wants to setup those configurations. Refer to each related
-documentations for each configurations.
-
-=== Administering or Managing `odl-neutron-service`
-There is no specific configuration regarding to Neutron service itself.
-For related configuration, please refer to OpenStack Neutron configuration
-and OpenDaylight related services which are providers for OpenStack.
-
-==== installing `odl-neutron-service` while the controller running
-
-. While OpenDaylight is running, in Karaf prompt, type:
- `feature:install odl-neutron-service`.
-. Wait a while until the initialization is done and the controller stabilizes.
-
-`odl-neutron-service` provides only a unified interface for OpenStack Neutron.
-It doesn't provide actual functionality for network virtualization.
-Refer to each OpenDaylight project documentation for actual configuration with
-OpenStack Neutron.
-
-=== Neutron Logger
-Another service, the Neutron Logger, is provided for debugging/logging purposes.
-It logs changes on Neutron YANG models.
-
- feature:install odl-neutron-logger
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/neutron-service-user-guide.html
+++ /dev/null
-==== Requirement
-
-* Before execute the follow steps, please, use default requirements. See section <<_default_requirements,Default Requirements>>.
-
-==== How to configure Log Action
-
-This section demonstrates log action in OF Renderer. This demonstration aims at enabling communication between two hosts and logging the flow statistics details of the particular traffic.
-
-===== Configuration
-
-Please execute the following CLI commands to test network intent using mininet:
-
-* To provision the network for the two hosts (h1 and h3), add intents that allows traffic in both directions by execute the following CLI command.
-----
-intent:add –a ALLOW -t <DESTINATION_MAC> -f <SOURCE_MAC>
-----
-
-Example:
-----
-intent:add -a ALLOW -t 00:00:00:00:00:03 -f 00:00:00:00:00:01
-intent:add -a ALLOW -t 00:00:00:00:00:01 -f 00:00:00:00:00:03
-----
-
-* To log the flow statistics details of the particular traffic.
-----
-intent:add –a LOG -t <DESTINATION_MAC> -f <SOURCE_MAC>
-----
-
-Example:
-----
-intent:add -a LOG -t 00:00:00:00:00:03 -f 00:00:00:00:00:01
-----
-
-====== Verification
-
-* As we have applied action type ALLOW now ping should happen between hosts h1 and h3.
-----
- mininet> h1 ping h3
- PING 10.0.0.3 (10.0.0.3) 56(84) bytes of data.
- 64 bytes from 10.0.0.3: icmp_req=1 ttl=64 time=0.984 ms
- 64 bytes from 10.0.0.3: icmp_req=2 ttl=64 time=0.110 ms
- 64 bytes from 10.0.0.3: icmp_req=3 ttl=64 time=0.098 ms
-----
-
-* To view the flow statistics log details such as, byte count, packet count and duration, check the karaf.log.
-----
-2015-12-15 22:56:20,256 | INFO | lt-dispatcher-23 | IntentFlowManager | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Creating block intent for endpoints: source00:00:00:00:00:01 destination 00:00:00:00:00:03
-2015-12-15 22:56:20,252 | INFO | lt-dispatcher-29 | FlowStatisticsListener | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Flow Statistics gathering for Byte Count:Counter64 [_value=238]
-2015-12-15 22:56:20,252 | INFO | lt-dispatcher-29 | FlowStatisticsListener | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Flow Statistics gathering for Packet Count:Counter64 [_value=3]
-2015-12-15 22:56:20,252 | INFO | lt-dispatcher-29 | FlowStatisticsListener | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Flow Statistics gathering for Duration in Nano second:Counter32 [_value=678000000]
-2015-12-15 22:56:20,252 | INFO | lt-dispatcher-29 | FlowStatisticsListener | 264 - org.opendaylight.nic.of-renderer - 1.1.0.SNAPSHOT | Flow Statistics gathering for Duration in Second:Counter32 [_value=49]
-----
+++ /dev/null
-==== How to configure QoS Attribute Mapping
-
-This section explains how to provision QoS attribute mapping constraint using NIC OF-Renderer.
-
-The QoS attribute mapping currently supports DiffServ. It uses a 6-bit differentiated services code point (DSCP) in the 8-bit differentiated services field (DS field) in the IP header.
-
-[options="header",cols="20%,80%"]
-|===
-| Action | Function
-|Allow | Permits the packet to be forwarded normally, but allows for packet header fields, e.g., DSCP, to be modified.
-|===
-
-The following steps explain QoS Attribute Mapping function:
-
-* Initially configure the QoS profile which contains profile name and DSCP value.
-* When a packet is transferred from a source to destination, the flow builder evaluates whether the transferred packet matches the condition such as action, endpoints in the flow.
-* If the packet matches the endpoints, the flow builder applies the flow matching action and DSCP value.
-
-===== Requirement
-
-* Before execute the following steps, please, use the default requirements. See section <<_default_requirements,Default Requirements>>.
-
-===== Configuration
-
-Please execute the following CLI commands to test network intent using mininet:
-
-* To apply the QoS constraint, configure the QoS profile.
-----
-intent:qosConfig -p <qos_profile_name> -d <valid_dscp_value>
-----
-
-Example:
-----
-intent:qosConfig -p High_Quality -d 46
-----
-NOTE: Valid DSCP value ranges from 0-63.
-
-* To provision the network for the two hosts (h1 and h3), add intents that allows traffic in both directions by execute the following CLI command.
-
-Demonstrates the ALLOW action with constraint QoS and QoS profile name.
-----
-intent:add -a ALLOW -t <DESTINATION_MAC> -f <SOURCE_MAC> -q QOS -p <qos_profile_name>
-----
-
-Example:
-----
-intent:add -a ALLOW -t 00:00:00:00:00:03 -f 00:00:00:00:00:01 -q QOS -p High_Quality
-intent:add -a ALLOW -t 00:00:00:00:00:01 -f 00:00:00:00:00:03 -q QOS -p High_Quality
-----
-
-====== Verification
-
-* As we have applied action type ALLOW now ping should happen between hosts h1 and h3.
-----
- mininet> h1 ping h3
- PING 10.0.0.3 (10.0.0.3) 56(84) bytes of data.
- 64 bytes from 10.0.0.3: icmp_req=1 ttl=64 time=0.984 ms
- 64 bytes from 10.0.0.3: icmp_req=2 ttl=64 time=0.110 ms
- 64 bytes from 10.0.0.3: icmp_req=3 ttl=64 time=0.098 ms
-----
-
-* Verification of the flow entry and ensuring the mod_nw_tos is part of actions.
-----
- mininet> dpctl dump-flows
- *** s1 ------------------------------------------------------------------------
- NXST_FLOW reply (xid=0x4):
- cookie=0x0, duration=21.873s, table=0, n_packets=3, n_bytes=294, idle_age=21, priority=9000,dl_src=00:00:00:00:00:03,dl_dst=00:00:00:00:00:01 actions=NORMAL,mod_nw_tos:184
- cookie=0x0, duration=41.252s, table=0, n_packets=3, n_bytes=294, idle_age=41, priority=9000,dl_src=00:00:00:00:00:01,dl_dst=00:00:00:00:00:03 actions=NORMAL,mod_nw_tos:184
-----
+++ /dev/null
-==== How to configure Redirect Action
-
-The section explains the redirect action supported in NIC. The redirect functionality supports forwarding (to redirect) the traffic to a service configured in SFC before forwarding it to the destination.
-
-.REDIRECT SERVICE
-image::nic/Service_Chaining.png[REDIRECT SERVICE,width=400]
-
-Following steps explain Redirect action function:
-
-* Configure the service in SFC using the SFC APIs.
-* Configure the intent with redirect action and the service information where the traffic needs to be redirected.
-* The flows are computed as below
-. First flow entry between the source host connected node and the ingress node of the configured service.
-. Second flow entry between the egress Node id the configured service and the ID and destination host connected host.
-. Third flow entry between the destination host node and the source host node.
-
-
-===== Requirement
-* Save the mininet <<_simple_mininet_topology,Simple Mininet topology>> script as redirect_test.py
-
-* Start mininet, and create switches in it.
-
-Replace <Controller IP> based on your environment.
-
-----
-sudo mn --controller=remote,ip=<Controller IP>--custom redirect_test.py --topo mytopo2
-----
-
-----
- mininet> net
- h1 h1-eth0:s1-eth1
- h2 h2-eth0:s1-eth2
- h3 h3-eth0:s2-eth1
- h4 h4-eth0:s2-eth2
- h5 h5-eth0:s2-eth3
- srvc1 srvc1-eth0:s3-eth3 srvc1-eth1:s4-eth3
- s1 lo: s1-eth1:h1-eth0 s1-eth2:h2-eth0 s1-eth3:s2-eth4 s1-eth4:s3-eth2
- s2 lo: s2-eth1:h3-eth0 s2-eth2:h4-eth0 s2-eth3:h5-eth0 s2-eth4:s1-eth3 s2-eth5:s4-eth1
- s3 lo: s3-eth1:s4-eth2 s3-eth2:s1-eth4 s3-eth3:srvc1-eth0
- s4 lo: s4-eth1:s2-eth5 s4-eth2:s3-eth1 s4-eth3:srvc1-eth1
- c0
-----
-
-===== Starting the Karaf
-
-* Before execute the following steps, please, use the default requirements. See section <<_default_requirements,Downloading and deploy Karaf distribution>>.
-
-===== Configuration
-
-====== Mininet
-
-.CONFIGURATION THE NETWORK IN MININET
-image::nic/Redirect_flow.png[CONFIGURATION OF THE NETWORK]
-
-* Configure srvc1 as service node in the mininet environment.
-
-Please execute the following commands in the mininet console (where mininet script is executed).
-----
- srvc1 ip addr del 10.0.0.6/8 dev srvc1-eth0
- srvc1 brctl addbr br0
- srvc1 brctl addif br0 srvc1-eth0
- srvc1 brctl addif br0 srvc1-eth1
- srvc1 ifconfig br0 up
- srvc1 tc qdisc add dev srvc1-eth1 root netem delay 200ms
-----
-
-====== Configure service in SFC
-The service (srvc1) is configured using SFC REST API. As part of the configuration the ingress and egress node connected the service is configured.
-
-----
-curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{
- "service-functions": {
- "service-function": [
- {
- "name": "srvc1",
- "sf-data-plane-locator": [
- {
- "name": "Egress",
- "service-function-forwarder": "openflow:4"
- },
- {
- "name": "Ingress",
- "service-function-forwarder": "openflow:3"
- }
- ],
- "nsh-aware": false,
- "type": "delay"
- }
- ]
- }
-}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function:service-functions/
-----
-
-*SFF RESTCONF Request*
-
-Configuring switch and port information for the service functions.
-----
-curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{
- "service-function-forwarders": {
- "service-function-forwarder": [
- {
- "name": "openflow:3",
- "service-node": "OVSDB2",
- "sff-data-plane-locator": [
- {
- "name": "Ingress",
- "data-plane-locator":
- {
- "vlan-id": 100,
- "mac": "11:11:11:11:11:11",
- "transport": "service-locator:mac"
- },
- "service-function-forwarder-ofs:ofs-port":
- {
- "port-id" : "3"
- }
- }
- ],
- "service-function-dictionary": [
- {
- "name": "srvc1",
- "sff-sf-data-plane-locator":
- {
- "sf-dpl-name" : "openflow:3",
- "sff-dpl-name" : "Ingress"
- }
- }
- ]
- },
- {
- "name": "openflow:4",
- "service-node": "OVSDB3",
- "sff-data-plane-locator": [
- {
- "name": "Egress",
- "data-plane-locator":
- {
- "vlan-id": 200,
- "mac": "44:44:44:44:44:44",
- "transport": "service-locator:mac"
- },
- "service-function-forwarder-ofs:ofs-port":
- {
- "port-id" : "3"
- }
- }
- ],
- "service-function-dictionary": [
- {
- "name": "srvc1",
- "sff-sf-data-plane-locator":
- {
- "sf-dpl-name" : "openflow:4",
- "sff-dpl-name" : "Egress"
- }
- }
- ]
- }
- ]
- }
-}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-forwarder:service-function-forwarders/
-----
-
-====== CLI Command
-To provision the network for the two hosts (h1 and h5).
-
-Demonstrates the redirect action with service name srvc1.
-
-----
-intent:add -f <SOURCE_MAC> -t <DESTINATION_MAC> -a REDIRECT -s <SERVICE_NAME>
-----
-
-Example:
-----
-intent:add -f 32:bc:ec:65:a7:d1 -t c2:80:1f:77:41:ed -a REDIRECT -s srvc1
-----
-
-====== Verification
-
-* As we have applied action type redirect now ping should happen between hosts h1 and h5.
-----
- mininet> h1 ping h5
- PING 10.0.0.5 (10.0.0.5) 56(84) bytes of data.
- 64 bytes from 10.0.0.5: icmp_seq=2 ttl=64 time=201 ms
- 64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=200 ms
- 64 bytes from 10.0.0.5: icmp_seq=4 ttl=64 time=200 ms
-----
-The redirect functionality can be verified by the time taken by the ping operation (200ms). The service srvc1 configured using SFC introduces 200ms delay. As the traffic from h1 to h5 is redirected via the srvc1, the time taken by the traffic from h1 to h5 will take about 200ms.
-
-* Flow entries added to nodes for the redirect action.
-----
- mininet> dpctl dump-flows
- *** s1 ------------------------------------------------------------------------
- NXST_FLOW reply (xid=0x4):
- cookie=0x0, duration=9.406s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=1,dl_src=32:bc:ec:65:a7:d1, dl_dst=c2:80:1f:77:41:ed actions=output:4
- cookie=0x0, duration=9.475s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=3,dl_src=c2:80:1f:77:41:ed, dl_dst=32:bc:ec:65:a7:d1 actions=output:1
- cookie=0x1, duration=362.315s, table=0, n_packets=144, n_bytes=12240, idle_age=4, priority=9500,dl_type=0x88cc actions=CONTROLLER:65535
- cookie=0x1, duration=362.324s, table=0, n_packets=4, n_bytes=168, idle_age=3, priority=10000,arp actions=CONTROLLER:65535,NORMAL
- *** s2 ------------------------------------------------------------------------
- NXST_FLOW reply (xid=0x4):
- cookie=0x0, duration=9.503s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=3,dl_src=c2:80:1f:77:41:ed, dl_dst=32:bc:ec:65:a7:d1 actions=output:4
- cookie=0x0, duration=9.437s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=5,dl_src=32:bc:ec:65:a7:d1, dl_dst=c2:80:1f:77:41:ed actions=output:3
- cookie=0x3, duration=362.317s, table=0, n_packets=144, n_bytes=12240, idle_age=4, priority=9500,dl_type=0x88cc actions=CONTROLLER:65535
- cookie=0x3, duration=362.32s, table=0, n_packets=4, n_bytes=168, idle_age=3, priority=10000,arp actions=CONTROLLER:65535,NORMAL
- *** s3 ------------------------------------------------------------------------
- NXST_FLOW reply (xid=0x4):
- cookie=0x0, duration=9.41s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=2,dl_src=32:bc:ec:65:a7:d1, dl_dst=c2:80:1f:77:41:ed actions=output:3
- *** s4 ------------------------------------------------------------------------
- NXST_FLOW reply (xid=0x4):
- cookie=0x0, duration=9.486s, table=0, n_packets=6, n_bytes=588, idle_age=3, priority=9000,in_port=3,dl_src=32:bc:ec:65:a7:d1, dl_dst=c2:80:1f:77:41:ed actions=output:1
-----
+++ /dev/null
-==== How to configure VTN Renderer
-
-The section demonstrates allow or block packets of the traffic within a VTN Renderer, according to the specified flow conditions.
-
-The table below lists the actions to be applied when a packet matches the condition:
-[options="header",cols="20%,80%"]
-|===
-| Action | Function
-|Allow | Permits the packet to be forwarded normally.
-|Block | Discards the packet preventing it from being forwarded.
-|===
-
-===== Requirement
-
-* Before execute the follow steps, please, use default requirements. See section <<_default_requirements,Default Requirements>>.
-
-===== Configuration
-
-Please execute the following curl commands to test network intent using mininet:
-
-====== Create Intent
-
-To provision the network for the two hosts(h1 and h2) and demonstrates the action allow.
-----
-curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X PUT http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436034 -d '{ "intent:intent" : { "intent:id": "b9a13232-525e-4d8c-be21-cd65e3436034", "intent:actions" : [ { "order" : 2, "allow" : {} } ], "intent:subjects" : [ { "order":1 , "end-point-group" : {"name":"10.0.0.1"} }, { "order":2 , "end-point-group" : {"name":"10.0.0.2"}} ] } }'
-----
-
-To provision the network for the two hosts(h2 and h3) and demonstrates the action allow.
-----
-curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X PUT http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436035 -d '{ "intent:intent" : { "intent:id": "b9a13232-525e-4d8c-be21-cd65e3436035", "intent:actions" : [ { "order" : 2, "allow" : {} } ], "intent:subjects" : [ { "order":1 , "end-point-group" : {"name":"10.0.0.2"} }, { "order":2 , "end-point-group" : {"name":"10.0.0.3"}} ] } }'
-----
-
-====== Verification
-
-As we have applied action type allow now ping should happen between hosts (h1 and h2) and (h2 and h3).
-----
- mininet> pingall
- Ping: testing ping reachability
- h1 -> h2 X X
- h2 -> h1 h3 X
- h3 -> X h2 X
- h4 -> X X X
-----
-
-====== Update the intent
-
-To provision block action that indicates traffic is not allowed between h1 and h2.
-----
-curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X PUT http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436034 -d '{ "intent:intent" : { "intent:id": "b9a13232-525e-4d8c-be21-cd65e3436034", "intent:actions" : [ { "order" : 2, "block" : {} } ], "intent:subjects" : [ { "order":1 , "end-point-group" : {"name":"10.0.0.1"} }, { "order":2 , "end-point-group" : {"name":"10.0.0.2"}} ] } }'
-----
-
-====== Verification
-
-As we have applied action type block now ping should not happen between hosts (h1 and h2).
-----
- mininet> pingall
- Ping: testing ping reachability
- h1 -> X X X
- h2 -> X h3 X
- h3 -> X h2 X
- h4 -> X X X
-----
-
-NOTE: Old actions and hosts are replaced by the new action and hosts.
-
-====== Delete the intent
-
-Respective intent and the traffics will be deleted.
-----
-curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X DELETE http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436035
-----
-
-====== Verification
-
-Deletion of intent and flow.
-----
- mininet> pingall
- Ping: testing ping reachability
- h1 -> X X X
- h2 -> X X X
- h3 -> X X X
- h4 -> X X X
-----
-
-NOTE: Ping between two hosts can also be done using MAC Address
-
-To provision the network for the two hosts(h1 MAC address and h2 MAC address).
-----
-curl -v --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X PUT http://localhost:8181/restconf/config/intent:intents/intent/b9a13232-525e-4d8c-be21-cd65e3436035 -d '{ "intent:intent" : { "intent:id": "b9a13232-525e-4d8c-be21-cd65e3436035", "intent:actions" : [ { "order" : 2, "allow" : {} } ], "intent:subjects" : [ { "order":1 , "end-point-group" : {"name":"6e:4f:f7:27:15:c9"} }, { "order":2 , "end-point-group" : {"name":"aa:7d:1f:4a:70:81"}} ] } }'
-----
+++ /dev/null
-=== Simple Mininet topology
-
-[source,python]
-----
-!/usr/bin/python
-
-from mininet.topo import Topo
-
-class SimpleTopology( Topo ):
- "Simple topology example."
-
- def __init__( self ):
- "Create custom topo."
-
- # <1>
- Topo.__init__( self )
-
- # <2>
- Switch1 = self.addSwitch( 's1' )
- Switch2 = self.addSwitch( 's2' )
- Switch3 = self.addSwitch( 's3' )
- Switch4 = self.addSwitch( 's4' )
- Host11 = self.addHost( 'h1' )
- Host12 = self.addHost( 'h2' )
- Host21 = self.addHost( 'h3' )
- Host22 = self.addHost( 'h4' )
- Host23 = self.addHost( 'h5' )
- Service1 = self.addHost( 'srvc1' ) # <3>
-
- # <4>
- self.addLink( Host11, Switch1 )
- self.addLink( Host12, Switch1 )
- self.addLink( Host21, Switch2 )
- self.addLink( Host22, Switch2 )
- self.addLink( Host23, Switch2 )
- self.addLink( Switch1, Switch2 )
- self.addLink( Switch2, Switch4 )
- self.addLink( Switch4, Switch3 )
- self.addLink( Switch3, Switch1 )
- self.addLink( Switch3, Service1 )
- self.addLink( Switch4, Service1 )
-
-
-topos = { 'simpletopology': ( lambda: SimpleTopology() ) }
-----
-<1> Initialize topology
-<2> Add hosts and switches
-<3> Host used to represent the service
-<4> Add links
-
-[quote]
-Source: https://gist.github.com/vinothgithub15/315d0a427d5afc39f2d7
+++ /dev/null
-==== Default Requirements
-
-Start mininet, and create three switches (s1, s2, and s3) and four hosts (h1, h2, h3, and h4) in it.
-
-Replace <Controller IP> based on your environment.
-
-----
-$ sudo mn --mac --topo single,2 --controller=remote,ip=<Controller IP>
-----
-
-----
- mininet> net
- h1 h1-eth0:s2-eth1
- h2 h2-eth0:s2-eth2
- h3 h3-eth0:s3-eth1
- h4 h4-eth0:s3-eth2
- s1 lo: s1-eth1:s2-eth3 s1-eth2:s3-eth3
- s2 lo: s2-eth1:h1-eth0 s2-eth2:h2-eth0 s2-eth3:s1-eth1
- s3 lo: s3-eth1:h3-eth0 s3-eth2:h4-eth0 s3-eth3:s1-eth2
-----
-
-==== Downloading and deploy Karaf distribution
-* Get the Beryllium distribution.
-
-* Unzip the downloaded zip distribution.
-
-* To run the Karaf.
-----
-./bin/karaf
-----
-
-* Once the console is up, type as below to install feature.
-----
-feature:install odl-nic-core-mdsal odl-nic-console odl-nic-listeners
-----
== Network Intent Composition (NIC) User Guide
-=== Overview
-Network Intent Composition (NIC) is an interface that allows clients to
-express a desired state in an implementation-neutral form that will be
-enforced via modification of available resources under the control of
-the OpenDaylight system.
-
-This description is purposely abstract as an intent interface might
-encompass network services, virtual devices, storage, etc.
-
-The intent interface is meant to be a controller-agnostic interface
-so that "intents" are portable across implementations, such as OpenDaylight
-and ONOS. Thus an intent specification should not contain implementation
-or technology specifics.
-
-The intent specification will be implemented by decomposing the intent
-and augmenting it with implementation specifics that are driven by
-local implementation rules, policies, and/or settings.
-
-=== Network Intent Composition (NIC) Architecture
-The core of the NIC architecture is the intent model, which specifies
-the details of the desired state. It is the responsibility of the NIC
-implementation transforms this desired state to the resources under
-the control of OpenDaylight. The component that transforms the
-intent to the implementation is typically referred to as a renderer.
-
-For the Boron release, multiple, simultaneous renderers will not be supported.
-Instead either the VTN or GBP renderer feature can be installed, but
-not both.
-
-For the Boron release, the only actions supported are "ALLOW" and
-"BLOCK". The "ALLOW" action indicates that traffic can flow between
-the source and destination end points, while "BLOCK" prevents that
-flow; although it is possible that an given implementation may augment
-the available actions with additional actions.
-
-Besides transforming a desired state to an actual state it is the
-responsibility of a renderer to update the operational state tree for
-the NIC data model in OpenDaylight to reflect the intent which the
-renderer implemented.
-
-=== Configuring Network Intent Composition (NIC)
-For the Boron release there is no default implementation of a renderer,
-thus without an additional module installed the NIC will not function.
-
-=== Administering or Managing Network Intent Composition (NIC)
-There is no additional administration of management capabilities
-related to the Network Intent Composition features.
-
-=== Interactions
-A user can interact with the Network Intent Composition (NIC) either
-through the RESTful interface using standard RESTCONF operations and
-syntax or via the Karaf console CLI.
-
-==== REST
-
-===== Configuration
-The Network Intent Composition (NIC) feature supports the following REST
-operations against the configuration data store.
-
-* POST - creates a new instance of an intent in the configuration store,
-which will trigger the realization of that intent. An ID _must_ be specified
-as part of this request as an attribute of the intent.
-
-* GET - fetches a list of all configured intents or a specific configured
-intent.
-
-* DELETE - removes a configured intent from the configuration store, which
-triggers the removal of the intent from the network.
-
-===== Operational
-The Network Intent Composition (NIC) feature supports the following REST
-operations against the operational data store.
-
-* GET - fetches a list of all operational intents or a specific operational
-intent.
-
-==== Karaf Console CLI
-This feature provides karaf console CLI command to manipulate the intent
-data model. The CLI essentailly invokes the equivalent data operations.
-
-===== intent:add
-
-Creates a new intent in the configuration data tree
-
-----
-DESCRIPTION
- intent:add
-
- Adds an intent to the controller.
-
-Examples: --actions [ALLOW] --from <subject> --to <subject>
- --actions [BLOCK] --from <subject>
-
-SYNTAX
- intent:add [options]
-
-OPTIONS
- -a, --actions
- Action to be performed.
- -a / --actions BLOCK/ALLOW
- (defaults to [BLOCK])
- --help
- Display this help message
- -t, --to
- Second Subject.
- -t / --to <subject>
- (defaults to any)
- -f, --from
- First subject.
- -f / --from <subject>
- (defaults to any)
-----
-
-===== intent:delete
-Removes an existing intent from the system
-
-----
-DESCRIPTION
- intent:remove
-
- Removes an intent from the controller.
-
-SYNTAX
- intent:remove id
-
-ARGUMENTS
- id Intent Id
-----
-
-===== intent:list
-Lists all the intents in the system
-
-----
-DESCRIPTION
- intent:list
-
- Lists all intents in the controller.
-
-SYNTAX
- intent:list [options]
-
-OPTIONS
- -c, --config
- List Configuration Data (optional).
- -c / --config <ENTER>
- --help
- Display this help message
-----
-
-===== intent:show
-Displayes the details of a single intent
-
-----
-DESCRIPTION
- intent:show
-
- Shows detailed information about an intent.
-
-SYNTAX
- intent:show id
-
-ARGUMENTS
- id Intent Id
-----
-
-
-===== intent:map
-
-List/Add/Delete current state from/to the mapping service.
-
-----
-DESCRIPTION
- intent:map
-
- List/Add/Delete current state from/to the mapping service.
-
-SYNTAX
- intent:map [options]
-
- Examples: --list, -l [ENTER], to retrieve all keys.
- --add-key <key> [ENTER], to add a new key with empty contents.
- --del-key <key> [ENTER], to remove a key with it's values."
- --add-key <key> --value [<value 1>, <value 2>, ...] [ENTER],
- to add a new key with some values (json format).
-OPTIONS
- --help
- Display this help message
- -l, --list
- List values associated with a particular key.
- -l / --filter <regular expression> [ENTER]
- --add-key
- Adds a new key to the mapping service.
- --add-key <key name> [ENTER]
- --value
- Specifies which value should be added/delete from the mapping service.
- --value "key=>value"... --value "key=>value" [ENTER]
- (defaults to [])
- --del-key
- Deletes a key from the mapping service.
- --del-key <key name> [ENTER]
-----
-
-=== NIC Usage Examples
-
-include::NIC_requirements.adoc[]
-
-include::NIC_redirect_test_topology.adoc[]
-
-include::NIC_How_To_configure_VTN_Renderer.adoc[How to configure VTN Renderer]
-
-include::NIC_How_To_configure_Redirect_Action.adoc[How to configure Redirect Action]
-
-include::NIC_How_To_configure_QoS_Attribute_Mapping.adoc[How to configure QoS Attribute Mapping]
-
-include::NIC_How_To_configure_Log_Action.adoc[How to configure Log Action]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/network-intent-composition-(nic)-user-guide.html
== OF-CONFIG User Guide ==
-=== Overview ===
-OF-CONFIG defines an OpenFlow switch as an abstraction called an
-OpenFlow Logical Switch. The OF-CONFIG protocol enables configuration of
-essential artifacts of an OpenFlow Logical Switch so that an OpenFlow
-controller can communicate and control the OpenFlow Logical switch via
-the OpenFlow protocol. OF-CONFIG introduces an operating context for one
-or more OpenFlow data paths called an OpenFlow Capable Switch for one or
-more switches. An OpenFlow Capable Switch is intended to be equivalent
-to an actual physical or virtual network element (e.g. an Ethernet
-switch) which is hosting one or more OpenFlow data paths by partitioning
-a set of OpenFlow related resources such as ports and queues among the
-hosted OpenFlow data paths. The OF-CONFIG protocol enables dynamic
-association of the OpenFlow related resources of an OpenFlow Capable
-Switch with specific OpenFlow Logical Switches which are being hosted on
-the OpenFlow Capable Switch. OF-CONFIG does not specify or report how
-the partitioning of resources on an OpenFlow Capable Switch is achieved.
-OF-CONFIG assumes that resources such as ports and queues are
-partitioned amongst multiple OpenFlow Logical Switches such that each
-OpenFlow Logical Switch can assume full control over the resources that
-is assigned to it.
-
-=== How to start ===
-- start OF-CONFIG feature as below:
-+
- feature:install odl-of-config-all
-
-=== Configuration on the OVS supporting OF-CONFIG ===
-
-NOTE: OVS is not supported by OF-CONFIG temporarily because
-the OpenDaylight version of OF-CONFIG is 1.2 while the OVS version of OF-CONFIG is not standard.
-
-The introduction of configuring the OVS can be referred to:
-
-_https://github.com/openvswitch/of-config._
-
-=== Connection Establishment between the Capable/Logical Switch and OF-CONFIG ===
-
-The OF-CONFIG protocol is based on NETCONF. So the
-switches supporting OF-CONFIG can also access OpenDaylight
-using the functions provided by NETCONF. This is the
-preparation step before connecting to OF-CONFIG. How to access the
-switch to OpenDaylight using the NETCONF can be referred
-to the <<_southbound_netconf_connector,NETCONF Southbound User Guide>> or
-https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf[NETCONF Southbound examples on the wiki].
-
-Now the switches supporting OF-CONFIG and they have connected to the
-controller using NETCONF as described in preparation phase.
-OF-CONFIG can check whether the switch can support OF-CONFIG by
-reading the capability list in NETCONF.
-
-The OF-CONFIG will get the information of the capable switch and logical
-switch via the NETCONF connection, and creates separate topologies for
-the capable and logical switches in the OpenDaylight Topology module.
-
-The Connection between the capable/logical switches and OF-CONFIG is
-finished.
-
-=== Configuration On Capable Switch ===
-Here is an example showing how to make the configuration to
-modify-controller-connection on the capable switch using OF-CONFIG.
-Other configurations can follow the same way of the example.
-
-- Example: modify-controller-connection
-
-NOTE: this configuration can execute via the NETCONF, which can be
-referred to the <<_southbound_netconf_connector,NETCONF Southbound User Guide>> or
-https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf[NETCONF Southbound examples on the wiki].
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/of-config-user-guide.html
== OpFlex agent-ovs User Guide
-=== Introduction
-agent-ovs is a policy agent that works with OVS to enforce a
-group-based policy networking model with locally attached virtual
-machines or containers. The policy agent is designed to work well with
-orchestration tools like OpenStack.
-
-=== Agent Configuration
-The agent configuration is handled using its config file which is by
-default found at "/etc/opflex-agent-ovs/opflex-agent-ovs.conf"
-
-Here is an example configuration file that documents the available
-options:
-
-----
-{
- // Logging configuration
- // "log": {
- // "level": "info"
- // },
-
- // Configuration related to the OpFlex protocol
- "opflex": {
- // The policy domain for this agent.
- "domain": "openstack",
-
- // The unique name in the policy domain for this agent.
- "name": "example-agent",
-
- // a list of peers to connect to, by hostname and port. One
- // peer, or an anycast pseudo-peer, is sufficient to bootstrap
- // the connection without needing an exhaustive list of all
- // peers.
- "peers": [
- // EXAMPLE:
- {"hostname": "10.0.0.30", "port": 8009}
- ],
-
- "ssl": {
- // SSL mode. Possible values:
- // disabled: communicate without encryption
- // encrypted: encrypt but do not verify peers
- // secure: encrypt and verify peer certificates
- "mode": "disabled",
-
- // The path to a directory containing trusted certificate
- // authority public certificates, or a file containing a
- // specific CA certificate.
- "ca-store": "/etc/ssl/certs/"
- },
-
- "inspector": {
- // Enable the MODB inspector service, which allows
- // inspecting the state of the managed object database.
- // Default: enabled
- "enabled": true,
-
- // Listen on the specified socket for the inspector
- // Default /var/run/opflex-agent-ovs-inspect.sock
- "socket-name": "/var/run/opflex-agent-ovs-inspect.sock"
- }
- },
-
- // Endpoint sources provide metadata about local endpoints
- "endpoint-sources": {
- // Filesystem path to monitor for endpoint information
- "filesystem": ["/var/lib/opflex-agent-ovs/endpoints"]
- },
-
- // Renderers enforce policy obtained via OpFlex.
- "renderers": {
- // Stitched-mode renderer for interoperating with a
- // hardware fabric such as ACI
- // EXAMPLE:
- "stitched-mode": {
- "ovs-bridge-name": "br0",
-
- // Set encapsulation type. Must set either vxlan or vlan.
- "encap": {
- // Encapsulate traffic with VXLAN.
- "vxlan" : {
- // The name of the tunnel interface in OVS
- "encap-iface": "br0_vxlan0",
-
- // The name of the interface whose IP should be used
- // as the source IP in encapsulated traffic.
- "uplink-iface": "eth0.4093",
-
- // The vlan tag, if any, used on the uplink interface.
- // Set to zero or omit if the uplink is untagged.
- "uplink-vlan": 4093,
-
- // The IP address used for the destination IP in
- // the encapsulated traffic. This should be an
- // anycast IP address understood by the upstream
- // stiched-mode fabric.
- "remote-ip": "10.0.0.32",
-
- // UDP port number of the encapsulated traffic.
- "remote-port": 8472
- }
-
- // Encapsulate traffic with a locally-significant VLAN
- // tag
- // EXAMPLE:
- // "vlan" : {
- // // The name of the uplink interface in OVS
- // "encap-iface": "team0"
- // }
- },
-
- // Configure forwarding policy
- "forwarding": {
- // Configure the virtual distributed router
- "virtual-router": {
- // Enable virtual distributed router. Set to true
- // to enable or false to disable. Default true.
- "enabled": true,
-
- // Override MAC address for virtual router.
- // Default is "00:22:bd:f8:19:ff"
- "mac": "00:22:bd:f8:19:ff",
-
- // Configure IPv6-related settings for the virtual
- // router
- "ipv6" : {
- // Send router advertisement messages in
- // response to router solicitation requests as
- // well as unsolicited advertisements. This
- // is not required in stitched mode since the
- // hardware router will send them.
- "router-advertisement": true
- }
- },
-
- // Configure virtual distributed DHCP server
- "virtual-dhcp": {
- // Enable virtual distributed DHCP server. Set to
- // true to enable or false to disable. Default
- // true.
- "enabled": true,
-
- // Override MAC address for virtual dhcp server.
- // Default is "00:22:bd:f8:19:ff"
- "mac": "00:22:bd:f8:19:ff"
- },
-
- "endpoint-advertisements": {
- // Enable generation of periodic ARP/NDP
- // advertisements for endpoints. Default true.
- "enabled": "true"
- }
- },
-
- // Location to store cached IDs for managing flow state
- "flowid-cache-dir": "/var/lib/opflex-agent-ovs/ids"
- }
- }
-}
-----
-
-=== Endpoint Registration
-The agent learns about endpoints using endpoint metadata files located
-by default in "/var/lib/opflex-agent-ovs/endpoints".
-
-These are JSON-format files such as the (unusually complex) example
-below:
-----
-{
- "uuid": "83f18f0b-80f7-46e2-b06c-4d9487b0c754",
- "policy-space-name": "test",
- "endpoint-group-name": "group1",
- "interface-name": "veth0",
- "ip": [
- "10.0.0.1", "fd8f:69d8:c12c:ca62::1"
- ],
- "dhcp4": {
- "ip": "10.200.44.2",
- "prefix-len": 24,
- "routers": ["10.200.44.1"],
- "dns-servers": ["8.8.8.8", "8.8.4.4"],
- "domain": "example.com",
- "static-routes": [
- {
- "dest": "169.254.169.0",
- "dest-prefix": 24,
- "next-hop": "10.0.0.1"
- }
- ]
- },
- "dhcp6": {
- "dns-servers": ["2001:4860:4860::8888", "2001:4860:4860::8844"],
- "search-list": ["test1.example.com", "example.com"]
- },
- "ip-address-mapping": [
- {
- "uuid": "91c5b217-d244-432c-922d-533c6c036ab4",
- "floating-ip": "5.5.5.1",
- "mapped-ip": "10.0.0.1",
- "policy-space-name": "common",
- "endpoint-group-name": "nat-epg"
- },
- {
- "uuid": "22bfdc01-a390-4b6f-9b10-624d4ccb957b",
- "floating-ip": "fdf1:9f86:d1af:6cc9::1",
- "mapped-ip": "fd8f:69d8:c12c:ca62::1",
- "policy-space-name": "common",
- "endpoint-group-name": "nat-epg"
- }
- ],
- "mac": "00:00:00:00:00:01",
- "promiscuous-mode": false
-}
-----
-
-The possible parameters for these files are:
-
-*uuid*:: A globally unique ID for the endpoint
-*endpoint-group-name*:: The name of the endpoint group for the endpoint
-*policy-space-name*:: The name of the policy space for the endpoint group.
-*interface-name*:: The name of the OVS interface to which the endpoint
-is attached
-*ip*:: A list of strings contains either IPv4 or IPv6 addresses that the
-endpoint is allowed to use
-*mac*:: The MAC address for the endpoint's interface.
-*promiscuous-mode*:: Allow traffic from this VM to bypass default port
-security
-*dhcp4*:: A distributed DHCPv4 configuration block (see below)
-*dhcp6*:: A distributed DHCPv6 configuration block (see below)
-*ip-address-mapping*:: A list of IP address mapping configuration blocks (see below)
-
-DHCPv4 configuration blocks can contain the following parameters:
-
-*ip*:: the IP address to return with DHCP. Must be one of the
-configured IPv4 addresses.
-*prefix*:: the subnet prefix length
-*routers*:: a list of default gateways for the endpoint
-*dns*:: a list of DNS server addresses
-*domain*:: The domain name parameter to send in the DHCP reply
-*static-routes*:: A list of static route configuration blocks, which
-contains a "dest", "dest-prefix", and "next-hop" parameters to send as
-static routes to the end host
-
-DHCPv6 configuration blocks can contain the following parameters:
-
-*dns*:: A list of DNS servers for the endpoint
-*search-patch*:: The DNS search path for the endpoint
-
-IP address mapping configuration blocks can contain the following
-parameters:
-
-*uuid*:: a globally unique ID for the virtual endpoint created by the
-mapping.
-*floating-ip*:: Map using DNAT to this floating IPv4 or IPv6 address
-*mapped-ip*:: the source IPv4 or IPv6 address; must be one of the IPs
-assigned to the endpoint.
-*endpoint-group-name*:: The name of the endpoint group for the NATed IP
-*policy-space-name*:: The name of the policy space for the NATed IP
-
-=== Inspector
-The Opflex inspector is a useful command-line tool that will allow you
-to inspect the state of the managed object database for the agent for
-debugging and diagnosis purposes.
-
-The command is called "gbp_inspect" and takes the following arguments:
-----
-# gbp_inspect -h
-Usage: ./gbp_inspect [options]
-Allowed options:
- -h [ --help ] Print this help message
- --log arg Log to the specified file (default
- standard out)
- --level arg (=warning) Use the specified log level (default
- info)
- --syslog Log to syslog instead of file or
- standard out
- --socket arg (=/usr/local/var/run/opflex-agent-ovs-inspect.sock)
- Connect to the specified UNIX domain
- socket (default /usr/local/var/run/opfl
- ex-agent-ovs-inspect.sock)
- -q [ --query ] arg Query for a specific object with
- subjectname,uri or all objects of a
- specific type with subjectname
- -r [ --recursive ] Retrieve the whole subtree for each
- returned object
- -f [ --follow-refs ] Follow references in returned objects
- --load arg Load managed objects from the specified
- file into the MODB view
- -o [ --output ] arg Output the results to the specified
- file (default standard out)
- -t [ --type ] arg (=tree) Specify the output format: tree, list,
- or dump (default tree)
- -p [ --props ] Include object properties in output
-----
-
-Here are some examples of the ways to use this tool.
-
-You can get information about the running system using one or more
-queries, which consist of an object model class name and optionally
-the URI of a specific object. The simplest query is to get a single
-object, nonrecursively:
-
-----
-# gbp_inspect -q DmtreeRoot
---* DmtreeRoot,/
-# gbp_inspect -q GbpEpGroup
---* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
---* GbpEpGroup,/PolicyUniverse/PolicySpace/test/GbpEpGroup/group1/
-# gbp_inspect -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
---* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
-----
-
-You can also display all the properties for each object:
-----
-# gbp_inspect -p -q GbpeL24Classifier
---* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier4/
- {
- connectionTracking : 1 (reflexive)
- dFromPort : 80
- dToPort : 80
- etherT : 2048 (ipv4)
- name : classifier4
- prot : 6
- }
---* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier3/
- {
- etherT : 34525 (ipv6)
- name : classifier3
- order : 100
- prot : 58
- }
---* GbpeL24Classifier,/PolicyUniverse/PolicySpace/test/GbpeL24Classifier/classifier2/
- {
- etherT : 2048 (ipv4)
- name : classifier2
- order : 101
- prot : 1
- }
-----
-
-You can also request to get the all the children of an object you query for:
-----
-# gbp_inspect -r -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
---* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
- |-* GbpeInstContext,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpeInstContext/
- `-* GbpEpGroupToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpEpGroupToNetworkRSrc/
-----
-
-You can also follow references found in any object downloads:
-----
-# gbp_inspect -fr -q GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
---* GbpEpGroup,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/
- |-* GbpeInstContext,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpeInstContext/
- `-* GbpEpGroupToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpEpGroup/nat-epg/GbpEpGroupToNetworkRSrc/
---* GbpFloodDomain,/PolicyUniverse/PolicySpace/common/GbpFloodDomain/fd_ext/
- `-* GbpFloodDomainToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpFloodDomain/fd_ext/GbpFloodDomainToNetworkRSrc/
---* GbpBridgeDomain,/PolicyUniverse/PolicySpace/common/GbpBridgeDomain/bd_ext/
- `-* GbpBridgeDomainToNetworkRSrc,/PolicyUniverse/PolicySpace/common/GbpBridgeDomain/bd_ext/GbpBridgeDomainToNetworkRSrc/
---* GbpRoutingDomain,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/
- |-* GbpRoutingDomainToIntSubnetsRSrc,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/GbpRoutingDomainToIntSubnetsRSrc/122/%2fPolicyUniverse%2fPolicySpace%2fcommon%2fGbpSubnets%2fsubnets_ext%2f/
- `-* GbpForwardingBehavioralGroupToSubnetsRSrc,/PolicyUniverse/PolicySpace/common/GbpRoutingDomain/rd_ext/GbpForwardingBehavioralGroupToSubnetsRSrc/
---* GbpSubnets,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/
- |-* GbpSubnet,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/GbpSubnet/subnet_ext4/
- `-* GbpSubnet,/PolicyUniverse/PolicySpace/common/GbpSubnets/subnets_ext/GbpSubnet/subnet_ext6/
-----
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/opflex-agend-ovs-user-guide.html
== ODL-SDNi User Guide
=== Introduction
-This user guide will help to setup the ODL-SDNi application for lithium release and contains the examples configuration using ODL-BGPCEP.
+This user guide will help to setup the ODL-SDNi application for boron release and contains the examples configuration using ODL-BGPCEP.
=== Components
SDNiAggregator(controller), SDNi REST API(controller) and SDNiWrapper(bgpcep) are the three components in ODL-SDNi App
* SDNiAggregator: Connects with switch, topology, hosttracker managers of controller to get the topology and other related data.
* SDNi REST API: It is a part of controller northbound, which gives the required information by quering SDNiAggregator through RESTCONF.
* SDNiWrapper: This component uses the SDNi REST API and gathers the information required to be shared among controllers.
+* SDNiUI:This component displays all the SDN controllers which are connected to each other.
=== Troubleshooting
To work with multiple controllers, change some of the configuration in config.ini file. For example change the listening port of one controller to 6653 and other controller to 6663 in /root/controller/opendaylight/distribution/opendaylight/target/distribution.opendaylight-osgipackage/opendaylight/configuration/config.ini (i.e of.listenPort=6653).
+++ /dev/null
-=== SFC Classifier User Guide
-
-==== Overview
-Description of classifier can be found in: https://datatracker.ietf.org/doc/draft-ietf-sfc-architecture/
-
-There are two types of classifier:
-
-. OpenFlow Classifier
-
-. Iptables Classifier
-
-==== OpenFlow Classifier
-
-OpenFlow Classifier implements the classification criteria based on OpenFlow rules deployed into an OpenFlow switch. An Open vSwitch will take the role of a classifier and performs various encapsulations such NSH, VLAN, MPLS, etc. In the existing implementation, classifier can support NSH encapsulation. Matching information is based on ACL for MAC addresses, ports, protocol, IPv4 and IPv6. Supported protocols are TCP, UDP and SCTP. Actions information in the OF rules, shall be forwarding of the encapsulated packets with specific information related to the RSP.
-
-===== Classifier Architecture
-
-The OVSDB Southbound interface is used to create an instance of a bridge in a specific location (via IP address). This bridge contains the OpenFlow rules that perform the classification of the packets and react accordingly. The OpenFlow Southbound interface is used to translate the ACL information into OF rules within the Open vSwitch.
-
-NOTE: in order to create the instance of the bridge that takes the role of a classifier, an "empty" SFF must be created.
-
-===== Configuring Classifier
-. An empty SFF must be created in order to host the ACL that contains the classification information.
-. SFF data plane locator must be configured
-. Classifier interface must be mannually added to SFF bridge.
-
-===== Administering or Managing Classifier
-Classification information is based on MAC addresses, protocol, ports and IP. ACL gathers this information and is assigned to an RSP which turns to be a specific path for a Service Chain.
-
-==== Iptables Classifier
-
-Classifier manages everything from starting the packet listener to creation (and removal) of appropriate ip(6)tables rules and marking received packets accordingly. Its functionality is *available only on Linux* as it leverdges *NetfilterQueue*, which provides access to packets matched by an *iptables* rule. Classifier requires *root privileges* to be able to operate.
-
-So far it is capable of processing ACL for MAC addresses, ports, IPv4 and IPv6. Supported protocols are TCP and UDP.
-
-===== Classifier Architecture
-Python code located in the project repository sfc-py/common/classifier.py.
-
-NOTE: classifier assumes that Rendered Service Path (RSP) *already exists* in ODL when an ACL referencing it is obtained
-
-.How it works:
-. sfc_agent receives an ACL and passes it for processing to the classifier
-. the RSP (its SFF locator) referenced by ACL is requested from ODL
-. if the RSP exists in the ODL then ACL based iptables rules for it are applied
-
-After this process is over, every packet successfully matched to an iptables rule (i.e. successfully classified) will be NSH encapsulated and forwarded to a related SFF, which knows how to traverse the RSP.
-
-Rules are created using appropriate iptables command. If the Access Control Entry (ACE) rule is MAC address related both iptables and ip6tabeles rules re issued. If ACE rule is IPv4 address related, only iptables rules are issued, same for IPv6.
-
-NOTE: iptables *raw* table contains all created rules
-
-===== Configuring Classifier
-Classfier does't need any configuration. +
-Its only requirement is that the *second (2) Netfilter Queue* is not used by any other process and is *avalilable for the classifier*.
-
-===== Administering or Managing Classifier
-Classfier runs alongside sfc_agent, therefore the commad for starting it locally is:
-
- sudo python3.4 sfc-py/sfc_agent.py --rest --odl-ip-port localhost:8181 --auto-sff-name --nfq-class
+++ /dev/null
-=== SFC IOS XE Renderer User Guide
-
-:SFCIOSXERNDR: SFC IOS-XE renderer
-
-==== Overview
-The early Service Function Chaining (SFC) renderer for IOS-XE devices
-({SFCIOSXERNDR}) implements Service Chaining functionality on IOS-XE
-capable switches. It listens for the creation of a Rendered Service
-Path (RSP) and sets up Service Function Forwarders (SFF) that are hosted
-on IOS-XE switches to steer traffic through the service chain.
-
-Common acronyms used in the following sections:
-
-* SF - Service Function
-* SFF - Service Function Forwarder
-* SFC - Service Function Chain
-* SP - Service Path
-* SFP - Service Function Path
-* RSP - Rendered Service Path
-* LSF - Local Service Forwarder
-* RSF - Remote Service Forwarder
-
-==== SFC IOS-XE Renderer Architecture
-When the {SFCIOSXERNDR} is initialized, all required listeners are registered
-to handle incoming data. It involves CSR/IOS-XE +NodeListener+ which stores
-data about all configurable devices including their mountpoints (used here
-as databrokers), +ServiceFunctionListener+, +ServiceForwarderListener+
-(see mapping) and +RenderedPathListener+ used to listen for
-RSP changes. When the {SFCIOSXERNDR} is invoked, +RenderedPathListener+ calls
-the +IosXeRspProcessor+ which processes the RSP change and creates all necessary
-Service Paths and Remote Service Forwarders (if necessary) on IOS-XE devices.
-
-==== Service Path details
-Each Service Path is defined by index (represented by NSP) and contains
-service path entries. Each entry has appropriate service index
-(NSI) and definition of next hop. Next hop can be Service Function, different
-Service Function Forwarder or definition of end of chain - terminate. After
-terminating, the packet is sent to destination. If a SFF is defined as a next hop,
-it has to be present on device in the form of Remote Service Forwarder.
-RSFs are also created during RSP processing.
-
-Example of Service Path:
-
- service-chain service-path 200
- service-index 255 service-function firewall-1
- service-index 254 service-function dpi-1
- service-index 253 terminate
-
-==== Mapping to IOS-XE SFC entities
-Renderer contains mappers for SFs and SFFs. IOS-XE capable device is using its
-own definition of Service Functions and Service Function Forwarders according to
-appropriate .yang file.
-+ServiceFunctionListener+ serves as a listener for SF changes. If SF appears in
-datastore, listener extracts its management ip address and looks into cached IOS-XE
-nodes. If some of available nodes match, Service function is mapped
-in +IosXeServiceFunctionMapper+ to be understandable by IOS-XE device and it's
-written into device's config.
-+ServiceForwarderListener+ is used in a similar way. All SFFs with suitable
-management ip address it mapped in +IosXeServiceForwarderMapper+. Remapped SFFs
-are configured as a Local Service Forwarders. It is not possible to directly create
-Remote Service Forwarder using IOS-XE renderer. RSF is created only during RSP processing.
-
-==== Administering {SFCIOSXERNDR}
-To use the SFC IOS-XE Renderer Karaf, at least the following Karaf
-features must be installed:
-
-* odl-aaa-shiro
-* odl-sfc-model
-* odl-sfc-provider
-* odl-restconf
-* odl-netconf-topology
-* odl-sfc-ios-xe-renderer
-
-==== {SFCIOSXERNDR} Tutorial
-
-===== Overview
-This tutorial is a simple example how to create Service Path on IOS-XE capable device
-using IOS-XE renderer
-
-===== Preconditions
-To connect to IOS-XE device, it is necessary to use several modified yang models and override
-device's ones. All .yang files are in the +Yang/netconf+ folder in the +sfc-ios-xe-renderer module+ in
-the SFC project. These files have to be copied to the +cache/schema+ directory, before
-Karaf is started. After that, custom capabilities have to be sent to network-topology:
-
-----
-PUT ./config/network-topology:network-topology/topology/topology-netconf/node/<device-name>
-
-<node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
- <node-id>device-name</node-id>
- <host xmlns="urn:opendaylight:netconf-node-topology">device-ip</host>
- <port xmlns="urn:opendaylight:netconf-node-topology">2022</port>
- <username xmlns="urn:opendaylight:netconf-node-topology">login</username>
- <password xmlns="urn:opendaylight:netconf-node-topology">password</password>
- <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
- <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">0</keepalive-delay>
- <yang-module-capabilities xmlns="urn:opendaylight:netconf-node-topology">
- <override>true</override>
- <capability xmlns="urn:opendaylight:netconf-node-topology">
- urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2013-07-15
- </capability>
- <capability xmlns="urn:opendaylight:netconf-node-topology">
- urn:ietf:params:xml:ns:yang:ietf-yang-types?module=ietf-yang-types&revision=2013-07-15
- </capability>
- <capability xmlns="urn:opendaylight:netconf-node-topology">
- urn:ios?module=ned&revision=2016-03-08
- </capability>
- <capability xmlns="urn:opendaylight:netconf-node-topology">
- http://tail-f.com/yang/common?module=tailf-common&revision=2015-05-22
- </capability>
- <capability xmlns="urn:opendaylight:netconf-node-topology">
- http://tail-f.com/yang/common?module=tailf-meta-extensions&revision=2013-11-07
- </capability>
- <capability xmlns="urn:opendaylight:netconf-node-topology">
- http://tail-f.com/yang/common?module=tailf-cli-extensions&revision=2015-03-19
- </capability>
- </yang-module-capabilities>
-</node>
-----
-
-NOTE: The device name in the URL and in the XML must match.
-
-===== Instructions
-When the IOS-XE renderer is installed, all NETCONF nodes in topology-netconf are
-processed and all capable nodes with accessible mountpoints are cached.
-The first step is to create LSF on node.
-
-+Service Function Forwarder configuration+
-
-----
-PUT ./config/service-function-forwarder:service-function-forwarders
-
-{
- "service-function-forwarders": {
- "service-function-forwarder": [
- {
- "name": "CSR1Kv-2",
- "ip-mgmt-address": "172.25.73.23",
- "sff-data-plane-locator": [
- {
- "name": "CSR1Kv-2-dpl",
- "data-plane-locator": {
- "transport": "service-locator:vxlan-gpe",
- "port": 6633,
- "ip": "10.99.150.10"
- }
- }
- ]
- }
- ]
- }
-}
-----
-
-If the IOS-XE node with appropriate management IP exists, this configuration
-is mapped and LSF is created on the device. The same approach is used for
-Service Functions.
-
-----
-PUT ./config/service-function:service-functions
-
-{
- "service-functions": {
- "service-function": [
- {
- "name": "Firewall",
- "ip-mgmt-address": "172.25.73.23",
- "type": "service-function-type: firewall",
- "nsh-aware": true,
- "sf-data-plane-locator": [
- {
- "name": "firewall-dpl",
- "port": 6633,
- "ip": "12.1.1.2",
- "transport": "service-locator:gre",
- "service-function-forwarder": "CSR1Kv-2"
- }
- ]
- },
- {
- "name": "Dpi",
- "ip-mgmt-address": "172.25.73.23",
- "type":"service-function-type: dpi",
- "nsh-aware": true,
- "sf-data-plane-locator": [
- {
- "name": "dpi-dpl",
- "port": 6633,
- "ip": "12.1.1.1",
- "transport": "service-locator:gre",
- "service-function-forwarder": "CSR1Kv-2"
- }
- ]
- },
- {
- "name": "Qos",
- "ip-mgmt-address": "172.25.73.23",
- "type":"service-function-type: qos",
- "nsh-aware": true,
- "sf-data-plane-locator": [
- {
- "name": "qos-dpl",
- "port": 6633,
- "ip": "12.1.1.4",
- "transport": "service-locator:gre",
- "service-function-forwarder": "CSR1Kv-2"
- }
- ]
- }
- ]
- }
-}
-----
-
-All these SFs are configured on the same device as the LSF. The next step is to
-prepare Service Function Chain. SFC is symmetric.
-
-----
-PUT ./config/service-function-chain:service-function-chains/
-
-{
- "service-function-chains": {
- "service-function-chain": [
- {
- "name": "CSR3XSF",
- "symmetric": "true",
- "sfc-service-function": [
- {
- "name": "Firewall",
- "type": "service-function-type: firewall"
- },
- {
- "name": "Dpi",
- "type": "service-function-type: dpi"
- },
- {
- "name": "Qos",
- "type": "service-function-type: qos"
- }
- ]
- }
- ]
- }
-}
-----
-
-Service Function Path:
-
-----
-PUT ./config/service-function-path:service-function-paths/
-
-{
- "service-function-paths": {
- "service-function-path": [
- {
- "name": "CSR3XSF-Path",
- "service-chain-name": "CSR3XSF",
- "starting-index": 255,
- "symmetric": "true"
- }
- ]
- }
-}
-----
-
-Without a classifier, there is possibility to POST RSP directly.
-
-----
-POST ./operations/rendered-service-path:create-rendered-path
-
-{
- "input": {
- "name": "CSR3XSF-Path-RSP",
- "parent-service-function-path": "CSR3XSF-Path",
- "symmetric": true
- }
-}
-----
-
-The resulting configuration:
-
-----
-!
-service-chain service-function-forwarder local
- ip address 10.99.150.10
-!
-service-chain service-function firewall
-ip address 12.1.1.2
- encapsulation gre enhanced divert
-!
-service-chain service-function dpi
-ip address 12.1.1.1
- encapsulation gre enhanced divert
-!
-service-chain service-function qos
-ip address 12.1.1.4
- encapsulation gre enhanced divert
-!
-service-chain service-path 1
- service-index 255 service-function firewall
- service-index 254 service-function dpi
- service-index 253 service-function qos
- service-index 252 terminate
-!
-service-chain service-path 2
- service-index 255 service-function qos
- service-index 254 service-function dpi
- service-index 253 service-function firewall
- service-index 252 terminate
-!
-----
-
-Service Path 1 is direct, Service Path 2 is reversed. Path numbers may vary.
-
-:SFCIOSXERNDR!:
+++ /dev/null
-=== Service Function Load Balancing User Guide
-
-==== Overview
-SFC Load-Balancing feature implements load balancing of Service Functions, rather than a one-to-one mapping between Service-Function-Forwarder and Service-Function.
-
-==== Load Balancing Architecture
-Service Function Groups (SFG) can replace Service Functions (SF) in the Rendered Path model.
-A Service Path can only be defined using SFGs or SFs, but not a combination of both.
-
-Relevant objects in the YANG model are as follows:
-
-1. Service-Function-Group-Algorithm:
-
- Service-Function-Group-Algorithms {
- Service-Function-Group-Algorithm {
- String name
- String type
- }
- }
-
- Available types: ALL, SELECT, INDIRECT, FAST_FAILURE
-
-2. Service-Function-Group:
-
- Service-Function-Groups {
- Service-Function-Group {
- String name
- String serviceFunctionGroupAlgorithmName
- String type
- String groupId
- Service-Function-Group-Element {
- String service-function-name
- int index
- }
- }
- }
-
-3. ServiceFunctionHop: holds a reference to a name of SFG (or SF)
-
-==== Tutorials
-This tutorial will explain how to create a simple SFC configuration, with SFG instead of SF. In this example, the SFG will include two existing SF.
-
-===== Setup SFC
-For general SFC setup and scenarios, please see the SFC wiki page: https://wiki.opendaylight.org/view/Service_Function_Chaining:Main#SFC_101
-
-===== Create an algorithm
-POST - http://127.0.0.1:8181/restconf/config/service-function-group-algorithm:service-function-group-algorithms
-----
-{
- "service-function-group-algorithm": [
- {
- "name": "alg1"
- "type": "ALL"
- }
- ]
-}
-----
-
-(Header "content-type": application/json)
-
-===== Verify: get all algorithms
-GET - http://127.0.0.1:8181/restconf/config/service-function-group-algorithm:service-function-group-algorithms
-
-In order to delete all algorithms:
-DELETE - http://127.0.0.1:8181/restconf/config/service-function-group-algorithm:service-function-group-algorithms
-
-===== Create a group
-POST - http://127.0.0.1:8181/restconf/config/service-function-group:service-function-groups
-----
-{
- "service-function-group": [
- {
- "rest-uri": "http://localhost:10002",
- "ip-mgmt-address": "10.3.1.103",
- "algorithm": "alg1",
- "name": "SFG1",
- "type": "service-function-type:napt44",
- "sfc-service-function": [
- {
- "name":"napt44-104"
- },
- {
- "name":"napt44-103-1"
- }
- ]
- }
- ]
-}
-----
-
-===== Verify: get all SFG's
-GET - http://127.0.0.1:8181/restconf/config/service-function-group:service-function-groups
\ No newline at end of file
+++ /dev/null
-=== SFC OpenFlow Renderer User Guide
-
-:SFCOFRNDR: SFC OF Renderer
-
-==== Overview
-The Service Function Chaining (SFC) OpenFlow Renderer ({SFCOFRNDR})
-implements Service Chaining on OpenFlow switches. It listens for the
-creation of a Rendered Service Path (RSP), and once received it programs
-Service Function Forwarders (SFF) that are hosted on OpenFlow capable
-switches to steer packets through the service chain.
-
-Common acronyms used in the following sections:
-
-* SF - Service Function
-* SFF - Service Function Forwarder
-* SFC - Service Function Chain
-* SFP - Service Function Path
-* RSP - Rendered Service Path
-
-==== SFC OpenFlow Renderer Architecture
-The {SFCOFRNDR} is invoked after a RSP is created using an MD-SAL listener
-called +SfcOfRspDataListener+. Upon {SFCOFRNDR} initialization, the
-+SfcOfRspDataListener+ registers itself to listen for RSP changes.
-When invoked, the +SfcOfRspDataListener+ processes the RSP and calls
-the +SfcOfFlowProgrammerImpl+ to create the necessary flows in the
-Service Function Forwarders configured in the RSP. Refer to the
-following diagram for more details.
-
-.SFC OpenFlow Renderer High Level Architecture
-image::sfc/sfcofrenderer_architecture.png["SFC OpenFlow Renderer High Level Architecture",width=500]
-
-==== SFC OpenFlow Switch Flow pipeline
-The SFC OpenFlow Renderer uses the following tables for its Flow pipeline:
-
-* Table 0, Classifier
-* Table 1, Transport Ingress
-* Table 2, Path Mapper
-* Table 3, Path Mapper ACL
-* Table 4, Next Hop
-* Table 10, Transport Egress
-
-The OpenFlow Table Pipeline is intended to be generic to work for
-all of the different encapsulations supported by SFC.
-
-All of the tables are explained in detail in the following section.
-
-The SFFs (SFF1 and SFF2), SFs (SF1), and topology used for the flow
-tables in the following sections are as described in the following
-diagram.
-
-.SFC OpenFlow Renderer Typical Network Topology
-image::sfc/sfcofrenderer_nwtopo.png["SFC OpenFlow Renderer Typical Network Topology",width=500]
-
-===== Classifier Table detailed
-
-It is possible for the SFF to also act as a classifier. This table maps subscriber
-traffic to RSPs, and is explained in detail in the classifier documentation.
-
-If the SFF is not a classifier, then this table will just have a simple Goto
-Table 1 flow.
-
-===== Transport Ingress Table detailed
-
-The Transport Ingress table has an entry per expected tunnel transport
-type to be received in a particular SFF, as established in the SFC
-configuration.
-
-Here are two example on SFF1: one where the RSP ingress tunnel is MPLS assuming
-VLAN is used for the SFF-SF, and the other where the RSP ingress tunnel is NSH
-GRE (UDP port 4789):
-
-.Table Transport Ingress
-[cols="1,3,2"]
-|===
-|Priority |Match | Action
-
-|256
-|EtherType==0x8847 (MPLS unicast)
-|Goto Table 2
-
-|256
-|EtherType==0x8100 (VLAN)
-|Goto Table 2
-
-|256
-|EtherType==0x0800,udp,tp_dst==4789 (IP v4)
-|Goto Table 2
-
-|5
-|Match Any
-|Drop
-|===
-
-===== Path Mapper Table detailed
-The Path Mapper table has an entry per expected tunnel transport info
-to be received in a particular SFF, as established in the SFC
-configuration. The tunnel transport info is used to determine the
-RSP Path ID, and is stored in the OpenFlow Metadata. This table is not
-used for NSH, since the RSP Path ID is stored in the NSH header.
-
-For SF nodes that do not support NSH tunneling, the IP header DSCP field is
-used to store the RSP Path Id. The RSP Path Id is written to the DSCP
-field in the Transport Egress table for those packets sent to an SF.
-
-Here is an example on SFF1, assuming the following details:
-
-* VLAN ID 1000 is used for the SFF-SF
-* The RSP Path 1 tunnel uses MPLS label 100 for ingress and 101 for egress
-* The RSP Path 2 (symmetric downlink path) uses MPLS label 101 for ingress and 100 for egress
-
-.Table Path Mapper
-[width=60%]
-|===
-|Priority |Match | Action
-
-|256
-|MPLS Label==100
-|RSP Path=1, Pop MPLS, Goto Table 4
-
-|256
-|MPLS Label==101
-|RSP Path=2, Pop MPLS, Goto Table 4
-
-|256
-|VLAN ID==1000, IP DSCP==1
-|RSP Path=1, Pop VLAN, Goto Table 4
-
-|256
-|VLAN ID==1000, IP DSCP==2
-|RSP Path=2, Pop VLAN, Goto Table 4
-
-|5
-|Match Any
-|Goto Table 3
-|===
-
-===== Path Mapper ACL Table detailed
-This table is only populated when PacketIn packets are received from the switch
-for TcpProxy type SFs. These flows are created with an inactivity timer of 60
-seconds and will be automatically deleted upon expiration.
-
-===== Next Hop Table detailed
-The Next Hop table uses the RSP Path Id and appropriate packet fields to
-determine where to send the packet next. For NSH, only the NSP (Network
-Services Path, RSP ID) and NSI (Network Services Index, next hop) fields
-from the NSH header are needed to determine the VXLAN tunnel destination
-IP. For VLAN or MPLS, then the source MAC address is used to determine
-the destination MAC address.
-
-Here are two examples on SFF1, assuming SFF1 is connected to SFF2. RSP Paths 1
-and 2 are symmetric VLAN paths. RSP Paths 3 and 4 are symmetric NSH paths.
-RSP Path 1 ingress packets come from external to SFC, for which we don’t have
-the source MAC address (MacSrc).
-
-.Table Next Hop
-[cols="1,3,3"]
-|===
-|Priority |Match | Action
-
-|256
-|RSP Path==1, MacSrc==SF1
-|MacDst=SFF2, Goto Table 10
-
-|256
-|RSP Path==2, MacSrc==SF1
-|Goto Table 10
-
-|256
-|RSP Path==2, MacSrc==SFF2
-|MacDst=SF1, Goto Table 10
-
-|246
-|RSP Path==1
-|MacDst=SF1, Goto Table 10
-
-|256
-|nsp=3,nsi=255 (SFF Ingress RSP 3)
-|load:0xa000002->NXM_NX_TUN_IPV4_DST[], Goto Table 10
-
-|256
-|nsp=3,nsi=254 (SFF Ingress from SF, RSP 3)
-|load:0xa00000a->NXM_NX_TUN_IPV4_DST[], Goto Table 10
-
-|256
-|nsp=4,nsi=254 (SFF1 Ingress from SFF2)
-|load:0xa00000a->NXM_NX_TUN_IPV4_DST[], Goto Table 10
-
-|5
-|Match Any
-|Drop
-|===
-
-===== Transport Egress Table detailed
-The Transport Egress table prepares egress tunnel information and
-sends the packets out.
-
-Here are two examples on SFF1. RSP Paths 1 and 2 are symmetric MPLS paths that
-use VLAN for the SFF-SF. RSP Paths 3 and 4 are symmetric NSH paths. Since it is
-assumed that switches used for NSH will only have one VXLANport, the NSH
-packets are just sent back where they came from.
-
-.Table Transport Egress
-[cols="1,3,3"]
-|===
-|Priority |Match | Action
-
-|256
-|RSP Path==1, MacDst==SF1
-|Push VLAN ID 1000, Port=SF1
-
-|256
-|RSP Path==1, MacDst==SFF2
-|Push MPLS Label 101, Port=SFF2
-
-|256
-|RSP Path==2, MacDst==SF1
-|Push VLAN ID 1000, Port=SF1
-
-|246
-|RSP Path==2
-|Push MPLS Label 100, Port=Ingress
-
-|256
-|nsp=3,nsi=255 (SFF Ingress RSP 3)
-|IN_PORT
-
-|256
-|nsp=3,nsi=254 (SFF Ingress from SF, RSP 3)
-|IN_PORT
-
-|256
-|nsp=4,nsi=254 (SFF1 Ingress from SFF2)
-|IN_PORT
-
-|5
-|Match Any
-|Drop
-|===
-
-==== Administering {SFCOFRNDR}
-To use the SFC OpenFlow Renderer Karaf, at least the following Karaf
-features must be installed.
-
-* odl-openflowplugin-nxm-extensions
-* odl-openflowplugin-flow-services
-* odl-sfc-provider
-* odl-sfc-model
-* odl-sfc-openflow-renderer
-* odl-sfc-ui (optional)
-
-The following command can be used to view all of the currently installed Karaf features:
-
- opendaylight-user@root>feature:list -i
-
-Or, pipe the command to a grep to see a subset of the currently installed Karaf features:
-
- opendaylight-user@root>feature:list -i | grep sfc
-
-To install a particular feature, use the Karaf `feature:install` command.
-
-==== {SFCOFRNDR} Tutorial
-
-===== Overview
-In this tutorial, 2 different encapsulations will be shown: MPLS and NSH. The
-following Network Topology diagram is a logical view of the SFFs and SFs involved
-in creating the Service Chains.
-
-.SFC OpenFlow Renderer Typical Network Topology
-image::sfc/sfcofrenderer_nwtopo.png["SFC OpenFlow Renderer Typical Network Topology",width=500]
-
-===== Prerequisites
-To use this example, SFF OpenFlow switches must be created and
-connected as illustrated above. Additionally, the SFs must be
-created and connected.
-
-===== Target Environment
-The target environment is not important, but this use-case was created
-and tested on Linux.
-
-===== Instructions
-The steps to use this tutorial are as follows. The referenced
-configuration in the steps is listed in the following sections.
-
-There are numerous ways to send the configuration. In the following
-configuration chapters, the appropriate `curl` command is shown for
-each configuration to be sent, including the URL.
-
-Steps to configure the {SFCOFRNDR} tutorial:
-
-. Send the `SF` RESTCONF configuration
-. Send the `SFF` RESTCONF configuration
-. Send the `SFC` RESTCONF configuration
-. Send the `SFP` RESTCONF configuration
-. Create the `RSP` with a RESTCONF RPC command
-
-Once the configuration has been successfully created, query the
-Rendered Service Paths with either the SFC UI or via RESTCONF.
-Notice that the RSP is symmetrical, so the following 2 RSPs will
-be created:
-
-* sfc-path1
-* sfc-path1-Reverse
-
-At this point the Service Chains have been created, and the OpenFlow
-Switches are programmed to steer traffic through the Service Chain.
-Traffic can now be injected from a client into the Service Chain.
-To debug problems, the OpenFlow tables can be dumped with the following
-commands, assuming SFF1 is called `s1` and SFF2 is called `s2`.
-
- sudo ovs-ofctl -O OpenFlow13 dump-flows s1
-
- sudo ovs-ofctl -O OpenFlow13 dump-flows s2
-
-In all the following configuration sections, replace the `${JSON}`
-string with the appropriate JSON configuration. Also, change the
-`localhost` desintation in the URL accordingly.
-
-====== {SFCOFRNDR} NSH Tutorial
-
-The following configuration sections show how to create the different elements
-using NSH encapsulation.
-
-*NSH Service Function configuration* +
-
-The Service Function configuration can be sent with the following command:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function:service-functions/
-
-.SF configuration JSON
-----
-{
- "service-functions": {
- "service-function": [
- {
- "name": "sf1",
- "type": "http-header-enrichment",
- "nsh-aware": true,
- "ip-mgmt-address": "10.0.0.2",
- "sf-data-plane-locator": [
- {
- "name": "sf1dpl",
- "ip": "10.0.0.10",
- "port": 4789,
- "transport": "service-locator:vxlan-gpe",
- "service-function-forwarder": "sff1"
- }
- ]
- },
- {
- "name": "sf2",
- "type": "firewall",
- "nsh-aware": true,
- "ip-mgmt-address": "10.0.0.3",
- "sf-data-plane-locator": [
- {
- "name": "sf2dpl",
- "ip": "10.0.0.20",
- "port": 4789,
- "transport": "service-locator:vxlan-gpe",
- "service-function-forwarder": "sff2"
- }
- ]
- }
- ]
- }
-}
-----
-
-*NSH Service Function Forwarder configuration* +
-
-The Service Function Forwarder configuration can be sent with the
-following command:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-forwarder:service-function-forwarders/
-
-.SFF configuration JSON
-----
-{
- "service-function-forwarders": {
- "service-function-forwarder": [
- {
- "name": "sff1",
- "service-node": "openflow:2",
- "sff-data-plane-locator": [
- {
- "name": "sff1dpl",
- "data-plane-locator":
- {
- "ip": "10.0.0.1",
- "port": 4789,
- "transport": "service-locator:vxlan-gpe"
- }
- }
- ],
- "service-function-dictionary": [
- {
- "name": "sf1",
- "sff-sf-data-plane-locator":
- {
- "sf-dpl-name": "sf1dpl",
- "sff-dpl-name": "sff1dpl"
- }
- }
- ]
- },
- {
- "name": "sff2",
- "service-node": "openflow:3",
- "sff-data-plane-locator": [
- {
- "name": "sff2dpl",
- "data-plane-locator":
- {
- "ip": "10.0.0.2",
- "port": 4789,
- "transport": "service-locator:vxlan-gpe"
- }
- }
- ],
- "service-function-dictionary": [
- {
- "name": "sf2",
- "sff-sf-data-plane-locator":
- {
- "sf-dpl-name": "sf2dpl",
- "sff-dpl-name": "sff2dpl"
- }
- }
- ]
- }
- ]
- }
-}
-----
-
-*NSH Service Function Chain configuration* +
-
-The Service Function Chain configuration can be sent with the following command:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-chain:service-function-chains/
-
-.SFC configuration JSON
-----
-{
- "service-function-chains": {
- "service-function-chain": [
- {
- "name": "sfc-chain1",
- "symmetric": true,
- "sfc-service-function": [
- {
- "name": "hdr-enrich-abstract1",
- "type": "http-header-enrichment"
- },
- {
- "name": "firewall-abstract1",
- "type": "firewall"
- }
- ]
- }
- ]
- }
-}
-----
-
-*NSH Service Function Path configuration* +
-
-The Service Function Path configuration can be sent with the following command:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-path:service-function-paths/
-
-.SFP configuration JSON
-----
-{
- "service-function-paths": {
- "service-function-path": [
- {
- "name": "sfc-path1",
- "service-chain-name": "sfc-chain1",
- "transport-type": "service-locator:vxlan-gpe",
- "symmetric": true
- }
- ]
- }
-}
-----
-
-*NSH Rendered Service Path creation* +
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:create-rendered-path/
-
-.RSP creation JSON
-----
-{
- "input": {
- "name": "sfc-path1",
- "parent-service-function-path": "sfc-path1",
- "symmetric": true
- }
-}
-----
-
-*NSH Rendered Service Path removal* +
-
-The following command can be used to remove a Rendered Service Path
-called `sfc-path1`:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{"input": {"name": "sfc-path1" } }' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:delete-rendered-path/
-
-*NSH Rendered Service Path Query* +
-
-The following command can be used to query all of the created Rendered Service Paths:
-
- curl -H "Content-Type: application/json" -H "Cache-Control: no-cache" -X GET --user admin:admin http://localhost:8181/restconf/operational/rendered-service-path:rendered-service-paths/
-
-
-====== {SFCOFRNDR} MPLS Tutorial
-
-The following configuration sections show how to create the different elements
-using MPLS encapsulation.
-
-*MPLS Service Function configuration* +
-
-The Service Function configuration can be sent with the following command:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function:service-functions/
-
-.SF configuration JSON
-----
-{
- "service-functions": {
- "service-function": [
- {
- "name": "sf1",
- "type": "http-header-enrichment",
- "nsh-aware": false,
- "ip-mgmt-address": "10.0.0.2",
- "sf-data-plane-locator": [
- {
- "name": "sf1-sff1",
- "mac": "00:00:08:01:02:01",
- "vlan-id": 1000,
- "transport": "service-locator:mac",
- "service-function-forwarder": "sff1"
- }
- ]
- },
- {
- "name": "sf2",
- "type": "firewall",
- "nsh-aware": false,
- "ip-mgmt-address": "10.0.0.3",
- "sf-data-plane-locator": [
- {
- "name": "sf2-sff2",
- "mac": "00:00:08:01:03:01",
- "vlan-id": 2000,
- "transport": "service-locator:mac",
- "service-function-forwarder": "sff2"
- }
- ]
- }
- ]
- }
-}
-----
-
-*MPLS Service Function Forwarder configuration* +
-
-The Service Function Forwarder configuration can be sent with the
-following command:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-forwarder:service-function-forwarders/
-
-.SFF configuration JSON
-----
-{
- "service-function-forwarders": {
- "service-function-forwarder": [
- {
- "name": "sff1",
- "service-node": "openflow:2",
- "sff-data-plane-locator": [
- {
- "name": "ulSff1Ingress",
- "data-plane-locator":
- {
- "mpls-label": 100,
- "transport": "service-locator:mpls"
- },
- "service-function-forwarder-ofs:ofs-port":
- {
- "mac": "11:11:11:11:11:11",
- "port-id" : "1"
- }
- },
- {
- "name": "ulSff1ToSff2",
- "data-plane-locator":
- {
- "mpls-label": 101,
- "transport": "service-locator:mpls"
- },
- "service-function-forwarder-ofs:ofs-port":
- {
- "mac": "33:33:33:33:33:33",
- "port-id" : "2"
- }
- },
- {
- "name": "toSf1",
- "data-plane-locator":
- {
- "mac": "22:22:22:22:22:22",
- "vlan-id": 1000,
- "transport": "service-locator:mac",
- },
- "service-function-forwarder-ofs:ofs-port":
- {
- "mac": "33:33:33:33:33:33",
- "port-id" : "3"
- }
- }
- ],
- "service-function-dictionary": [
- {
- "name": "sf1",
- "sff-sf-data-plane-locator":
- {
- "sf-dpl-name": "sf1-sff1",
- "sff-dpl-name": "toSf1"
- }
- }
- ]
- },
- {
- "name": "sff2",
- "service-node": "openflow:3",
- "sff-data-plane-locator": [
- {
- "name": "ulSff2Ingress",
- "data-plane-locator":
- {
- "mpls-label": 101,
- "transport": "service-locator:mpls"
- },
- "service-function-forwarder-ofs:ofs-port":
- {
- "mac": "44:44:44:44:44:44",
- "port-id" : "1"
- }
- },
- {
- "name": "ulSff2Egress",
- "data-plane-locator":
- {
- "mpls-label": 102,
- "transport": "service-locator:mpls"
- },
- "service-function-forwarder-ofs:ofs-port":
- {
- "mac": "66:66:66:66:66:66",
- "port-id" : "2"
- }
- },
- {
- "name": "toSf2",
- "data-plane-locator":
- {
- "mac": "55:55:55:55:55:55",
- "vlan-id": 2000,
- "transport": "service-locator:mac"
- },
- "service-function-forwarder-ofs:ofs-port":
- {
- "port-id" : "3"
- }
- }
- ],
- "service-function-dictionary": [
- {
- "name": "sf2",
- "sff-sf-data-plane-locator":
- {
- "sf-dpl-name": "sf2-sff2",
- "sff-dpl-name": "toSf2"
-
- },
- "service-function-forwarder-ofs:ofs-port":
- {
- "port-id" : "3"
- }
- }
- ]
- }
- ]
- }
-}
-----
-
-*MPLS Service Function Chain configuration* +
-
-The Service Function Chain configuration can be sent with the
-following command:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-chain:service-function-chains/
-
-.SFC configuration JSON
-----
-{
- "service-function-chains": {
- "service-function-chain": [
- {
- "name": "sfc-chain1",
- "symmetric": true,
- "sfc-service-function": [
- {
- "name": "hdr-enrich-abstract1",
- "type": "http-header-enrichment"
- },
- {
- "name": "firewall-abstract1",
- "type": "firewall"
- }
- ]
- }
- ]
- }
-}
-----
-
-*MPLS Service Function Path configuration* +
-
-The Service Function Path configuration can be sent with the following
-command:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-path:service-function-paths/
-
-.SFP configuration JSON
-----
-{
- "service-function-paths": {
- "service-function-path": [
- {
- "name": "sfc-path1",
- "service-chain-name": "sfc-chain1",
- "transport-type": "service-locator:mpls",
- "symmetric": true
- }
- ]
- }
-}
-----
-
-*MPLS Rendered Service Path creation* +
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:create-rendered-path/
-
-.RSP creation JSON
-----
-{
- "input": {
- "name": "sfc-path1",
- "parent-service-function-path": "sfc-path1",
- "symmetric": true
- }
-}
-----
-
-*MPLS Rendered Service Path removal* +
-
-The following command can be used to remove a Rendered Service Path
-called `sfc-path1`:
-
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{"input": {"name": "sfc-path1" } }' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:delete-rendered-path/
-
-*MPLS Rendered Service Path Query* +
-
-The following command can be used to query all of the created Rendered Service Paths:
-
- curl -H "Content-Type: application/json" -H "Cache-Control: no-cache" -X GET --user admin:admin http://localhost:8181/restconf/operational/rendered-service-path:rendered-service-paths/
-
-
-
-
-:SFCOFRNDR!:
-
+++ /dev/null
-=== SFC-OVS integration
-
-==== Overview
-SFC-OVS provides integration of SFC with Open vSwitch (OVS) devices.
-Integration is realized through mapping of SFC objects (like SF, SFF,
-Classifier, etc.) to OVS objects (like Bridge, TerminationPoint=Port/Interface).
-The mapping takes care of automatic instantiation (setup) of corresponding object
-whenever its counterpart is created. For example, when a new SFF is created,
-the SFC-OVS plugin will create a new OVS bridge and when a new OVS Bridge is
-created, the SFC-OVS plugin will create a new SFF.
-
-The feature is intended for SFC users willing to use Open vSwitch as underlying
-network infrastructure for deploying RSPs (Rendered Service Paths).
-
-==== SFC-OVS Architecture
-SFC-OVS uses the OVSDB MD-SAL Southbound API for getting/writing information
-from/to OVS devices. From the user perspective SFC-OVS acts as a layer between
-SFC DataStore and OVSDB.
-
-.SFC-OVS integration into ODL
-image::sfc/sfc-ovs-architecture-user.png[width=250]
-
-==== Configuring SFC-OVS
-.Configuration steps:
-. Run ODL distribution (run karaf)
-. In karaf console execute: +feature:install odl-sfc-ovs+
-. Configure Open vSwitch to use ODL as a manager, using following command:
-+ovs-vsctl set-manager tcp:<odl_ip_address>:6640+
-
-==== Tutorials
-
-===== Verifying mapping from OVS to SFF
-
-====== Overview
-This tutorial shows the usual workflow when OVS configuration is transformed to
-corresponding SFC objects (in this case SFF).
-
-====== Prerequisities
-* Open vSwitch installed (ovs-vsctl command available in shell)
-* SFC-OVS feature configured as stated above
-
-====== Instructions
-.In shell execute:
-. +ovs-vsctl set-manager tcp:<odl_ip_address>:6640+
-. +ovs-vsctl add-br br1+
-. +ovs-vsctl add-port br1 testPort+
-
-====== Verification
-.There are two possible ways to verify if SFF was created:
-a. visit SFC User Interface:
-+http://<odl_ip_address>:8181/sfc/index.html#/sfc/serviceforwarder+
-b. use pure RESTCONF and send GET request to URL:
-+http://<odl_ip_address>:8181/restconf/config/service-function-forwarder:service-function-forwarders+
-
-There should be SFF, which name will be ending with 'br1' and the SFF should
-containt two DataPlane locators: 'br1' and 'testPort'.
-
-===== Verifying mapping from SFF to OVS
-
-====== Overview
-This tutorial shows the usual workflow during creation of OVS Bridge with use
-of SFC APIs.
-
-====== Prerequisities
-* Open vSwitch installed (ovs-vsctl command available in shell)
-* SFC-OVS feature configured as stated above
-
-====== Instructions
-.Steps:
-. In shell execute: +ovs-vsctl set-manager tcp:<odl_ip_address>:6640+
-. Send POST request to URL:
-+http://<odl_ip_address>:8181/restconf/operations/service-function-forwarder-ovs:create-ovs-bridge+
-Use Basic auth with credentials: "admin", "admin" and set +Content-Type: application/json+.
-The content of POST request should be following:
-----
-{
- "input":
- {
- "name": "br-test",
- "ovs-node": {
- "ip": "<Open_vSwitch_ip_address>"
- }
- }
-}
-----
-Open_vSwitch_ip_address is IP address of machine, where Open vSwitch is installed.
-
-====== Verification
-In shell execute: +ovs-vsctl show+. There should be Bridge with name 'br-test'
-and one port/interface called 'br-test'.
-
-Also, corresponding SFF for this OVS Bridge should be configured, which can be
-verified through SFC User Interface or RESTCONF as stated in previous tutorial.
+++ /dev/null
-=== SFC Proof of Transit User Guide
-
-:SFCPOT: SFC Proof of Transit
-
-==== Overview
-Early Service Function Chaining (SFC) Proof of Transit ({SFCPOT})
-implements Service Chaining Proof of Transit functionality on
-capable switches. After the creation of an Rendered Service
-Path (RSP), a user can configure to enable SFC proof of transit
-on the selected RSP to effect the proof of transit.
-
-Common acronyms used in the following sections:
-
-* SF - Service Function
-* SFF - Service Function Forwarder
-* SFC - Service Function Chain
-* SFP - Service Function Path
-* RSP - Rendered Service Path
-* SFCPOT - Service Function Chain Proof of Transit
-
-==== SFC Proof of Transit Architecture
-When {SFCPOT} is initialized, all required listeners are registered
-to handle incoming data. It involves +SfcPotNodeListener+ which stores
-data about all node devices including their mountpoints (used here
-as databrokers), +SfcPotRSPDataListener+, +RenderedPathListener+.
-+RenderedPathListener+ is used to listen for RSP changes.
-+SfcPotRSPDataListener+ implements RPC services to enable or disable
-SFC Proof of Transit on a particular RSP. When the {SFCPOT} is invoked,
-RSP listeners and service implementations are setup to receive SFCPOT
-configurations. When a user configures via a POST RPC call to enable
-SFCPOT on a particular RSP, the configuration drives the creation of
-necessary augmentations to the RSP to effect the SFCPOT configurations.
-
-==== SFC Proof of Transit details
-Several deployments use traffic engineering, policy routing,
-segment routing or service function chaining (SFC) to steer packets
-through a specific set of nodes. In certain cases regulatory obligations
-or a compliance policy require to prove that all packets that are
-supposed to follow a specific path are indeed being forwarded across
-the exact set of nodes specified. I.e. if a packet flow is supposed to
-go through a series of service functions or network nodes, it has to
-be proven that all packets of the flow actually went through the
-service chain or collection of nodes specified by the policy.
-In case the packets of a flow weren't appropriately processed, a
-proof of transit egress device would be required to identify the policy
-violation and take corresponding actions (e.g. drop or redirect the packet,
-send an alert etc.) corresponding to the policy.
-
-The SFCPOT approach is based on meta-data which is added to every packet.
-The meta data is updated at every hop and is used to verify whether
-a packet traversed all required nodes. A particular path is either
-described by a set of secret keys, or a set of shares of a single
-secret. Nodes on the path retrieve their individual keys or shares
-of a key (using for e.g. Shamir's Shared Sharing Secret scheme) from
-a central controller. The complete key set is only known to the
-verifier- which is typically the ultimate node on a path that
-requires proof of transit. Each node in the path uses its secret or share
-of the secret to update the meta-data of the packets as the packets
-pass through the node. When the verifier receives a packet, it can use
-its key(s) along with the meta-data to validate whether the packet
-traversed the service chain correctly.
-
-==== SFC Proof of Transit entities
-In order to implement SFC Proof of Transit for a service function chain,
-an RSP is a pre-requisite to identify the SFC to enable SFC PoT
-on. SFC Proof of Transit for a particular RSP is enabled by an RPC request
-to the controller along with necessary parameters to control some of the
-aspects of the SFC Proof of Transit process.
-
-The RPC handler identifies the RSP and generates SFC Proof of Transit
-parameters like secret share, secret etc., and adds the generated SFCPOT
-configuration parameters to SFC main as well as the various SFC hops.
-The last node in the SFC is configured as a verifier node to allow SFCPOT
-Proof of Transit process to be completed.
-
-The SFCPOT configuration generators and related handling are done by
-+SfcPotAPI+, +SfcPotConfigGenerator+,
-+SfcPotListener+, +SfcPotPolyAPI+,
-+SfcPotPolyClassAPI+ and +SfcPotPolyClass+.
-
-==== Administering {SFCPOT}
-To use the SFC Proof of Transit Karaf, at least the following Karaf
-features must be installed:
-
-* odl-sfc-model
-* odl-sfc-provider
-* odl-sfc-netconf
-* odl-restconf
-* odl-netconf-topology
-* odl-netconf-connector-all
-* odl-sfc-pot
-
-==== {SFCPOT} Tutorial
-
-===== Overview
-This tutorial is a simple example how to configure Service Function Chain
-Proof of Transit using SFC POT feature.
-
-===== Preconditions
-To enable a device to handle SFC Proof of Transit, it is expected that the netconf server
-device advertise capability as under ioam-scv.yang present under src/main/yang folder of
-sfc-pot feature. It is also expected that netconf notifications be enabled and its
-support capability advertised as capabilities.
-
-It is also expected that the devices are netconf mounted and available in the
-topology-netconf store.
-
-===== Instructions
-When SFC Proof of Transit is installed, all netconf nodes in topology-netconf are
-processed and all capable nodes with accessible mountpoints are cached.
-
-First step is to create the required RSP as usually done.
-
-Once RSP name is avaiable it is used to send a POST RPC to the controller similar to
-below:
-
-----
-
-POST ./restconf/operations/sfc-ioam-nb-pot:enable-sfc-ioam-pot-rendered-path
-
-{
- "input": {
- "sfc-ioam-pot-rsp-name": "rsp1"
- }
-}
-
-----
-
-The following can be used to disable the SFC Proof of Transit on an RSP which removes
-the augmentations and stores back the RSP without the SFCPOT enabled features and also
-sending down a delete configuration to the SFCPOT configuration sub-tree in the nodes.
-
-----
-
-POST ./restconf/operations/sfc-ioam-nb-pot:disable-sfc-ioam-pot-rendered-path
-
-{
- "input": {
- "sfc-ioam-pot-rsp-name": "rsp1"
- }
-}
-
-----
-
-:SFCPOT!:
+++ /dev/null
-=== SFC Southbound REST Plugin
-
-==== Overview
-The Southbound REST Plugin is used to send configuration from DataStore down to
-network devices supporting a REST API (i.e. they have a configured REST URI).
-It supports POST/PUT/DELETE operations, which are triggered accordingly by
-changes in the SFC data stores.
-
-.In its current state it listens to changes in these SFC data stores:
-* Access Control List (ACL)
-* Service Classifier Function (SCF)
-* Service Function (SF)
-* Service Function Group (SFG)
-* Service Function Schedule Type (SFST)
-* Service Function Forwader (SFF)
-* Rendered Service Path (RSP)
-
-==== Southbound REST Plugin Architecture
-From the user perspective, the REST plugin is another SFC Southbound plugin
-used to communicate with network devices.
-
-.Soutbound REST Plugin integration into ODL
-image::sfc/sb-rest-architecture-user.png[width=250]
-
-==== Configuring Southbound REST Plugin
-.Configuration steps:
-. Run ODL distribution (run karaf)
-. In karaf console execute: +feature:install odl-sfc-sb-rest+
-. Configure REST URIs for SF/SFF through SFC User Interface or RESTCONF
-(required configuration steps can be found in the tutorial stated bellow)
-
-==== Tutorial
-Comprehensive tutorial on how to use the Southbound REST Plugin and how to
-control network devices with it can be found on:
-https://wiki.opendaylight.org/view/Service_Function_Chaining:Main#SFC_101
+++ /dev/null
-=== Service Function Monitoring
-TBD
-
-==== SF Monitoring Overview
-TBD
-
-==== SF Monitoring Architecture
-TBD
-
-==== The way of getting SF monitor information
-TBD
-
-===== SF NETCONF server configuration
-TBD
-
-===== ODL configuration
-TBD
-
+++ /dev/null
-=== Service Function Scheduling Algorithms
-
-==== Overview
-When creating the Rendered Service Path, the origin SFC controller chose
-the first available service function from a list of service function names.
-This may result in many issues such as overloaded service functions
-and a longer service path as SFC has no means to understand the status of
-service functions and network topology. The service function selection
-framework supports at least four algorithms (Random, Round Robin,
-Load Balancing and Shortest Path) to select the most appropriate service
-function when instantiating the Rendered Service Path. In addition, it is an
-extensible framework that allows 3rd party selection algorithm to be plugged in.
-
-==== Architecture
-The following figure illustrates the service function selection framework
-and algorithms.
-
-.SF Selection Architecture
-image::sfc/sf-selection-arch.png["SF Selection Architecture",width=500]
-
-A user has three different ways to select one service function selection
-algorithm:
-
-. Integrated RESTCONF Calls. OpenStack and/or other administration system
- could provide plugins to call the APIs to select one scheduling algorithm.
-. Command line tools. Command line tools such as curl or browser plugins
- such as POSTMAN (for Google Chrome) and RESTClient (for Mozilla Firefox)
- could select schedule algorithm by making RESTCONF calls.
-. SFC-UI. Now the SFC-UI provides an option for choosing a selection algorithm
- when creating a Rendered Service Path.
-
-The RESTCONF northbound SFC API provides GUI/RESTCONF interactions for choosing
-the service function selection algorithm.
-MD-SAL data store provides all supported service function selection algorithms,
-and provides APIs to enable one of the provided service function selection
-algorithms.
-Once a service function selection algorithm is enabled, the service function
-selection algorithm will work when creating a Rendered Service Path.
-
-==== Select SFs with Scheduler
-Administrator could use both the following ways to select one of the selection
-algorithm when creating a Rendered Service Path.
-
-* Command line tools. Command line tools includes Linux commands curl or even
- browser plugins such as POSTMAN(for Google Chrome) or RESTClient(for Mozilla
- Firefox). In this case, the following JSON content is needed at the moment:
- Service_function_schudule_type.json
-+
- {
- "service-function-scheduler-types": {
- "service-function-scheduler-type": [
- {
- "name": "random",
- "type": "service-function-scheduler-type:random",
- "enabled": false
- },
- {
- "name": "roundrobin",
- "type": "service-function-scheduler-type:round-robin",
- "enabled": true
- },
- {
- "name": "loadbalance",
- "type": "service-function-scheduler-type:load-balance",
- "enabled": false
- },
- {
- "name": "shortestpath",
- "type": "service-function-scheduler-type:shortest-path",
- "enabled": false
- }
- ]
- }
- }
-+
-If using the Linux curl command, it could be:
-+
- curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '$${Service_function_schudule_type.json}'
- -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-scheduler-type:service-function-scheduler-types/
-+
-Here is also a snapshot for using the RESTClient plugin:
-
-.Mozilla Firefox RESTClient
-image::sfc/RESTClient-snapshot.png["Mozilla Firefox RESTClient",width=500]
-
-* SFC-UI.SFC-UI provides a drop down menu for service function selection
- algorithm. Here is a snapshot for the user interaction from SFC-UI when
- creating a Rendered Service Path.
-
-.Karaf Web UI
-image::sfc/karaf-webui-select-a-type.png["Karaf Web UI",width=500]
-NOTE: Some service function selection algorithms in the drop list are not
- implemented yet. Only the first three algorithms are committed at the
- moment.
-
-===== Random
-Select Service Function from the name list randomly.
-
-====== Overview
-The Random algorithm is used to select one Service Function from the name list
-which it gets from the Service Function Type randomly.
-
-====== Prerequisites
-* Service Function information are stored in datastore.
-* Either no algorithm or the Random algorithm is selected.
-
-====== Target Environment
-The Random algorithm will work either no algorithm type is selected or the
-Random algorithm is selected.
-
-====== Instructions
-Once the plugins are installed into Karaf successfully, a user can use his
-favorite method to select the Random scheduling algorithm type.
-There are no special instructions for using the Random algorithm.
-
-===== Round Robin
-Select Service Function from the name list in Round Robin manner.
-
-====== Overview
-The Round Robin algorithm is used to select one Service Function from the name
-list which it gets from the Service Function Type in a Round Robin manner, this
-will balance workloads to all Service Functions. However, this method cannot
-help all Service Functions load the same workload because it's flow-based
-Round Robin.
-
-====== Prerequisites
-* Service Function information are stored in datastore.
-* Round Robin algorithm is selected
-
-====== Target Environment
-The Round Robin algorithm will work one the Round Robin algorithm is selected.
-
-====== Instructions
-Once the plugins are installed into Karaf successfully, a user can use his
-favorite method to select the Round Robin scheduling algorithm type.
-There are no special instructions for using the Round Robin algorithm.
-
-===== Load Balance Algorithm
-Select appropriate Service Function by actual CPU utilization.
-
-====== Overview
-The Load Balance Algorithm is used to select appropriate Service Function
-by actual CPU utilization of service functions. The CPU utilization of
-service function obtained from monitoring information reported via NETCONF.
-
-====== Prerequisites
-* CPU-utilization for Service Function.
-* NETCONF server.
-* NETCONF client.
-* Each VM has a NETCONF server and it could work with NETCONF client well.
-
-====== Instructions
-Set up VMs as Service Functions. enable NETCONF server in VMs.
-Ensure that you specify them separately. For example:
-
-.1 *Setting up the VM*
-.. Set up 4 VMs include 2 SFs' type are Firewall, Others are Napt44. Name them
- as firewall-1, firewall-2, napt44-1, napt44-2 as Service Function.
- The four VMs can run either the same server or different servers.
-.. Install NETCONF server on every VM and enable it.
- More information on NETCONF can be found on the OpenDaylight wiki here:
- https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf:Manual_netopeer_installation
-.. Get Monitoring data from NETCONF server.
- These monitoring data should be get from the NETCONF server which is running
- in VMs. The following static XML data is an example:
-
-static XML data like this:
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<service-function-description-monitor-report>
- <SF-description>
- <number-of-dataports>2</number-of-dataports>
- <capabilities>
- <supported-packet-rate>5</supported-packet-rate>
- <supported-bandwidth>10</supported-bandwidth>
- <supported-ACL-number>2000</supported-ACL-number>
- <RIB-size>200</RIB-size>
- <FIB-size>100</FIB-size>
- <ports-bandwidth>
- <port-bandwidth>
- <port-id>1</port-id>
- <ipaddress>10.0.0.1</ipaddress>
- <macaddress>00:1e:67:a2:5f:f4</macaddress>
- <supported-bandwidth>20</supported-bandwidth>
- </port-bandwidth>
- <port-bandwidth>
- <port-id>2</port-id>
- <ipaddress>10.0.0.2</ipaddress>
- <macaddress>01:1e:67:a2:5f:f6</macaddress>
- <supported-bandwidth>10</supported-bandwidth>
- </port-bandwidth>
- </ports-bandwidth>
- </capabilities>
- </SF-description>
- <SF-monitoring-info>
- <liveness>true</liveness>
- <resource-utilization>
- <packet-rate-utilization>10</packet-rate-utilization>
- <bandwidth-utilization>15</bandwidth-utilization>
- <CPU-utilization>12</CPU-utilization>
- <memory-utilization>17</memory-utilization>
- <available-memory>8</available-memory>
- <RIB-utilization>20</RIB-utilization>
- <FIB-utilization>25</FIB-utilization>
- <power-utilization>30</power-utilization>
- <SF-ports-bandwidth-utilization>
- <port-bandwidth-utilization>
- <port-id>1</port-id>
- <bandwidth-utilization>20</bandwidth-utilization>
- </port-bandwidth-utilization>
- <port-bandwidth-utilization>
- <port-id>2</port-id>
- <bandwidth-utilization>30</bandwidth-utilization>
- </port-bandwidth-utilization>
- </SF-ports-bandwidth-utilization>
- </resource-utilization>
- </SF-monitoring-info>
-</service-function-description-monitor-report>
-----
-
-.2 *Start SFC*
-.. Unzip SFC release tarball.
-.. Run SFC: ${SFC}/bin/karaf.
-More information on Service Function Chaining can be found on the OpenDaylight
-SFC's wiki page:
-https://wiki.opendaylight.org/view/Service_Function_Chaining:Main
-
-.3 *Verify the Load Balance Algorithm*
-.. Deploy the SFC2 (firewall-abstract2=>napt44-abstract2) and click button to
- Create Rendered Service Path in SFC UI (http://localhost:8181/sfc/index.html).
-.. Verify the Rendered Service Path to ensure the CPU utilization of the
- selected hop is the minimum one among all the service functions with same
- type.
-The correct RSP is firewall-1=>napt44-2
-
-===== Shortest Path Algorithm
-Select appropriate Service Function by Dijkstra's algorithm. Dijkstra's
-algorithm is an algorithm for finding the shortest paths between nodes in a
-graph.
-
-====== Overview
-The Shortest Path Algorithm is used to select appropriate Service Function by
-actual topology.
-
-====== Prerequisites
-* Depolyed topology (include SFFs, SFs and their links).
-* Dijkstra's algorithm. More information on Dijkstra's algorithm can be found
-on the wiki here:
-http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
-
-====== Instructions
-.1 *Start SFC*
-.. Unzip SFC release tarball.
-.. Run SFC: ${SFC}/bin/karaf.
-.. Depoly SFFs and SFs. import the service-function-forwarders.json and
- service-functions.json in UI (http://localhost:8181/sfc/index.html#/sfc/config)
-
-service-function-forwarders.json:
-----
-{
- "service-function-forwarders": {
- "service-function-forwarder": [
- {
- "name": "SFF-br1",
- "service-node": "OVSDB-test01",
- "rest-uri": "http://localhost:5001",
- "sff-data-plane-locator": [
- {
- "name": "eth0",
- "service-function-forwarder-ovs:ovs-bridge": {
- "uuid": "4c3778e4-840d-47f4-b45e-0988e514d26c",
- "bridge-name": "br-tun"
- },
- "data-plane-locator": {
- "port": 5000,
- "ip": "192.168.1.1",
- "transport": "service-locator:vxlan-gpe"
- }
- }
- ],
- "service-function-dictionary": [
- {
- "sff-sf-data-plane-locator": {
- "port": 10001,
- "ip": "10.3.1.103"
- },
- "name": "napt44-1",
- "type": "service-function-type:napt44"
- },
- {
- "sff-sf-data-plane-locator": {
- "port": 10003,
- "ip": "10.3.1.102"
- },
- "name": "firewall-1",
- "type": "service-function-type:firewall"
- }
- ],
- "connected-sff-dictionary": [
- {
- "name": "SFF-br3"
- }
- ]
- },
- {
- "name": "SFF-br2",
- "service-node": "OVSDB-test01",
- "rest-uri": "http://localhost:5002",
- "sff-data-plane-locator": [
- {
- "name": "eth0",
- "service-function-forwarder-ovs:ovs-bridge": {
- "uuid": "fd4d849f-5140-48cd-bc60-6ad1f5fc0a1",
- "bridge-name": "br-tun"
- },
- "data-plane-locator": {
- "port": 5000,
- "ip": "192.168.1.2",
- "transport": "service-locator:vxlan-gpe"
- }
- }
- ],
- "service-function-dictionary": [
- {
- "sff-sf-data-plane-locator": {
- "port": 10002,
- "ip": "10.3.1.103"
- },
- "name": "napt44-2",
- "type": "service-function-type:napt44"
- },
- {
- "sff-sf-data-plane-locator": {
- "port": 10004,
- "ip": "10.3.1.101"
- },
- "name": "firewall-2",
- "type": "service-function-type:firewall"
- }
- ],
- "connected-sff-dictionary": [
- {
- "name": "SFF-br3"
- }
- ]
- },
- {
- "name": "SFF-br3",
- "service-node": "OVSDB-test01",
- "rest-uri": "http://localhost:5005",
- "sff-data-plane-locator": [
- {
- "name": "eth0",
- "service-function-forwarder-ovs:ovs-bridge": {
- "uuid": "fd4d849f-5140-48cd-bc60-6ad1f5fc0a4",
- "bridge-name": "br-tun"
- },
- "data-plane-locator": {
- "port": 5000,
- "ip": "192.168.1.2",
- "transport": "service-locator:vxlan-gpe"
- }
- }
- ],
- "service-function-dictionary": [
- {
- "sff-sf-data-plane-locator": {
- "port": 10005,
- "ip": "10.3.1.104"
- },
- "name": "test-server",
- "type": "service-function-type:dpi"
- },
- {
- "sff-sf-data-plane-locator": {
- "port": 10006,
- "ip": "10.3.1.102"
- },
- "name": "test-client",
- "type": "service-function-type:dpi"
- }
- ],
- "connected-sff-dictionary": [
- {
- "name": "SFF-br1"
- },
- {
- "name": "SFF-br2"
- }
- ]
- }
- ]
- }
-}
-----
-
-service-functions.json:
-----
-{
- "service-functions": {
- "service-function": [
- {
- "rest-uri": "http://localhost:10001",
- "ip-mgmt-address": "10.3.1.103",
- "sf-data-plane-locator": [
- {
- "name": "preferred",
- "port": 10001,
- "ip": "10.3.1.103",
- "service-function-forwarder": "SFF-br1"
- }
- ],
- "name": "napt44-1",
- "type": "service-function-type:napt44",
- "nsh-aware": true
- },
- {
- "rest-uri": "http://localhost:10002",
- "ip-mgmt-address": "10.3.1.103",
- "sf-data-plane-locator": [
- {
- "name": "master",
- "port": 10002,
- "ip": "10.3.1.103",
- "service-function-forwarder": "SFF-br2"
- }
- ],
- "name": "napt44-2",
- "type": "service-function-type:napt44",
- "nsh-aware": true
- },
- {
- "rest-uri": "http://localhost:10003",
- "ip-mgmt-address": "10.3.1.103",
- "sf-data-plane-locator": [
- {
- "name": "1",
- "port": 10003,
- "ip": "10.3.1.102",
- "service-function-forwarder": "SFF-br1"
- }
- ],
- "name": "firewall-1",
- "type": "service-function-type:firewall",
- "nsh-aware": true
- },
- {
- "rest-uri": "http://localhost:10004",
- "ip-mgmt-address": "10.3.1.103",
- "sf-data-plane-locator": [
- {
- "name": "2",
- "port": 10004,
- "ip": "10.3.1.101",
- "service-function-forwarder": "SFF-br2"
- }
- ],
- "name": "firewall-2",
- "type": "service-function-type:firewall",
- "nsh-aware": true
- },
- {
- "rest-uri": "http://localhost:10005",
- "ip-mgmt-address": "10.3.1.103",
- "sf-data-plane-locator": [
- {
- "name": "3",
- "port": 10005,
- "ip": "10.3.1.104",
- "service-function-forwarder": "SFF-br3"
- }
- ],
- "name": "test-server",
- "type": "service-function-type:dpi",
- "nsh-aware": true
- },
- {
- "rest-uri": "http://localhost:10006",
- "ip-mgmt-address": "10.3.1.103",
- "sf-data-plane-locator": [
- {
- "name": "4",
- "port": 10006,
- "ip": "10.3.1.102",
- "service-function-forwarder": "SFF-br3"
- }
- ],
- "name": "test-client",
- "type": "service-function-type:dpi",
- "nsh-aware": true
- }
- ]
- }
-}
-----
-
-The depolyed topology like this:
-----
-
- +----+ +----+ +----+
- |sff1|+----------|sff3|---------+|sff2|
- +----+ +----+ +----+
- | |
- +--------------+ +--------------+
- | | | |
- +----------+ +--------+ +----------+ +--------+
- |firewall-1| |napt44-1| |firewall-2| |napt44-2|
- +----------+ +--------+ +----------+ +--------+
-
-----
-
-.2 *Verify the Shortest Path Algorithm*
-** Deploy the SFC2(firewall-abstract2=>napt44-abstract2), select "Shortest
- Path" as schedule type and click button to Create Rendered Service Path in
- SFC UI (http://localhost:8181/sfc/index.html).
-
-.select schedule type
-image::sfc/sf-schedule-type.png["select schedule type",width=500]
-
-** Verify the Rendered Service Path to ensure the selected hops are linked in
- one SFF. The correct RSP is firewall-1=>napt44-1 or firewall-2=>napt44-2.
- The first SF type is Firewall in Service Function Chain. So the algorithm
- will select first Hop randomly among all the SFs type is Firewall.
- Assume the first selected SF is firewall-2.
- All the path from firewall-1 to SF which type is Napt44 are list:
-
-* Path1: firewall-2 -> sff2 -> napt44-2
-* Path2: firewall-2 -> sff2 -> sff3 -> sff1 -> napt44-1
-The shortest path is Path1, so the selected next hop is napt44-2.
-
-.rendered service path
-image::sfc/sf-rendered-service-path.png["rendered service path",width=500]
+++ /dev/null
-=== SFC User Interface
-
-==== Overview
-SFC User Interface (SFC-UI) is based on Dlux project. It provides an easy way
-to create, read, update and delete configuration stored in Datastore. Moreover,
-it shows the status of all SFC features (e.g installed, uninstalled) and
-Karaf log messages as well.
-
-==== SFC-UI Architecture
-SFC-UI operates purely by using RESTCONF.
-
-.SFC-UI integration into ODL
-image::sfc/sfc-ui-architecture.png[width=250]
-
-==== Configuring SFC-UI
-.Configuration steps
-. Run ODL distribution (run karaf)
-. In karaf console execute: +feature:install odl-sfc-ui+
-. Visit SFC-UI on: +http://<odl_ip_address>:8181/sfc/index.html+
== Service Function Chaining
-include::sfc_overview.adoc[SFC Overview]
-
-include::odl-sfc-ui-user.adoc[SFC UI User guide]
-
-include::odl-sfc-sb-rest-user.adoc[SFC Southbound REST plugin User guide]
-
-include::odl-sfc-ovs-user.adoc[SFC OVS User guide]
-
-include::odl-sfc-classifier-user.adoc[SFC Classifier configuration User guide]
-
-// SFC Renderers
-include::odl-sfc-openflow-renderer-user.adoc[SFC OpenFlow Renderer]
-
-include::odl-sfc-iosxe-renderer-user.adoc[SFC IOS XE Renderer]
-
-include::odl-sfc-vpp-renderer-user.adoc[SFC VPP Renderer]
-// SFC Renderers
-
-include::odl-sfc-sf-scheduler-user.adoc[Service Function selection scheduler]
-
-// Removed because there is no content
-// include::odl-sfc-sf-monitoring-user.adoc[Service Function Monitoring]
-
-include::odl-sfc-load-balance-user.adoc[Service Function Grouping and Load Balancing user guide]
-
-include::odl-sfc-pot-user.adoc[SFC Proof of Transit]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/service-function-chaining.html
+++ /dev/null
-=== OpenDaylight Service Function Chaining (SFC) Overiew
-
-OpenDaylight Service Function Chaining (SFC) provides the ability to define an ordered list of a network services (e.g. firewalls, load balancers). These service are then "stitched" together in the network to create a service chain. This project provides the infrastructure (chaining logic, APIs) needed for ODL to provision a service chain in the network and an end-user application for defining such chains.
-
-.List of acronyms:
-* ACE - Access Control Entry
-* ACL - Access Control List
-* SCF - Service Classifier Function
-* SF - Service Function
-* SFC - Service Function Chain
-* SFF - Service Function Forwarder
-* SFG - Service Function Group
-* SFP - Service Function Path
-* RSP - Rendered Service Path
-* NSH - Network Service Header
\ No newline at end of file
== SNMP4SDN User Guide\r
-=== Overview\r
-We propose a southbound plugin that can control the off-the-shelf commodity Ethernet switches for the purpose of building SDN using Ethernet switches. For Ethernet switches, forwarding table, VLAN table, and ACL are where one can install flow configuration on, and this is done via SNMP and CLI in the proposed plugin. In addition, some settings required for Ethernet switches in SDN, e.g., disabling STP and flooding, are proposed.\r
-\r
-.SNMP4SDN as an OpenDaylight southbound plugin \r
-image::snmp4sdn_in_odl_architecture.jpg["SNMP4SDN as an OpenDaylight southbound plugin",width=400]\r
-\r
-=== Configuration\r
-Just follow the steps:\r
-\r
-==== Prepare the switch list database file\r
-A sample is https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file[here], and we suggest to save it as '/etc/snmp4sdn_swdb.csv' so that SNMP4SDN Plugin can automatically load this file. Note that the first line is title and should not be removed.\r
-\r
-==== Prepare the vendor-specific configuration file\r
-A sample is https://wiki.opendaylight.org/view/SNMP4SDN:snmp4sdn_VendorSpecificSwitchConfig_file[here], and we suggest to save it as '/etc/snmp4sdn_VendorSpecificSwitchConfig.xml' so that SNMP4SDN Plugin can automatically load this file.\r
-\r
-=== Install SNMP4SDN Plugin\r
-If using SNMP4SDN Plugin provided in OpenDaylight release, just do the following from the Karaf CLI:\r
-\r
-----\r
-feature:install odl-snmp4sdn-all\r
-----\r
-\r
-=== Troubleshooting\r
-==== Installation Troubleshooting\r
-===== Feature installation failure\r
-When trying to install a feature, if the following failure occurs:\r
-----\r
-Error executing command: Could not start bundle ... \r
-Reason: Missing Constraint: Require-Capability: osgi.ee; filter="(&(osgi.ee=JavaSE)(version=1.7))"\r
-----\r
-A workaround: exit Karaf, and edit the file <karaf_directory>/etc/config.properties, remove the line '${services-${karaf.framework}}' and the ", \" in the line above.\r
-\r
-==== Runtime Troubleshooting\r
-===== Problem starting SNMP Trap Interface\r
-It is possible to get the following exception during controller startup. (The error would not be printed in Karaf console, one may see it in <karaf_directory>/data/log/karaf.log)\r
-----\r
-2014-01-31 15:00:44.688 CET [fileinstall-./plugins] WARN o.o.snmp4sdn.internal.SNMPListener - Problem starting SNMP Trap Interface: {}\r
- java.net.BindException: Permission denied\r
- at java.net.PlainDatagramSocketImpl.bind0(Native Method) ~[na:1.7.0_51]\r
- at java.net.AbstractPlainDatagramSocketImpl.bind(AbstractPlainDatagramSocketImpl.java:95) ~[na:1.7.0_51]\r
- at java.net.DatagramSocket.bind(DatagramSocket.java:376) ~[na:1.7.0_51]\r
- at java.net.DatagramSocket.<init>(DatagramSocket.java:231) ~[na:1.7.0_51]\r
- at java.net.DatagramSocket.<init>(DatagramSocket.java:284) ~[na:1.7.0_51]\r
- at java.net.DatagramSocket.<init>(DatagramSocket.java:256) ~[na:1.7.0_51]\r
- at org.snmpj.SNMPTrapReceiverInterface.<init>(SNMPTrapReceiverInterface.java:126) ~[org.snmpj-1.4.3.jar:na]\r
- at org.snmpj.SNMPTrapReceiverInterface.<init>(SNMPTrapReceiverInterface.java:99) ~[org.snmpj-1.4.3.jar:na]\r
- at org.opendaylight.snmp4sdn.internal.SNMPListener.<init>(SNMPListener.java:75) ~[bundlefile:na]\r
- at org.opendaylight.snmp4sdn.core.internal.Controller.start(Controller.java:174) [bundlefile:na]\r
-...\r
-----\r
-This indicates that the controller is being run as a user which does not have sufficient OS privileges to bind the SNMPTRAP port (162/UDP)\r
-\r
-==== Switch list file missing\r
-The SNMP4SDN Plugin needs a switch list file, which is necessary for topology discovery and should be provided by the administrator (so please prepare one for the first time using SNMP4SDN Plugin, here is the https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file[sample]). The default file path is /etc/snmp4sdn_swdb.csv. SNMP4SDN Plugin would automatically load this file and start topology discovery. If this file is not ready there, the following message like this will pop up:\r
-----\r
-2016-02-02 04:21:52,476 | INFO| Event Dispatcher | CmethUtil | 466 - org.opendaylight.snmp4sdn - 0.3.0.SNAPSHOT | CmethUtil.readDB() err: {}\r
-java.io.FileNotFoundException: /etc/snmp4sdn_swdb.csv (No such file or directory)\r
- at java.io.FileInputStream.open0(Native Method)[:1.8.0_65]\r
- at java.io.FileInputStream.open(FileInputStream.java:195)[:1.8.0_65]\r
- at java.io.FileInputStream.<init>(FileInputStream.java:138)[:1.8.0_65]\r
- at java.io.FileInputStream.<init>(FileInputStream.java:93)[:1.8.0_65]\r
- at java.io.FileReader.<init>(FileReader.java:58)[:1.8.0_65]\r
- at org.opendaylight.snmp4sdn.internal.util.CmethUtil.readDB(CmethUtil.java:66)\r
- at org.opendaylight.snmp4sdn.internal.util.CmethUtil.<init>(CmethUtil.java:43)\r
-...\r
-----\r
-\r
-=== Configuration\r
-Just follow the steps:\r
-\r
-==== 1. Prepare the switch list database file\r
-A sample is https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file[here], and we suggest to save it as '/etc/snmp4sdn_swdb.csv' so that SNMP4SDN Plugin can automatically load this file.\r
-\r
-NOTE:\r
-The first line is title and should not be removed.\r
-\r
-==== 2. Prepare the vendor-specific configuration file\r
-A sample is https://wiki.opendaylight.org/view/SNMP4SDN:snmp4sdn_VendorSpecificSwitchConfig_file[here], and we suggest to save it as '/etc/snmp4sdn_VendorSpecificSwitchConfig.xml' so that SNMP4SDN Plugin can automatically load this file.\r
-\r
-==== 3. Install SNMP4SDN Plugin\r
-If using SNMP4SDN Plugin provided in OpenDaylight release, just do the following:\r
-\r
-Launch Karaf in Linux console:\r
-----\r
-cd <Beryllium_controller_directory>/bin\r
-(for example, cd distribution-karaf-x.x.x-Beryllium/bin)\r
-----\r
-----\r
-./karaf\r
-----\r
-Then in Karaf console, execute:\r
-----\r
-feature:install odl-snmp4sdn-all\r
-----\r
-\r
-==== 4. Load switch list\r
-For initialization, we need to feed SNMP4SDN Plugin the switch list. Actually SNMP4SDN Plugin automatically try to load the switch list at /etc/snmp4sdn_swdb.csv if there is. If so, this step could be skipped.\r
-In Karaf console, execute:\r
-----\r
-snmp4sdn:ReadDB <switch_list_path>\r
-(For example, snmp4sdn:ReadDB /etc/snmp4sdn_swdb.csv)\r
-(in Windows OS, For example, snmp4sdn:ReadDB D://snmp4sdn_swdb.csv)\r
-----\r
-A sample is https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file[here], and we suggest to save it as '/etc/snmp4sdn_swdb.csv' so that SNMP4SDN Plugin can automatically load this file. \r
-\r
-NOTE:\r
-The first line is title and should not be removed.\r
-\r
-==== 5. Show switch list\r
-----\r
-snmp4sdn:PrintDB\r
-----\r
-\r
-=== Tutorial\r
-==== Topology Service\r
-===== Execute topology discovery\r
-\r
-The SNMP4SDN Plugin automatically executes topology discovery on startup. One may use the following commands to invoke topology discovery manually. Note that you may need to wait for seconds for itto complete. \r
-\r
-NOTE:\r
-Currently, one needs to manually execute 'snmp4sdn:TopoDiscover' first (just once), then later the automatic topology discovery can be successful. If switches change (switch added or removed), 'snmp4sdn:TopoDiscover' is also required. A future version will fix it to eliminate these requirements.\r
-----\r
-snmp4sdn:TopoDiscover\r
-----\r
-\r
-If one like to discover all inventory (i.e. switches and their ports) but not edges, just execute "TopoDiscoverSwitches":\r
-----\r
-snmp4sdn:TopoDiscoverSwitches\r
-----\r
-\r
-If one like to only discover all edges but not inventory, just execute "TopoDiscoverEdges":\r
-----\r
-snmp4sdn:TopoDiscoverEdges\r
-----\r
-\r
-You can also trigger topology discovery via the REST API by using +curl+ from the Linux console (or any other REST client):\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:rediscover\r
-----\r
-\r
-You can change the periodic topology discovery interval via a REST API:\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:set-discovery-interval -d "{"input":{"interval-second":'<interval_time>'}}" \r
-For example, set the interval as 15 seconds:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:set-discovery-interval -d "{"input":{"interval-second":'15'}}" \r
-----\r
-\r
-===== Show the topology\r
-\r
-SNMP4SDN Plugin supports to show topology via REST API:\r
-\r
-* Get topology\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:get-edge-list\r
-----\r
-+\r
-* Get switch list\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:get-node-list\r
-----\r
-+\r
-* Get switches' ports list\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:get-node-connector-list\r
-----\r
-+\r
-* The three commands above are just for user to get the latest topology discovery result, it does not trigger SNMP4SDN Plugin to do topology discovery.\r
-* To trigger SNMP4SDN Plugin to do topology discover, as described in aforementioned 'Execute topology discovery'.\r
-\r
-==== Flow configuration\r
-\r
-===== FDB configuration\r
-\r
-SNMP4SDN supports to add entry on FDB table via REST API:\r
-\r
-* Get FDB table\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:get-fdb-table -d "{input:{"node-id":<switch-mac-address-in-number>}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:get-fdb-table -d "{input:{"node-id":158969157063648}}" \r
-----\r
-+\r
-* Get FDB table entry\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:get-fdb-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "dest-mac-addr":<destination-mac-address-in-number>}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:get-fdb-entry -d "{input:{"node-id":158969157063648, "vlan-id":1, "dest-mac-addr":158969157063648}}" \r
-----\r
-+\r
-* Set FDB table entry\r
-+\r
-(Notice invalid value: (1) non unicast mac (2) port not in the VLAN)\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:set-fdb-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "dest-mac-addr":<destination-mac-address-in-number>, "port":<port-in-number>, "type":'<type>'}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:set-fdb-entry -d "{input:{"node-id":158969157063648, "vlan-id":1, "dest-mac-addr":187649984473770, "port":23, "type":'MGMT'}}" \r
-----\r
-+\r
-* Delete FDB table entry\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:del-fdb-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "dest-mac-addr":<destination-mac-address-in-number>}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:del-fdb-entry -d "{input:{"node-id":158969157063648, "vlan-id":1, "dest-mac-addr":187649984473770}}" \r
-----\r
-\r
-===== VLAN configuration\r
-\r
-SNMP4SDN supports to add entry on VLAN table via REST API:\r
-\r
-* Get VLAN table\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:get-vlan-table -d "{input:{node-id:<switch-mac-address-in-number>}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:get-vlan-table -d "{input:{node-id:158969157063648}}" \r
-----\r
-+\r
-* Add VLAN\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:add-vlan -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "vlan-name":'<vlan-name>'}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:add-vlan -d "{"input":{"node-id":158969157063648, "vlan-id":123, "vlan-name":'v123'}}" \r
-----\r
-+\r
-* Delete VLAN\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:delete-vlan -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:delete-vlan -d "{"input":{"node-id":158969157063648, "vlan-id":123}}" \r
-----\r
-+\r
-* Add VLAN and set ports\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:add-vlan-and-set-ports -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "vlan-name":'<vlan-name>', "tagged-port-list":'<tagged-ports-separated-by-comma>', "untagged-port-list":'<untagged-ports-separated-by-comma>'}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:add-vlan-and-set-ports -d "{"input":{"node-id":158969157063648, "vlan-id":123, "vlan-name":'v123', "tagged-port-list":'1,2,3', "untagged-port-list":'4,5,6'}}" \r
-----\r
-+\r
-* Set VLAN ports\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:set-vlan-ports -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "tagged-port-list":'<tagged-ports-separated-by-comma>', "untagged-port-list":'<untagged-ports-separated-by-comma>'}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:set-vlan-ports -d "{"input":{"node-id":"158969157063648", "vlan-id":"123", "tagged-port-list":'4,5', "untagged-port-list":'2,3'}}"\r
-----\r
-\r
-===== ACL configuration\r
-\r
-SNMP4SDN supports to add flow on ACL table via REST API. However, it is so far only implemented for the D-Link DGS-3120 switch.\r
-\r
-ACL configuration via CLI is vendor-specific, and SNMP4SDN will support configuration with vendor-specific CLI in future release.\r
-\r
-To do ACL configuration using the REST APIs, use commands like the following:\r
-\r
-* Clear ACL table\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:clear-acl-table -d "{"input":{"nodeId":<switch-mac-address-in-number>}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:clear-acl-table -d "{"input":{"nodeId":158969157063648}}"\r
-----\r
-+\r
-* Create ACL profile (IP layer)\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"acl-layer":'IP',"vlan-mask":<vlan_mask_in_number>,"src-ip-mask":'<src_ip_mask>',"dst-ip-mask":"<destination_ip_mask>"}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":158969157063648,"profile-id":1,"profile-name":'profile_1',"acl-layer":'IP',"vlan-mask":1,"src-ip-mask":'255.255.0.0',"dst-ip-mask":'255.255.255.255'}}"\r
-----\r
-+\r
-* Create ACL profile (MAC layer)\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"acl-layer":'ETHERNET',"vlan-mask":<vlan_mask_in_number>}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":158969157063648,"profile-id":2,"profile-name":'profile_2',"acl-layer":'ETHERNET',"vlan-mask":4095}}"\r
-----\r
-+\r
-* Delete ACL profile\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":158969157063648,"profile-id":1}}"\r
-----\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-name":"<profile_name>"}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":158969157063648,"profile-name":'profile_2'}}"\r
-----\r
-+\r
-* Set ACL rule\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:set-acl-rule -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"rule-id":<rule_id_in_number>,"port-list":[<port_number>,<port_number>,...],"acl-layer":'<acl_layer>',"vlan-id":<vlan_id_in_number>,"src-ip":"<src_ip_address>","dst-ip":'<dst_ip_address>',"acl-action":'<acl_action>'}}" \r
-(<acl_layer>: IP or ETHERNET)\r
-(<acl_action>: PERMIT as permit, DENY as deny)\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:set-acl-rule -d "{input:{"nodeId":158969157063648,"profile-id":1,"profile-name":'profile_1',"rule-id":1,"port-list":[1,2,3],"acl-layer":'IP',"vlan-id":2,"src-ip":'1.1.1.1',"dst-ip":'2.2.2.2',"acl-action":'PERMIT'}}" \r
-----\r
-+\r
-* Delete ACL rule\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:del-acl-rule -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"rule-id":<rule_id_in_number>}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-rule -d "{input:{"nodeId":158969157063648,"profile-id":1,"profile-name":'profile_1',"rule-id":1}}"\r
-----\r
-\r
-==== Special configuration\r
-\r
-SNMP4SDN supports setting the following special configurations via REST API:\r
-\r
-* Set STP port state\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:set-stp-port-state -d "{input:{"node-id":<switch-mac-address-in-number>, "port":<port_number>, enable:<true_or_false>}}" \r
-(true: enable, false: disable)\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:set-stp-port-state -d "{input:{"node-id":158969157063648, "port":2, enable:false}}" \r
-----\r
-+\r
-* Get STP port state\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-stp-port-state -d "{input:{"node-id":<switch-mac-address-in-number>, "port":<port_number>}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-stp-port-state -d "{input:{"node-id":158969157063648, "port":2}}" \r
-----\r
-+\r
-* Get STP port root\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-stp-port-root -d "{input:{"node-id":<switch-mac-address-in-number>, "port":<port_number>}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-stp-port-root -d "{input:{"node-id":158969157063648, "port":2}}" \r
-----\r
-+\r
-* Enable STP\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:enable-stp -d "{input:{"node-id":<switch-mac-address-in-number>}}" \r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:enable-stp -d "{input:{"node-id":158969157063648}}" \r
-----\r
-+\r
-* Disable STP\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:disable-stp -d "{input:{"node-id":<switch-mac-address-in-number>}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:disable-stp -d "{input:{"node-id":158969157063648}}"\r
-----\r
-+\r
-* Get ARP table\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-arp-table -d "{input:{"node-id":<switch-mac-address-in-number>}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-arp-table -d "{input:{"node-id":158969157063648}}"\r
-----\r
-+\r
-* Set ARP entry\r
-+\r
-(Notice to give IP address with subnet prefix)\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:set-arp-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "ip-address":'<ip_address>', "mac-address":<mac_address_in_number>}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:set-arp-entry -d "{input:{"node-id":158969157063648, "ip-address":'10.217.9.9', "mac-address":1}}"\r
-----\r
-+\r
-* Get ARP entry\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-arp-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "ip-address":'<ip_address>'}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-arp-entry -d "{input:{"node-id":158969157063648, "ip-address":'10.217.9.9'}}"\r
-----\r
-+\r
-* Delete ARP entry\r
-+\r
-----\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:delete-arp-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "ip-address":'<ip_address>'}}"\r
-\r
-For example:\r
-curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:delete-arp-entry -d "{input:{"node-id":158969157063648, "ip-address":'10.217.9.9'}}"\r
-----\r
-\r
-==== Using Postman to invoke REST API\r
-Besides using the curl tool to invoke REST API, like the examples aforementioned, one can also use GUI tool like Postman for better data display.\r
-\r
-* Install Postman: \r
-https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Install Postman in the Chrome browser]\r
-+\r
-* In the chrome browser bar enter \r
-+\r
-----\r
-chrome://apps/\r
-----\r
-+\r
-* Click on Postman.\r
-\r
-===== Example: Get VLAN table using Postman\r
-\r
-As the screenshot shown below, one needs to fill in required fields.\r
-----\r
-URL:\r
-http://<controller_ip_address>:8181/restconf/operations/vlan:get-vlan-table\r
-\r
-Accept header:\r
-application/json\r
-\r
-Content-type:\r
-application/json\r
-\r
-Body:\r
-{input:{"node-id":<node_id>}}\r
-for example:\r
-{input:{"node-id":158969157063648}}\r
-----\r
-\r
-.Example: Get VLAN table using Postman\r
-image::snmp4sdn_getvlantable_postman.jpg["Example: Get VLAN table using Postman",width=500]\r
-\r
-=== Multi-vendor support\r
-\r
-So far the supported vendor-specific configurations:\r
-\r
-* Add VLAN and set ports\r
-* (More functions are TBD)\r
-\r
-The SNMP4SDN Plugin would examine whether the configuration is described in the vendor-specific configuration file. If yes, the configuration description would be adopted, otherwise just use the default configuration. For example, adding VLAN and setting the ports is supported via SNMP standard MIB. However we found some special cases, for example, certain Accton switch requires to add VLAN first and then allows to set the ports. So one may describe this in the vendor-specific configuration file.\r
-\r
-A vendor-specific configuration file sample is https://wiki.opendaylight.org/view/SNMP4SDN:snmp4sdn_VendorSpecificSwitchConfig_file[here], and we suggest to save it as '/etc/snmp4sdn_VendorSpecificSwitchConfig.xml' so that SNMP4SDN Plugin can automatically load it.\r
-\r
-=== Help\r
-* https://wiki.opendaylight.org/view/SNMP4SDN:Main[SNMP4SDN Wiki]\r
-* SNMP4SDN Mailing Lists: (https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-users[user], https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-dev[developer])\r
-* Latest https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Troubleshooting[troubleshooting] in Wiki\r
\r
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/snmp4sdn-user-guide.html\r
== SXP User Guide
-=== Overview
-SXP (Source-Group Tag eXchange Protocol) project is an effort to enhance OpenDaylight platform with IP-SGT (IP Address to Source Group Tag) bindings that can be learned from connected SXP-aware network nodes. The current implementation supports SXP protocol version 4 according to the Smith, Kandula - SXP https://tools.ietf.org/html/draft-smith-kandula-sxp-04[IETF draft] and grouping of peers and creating filters based on ACL/Prefix-list syntax for filtering outbound and inbound IP-SGT bindings. All protocol legacy versions 1-3 are supported as well. Additionally, version 4 adds bidirectional connection type as an extension of a unidirectional one.
-
-=== SXP Architecture
-The SXP Server manages all connected clients in separate threads and a common SXP protocol agreement is used between connected peers. Each SXP network peer is modelled with its pertaining class, e.g., SXP Server represents the SXP Speaker, SXP Listener the Client. The server program creates the ServerSocket object on a specified port and waits until a client starts up and requests connect on the IP address and port of the server. The client program opens a Socket that is connected to the server running on the specified host IP address and port.
-
-The SXP Listener maintains connection with its speaker peer. From an opened channel pipeline, all incoming SXP messages are processed by various handlers. Message must be decoded, parsed and validated.
-
-The SXP Speaker is a counterpart to the SXP Listener. It maintains a connection with its listener peer and sends composed messages.
-
-The SXP Binding Handler extracts the IP-SGT binding from a message and pulls it into the SXP-Database. If an error is detected during the IP-SGT extraction, an appropriate error code and sub-code is selected and an error message is sent back to the connected peer. All transitive messages are routed directly to the output queue of SXP Binding Dispatcher.
-
-The SXP Binding Dispatcher represents a selector that will decides how many data from the SXP-database will be sent and when. It is responsible for message content composition based on maximum message length.
-
-The SXP Binding Filters handles filtering of outgoing and incoming IP-SGT bindings according to BGP filtering using ACL and Prefix List syntax for specifying filter or based on Peer-sequence length.
-
-The SXP Domains feature provides isolation of SXP peers and bindings learned between them, also exchange of Bindings is possible across SXP-Domains by ACL, Prefix List or Peer-Sequence filters
-
-=== Configuring SXP
-The OpenDaylight Karaf distribution comes pre-configured with baseline SXP configuration.
-Configuration of SXP Nodes is also possible via NETCONF.
-
-- *22-sxp-controller-one-node.xml* (defines the basic parameters)
-
-=== Administering or Managing SXP
-By RPC (response is XML document containing requested data or operation status):
-
-* Get Connections
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:get-connections
-[source,xml]
-----
-<input xmlns:xsi="urn:opendaylight:sxp:controller">
- <domain-name>global</domain-name>
- <requested-node>0.0.0.100</requested-node>
-</input>
-----
-* Add Connection
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:add-connection
-[source,xml]
-----
-<input xmlns:xsi="urn:opendaylight:sxp:controller">
- <requested-node>0.0.0.100</requested-node>
- <domain-name>global</domain-name>
- <connections>
- <connection>
- <peer-address>172.20.161.50</peer-address>
- <tcp-port>64999</tcp-port>
- <!-- Password setup: default | none leave empty -->
- <password>default</password>
- <!-- Mode: speaker/listener/both -->
- <mode>speaker</mode>
- <version>version4</version>
- <description>Connection to ASR1K</description>
- <!-- Timers setup: 0 to disable specific timer usability, the default value will be used -->
- <connection-timers>
- <!-- Speaker -->
- <hold-time-min-acceptable>45</hold-time-min-acceptable>
- <keep-alive-time>30</keep-alive-time>
- </connection-timers>
- </connection>
- <connection>
- <peer-address>172.20.161.178</peer-address>
- <tcp-port>64999</tcp-port>
- <!-- Password setup: default | none leave empty-->
- <password>default</password>
- <!-- Mode: speaker/listener/both -->
- <mode>listener</mode>
- <version>version4</version>
- <description>Connection to ISR</description>
- <!-- Timers setup: 0 to disable specific timer usability, the default value will be used -->
- <connection-timers>
- <!-- Listener -->
- <reconciliation-time>120</reconciliation-time>
- <hold-time>90</hold-time>
- <hold-time-min>90</hold-time-min>
- <hold-time-max>180</hold-time-max>
- </connection-timers>
- </connection>
- </connections>
-</input>
-----
-
-* Delete Connection
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-connection
-[source,xml]
-----
-<input xmlns:xsi="urn:opendaylight:sxp:controller">
- <requested-node>0.0.0.100</requested-node>
- <domain-name>global</domain-name>
- <peer-address>172.20.161.50</peer-address>
-</input>
-----
-* Add Binding Entry
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:add-entry
-[source,xml]
-----
-<input xmlns:xsi="urn:opendaylight:sxp:controller">
- <requested-node>0.0.0.100</requested-node>
- <domain-name>global</domain-name>
- <ip-prefix>192.168.2.1/32</ip-prefix>
- <sgt>20</sgt >
-</input>
-----
-* Update Binding Entry
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:update-entry
-[source,xml]
-----
-<input xmlns:xsi="urn:opendaylight:sxp:controller">
- <requested-node>0.0.0.100</requested-node>
- <domain-name>global</domain-name>
- <original-binding>
- <ip-prefix>192.168.2.1/32</ip-prefix>
- <sgt>20</sgt>
- </original-binding>
- <new-binding>
- <ip-prefix>192.168.3.1/32</ip-prefix>
- <sgt>30</sgt>
- </new-binding>
-</input>
-----
-* Delete Binding Entry
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-entry
-[source,xml]
-----
-<input xmlns:xsi="urn:opendaylight:sxp:controller">
- <requested-node>0.0.0.100</requested-node>
- <domain-name>global</domain-name>
- <ip-prefix>192.168.3.1/32</ip-prefix>
- <sgt>30</sgt >
-</input>
-----
-* Get Node Bindings
-+
-This RPC gets particular device bindings. An SXP-aware node is identified with a unique Node-ID. If a user requests bindings
-for a Speaker 20.0.0.2, the RPC will search for an appropriate path, which contains 20.0.0.2 Node-ID, within locally learnt
-SXP data in the SXP database and replies with associated bindings.
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:get-node-bindings
-[source,xml]
-----
-<input xmlns:xsi="urn:opendaylight:sxp:controller">
- <requested-node>20.0.0.2</requested-node>
- <bindings-range>all</bindings-range>
- <domain-name>global</domain-name>
-</input>
-----
-* Get Binding SGTs
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:get-binding-sgts
-[source,xml]
-----
-<input xmlns:xsi="urn:opendaylight:sxp:controller">
- <requested-node>0.0.0.100</requested-node>
- <domain-name>global</domain-name>
- <ip-prefix>192.168.12.2/32</ip-prefix>
-</input>
-----
-* Add PeerGroup with or without filters to node.
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:add-peer-group
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <requested-node>127.0.0.1</requested-node>
- <sxp-peer-group>
- <name>TEST</name>
- <sxp-peers>
- </sxp-peers>
- <sxp-filter>
- <filter-type>outbound</filter-type>
- <acl-entry>
- <entry-type>deny</entry-type>
- <entry-seq>1</entry-seq>
- <sgt-start>1</sgt-start>
- <sgt-end>100</sgt-end>
- </acl-entry>
- <acl-entry>
- <entry-type>permit</entry-type>
- <entry-seq>45</entry-seq>
- <matches>1</matches>
- <matches>3</matches>
- <matches>5</matches>
- </acl-entry>
- </sxp-filter>
- </sxp-peer-group>
-</input>
-----
-* Delete PeerGroup with peer-group-name from node request-node.
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-peer-group
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <requested-node>127.0.0.1</requested-node>
- <peer-group-name>TEST</peer-group-name>
-</input>
-----
-* Get PeerGroup with peer-group-name from node request-node.
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:get-peer-group
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <requested-node>127.0.0.1</requested-node>
- <peer-group-name>TEST</peer-group-name>
-</input>
-----
-* Add Filter to peer group on node request-node.
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:add-filter
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <requested-node>127.0.0.1</requested-node>
- <peer-group-name>TEST</peer-group-name>
- <sxp-filter>
- <filter-type>outbound</filter-type>
- <acl-entry>
- <entry-type>deny</entry-type>
- <entry-seq>1</entry-seq>
- <sgt-start>1</sgt-start>
- <sgt-end>100</sgt-end>
- </acl-entry>
- <acl-entry>
- <entry-type>permit</entry-type>
- <entry-seq>45</entry-seq>
- <matches>1</matches>
- <matches>3</matches>
- <matches>5</matches>
- </acl-entry>
- </sxp-filter>
-</input>
-----
-* Delete Filter from peer group on node request-node.
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-filter
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <requested-node>127.0.0.1</requested-node>
- <peer-group-name>TEST</peer-group-name>
- <filter-type>outbound</filter-type>
-</input>
-----
-* Update Filter of the same type in peer group on node request-node.
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:update-filter
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <requested-node>127.0.0.1</requested-node>
- <peer-group-name>TEST</peer-group-name>
- <sxp-filter>
- <filter-type>outbound</filter-type>
- <acl-entry>
- <entry-type>deny</entry-type>
- <entry-seq>1</entry-seq>
- <sgt-start>1</sgt-start>
- <sgt-end>100</sgt-end>
- </acl-entry>
- <acl-entry>
- <entry-type>permit</entry-type>
- <entry-seq>45</entry-seq>
- <matches>1</matches>
- <matches>3</matches>
- <matches>5</matches>
- </acl-entry>
- </sxp-filter>
-</input>
-----
-* Add new SXP aware Node
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:add-node
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <node-id>1.1.1.1</node-id>
- <source-ip>0.0.0.0</source-ip>
- <timers>
- <retry-open-time>5</retry-open-time>
- <hold-time-min-acceptable>120</hold-time-min-acceptable>
- <delete-hold-down-time>120</delete-hold-down-time>
- <hold-time-min>90</hold-time-min>
- <reconciliation-time>120</reconciliation-time>
- <hold-time>90</hold-time>
- <hold-time-max>180</hold-time-max>
- <keep-alive-time>30</keep-alive-time>
- </timers>
- <mapping-expanded>150</mapping-expanded>
- <security>
- <password>password</password>
- </security>
- <tcp-port>64999</tcp-port>
- <version>version4</version>
- <description>ODL SXP Controller</description>
- <master-database></master-database>
-</input>
-----
-* Delete SXP aware node
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-node
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <node-id>1.1.1.1</node-id>
-</input>
-----
-* Add SXP Domain on node request-node.
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:add-domain
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <node-id>1.1.1.1</node-id>
- <domain-name>global</domain-name>
-</input>
-----
-* Delete SXP Domain on node request-node.
-POST http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-domain
-[source,xml]
-----
-<input xmlns="urn:opendaylight:sxp:controller">
- <node-id>1.1.1.1</node-id>
- <domain-name>global</domain-name>
-</input>
-----
-
-==== Use cases for SXP
-Cisco has a wide installed base of network devices supporting SXP. By including SXP in OpenDaylight, the binding of policy groups to IP addresses can be made available for possible further processing to a wide range of devices, and applications running on OpenDaylight. The range of applications that would be enabled is extensive. Here are just a few of them:
-
-OpenDaylight based applications can take advantage of the IP-SGT binding information. For example, access control can be defined by an operator in terms of policy groups, while OpenDaylight can configure access control lists on network elements using IP addresses, e.g., existing technology.
-
-Interoperability between different vendors. Vendors have different policy systems. Knowing the IP-SGT binding for Cisco makes it possible to maintain policy groups between Cisco and other vendors.
-
-OpenDaylight can aggregate the binding information from many devices and communicate it to a network element. For example, a firewall can use the IP-SGT binding information to know how to handle IPs based on the group-based ACLs it has set. But to do this with SXP alone, the firewall has to maintain a large number of network connections to get the binding information. This incurs heavy overhead costs to maintain all of the SXP peering and protocol information. OpenDaylight can aggregate the IP-group information so that the firewall need only connect to OpenDaylight. By moving the information flow outside of the network elements to a centralized position, we reduce the overhead of the CPU consumption on the enforcement element. This is a huge savings - it allows the enforcement point to only have to make one connection rather than thousands, so it can concentrate on its primary job of forwarding and enforcing.
-
-OpenDaylight can relay the binding information from one network element to others. Changes in group membership can be propagated more readily through a centralized model. For example, in a security application a particular host (e.g., user or IP Address) may be found to be acting suspiciously or violating established security policies. The defined response is to put the host into a different source group for remediation actions such as a lower quality of service, restricted access to critical servers, or special routing conditions to ensure deeper security enforcement (e.g., redirecting the host’s traffic through an IPS with very restrictive policies). Updated group membership for this host needs to be communicated to multiple network elements as soon as possible; a very efficient and effective method of propagation can be performed using OpenDaylight as a centralized point for relaying the information.
-
-OpenDayLight can create filters for exporting and receiving IP-SGT bindings used on specific peer groups, thus can provide more complex maintaining of policy groups.
-
-Although the IP-SGT binding is only one specific piece of information, and although SXP is implemented widely in a single vendor’s equipment, bringing the ability of OpenDaylight to process and distribute the bindings, is a very specific immediate useful implementation of policy groups. It would go a long way to develop both the usefulness of OpenDaylight and of policy groups.
-
-
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/sxp-user-guide.html
== TSDR User Guide
-This document describes how to use HSQLDB, HBase, and Cassandra data stores to
-capture time series data using Time Series Data Repository (TSDR) features
-in OpenDaylight. This document contains configuration, administration, management,
-usage, and troubleshooting sections for the features.
-=== Overview
-The Time Series Data Repository (TSDR) project in OpenDaylight (ODL) creates a
-framework for collecting, storing, querying, and maintaining time series data.
-TSDR provides the framework for plugging in proper data collectors to collect
-various time series data and store the data into
-TSDR Data Stores. With a common data model and generic TSDR data persistence
-APIs, the user can choose various data stores to be plugged into the TSDR
-persistence framework. Currently, three types of data stores are supported:
-HSQLDB relational database, HBase NoSQL database, and Cassandra NoSQL database.
-
-With the capabilities of data collection, storage, query, aggregation, and
-purging provided by TSDR, network administrators can leverage various data
-driven appliations built on top of TSDR for security risk detection,
-performance analysis, operational configuration optimization, traffic
-engineering, and network analytics with automated intelligence.
-
-
-=== TSDR Architecture
-TSDR has the following major components:
-
-* Data Collection Service
-* Data Storage Service
-* TSDR Persistence Layer with data stores as plugins
-* TSDR Data Stores
-* Data Query Service
-* Grafana integration for time series data visualization
-* Data Aggregation Service
-* Data Purging Service
-
-The Data Collection Service handles the collection of time series data into TSDR and
-hands it over to the Data Storage Service. The Data Storage Service stores the data
-into TSDR through the TSDR Persistence Layer. The TSDR Persistence Layer provides generic
-Service APIs allowing various data stores to be plugged in. The Data Aggregation
-Service aggregates time series fine-grained raw data into course-grained roll-up
-data to control the size of the data. The Data Purging Service periodically purges
-both fine-grained raw data and course-granined aggregated data according to
-user-defined schedules.
-
-We have implemented The Data Collection Service, Data Storage Service, TSDR
-Persistence Layer, TSDR HSQLDB Data Store, TSDR HBase Data Store, and TSDR Cassandra
-Datastore. Among these services and components, time series data is communicated
-using a common TSDR data model, which is designed and implemented for the
-abstraction of time series data commonalities. With these functions, TSDR is
-able to collect the data from the data sources and store them into one of
-the TSDR data stores: HSQLDB Data Store, HBase Data Store or Cassandra Data
-Store. Besides a simple query command from Karaf console to retrieve data from the
-TSDR data stores, we also provided a Data Query Service for the user to use REST API
-to query the data from the data stores. Moreover, the user can use Grafana, which is
-a time series visualization tool to view the data stored in TSDR in various charting
-formats.
-
-=== Configuring TSDR Data Stores
-==== To Configure HSQLDB Data Store
-
-The HSQLDB based storage files get stored automatically in <karaf install folder>/tsdr/
-directory. If you want to change the default storage location, the configuration
-file to change can be found in <karaf install folder>/etc directory. The filename
-is org.ops4j.datasource-metric.cfg. Change the last portion of the url=jdbc:hsqldb:./tsdr/metric
-to point to different directory.
-
-==== To Configure HBase Data Store
-
-After installing HBase Server on the same machine as OpenDaylight, if the user accepts the default configuration of the HBase Data Store, the user can directly proceed with the installation of HBase Data Store from Karaf console.
-
-Optionally, the user can configure TSDR HBase Data Store following HBase Data Store Configuration Procedure.
-
-* HBase Data Store Configuration Steps
-
-** Open the file etc/tsdr-persistence-hbase.peroperties under karaf distribution directory.
-** Edit the following parameters:
-*** HBase server name
-*** HBase server port
-*** HBase client connection pool size
-*** HBase client write buffer size
-
-After the configuration of HBase Data Store is complete, proceed with the installation of HBase Data Store from Karaf console.
-
-* HBase Data Store Installation Steps
-
-** Start Karaf Console
-** Run the following commands from Karaf Console:
-feature:install odl-tsdr-hbase
-
-==== To Configure Cassandra Data Store
-
-Currently, there's no configuration needed for Cassandra Data Store. The user can use Cassandra data store directly after installing the feature from Karaf console.
-
-Additionally separate commands have been implemented to install various data collectors.
-
-=== Administering or Managing TSDR Data Stores
-==== To Administer HSQLDB Data Store
-
-Once the TSDR default datastore feature (odl-tsdr-hsqldb-all) is enabled, the TSDR captured OpenFlow statistics metrics can be accessed from Karaf Console by executing the command
-
- tsdr:list <metric-category> <starttimestamp> <endtimestamp>
-
-wherein
-
-* <metric-category> = any one of the following categories FlowGroupStats, FlowMeterStats, FlowStats, FlowTableStats, PortStats, QueueStats
-* <starttimestamp> = to filter the list of metrics starting this timestamp
-* <endtimestamp> = to filter the list of metrics ending this timestamp
-* <starttimestamp> and <endtimestamp> are optional.
-* Maximum 1000 records will be displayed.
-
-==== To Administer HBase Data Store
-
-* Using Karaf Command to retrieve data from HBase Data Store
-
-The user first need to install hbase data store from karaf console:
-
-feature:install odl-tsdr-hbase
-
-The user can retrieve the data from HBase data store using the following commands from Karaf console:
-
- tsdr:list
- tsdr:list <CategoryName> <StartTime> <EndTime>
-
-Typing tab will get the context prompt of the arguments when typeing the command in Karaf console.
-
-==== To Administer Cassandra Data Store
-
-The user first needs to install Cassandra data store from Karaf console:
-
- feature:install odl-tsdr-cassandra
-
-Then the user can retrieve the data from Cassandra data store using the following commands from Karaf console:
-
- tsdr:list
- tsdr:list <CategoryName> <StartTime> <EndTime>
-
-Typing tab will get the context prompt of the arguments when typeing the command in Karaf console.
-
-=== Installing TSDR Data Collectors
-
-When the user uses HSQLDB data store and installed "odl-tsdr-hsqldb-all" feature from Karaf console, besides the HSQLDB data store, OpenFlow data collector is also installed with this command. However, if the user needs to use other collectors, such as NetFlow Collector, Syslog Collector, SNMP Collector, and Controller Metrics Collector, the user needs to install them with separate commands. If the user uses HBase or Cassandra data store, no collectors will be installed when the data store is installed. Instead, the user needs to install each collector separately using feature install command from Karaf console.
-
-The following is the list of supported TSDR data collectors with the associated feature install commands:
-
-* OpenFlow Data Collector
-
- feature:install odl-tsdr-openflow-statistics-collector
-
-* SNMP Data Collector
-
- feature:install odl-tsdr-snmp-data-collector
-
-* NetFlow Data Collector
-
- feature:install odl-tsdr-netflow-statistics-collector
-
-* sFlow Data Collector
- feature:install odl-tsdr-sflow-statistics-colletor
-
-* Syslog Data Collector
-
- feature:install odl-tsdr-syslog-collector
-
-* Controller Metrics Collector
-
- feature:install odl-tsdr-controller-metrics-collector
-
-In order to use controller metrics collector, the user needs to install Sigar library.
-
-The following is the instructions for installing Sigar library on Ubuntu:
-
-*** Install back end library by "sudo apt-get install libhyperic-sigar-java"
-*** Execute "export LD_LIBRARY_PATH=/usr/lib/jni/:/usr/lib:/usr/local/lib" to set the path of the JNI (you can add this to the ".bashrc" in your home directory)
-*** Download the file "sigar-1.6.4.jar". It might be also in your ".m2" directory under "~/.m2/resources/org/fusesource/sigar/1.6.4"
-*** Create the directory "org/fusesource/sigar/1.6.4" under the "system" directory in your controller home directory and place the "sigar-1.6.4.jar" there
-
-=== Configuring TSDR Data Collectors
-
-* SNMP Data Collector Device Credential Configuration
-
-After installing SNMP Data Collector, a configuration file under etc/ directory of ODL distribution is generated: etc/tsdr.snmp.cfg is created.
-
-The following is a sample tsdr.snmp.cfg file:
-
-credentials=[192.168.0.2,public],[192.168.0.3,public]
-
-The above credentials indicate that TSDR SNMP Collector is going to connect to two devices. The IPAddress and Read community string of these two devices are (192.168.0.2, public), and (192.168.0.3) respectively.
-
-The user can make changes to this configuration file any time during runtime. The configuration will be picked up by TSDR in the next cycle of data collection.
-
-==== Polling interval configuration for SNMP Collector and OpenFlow Stats Collector
-
-The default polling interval of SNMP Collector and OpenFlow Stats Collector is 30 seconds and 15 seconds respectively. The user can change the polling interval through restconf APIs at any time. The new polling interval will be picked up by TSDR in the next collection cycle.
-
-* Retrieve Polling Interval API for SNMP Collector
-** URL: http://localhost:8181/restconf/config/tsdr-snmp-data-collector:TSDRSnmpDataCollectorConfig
-** Verb: GET
-
-* Update Polling Interval API for SNMP Collector
-** URL: http://localhost:8181/restconf/operations/tsdr-snmp-data-collector:setPollingInterval
-** Verb: POST
-** Content Type: application/json
-** Input Payload:
-
- {
- "input": {
- "interval": "15000"
- }
- }
-
-* Retrieve Polling Interval API for OpenFlowStats Collector
-** URL: http://localhost:8181/restconf/config/tsdr-openflow-statistics-collector:TSDROSCConfig
-** Verb: GET
-
-* Update Polling Interval API for OpenFlowStats Collector
-** URL: http://localhost:8181/restconf/operations/tsdr-openflow-statistics-collector:setPollingInterval
-** Verb: POST
-** Content Type: application/json
-** Input Payload:
-
- {
- "input": {
- "interval": "15000"
- }
- }
-
-=== Querying TSDR from REST APIs
-
-TSDR provides two REST APIs for querying data stored in TSDR data stores.
-
-* Query of TSDR Metrics
-** URL: http://localhost:8181/tsdr/metrics/query
-** Verb: GET
-** Parameters:
-*** tsdrkey=[NID=][DC=][MN=][RK=]
-
- The TSDRKey format indicates the NodeID(NID), DataCategory(DC), MetricName(MN), and RecordKey(RK) of the monitored objects.
- For example, the following is a valid tsdrkey:
- [NID=openflow:1][DC=FLOWSTATS][MN=PacketCount][RK=Node:openflow:1,Table:0,Flow:3]
- The following is also a valid tsdrkey:
- tsdrkey=[NID=][DC=FLOWSTATS][MN=][RK=]
- In the case when the sections in the tsdrkey is empty, the query will return all the records in the TSDR data store that matches the filled tsdrkey. In the above example, the query will return all the data in FLOWSTATS data category.
- The query will return only the first 1000 records that match the query criteria.
-
-*** from=<time_in_seconds>
-*** until=<time_in_seconds>
-
-The following is an example curl command for querying metric data from TSDR data store:
-
-curl -G -v -H "Accept: application/json" -H "Content-Type: application/json" "http://localhost:8181/tsdr/metrics/query" --data-urlencode "tsdrkey=[NID=][DC=FLOWSTATS][MN=][RK=]" --data-urlencode "from=0" --data-urlencode "until=240000000000"|more
-
-* Query of TSDR Log type of data
-** URL:http://localhost:8181/tsdr/logs/query
-** Verb: GET
-** Parameters:
-*** tsdrkey=tsdrkey=[NID=][DC=][RK=]
-
- The TSDRKey format indicates the NodeID(NID), DataCategory(DC), and RecordKey(RK) of the monitored objects.
- For example, the following is a valid tsdrkey:
- [NID=openflow:1][DC=NETFLOW][RK]
- The query will return only the first 1000 records that match the query criteria.
-
-*** from=<time_in_seconds>
-*** until=<time_in_seconds>
-
-The following is an example curl command for querying log type of data from TSDR data store:
-
-curl -G -v -H "Accept: application/json" -H "Content-Type: application/json" "http://localhost:8181/tsdr/logs/query" --data-urlencode "tsdrkey=[NID=][DC=NETFLOW][RK=]" --data-urlencode "from=0" --data-urlencode "until=240000000000"|more
-
-=== Grafana integration with TSDR
-
-TSDR provides northbound integration with Grafana time series data visualization tool. All the metric type of data stored in TSDR data store can be visualized using Grafana.
-
-For the detailed instruction about how to install and configure Grafana to work with TSDR, please refer to the following link:
-
-https://wiki.opendaylight.org/view/Grafana_Integration_with_TSDR_Step-by-Step
-
-=== Purging Service configuration
-
-After the data stores are installed from Karaf console, the purging service will be installed as well. A configuration file called tsdr.data.purge.cfg will be generated under etc/ directory of ODL distribution.
-
-The following is the sample default content of the tsdr.data.purge.cfg file:
-
-host=127.0.0.1
-data_purge_enabled=true
-data_purge_time=23:59:59
-data_purge_interval_in_minutes=1440
-retention_time_in_hours=168
-
-The host indicates the IPAddress of the data store. In the case when the data store is together with ODL controller, 127.0.0.1 should be the right value for the host IP. The other attributes are self-explained. The user can change those attributes at any time. The configuration change will be picked up right away by TSDR Purging service at runtime.
-
-=== How to use TSDR to collect, store, and view OpenFlow Interface Statistics
-
-==== Overview
-This tutorial describes an example of using TSDR to collect, store, and view one type of time series data in OpenDaylight environment.
-
-
-==== Prerequisites
-You would need to have the following as prerequisits:
-
-* One or multiple OpenFlow enabled switches. Alternatively, you can use mininet to simulate such a switch.
-* Successfully installed OpenDaylight Controller.
-* Successfully installed HBase Data Store following TSDR HBase Data Store Installation Guide.
-* Connect the OpenFlow enabled switch(es) to OpenDaylight Controller.
-
-==== Target Environment
-HBase data store is only supported in Linux operation system.
-
-==== Instructions
-
-* Start OpenDaylight.
-
-* Connect OpenFlow enabled switch(es) to the controller.
-
-** If using mininet, run the following commands from mininet command line:
-
-*** mn --topo single,3 --controller 'remote,ip=172.17.252.210,port=6653' --switch ovsk,protocols=OpenFlow13
-
-
-* Install tsdr hbase feature from Karaf:
-
-** feature:install odl-tsdr-hbase
-
-* Install OpenFlow Statistics Collector from Karaf:
-
-** feature:install odl-tsdr-openflow-statistics-collector
-
-* run the following command from Karaf console:
-
-** tsdr:list PORTSTATS
-
-You should be able to see the interface statistics of the switch(es) from the HBase Data Store. If there are too many rows, you can use "tsdr:list InterfaceStats|more" to view it page by page.
-
-By tabbing after "tsdr:list", you will see all the supported data categories. For example, "tsdr:list FlowStats" will output the Flow statistics data collected from the switch(es).
-
-=== Troubleshooting
-==== Karaf logs
-
-All TSDR features and components write logging information including information messages, warnings, errors and debug messages into karaf.log.
-
-==== HBase and Cassandra logs
-
-For HBase and Cassandra data stores, the database level logs are written into HBase log and Cassandra logs.
-
-** HBase log
-*** HBase log is under <HBase-installation-directory>/logs/.
-
-** Cassandra log
-*** Cassandra log is under {cassandra.logdir}/system.log. The default {cassandra.logdir} is /var/log/cassandra/.
-
-=== Security
-
-TSDR gets the data from a variety of sources, which can be secured in different ways.
-
-** OpenFlow Security
-*** The OpenFlow data can be configured with Transport Layer Security (TLS) since the OpenFlow Plugin that TSDR depends on provides this security support.
-
-** SNMP Security
-*** The SNMP version3 has security support. However, since ODL SNMP Plugin that TSDR depends on does not support version 3, we (TSDR) will not have security support at this moment.
-
-** NetFlow Security
-*** NetFlow, which cannot be configured with security so we recommend making sure it flows only over a secured management network.
-
-** Syslog Security
-*** Syslog, which cannot be configured with security so we recommend making sure it flows only over a secured management network.
-
-=== Support multiple data stores simultaneously at runtime
-
-TSDR supports running multiple data stores simultaneously at runtim. For example, it is possible to configure TSDR to push log type of data into Cassandra data store, while pushing metrics type of data into HBase.
-
-When you install one TSDR data store from karaf console, such as using feature:install odl-tsdr-hsqldb, a properties file will be generated under <Karaf-distribution-directory>/etc/. For example, when you install hsqldb, a file called tsdr-persistence-hsqldb.properties is generated under that directory.
-
-By default, all the types of data are supported in the data store. For example, the default content of tsdr-persistence-hsqldb.properties is as follows:
-
- metric-persistency=true
- log-persistency=true
- binary-persistency=true
-
-When the user would like to use different data stores to support different types of data, he/she could enable or disable a particular type of data persistence in the data stores by configuring the properties file accordingly.
-
-For example, if the user would like to store the log type of data in HBase, and store the metric and binary type of data in Cassandra, he/she needs to install both hbase and cassandra data stores from Karaf console. Then the user needs to modify the properties file under <Karaf-distribution-directory>/etc as follows:
-
-* tsdr-persistence-hbase.properties
-
- metric-persistency=false
- log-persistency=true
- binary-persistency=true
-
-
-* tsdr-persistence-cassandra.properties
-
- metric-psersistency=true
- log-persistency=false
- binary-persistency=false
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/tsdr-user-guide.html
== TTP CLI Tools User Guide
-=== Overview
-Table Type Patterns are a specification developed by the
-https://www.opennetworking.org/[Open Networking Foundation] to enable
-the description and negotiation of subsets of the OpenFlow protocol.
-This is particularly useful for hardware switches that support OpenFlow
-as it enables the to describe what features they do (and thus also what
-features they do not) support. More details can be found in the full
-specification listed on the
-https://www.opennetworking.org/sdn-resources/onf-specifications/openflow[OpenFlow
-specifications page].
-
-=== TTP CLI Tools Architecture
-The TTP CLI Tools use the TTP Model and the YANG Tools/RESTCONF codecs
-to translate between the Data Transfer Objects (DTOs) and JSON/XML.
-
-// === Configuring <feature>
-//
-// Describe how to configure the feature or the project after installation.
-// Configuration information could include day-one activities for a project
-// such as configuring users, configuring clients/servers and so on.
-//
-// === Administering or Managing <feature>
-// Include related command reference or operations that you could perform
-// using the feature. For example viewing network statistics, monitoring
-// the network, generating reports, and so on.
-//
-// NOTE: Ensure that you create a step procedure whenever required and
-// avoid concepts.
-//
-// For example:
-//
-// .To configure L2switch components perform the following steps.
-// . Step 1:
-// . Step 2:
-// . Step 3:
-
-// === Using the CLI Tools
-//
-// TODO: provide a few examples of using the CLI tools.
-
-// <optional>
-// If there is only one tutorial, you skip the "Tutorials" section and
-// instead just lead with the single tutorial's name.
-//
-// ==== <Tutorial Name>
-// Ensure that the title starts with a gerund. For example using,
-// monitoring, creating, and so on.
-//
-// ===== Overview
-// An overview of the use case.
-//
-// ===== Prerequisites
-// Provide any prerequisite information, assumed knowledge, or environment
-// required to execute the use case.
-//
-// ===== Target Environment
-// Include any topology requirement for the use case. Ideally, provide
-// visual (abstract) layout of network diagrams and any other useful visual
-// aides.
-//
-// ===== Instructions
-// Use case could be a set of configuration procedures. Including
-// screenshots to help demonstrate what is happening is especially useful.
-// Ensure that you specify them separately. For example:
-//
-// . *Setting up the VM*
-// To set up a VM perform the following steps.
-// .. Step 1
-// .. Step 2
-// .. Step 3
-//
-// . *Installing the feature*
-// To install the feature perform the following steps.
-// .. Step 1
-// .. Step 2
-// .. Step 3
-//
-// . *Configuring the environment*
-// To configure the system perform the following steps.
-// .. Step 1
-// .. Step 2
-// .. Step 3
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/ttp-cli-tools-user-guide.html
== UNI Manager Plug In Project
-=== Overview
-The version of the UNI Manager (UNIMgr) plug-in included in OpenDaylight
-Beryllium release is experimental, serving as a proof-of-concept (PoC) for using
-features of OpenDaylight to provision networked elements with attributes
-satisfying Metro Ethernet Forum (MEF) requirements for delivery of Carrier
-Ethernet service. This initial version of UNIMgr does not enable the full set
-of MEF-defined functionality for Carrier Ethernet service. UNI Manager adheres
-to a minimum set of functionality defined by MEF 7.2 and 10.2 specifications.
-
-UNIMgr receives a request from applications to create an Ethernet Private Line
-(EPL) private Ethernet connection between two endpoints on the network. The
-request must include the IP addresses of the endpoints and a class of service
-identifier.
-
-UNI Manager plug-in translates the request for EPL service into (a) configuring
-two instances of Open vSwitch (OVS), each instance running in one of the
-UNI endpoints, with two ports and a bridge between the ports, and (b) creating a
-GRE tunnel to provide a private connection between the endpoints. This initial
-version of UNIMgr uses only OVSDB on its southbound interface to send
-configuration commands.
-
-UNIMgr also accepts a bits per second datarate parameter, which is translated
-to an OVSDB command to limit the rate at which the OVS instances will forward
-data traffic.
-
-The YANG module used to create the UNIMgr plug-in models MEF-defined UNI and
-Ethernet Virtual Connection (EVC) attributes but does not include the full set
-of UNI and EVC attributes. And of the attributes modeled in the YANG module
-only a subset of them are implemented in the UNIMgr listener code translating
-the Operational data tree to OVSDB commands. The YANG module used to develop
-the PoC UNIMgr plug-in is cl-unimgr-mef.yang. A copy of this module is
-available in the odl-unimgr-api bundle of the UNIMgr project.
-
-Limitations of the PoC version of UNI Manager in OpenDaylight Beryllium include
-those listed below:
-* Uses only OVSDB southbound interface of OpenDaylight
-* Only uses UNI ID, IP Address, and speed UNI attributes
-* Only uses a subset of EVC per UNI attributes
-* Does not use MEF Class of Service or Bandwidth Profile attributes
-* Configures only Open vSwitch network elements
-
-Opportunities for evolution of the UNI Manager plug in include using complete
-MEF Service Layer and MEF Resource Layer YANG models and supporting other
-OpenDaylight southbound protocols like NetConf and OpenFlow.
-
-=== UNI Manager Components
-
-UNI Manager is comprised of the following OpenDaylight Karaf features:
-
-[width="60%",frame="topbot"]
-|======================
-|odl-unimgr-api | OpenDaylight :: UniMgr :: api
-|odl-unimgr | OpenDaylight :: UniMgr
-|odl-unimgr-console | OpenDaylight :: UniMgr :: CLI
-|odl-unimgr-rest | OpenDaylight :: UniMgr :: REST
-|odl-unimgr-ui | OpenDaylight :: UniMgr :: UI
-|======================
-
-=== Installing UNI Manager Plug-in
-
-After launching OpenDaylight install the feature for the UNI Manager plug-in.
-From the karaf command prompt execute the following command to install
-the UNI Manager plug-in:
-
- $ feature:install odl-manager-ui
-
-=== Explore and exercise the UNI Manager REST API
-
-To see the UNI Manager APIs, browse to this URL:
-http://localhost:8181/apidoc/explorer/index.html
-
-Replace localhost with the IP address or hostname where OpenDaylight is
-running if you are not running OpenDaylight locally on your machine.
-
-See also the UNI Manager Developer's Guide for a full list and description of
-UNI Manager POSTMAN calls.
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/uni-manager-plug-in-project.html
== L3VPN Service: User Guide
-=== Overview
-L3VPN Service in OpenDaylight provides a framework to create L3VPN based on BGP-MP. It also helps to create Network Virtualization for DC Cloud environment.
-
-=== Modules & Interfaces
-L3VPN service can be realized using the following modules -
-
-==== VPN Service Modules
-. *VPN Manager* : Creates and manages VPNs and VPN Interfaces
-. *BGP Manager* : Configures BGP routing stack and provides interface to routing services
-. *FIB Manager* : Provides interface to FIB, creates and manages forwarding rules in Dataplane
-. *Nexthop Manager* : Creates and manages nexthop egress pointer, creates egress rules in Dataplane
-. *Interface Manager* : Creates and manages different type of network interfaces, e.g., VLAN, l3tunnel etc.,
-. *Id Manager* : Provides cluster-wide unique ID for a given key. Used by different modules to get unique IDs for different entities.
-. *MD-SAL Util* : Provides interface to MD-SAL. Used by service modules to access MD-SAL Datastore and services.
-
-All the above modules can function independently and can be utilized by other services as well.
-
-==== Configuration Interfaces
-The following modules expose configuration interfaces through which user can configure L3VPN Service.
-
-. BGP Manager
-. VPN Manager
-. Interface Manager
-. FIB Manager
-
-===== Configuration Interface Details
-
-.BGP Manager Interface
-. Data Node Path : _/config/bgp:bgp-router/_
-.. Fields :
-... local-as-identifier
-... local-as-number
-.. REST Methods : GET, PUT, DELETE, POST
-. Data Node Path : _/config/bgp:bgp-neighbors/_
-.. Fields :
-... List of bgp-neighbor
-.. REST Methods : GET, PUT, DELETE, POST
-. Data Node Path : _/config/bgp:bgp-neighbors/bgp-neighbor/`{as-number}`/_
-.. Fields :
-... as-number
-... ip-address
-.. REST Methods : GET, PUT, DELETE, POST
-
-.VPN Manager Interface
-. Data Node Path : _/config/l3vpn:vpn-instances/_
-.. Fields :
-... List of vpn-instance
-.. REST Methods : GET, PUT, DELETE, POST
-. Data Node Path : _/config/l3vpn:vpn-interfaces/vpn-instance_
-.. Fields :
-... name
-... route-distinguisher
-... import-route-policy
-... export-route-policy
-.. REST Methods : GET, PUT, DELETE, POST
-. Data Node Path : _/config/l3vpn:vpn-interfaces/_
-.. Fields :
-... List of vpn-interface
-.. REST Methods : GET, PUT, DELETE, POST
-. Data Node Path : _/config/l3vpn:vpn-interfaces/vpn-interface_
-.. Fields :
-... name
-... vpn-instance-name
-.. REST Methods : GET, PUT, DELETE, POST
-. Data Node Path : _/config/l3vpn:vpn-interfaces/vpn-interface/`{name}`/adjacency_
-.. Fields :
-... ip-address
-... mac-address
-.. REST Methods : GET, PUT, DELETE, POST
-
-.Interface Manager Interface
-. Data Node Path : _/config/if:interfaces/interface_
-.. Fields :
-... name
-... type
-... enabled
-... of-port-id
-... tenant-id
-... base-interface
-.. type specific fields
-... when type = _l2vlan_
-.... vlan-id
-... when type = _stacked_vlan_
-.... stacked-vlan-id
-... when type = _l3tunnel_
-.... tunnel-type
-.... local-ip
-.... remote-ip
-.... gateway-ip
-... when type = _mpls_
-.... list labelStack
-.... num-labels
-.. REST Methods : GET, PUT, DELETE, POST
-
-.FIB Manager Interface
-. Data Node Path : _/config/odl-fib:fibEntries/vrfTables_
-.. Fields :
-... List of vrfTables
-.. REST Methods : GET, PUT, DELETE, POST
-. Data Node Path : _/config/odl-fib:fibEntries/vrfTables/`{routeDistinguisher}`/_
-.. Fields :
-... route-distinguisher
-... list vrfEntries
-.... destPrefix
-.... label
-.... nexthopAddress
-.. REST Methods : GET, PUT, DELETE, POST
-. Data Node Path : _/config/odl-fib:fibEntries/ipv4Table_
-.. Fields :
-... list ipv4Entry
-.... destPrefix
-.... nexthopAddress
-.. REST Methods : GET, PUT, DELETE, POST
-
-
-=== Provisioning Sequence & Sample Configurations
-
-[[install]]
-==== Installation
-1. Edit 'etc/custom.properties' and set the following property:
-'vpnservice.bgpspeaker.host.name = <bgpserver-ip>'
-'<bgpserver-ip>' here refers to the IP address of the host where BGP is running.
-
-2. Run ODL and install VPN Service
-'feature:install odl-vpnservice-core'
-
-Use REST interface to configure L3VPN service
-
-[[prer]]
-==== Pre-requisites:
-
-1. BGP stack with VRF support needs to installed and configured
-a. _Configure BGP as specified in Step 1 below._
-
-2. Create pairs of GRE/VxLAN Tunnels (using ovsdb/ovs-vsctl) between each switch and between each switch to the Gateway node
-a. _Create 'l3tunnel' interfaces corresponding to each tunnel in interfaces DS as specified in Step 2 below._
-
-==== Step 1 : Configure BGP
-
-===== 1. Configure BGP Router
-
-*REST API* : _PUT /config/bgp:bgp-router/_
-
-*Sample JSON Data*
-[source,json]
------------------
-{
- "bgp-router": {
- "local-as-identifier": "10.10.10.10",
- "local-as-number": 108
- }
-}
------------------
-
-
-===== 2. Configure BGP Neighbors
-
-*REST API* : _PUT /config/bgp:bgp-neighbors/_
-
-*Sample JSON Data*
-
-[source,json]
------------------
- {
- "bgp-neighbor" : [
- {
- "as-number": 105,
- "ip-address": "169.144.42.168"
- }
- ]
- }
------------------
-
-==== Step 2 : Create Tunnel Interfaces
-Create l3tunnel interfaces corresponding to all GRE/VxLAN tunnels created with ovsdb (<<prer, refer Prerequisites>>). Use following REST Interface -
-
-*REST API* : _PUT /config/if:interfaces/if:interfacce_
-
-*Sample JSON Data*
-
-[source,json]
------------------
-{
- "interface": [
- {
- "name" : "GRE_192.168.57.101_192.168.57.102",
- "type" : "odl-interface:l3tunnel",
- "odl-interface:tunnel-type": "odl-interface:tunnel-type-gre",
- "odl-interface:local-ip" : "192.168.57.101",
- "odl-interface:remote-ip" : "192.168.57.102",
- "odl-interface:portId" : "openflow:1:3",
- "enabled" : "true"
- }
- ]
-}
-
------------------
-
-===== Following is expected as a result of these configurations
-
-1. Unique If-index is generated
-2. 'Interface-state' operational DS is updated
-3. Corresponding Nexthop Group Entry is created
-
-==== Step 3 : OS Create Neutron Ports and attach VMs
-
-At this step user creates VMs.
-
-==== Step 4 : Create VM Interfaces
-Create l2vlan interfaces corresponding to VM created in step 3
-
-*REST API* : _PUT /config/if:interfaces/if:interface_
-
-*Sample JSON Data*
-
-[source,json]
------------------
-{
- "interface": [
- {
- "name" : "dpn1-dp1.2",
- "type" : "l2vlan",
- "odl-interface:of-port-id" : "openflow:1:2",
- "odl-interface:vlan-id" : "1",
- "enabled" : "true"
- }
- ]
-}
-
------------------
-
-==== Step 5: Create VPN Instance
-
-*REST API* : _PUT /config/l3vpn:vpn-instances/l3vpn:vpn-instance/_
-
-*Sample JSON Data*
-
-[source,json]
------------------
-{
- "vpn-instance": [
- {
- "description": "Test VPN Instance 1",
- "vpn-instance-name": "testVpn1",
- "ipv4-family": {
- "route-distinguisher": "4000:1",
- "export-route-policy": "4000:1,5000:1",
- "import-route-policy": "4000:1,5000:1",
- }
- }
- ]
-}
-
------------------
-
-===== Following is expected as a result of these configurations
-
-1. VPN ID is allocated and updated in data-store
-2. Corresponding VRF is created in BGP
-3. If there are vpn-interface configurations for this VPN, corresponding action is taken as defined in step 5
-
-==== Step 5 : Create VPN-Interface and Local Adjacency
-
-_this can be done in two steps as well_
-
-===== 1. Create vpn-interface
-
-*REST API* : _PUT /config/l3vpn:vpn-interfaces/l3vpn:vpn-interface/_
-
-*Sample JSON Data*
-
-[source,json]
------------------
-{
- "vpn-interface": [
- {
- "vpn-instance-name": "testVpn1",
- "name": "dpn1-dp1.2",
- }
- ]
-}
------------------
-
-[NOTE]
-name here is the name of VM interface created in step 3, 4
-
-===== 2. Add Adjacencies on vpn-interafce
-
-*REST API* : _PUT /config/l3vpn:vpn-interfaces/l3vpn:vpn-interface/dpn1-dp1.3/adjacency_
-
-*Sample JSON Data*
-
-[source,json]
------------------
- {
- "adjacency" : [
- {
- "ip-address" : "169.144.42.168",
- "mac-address" : "11:22:33:44:55:66"
- }
- ]
- }
------------------
-
-
-[quote]
-its a list, user can define more than one adjacency on a vpn_interface
-
-Above steps can be carried out in a single step as following
-
-[source,json]
------------------
-{
- "vpn-interface": [
- {
- "vpn-instance-name": "testVpn1",
- "name": "dpn1-dp1.3",
- "odl-l3vpn:adjacency": [
- {
- "odl-l3vpn:mac_address": "11:22:33:44:55:66",
- "odl-l3vpn:ip_address": "11.11.11.2",
- }
- ]
- }
- ]
-}
-
------------------
-
-
-===== Following is expected as a result of these configurations
-
-1. Prefix label is generated and stored in DS
-2. Ingress table is programmed with flow corresponding to interface
-3. Local Egress Group is created
-4. Prefix is added to BGP for advertisement
-5. BGP pushes route update to FIB YANG Interface
-6. FIB Entry flow is added to FIB Table in OF pipeline
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/l3vpn-service_-user-guide.html
== YANG IDE User Guide
-=== Overview
-
-The YANG IDE project provides an Eclipse plugin that is used to create,
-view, and edit Yang model files. It currently supports version 1.0 of
-the Yang specification.
-
-The YANG IDE project uses components from the OpenDaylight project for
-parsing and verifying Yang model files. The "yangtools" parser in
-OpenDaylight is generally used for generating Java code associated
-with Yang models. If you are just using the YANG IDE to view and edit
-Yang models, you do not need to know any more about this.
-
-Although the YANG IDE plugin is used in Eclipse, it is not necessary to
-be familiar with the Java programming language to use it effectively.
-
-The YANG IDE also uses the Maven build tool, but you do not have to be
-a Maven expert to use it, or even know that much about it. Very
-little configuration of Maven files will have to be done by you. In
-fact, about the only thing you will likely ever need to change can be
-done entirely in the Eclipse GUI forms, without even seeing the
-internal structure of the Maven POM file (Project Object Model).
-
-The YANG IDE plugin provides features that are similar to other
-programming language plugins in the Eclipse ecosystem.
-
-For instance, you will find support for the following:
-
-* Immediate "as-you-type" display of syntactic and semantic errors
-* Intelligent completion of language tokens, limited to only choices
-valid in the current scope and namespace
-* Consistent (and customizable) color-coding of syntactic and semantic symbols
-* Provides access to remote Yang models by specifying dependency on
-Maven artifact containing models (or by manual inclusion in project)
-* One-click navigation to referenced symbols in external files
-* Mouse hovers display descriptions of referenced components
-* Tools for refactoring or renaming components respect namespaces
-* Code templates can be entered for common conventions
-
-Forthcoming sections of this manual will step through how to utilize
-these features.
-
-=== Creating a Yang Project
-
-After the plugin is installed, the next thing you have to do is create
-a Yang Project. This is done from the "File" menu, selecting "New",
-and navigating to the "Yang" section and selecting "YANG Project", and
-then clicking "Next" for more items to configure.
-
-Some shortcuts for these steps are the following:
-
-* Typically, the key sequence "Ctrl+n" (press "n" while holding down
-one of the "ctrl" keys) is bound to the "new" function
-* In the "New" wizard dialog, the initial focus is in the filter
-field, where you can enter "yang" to limit the choices to only the
-functions provided by the YANG IDE plugin
-* On the "New" wizard dialog, instead of clicking the "Next" button
-with your mouse, you can press "Alt+n" (you will see a hint for this
-with the "N" being underlined)
-
-==== First Yang Project Wizard Page
-
-After the "Next" button is pressed, it goes to the first wizard page
-that is specific to creating Yang projects. you will see a subtitle on
-this page of "YANG Tools Configuration". In almost all cases, you
-should be able to click "Next" again on this page to go to the next
-wizard page.
-
-However, some information about the fields on this page would be helpful.
-
-You will see the following labeled fields and sections:
-
-===== Yang Files Root Directory
-
-This defaults to "src/main/yang". Except when creating your first
-Yang file, you, you do not even have to know this, as Eclipse presents
-the same interface to view your Yang files no matter what you set
-this to.
-
-===== Source Code Generators
-
-If you do not know what this is, you do not need to know about it. The
-"yangtools" Yang parser from OpenDaylight uses a "code generator"
-component to generate specific kinds of Java classes from the Yang
-models. Again, if you do not need to work with the generated Java
-code, you do not need to change this.
-
-===== Create Example YANG File
-
-This is likely the only field you will ever have any reason to change.
-If this checkbox is set, when the YANG IDE creates the Yang project,
-it will create a sample "acme-system.yang" file which you can view and
-edit to demonstrate the features of the tool to yourself. If you
-do not need this file, then either delete it from the project or
-uncheck the checkbox to prevent its creation.
-
-When done with the fields on this page, click the "Next" button to go
-to the next wizard page.
-
-==== Second Yang Project Wizard Page
-
-This page has a subtitle of "New Maven project". There are several
-fields on this page, but you will only ever have to see and change the
-setting of the first field, the "Create a simple project" checkbox.
-You should always set this ON to avoid the selection of a Maven
-archetype, which is something you do not need to do for creating a
-Yang project.
-
-Click "Next" at the bottom of the page to move to the next wizard page.
-
-==== Third Yang Project Wizard Page
-
-This also has a subtitle of "New Maven project", but with different
-fields to set. You will likely only ever set the first two fields,
-and completely ignore everything else.
-
-The first field is labeled "Group id" in the "Artifact" section. It
-really does not matter what you set this to, but it does have to be set
-to something. For consistency, you might set this to the name or
-nickname of your organization. Otherwise, there are no constraints on
-the value of this field.
-
-The second field is labeled "Artifact id". The value of this field
-will be used as the name of the project you create, so you will have
-to think about what you want the project to be called. Also note that
-this name has to be unique in the Eclipse workspace. You cannot have
-two projects with the same name.
-
-After you have set this field, you will notice that the "Next" button is
-insensitive, but now the "Finish" button is sensitive. You can click
-"Finish" now (or use the keyboard shortcut of "Alt+f"), and the Yang
-IDE will finally create your project.
-
-=== Creating a Yang File
-
-Now that you have created your project, it is time to create your first Yang file.
-
-When you created the Yang project, you might have noticed the other
-option next to "YANG Project", which was "YANG File". That is what
-you will select now. Click "Next" to go to the first wizard page.
-
-==== First Yang File Wizard Page
-
-This wizard page lets you specify where the new file will be located, and its name.
-
-You have to select the particular project you want the file to go
-into, and it needs to go into the "src/main/yang" folder (or a
-different location if you changed that field when creating the
-project).
-
-You then enter the desired name of the file in the "File name". The
-file name should have no spaces or "special characters" in it. You
-can specify a ".yang" extent if you want. If you do not specify an
-extent, the YANG IDE will create it with the ".yang" extent.
-
-Click "Next" to go to the next wizard page.
-
-==== Second Yang File Wizard Page
-
-On this wizard page, you set some metadata about the module that is
-used to initialize the contents of the Yang file.
-
-It has the following fields:
-
-===== Module Name
-
-This will default to the "base name" of the file name you created.
-For instance, if the file name you created was "network-setup.yang",
-this field will default to "network-setup". You should leave this
-value as is. There is no good reason to define a model with a name
-different from the file name.
-
-===== Namespace
-
-This defaults to "urn:opendaylight:xxx", where "xxx" is the "base
-name" of the file name you created. You should put a lot of thought
-into designing a namespace naming scheme that is used throughout your
-organization. It is quite common for this namespace value to look like
-a "http" URL, but note that that is just a convention, and will not
-necessarily imply that there is a web page residing at that HTTP
-address.
-
-===== Prefix
-
-This defaults to the "base name" of the file name you created. It
-mostly does not technically matter what you set this to, as long as
-it is not empty. Conventionally, it should be a "nickname" that is
-used to refer to the given namespace in an abbreviated form, when
-referenced in an "import" statement in another Yang model file.
-
-===== Revision
-
-This has to be a date value in the form of "yyyy-mm-dd", representing
-the last modified date of this Yang model. The value will default to
-the current date.
-
-===== Revision Description
-
-This is just human-readable text, which will go into the "description"
-field underneath the Yang "revision" field, which will describe what
-went into this revision.
-
-When all the fields have the content you want, click the "Finish"
-button to set the YANG IDE create the file in the specified location.
-It will then present the new file in the editor view for additional
-modifications.
-
-=== Accessing Artifacts for Yang Model Imports
-
-You might be working on Yang models that are "abstract" or are
-intended to be imported by other Yang models. You might also, and
-more likely, be working on Yang models that import other "abstract"
-Yang models.
-
-Assuming you are in that latter more common group, you need to consider
-for yourself, and for your organization, how you are going to get
-access to those models that you import.
-
-You could use a very simple and primitive approach of somehow
-obtaining those models from some source as plain files and just
-copying them into the "src/main/yang" folder of your project. For a
-simple demo or a "one-off" very short project, that might be
-sufficient.
-
-A more robust and maintainable approach would be to reference
-"coordinates" of the artifacts containing Yang models to import. When
-you specify unique coordinates associated with that artifact, the Yang
-IDE can retrieve the artifact in the background and make it available
-for your "import" statements.
-
-Those "coordinates" that I speak of refer to the Maven concepts of
-"group id", "artifact id", and "version". you may remember "group id"
-and "artifact id" from the wizard page for creating a Yang project.
-It is the same idea. If you ever produce Yang model artifacts that
-other people are going to import, you will want to think more about what
-you set those values to when you created the project.
-
-For example, the OpenDaylight project produces several importable
-artifacts that you can specify to get access to common Yang models.
-
-==== Turning on Indexing for Maven Repositories
-
-Before we talk about how to add dependencies to Maven artifacts with
-Yang models for import, I need to explain how to make it easier to
-find those artifacts.
-
-In the Yang project that you have created, the "pom.xml" file (also
-called a "POM file") is the file that Maven uses to specify
-dependencies. We will talk about that in a minute, but first we need to
-talk about "repositories". These are where artifacts are stored.
-
-We are going to have Eclipse show us the "Maven Repositories" view.
-In the main menu, select "Window" and then "Show View", and then
-"Other". Like in the "New" dialog, you can enter "maven" in the
-filter field to limit the list to views with "maven" in the name.
-Click on the "Maven Repositories" entry and click OK.
-
-This will usually create the view in the bottom panel of the window.
-
-The view presents an outline view of four principal elements:
-
-* Local Repositories
-* Global Repositories
-* Project Repositories
-* Custom Repositories
-
-For this purpose, the only section you care about is "Project
-Repositories", being the repositories that are only specified in the
-POM for the project. There should be a "right-pointing arrow" icon on
-the line. Click that to expand the entry.
-
-You should see two entries there:
-
-* opendaylight-release
-* opendaylight-snapshot
-
-You will also see internet URLs associated with each of those repositories.
-
-For this purpose, you only care about the first one. Right-click on
-that entry and select "Full Index Enabled". The first time you do
-this on the first project you create, it will spend several minutes
-walking the entire tree of artifacts available at that repository and
-"indexing" all of those components. When this is done, searching for
-available artifacts in that repository will go very quickly.
-
-=== Adding Dependencies Containing Yang Models
-
-Double-click the "pom.xml" file in your project. Instead of just
-bringing up the view of an XML file (although you can see that if you
-like), it presents a GUI form editor with a handful of tabs.
-
-The first tab, "Overview", shows things like the "Group Id", "Artifact
-Id", and "Version", which represents the "Maven coordinate" of your
-project, which I have mentioned before.
-
-Now click on the "Dependencies" tab. You will now see two list
-components, labeled "Dependencies" and "Dependency Management". You
-only care about the "Dependencies" section.
-
-In the "Dependencies" section, you should see one dependency for an
-artifact called "yang-binding". This artifact is part of
-OpenDaylight, but you do not need to know anything about it.
-
-Now click the "Add" button.
-
-This brings up a dialog titled "Select Dependency". It has three
-fields at the top labeled "Group Id", "Artifact Id", and "Version",
-with a "Scope" dropdown. You will never have a need to change the
-"Scope" dropdown, so ignore it. Despite the fact that you will need to
-get values into these fields, in general usage, you will never have to
-manually enter values into them, but you will see values being inserted
-into these fields by the next steps I describe.
-
-Below those fields is a field labeled "Enter groupId, artifactId ...".
-This is effectively a "filter field", like on the "New" dialog, but
-instead of limiting the list from a short list of choices, the value
-you enter there will be matched against all of the artifacts that were
-indexed in the "opendaylight-release" repository (and others). It
-will match the string you enter as a substring of any groupId or
-artifactId.
-
-For all of the entries that match that substring, it will list an
-entry showing the groupId and artifactId, with an expansion arrow. If
-you open it by clicking on the arrow, you will see individual entries
-corresponding to each available version of that artifact, along with
-some metadata about the artifacts between square brackets, mostly
-indicating what "type" of artifact is.
-
-For your purposes, you only ever want to use "bundle" or "jar" artifacts.
-
-Let us consider an example that many people will probably be using.
-
-In the filter field, enter "ietf-yang-types". Depending on what
-versions are available, you should see a small handful of "groupId,
-artifactId" entries there. One of them should be groupId
-"org.opendaylight.mdsal.model" and artifactId "ietf-yang-types".
-Click on the expansion arrow to open that.
-
-What you will see at this point depends on what versions are
-available. You will likely want to select the newest one (most likely
-top of the list) that is also either a "bundle" or "jar" type
-artifact.
-
-If you click on that resulting version entry, you should notice at
-this point that the "Group Id", "Artifact Id", and "Version" fields at
-the top of the dialog are now filled in with the values corresponding
-to this artifact and version.
-
-If this is the version that you want, click OK and this artifact will
-be added to the dependencies in the POM.
-
-This will now make the Yang models found in that artifact available in
-"import" statements in Yang models, not to mention the completion
-choices for that "import" statement.
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/yang-ide-user-guide.html
Code Review / docs.git / commitdiff
